更新日志

Browser Run 现在支持独立的 /accessibilityTree 端点，为 Agent 和自动化工作流提供对已渲染网页浏览器无障碍树的直接访问。

无障碍树是浏览器对已渲染页面的结构化视图：角色、名称、状态、值和层级关系。它对无障碍工具很有用，同时也对需要页面结构而无需处理原始 HTML 噪音或截图成本的 AI Agent 和自动化工作流非常实用。

对于 AI Agent 而言，这意味着减少了从像素推断信息以及解析 HTML 的工作。您可以直接提供页面结构，帮助 Agent 识别可用元素并判断其可执行的操作。

使用新的 /accessibilityTree 端点，当您只需要页面的语义结构时，可以直接请求无障碍树。如果需要在单次 API 调用中获取多种页面格式，可以使用 /snapshot 端点，该端点同时返回 Markdown、HTML 和截图。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/accessibilityTree' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/"
}'

{
	"success": true,
	"result": {
		"accessibilityTree": {
			"role": "RootWebArea",
			"name": "Example Domain",
			"children": [
				{
					"role": "heading",
					"name": "Example Domain",
					"level": 1
				},
				{
					"role": "link",
					"name": "Learn more"
				}
			]
		}
	}
}

使用 interestingOnly 仅返回语义上有意义的节点，或使用 root 捕获特定子树的无障碍树。

请参阅 /accessibilityTree 文档 以获取使用示例和支持的参数。

R2 Data Catalog 是直接内置于 R2 存储桶的托管 Apache Iceberg ↗ 目录。Iceberg 通过元数据文件树追踪您的数据，因此每次插入、更新和删除都必须通过目录事务进行。在目录外手动添加、修改或删除对象可能会留下指向不再存在的文件的指针，使表损坏成难以恢复的不一致状态。

为帮助防止此类情况，R2 仪表板和 Wrangler 现在会在您尝试对启用 Data Catalog 的存储桶执行手动删除操作时发出警告。

当您尝试从启用 R2 Data Catalog 的存储桶中删除对象时，仪表板会显示一个警告，解释该操作可能使目录处于无效状态，并提供正确删除数据的文档链接。您可以取消操作或选择继续执行。

Wrangler 现在在运行删除操作前会检查存储桶是否启用了 Data Catalog，并在继续之前发出警告：

Data Catalog is enabled for this bucket. 
Proceeding may leave the data catalog in an invalid state. Continue?

要了解如何安全管理和删除表中的数据，请参阅 R2 Data Catalog 文档。

Wrangler 配置文件中全新的声明式 exports 字段取代了用于管理 Durable Object 类生命周期的命令式 migrations 数组。您无需再编写带有唯一标签的有序迁移步骤列表，而是声明 Worker 导出的每个 Durable Object 类，Cloudflare 会将其与已部署的内容进行对比，以确定需要创建、重命名还是删除哪些 Durable Object 状态。

在使用旧版迁移时，将 ChatRoom 重命名为 Room 需要保留这两个标记的步骤：

{
	"migrations": [
		{ "tag": "v1", "new_sqlite_classes": ["ChatRoom"] },
		{
			"tag": "v2",
			"renamed_classes": [{ "from": "ChatRoom", "to": "Room" }],
		},
	],
}

而使用 exports，您只需将 Room 声明为当前类，并将 ChatRoom 标记为已重命名：

{
	"exports": {
		"ChatRoom": {
			"type": "durable-object",
			"state": "renamed",
			"renamed_to": "Room",
		},
		"Room": { "type": "durable-object", "storage": "sqlite" },
	},
}

每个条目都以类名作为键。state 字段承载生命周期（默认为 created——活动类——以及墓碑（tombstone）状态 deleted、renamed、transferred，和用于跨 Worker 传输的接收状态 expecting-transfer）。

与旧版 migrations 数组相比的关键改进：

• 无需迁移标签。 当前的 exports 映射是唯一的真实数据源——无需维护 v1、v2、v3 条目的历史链。
• 结构化的部署输出。 Wrangler 会在创建、更新、删除、重命名或传输 Durable Object 类时进行报告。它还会识别可安全删除的陈旧配置条目。没有更改或通知的部署不会打印此输出。
• 零停机重命名和传输模式是一等公民。 墓碑（Tombstones）可以与代码中仍然存在的源类共存，从而实现 三次部署重命名 和 四次部署跨 Worker 传输，在滚动部署期间不会出现运行时错误。
• 跨 Worker 安全性。 当您删除或重命名类时，Cloudflare 会列出您账户中其绑定（binding）仍引用该命名空间的其他所有 Worker，以便您在更改生效前重新部署它们。

使用旧版 migrations 数组的现有 Workers 仍可照常工作，无需任何更改。要过渡到 exports，请参阅迁移指南。在单个 Worker 中，exports 和 migrations 是互斥的。

欲了解完整的参考信息，请参阅 Durable Object 类导出。

我们已经发布了 @cloudflare/workers-types ↗ 的第 5 版。此版本简化了该包，使其仅公开最新的运行时类型。

我们仍然建议您使用 wrangler types 为您的 Worker 生成类型，但如果您想直接使用该包，您可以使用您选择的包管理器进行安装：

npm i -D @cloudflare/workers-types@latest

yarn add -D @cloudflare/workers-types@latest

pnpm add -D @cloudflare/workers-types@latest

bun add -d @cloudflare/workers-types@latest

该包现在公开了两个入口点：

• @cloudflare/workers-types 反映了最新的兼容性日期，使用最新的稳定兼容性标志。
• @cloudflare/workers-types/experimental 反映了处于实验性兼容性标志之下的 API。

删除了带有日期的入口点，例如 @cloudflare/workers-types/2022-11-30 和 @cloudflare/workers-types/2023-03-01。借助 Wrangler v4 中的运行时类型生成功能，您可以使用 wrangler types 命令来生成这些类型，以创建锁定到您的 Worker 兼容日期的类型。

有关更多信息，请参阅 TypeScript 语言支持。

当您将数据源连接到您的 AI Search 实例时，AI Search 会运行同步作业以使您的索引与您的内容保持最新。您现在可以直接从 Wrangler 管理这些作业。

例如，您可以使用 jobs create 命令从您的 CI/CD 或自动化流水线触发同步作业，以便在推送更改时刷新索引：

wrangler ai-search jobs create my-instance

这将创建一个异步同步作业，该作业会检查数据源中的更改，并发送新增、修改或删除的文件以进行索引。 以下命令可用：

所有命令都接受 --namespace/-n（默认为 default）和 --json，以输出自动化和 AI 代理可以直接解析的结构化数据。list 和 logs 命令还支持用于分页的 --page 和 --per-page，并且除非您传递 -y/--force，否则 cancel 会提示确认。

有关完整的用法详细信息，请参阅 AI Search Wrangler 命令文档。

Wrangler CLI 现在支持身份验证配置文件（auth profiles）：命名登录，您可以将其范围限制为特定的 Cloudflare 账户，并根据您正在工作的目录自动在它们之间进行切换。

配置文件（profile）是绑定到目录的命名 OAuth 登录。在该目录及其子目录中运行的命令将使用匹配的账户 —— 这样您就可以在账户之间切换，而无需重新运行 wrangler login。

当您在代理机构工作时，使用配置文件为每个客户保留单独的登录，或者将暂存（staging）和生产（production）环境分隔到不同的账户中。在您的 Wrangler 配置文件 中将配置文件与 account_id 配对，这样命令就不会访问到错误的账户。

# 为每个账户创建一个配置文件，选择它能访问的账户
wrangler auth create client-a
wrangler auth activate client-a ~/clients/client-a

wrangler auth create client-b
wrangler auth activate client-b ~/clients/client-b

使用 --profile 标志以特定配置文件运行单个命令：

wrangler deploy --profile personal

在 CI 和其他自动化环境中，CLOUDFLARE_API_TOKEN 仍然优先于所有配置文件。

有关设置、解析顺序和完整命令参考，请参阅身份验证配置文件（Authentication profiles）。

Containers 现在支持 Google Artifact Registry ↗ 镜像。配置凭据后，您可以在 Wrangler 配置中使用完全限定的 Google Artifact Registry 镜像引用，而无需先将镜像推送到 Cloudflare Registry。

使用 --gar-email 提供服务账户电子邮件，并通过 stdin 用管道传输服务账户 JSON 密钥：

cat <PATH_TO_KEY> | npx wrangler containers registries configure <REGION>-docker.pkg.dev --gar-email=<SERVICE_ACCOUNT_EMAIL> --secret-name=<SECRET_NAME>

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "containers": [
    {
      "image": "<REGION>-docker.pkg.dev/<PROJECT_ID>/<REPOSITORY>/<IMAGE>:<TAG>"
    }
  ]
}

# 示例: us-central1-docker.pkg.dev/my-project/my-repo/my-image:latest
[[containers]]
image = "<REGION>-docker.pkg.dev/<PROJECT_ID>/<REPOSITORY>/<IMAGE>:<TAG>"

仅支持 *-docker.pkg.dev 主机。要配置凭据，请参阅使用私有 Google Artifact Registry 镜像。

欲了解更多信息，请参阅镜像管理。

Images 绑定（binding）现在按唯一转换计费，这与已用于基于 URL 转换的计费模型一致。在同一个日历月内对相同源图像和参数组合的重复请求仅计算一次。

在此之前，无论图像或参数是否唯一，对绑定的每次调用都被计为一次单独的转换。有了这项改进，您可以在热点路径上调用绑定，而无需为每个单独的请求付费。

对 .info() 的调用不再计费。

欲了解更多信息，请参阅 Images 定价和 Images 绑定文档。

我们大幅提升了 Vectorize 预写日志（WAL） ↗的吞吐量。因此，向量变更变为可查询的端到端延迟显著降低：中位延迟从 2 分钟降至 30 秒以内，p99 延迟从 5 分钟降至 2 分钟以内。

这意味着插入、upsert 和删除操作将更快地反映在查询结果中，提升语义搜索、推荐和检索增强生成（RAG）工作负载的数据新鲜度。您无需更改代码或配置即可受益于此改进。

有关更多信息，请参阅 Vectorize 文档。

您现在可以使用 Workers 指标（Metrics）选项卡中新增的 Memory Usage（内存使用情况） 图表，监控您的 Workers 和 Durable Objects 在多次调用中消耗了多少内存，图表按 P50、P90、P99 和 P999 百分位数进行了细分。

内存使用情况测量的是每次调用时的 V8 isolate 内存，受限于 每个 isolate 128 MB 的限制 —— 单个 isolate 可以处理许多并发请求并在它们之间共享内存。

使用内存使用情况图表可以：

• 跟踪内存趋势 —— 在导致 Exceeded Memory（超出内存）错误之前，发现可能表明存在内存泄漏的渐进式内存增加。
• 与部署关联 —— 图表上的部署标记可帮助您确定新版本是否引入了内存回归。
• 合理调整您的 Worker 规模 —— 了解您的基准内存占用量，以及在达到 128 MB 限制之前您还有多少余量。

对于 Durable Objects，内存使用情况反映了对象保存的内存中状态（类属性、缓存、活动的 WebSocket 连接），该状态在多次调用之间保持不变，直到对象被休眠或逐出。在逐出、休眠或崩溃时，此状态不会保留，因此请将任何重要内容持久化保存到存储中。

要查看内存使用情况，请打开您的 Worker ↗ 或 Durable Object 命名空间 ↗ 的 Metrics（指标） 选项卡。对于 Durable Objects，您可以按 DO ID 或名称进行过滤，以深入查看特定对象的内存使用情况。您还可以通过 GraphQL Analytics API 使用 workersInvocationsAdaptive 数据集以编程方式查询内存使用情况 —— 从 quantiles.memoryUsageBytesP50 到 quantiles.memoryUsageBytesP999 的字段以字节为单位返回百分位数。

对于本地内存调试，您还可以使用 DevTools 剖析内存以获取堆快照并识别导致高内存占用的特定对象。

Workers fetch() 请求现在支持 cf.vary 请求选项。使用 cf.vary 可以控制 Cloudflare 如何为单个子请求缓存具有 Vary 标头的源服务器响应。

export default {
	async fetch(request) {
		return fetch(request, {
			cf: {
				vary: {
					default: { action: "bypass" },
					headers: {
						accept: {
							action: "normalize",
							media_types: ["text/html", "application/json"],
						},
						"accept-language": {
							action: "normalize",
							languages: ["en", "fr", "de"],
						},
					},
				},
			},
		});
	},
};

export default {
	async fetch(request): Promise<Response> {
		return fetch(request, {
			cf: {
				vary: {
					default: { action: "bypass" },
					headers: {
						accept: {
							action: "normalize",
							media_types: ["text/html", "application/json"],
						},
						"accept-language": {
							action: "normalize",
							languages: ["en", "fr", "de"],
						},
					},
				},
			},
		});
	},
} satisfies ExportedHandler;

有关更多信息，请参阅 cf.vary。

Agents SDK ↗ 的最新版本使得在后台运行长时间工作、通过一个入口点驱动轮次以及让聊天 agent 在部署、驱逐和重新连接期间保持正常工作变得更加容易。

此版本添加了一等的独立（后台）子 agent 运行（具有实时进度和持久里程碑）、单个 runTurn 轮次准入入口点，以及大量的恢复和可靠性修复，这些修复继续将 @cloudflare/think 和 @cloudflare/ai-chat 收敛到同一个模型上。

runAgentTool 现在可以派发一个子 agent，而不会阻塞调用轮次。独立的运行会立即返回一个句柄，并由一个持久的、在驱逐中存活的骨干（backbone）所拥有，而不是在派发轮次结束时被放弃。

class OrdersAgent extends Think {
	async startImport(input) {
		// Fire-and-forget, or wire a durable completion callback
		// (by method name, like schedule()):
		await this.runAgentTool(ImportAgent, {
			input,
			detached: { onFinish: "onImportDone", maxBudgetMs: 60 * 60 * 1000 },
		});
	}

	// result.status: "completed" | "error" | "aborted" | "interrupted"
	async onImportDone(run, result) {}
}

class OrdersAgent extends Think {
	async startImport(input) {
		// Fire-and-forget, or wire a durable completion callback
		// (by method name, like schedule()):
		await this.runAgentTool(ImportAgent, {
			input,
			detached: { onFinish: "onImportDone", maxBudgetMs: 60 * 60 * 1000 },
		});
	}

	// result.status: "completed" | "error" | "aborted" | "interrupted"
	async onImportDone(run, result) {}
}

亮点：

• 持久的、在正常路径上仅执行一次的完成：通过热快速路径以及一个在驱逐和部署中存活的自调度对齐骨干。
• 有边界。 绝对的 maxBudgetMs 上限（默认 24 小时）和 cancelAgentTool(runId) 可以防止被放弃的运行永远占用并发槽位。
• detached: { notify: true } 允许已完成的后台运行将消息注入回聊天中，以便模型对结果做出反应 —— 无需手动连接 onFinish。

子 agent 还可以报告运行中进度，这些进度会通过它们自己的轮次流返回到父级连接的客户端：

// Inside the child sub-agent:
await this.reportProgress({
	fraction: 0.6,
	phase: "deploying",
	message: "Generating menu page…",
});

// Inside the child sub-agent:
await this.reportProgress({
	fraction: 0.6,
	phase: "deploying",
	message: "Generating menu page…",
});

进度通过 useAgentToolEvents 呈现在 AgentToolRunState.progress 上，因此后台运行托盘（tray）可以渲染实时进度条而无需深入查看，并且最新快照会被持久化以便在驱逐后进行检查。命名一个 milestone（里程碑）会将一个信号提升为持久的、可重放的行，并且 detached: { onMilestones } 可以将里程碑呈现为合成聊天消息（对于简单的状态行使用 "narrate"，或者使用 "react" 来驱动模型轮次）。

@cloudflare/think 添加了一个公共 runTurn(options) 外观（facade），将轮次准入统一在单个 mode 后面：

await this.runTurn({ mode: "wait", messages }); // saveMessages / continueLastTurn
await this.runTurn({ mode: "submit", messages }); // durable submitMessages
await this.runTurn({ mode: "stream", messages }); // chat()

await this.runTurn({ mode: "wait", messages }); // saveMessages / continueLastTurn
await this.runTurn({ mode: "submit", messages }); // durable submitMessages
await this.runTurn({ mode: "stream", messages }); // chat()

stream 模式接受数组和函数输入以匹配 wait 模式，所有入口点现在都通过共享的内部准入路径进行路由，该路径在之前可能导致死锁的嵌套阻塞准入上会抛出清晰的错误。

此版本的很大一部分继续强化恢复，并将 @cloudflare/think 和 @cloudflare/ai-chat 收敛到同一个模型上：

• 流停滞看门狗。 AIChatAgent 可以通过选择启用的 chatStreamStallTimeoutMs 看门狗检测并从挂起的模型/传输流中恢复。启用 chatRecovery 后，停滞将路由到部署或驱逐使用的相同有界恢复机制中；否则，它会作为终端流错误显现，以便清除加载指示器。
• 中断的工具调用修复。 AIChatAgent 现在在重新进入推理之前会修复带有已死服务器工具调用的脚本（与 @cloudflare/think 保持一致），因此恢复的轮次不再因 AI_MissingToolResultsError 而失败。可重写的 repairInterruptedToolPart(part) Hook 允许应用程序自定义修复后的形状。
• 重连后状态卡住。 修复了当重连与已接受但尚未开始流式传输的轮次发生竞态时，AI SDK status 卡住的问题，因此 UI 现在会渲染进行中的轮次，而不是卡在 ready。
• 连接时的实时 “recovering…”。 AIChatAgent 现在会将恢复状态回放到在恢复途中连接的客户端，因此 useAgentChat 的 isRecovering 会立即反映进行中的恢复，而不是显得冻结。
• 终端连接失败。 客户端在终端 WebSocket 关闭事件上停止重新连接，并通过 AgentClient、useAgent 和 useAgentChat 上的 connectionError / onConnectionError 暴露它们。
• Agent-tool 子节点恢复。 在部署后，健康的长期运行子 agent 运行不再被作为 interrupted（中断）放弃（对于 @cloudflare/think 和 AIChatAgent 皆是如此）。
• 来自子 agent 侧面（facets）的 Workflow。 Agent Workflows 现在可以从子 agent 侧面（facets）开始，回调和 Workflow RPC 会被路由回源侧面。
• 此外还有前向进度信用收敛、广播优先放弃顺序、事件驱动的自动继续屏障，以及 AIChatAgent 中的结构化行大小压缩。

• 共享聊天 React 核心。 新的 agents/chat/react 入口暴露了 useAgentChat、传输辅助函数和共享线缆（wire）类型，具有用于服务器权威脚本存储的 syncMessagesToServer。@cloudflare/think/react and @cloudflare/ai-chat/react 现在只是它的薄包装器。
• 可选的 ai 同级依赖。 根 agents and @cloudflare/codemode 运行时不再引用 AI SDK 类型，因此它们可以在不安装 ai / zod 的情况下打包；特定于 AI 的入口点在导入时仍然需要同级依赖。just-bash 同样移动到了仅由 skills bash 运行器使用的可选同级依赖中。
• Code Mode。 默认的 DynamicWorkerExecutor 超时时间从 30 秒增加到 60 秒，每次运行后现在会销毁动态加载的 Worker 及其 RPC 存根（stub）（修复了不稳定的隔离区关闭断言），连接器导入已被清理，并且外部 MCP 工具调用上下文会被传递给 openApiMcpServer 请求回调。
• Voice。 Voice 轮次现在支持 AI SDK fullStream 响应（并在使用 textStream 时发出警告）。
• MCP。 McpAgent 服务器到客户端的请求现在可以从不继承 agent 异步上下文的回调中发送，包括通过 Worker Loader RPC 到达的回调。
• 实验性：服务器操作和通道。 此版本为受保护的服务器操作（带有持久重放账本和批准的 action() / getActions()）和统一的通道表面（configureChannels()、deliverNotice()）奠定了基础。两者都是实验性的，它们的 API 可能会发生变化，因此我们目前不建议依赖它们。

要更新到最新版本：

npm i agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/voice@latest

yarn add agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/voice@latest

pnpm add agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/voice@latest

bun add agents@latest @cloudflare/think@latest @cloudflare/ai-chat@latest @cloudflare/codemode@latest @cloudflare/voice@latest

有关更多信息，请参阅 Think 文档、Code Mode 文档和 Agents 文档。

Durable Objects 现在支持 us 管辖区（jurisdiction），允许您创建仅在美国境内运行并存储数据的 Durable Objects。当您需要将 Durable Object 的计算和存储保留在美国境内以满足数据驻留要求时，请使用 us 管辖区。

像使用任何其他管辖区一样，创建一个受限于 us 管辖区的命名空间：

// Worker
export default {
	async fetch(request, env) {
		const usSubnamespace = env.MY_DURABLE_OBJECT.jurisdiction("us");
		const stub = usSubnamespace.getByName("general");
		return stub.fetch(request);
	},
};

Workers 仍可从世界任何地方访问受限于 us 管辖区的 Durable Objects。管辖区限制仅控制 Durable Object 本身在何处运行和持久化数据。

如需查看支持的管辖区的完整列表，请参阅数据位置 — 限制 Durable Objects 至特定管辖区。

@cloudflare/vitest-pool-workers 包现在包含了从 cloudflare:test 导出的 evictDurableObject 和 evictAllDurableObjects 测试辅助函数。

这些辅助函数允许您测试 Durable Object 在逐出发生时的行为，模拟闲置 Durable Object 从内存中逐出的实际生产生命周期。

有关更多背景信息，请参阅 Durable Object 的生命周期。

import { evictDurableObject, evictAllDurableObjects } from "cloudflare:test";
import { env } from "cloudflare:workers";

const id = env.COUNTER.idFromName("my-counter");
const stub = env.COUNTER.get(id);

// 逐出特定 stub 所指向的 Durable Object 实例
await evictDurableObject(stub);

// 关闭 WebSockets 而不是将它们休眠
await evictDurableObject(stub, { webSockets: "close" });

// 逐出当前在可逐出命名空间中运行的所有 Durable Objects
await evictAllDurableObjects();

这些辅助函数在 @cloudflare/[email protected] 及更高版本中可用。

请在 测试 API 参考和测试 Durable Objects 指南中了解更多信息。

AI Search 现在让您能够更好地控制相似性缓存新鲜度。相似性缓存通过重用语义相似查询的响应，有助于降低延迟和推理成本。

通过这些更新，您可以选择允许重用响应的时间长度，并在缓存的响应可能过时时将其清除。

以前，AI Search 缓存响应的固定时间为 30 天。缓存的响应现在使用实例的 cache_ttl 设置，默认值为 48 小时。

您可以在创建或更新实例时设置 cache_ttl，以选择从 10 分钟到 6 天不等的缓存持续时间。

当您的源内容变化频繁且新鲜度更重要时，请使用较短的 TTL。当您的内容稳定且您希望更多地重用缓存时，请使用较长的 TTL。

例如，将 cache_ttl 设置为 518400 以将缓存的响应保留 6 天：

{
	"cache_ttl": 518400
}

您还可以按需清除实例的所有缓存响应。清除缓存响应不会删除已索引的内容或源文件。

这会阻止 AI Search 重用以前缓存的响应，因此后续的相似查询会生成新鲜的答案并重新填充缓存。

curl -X POST "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/ai-search/instances/$INSTANCE_NAME/purge_cache" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

您还可以从 Cloudflare 仪表板中的实例设置页面清除缓存响应。

请参阅相似性缓存以获取支持的 cache_ttl 值的完整列表以及有关缓存行为的更多详细信息。

Workflows 使构建可靠的多步骤应用程序变得更加容易，这些应用程序能够在下游系统故障时恢复。回滚处理程序现在通过 ctx 对象接收正在回滚的步骤的原始步骤上下文。这包括 ctx.step.name、ctx.step.count、ctx.attempt 以及应用了默认值的步骤 config。

步骤配置包含用于该步骤的重试和超时设置，因此您可以根据这些字段自定义步骤恢复逻辑。

await step.do(
	"create charge",
	async () => {
		const charge = await createCharge();
		return { chargeId: charge.id };
	},
	{
		rollback: async ({ ctx, output, error }) => {
			// `output` 是被回滚步骤返回的值。
			const { chargeId } = output as { chargeId: string };
			await refundCharge(chargeId, {
				// `ctx` 是原始步骤上下文，包括步骤名称、计数、尝试次数和配置。
				reason: `${ctx.step.name}: ${error.message}`,
			});
		},
		rollbackConfig: {
			// `rollbackConfig` 控制回滚处理程序的重试和超时。
			retries: { limit: 3, delay: "30 seconds", backoff: "linear" },
			timeout: "5 minutes",
		},
	},
);

请参阅回滚选项了解更多信息。

Regional Services 现在支持 Regionalized IP Bindings，让您能够针对通过 Bring Your Own IP (BYOIP) 引入 Cloudflare 的前缀在 IP 层实现流量区域化。

Regional Hostnames 是按主机名对流量进行区域化，而 Regionalized IP Bindings 允许您将来自前缀之一的 CIDR 绑定（binding）到某个区域 —— 这非常适合地址映射部署以及任何您通过 IP 而非主机名寻址的服务。然后，Cloudflare 会在 TLS 终止后，仅在该区域的数据中心内处理发往这些地址的流量。

Regionalized IP Bindings 需要 Regional Services 和 Regional Services for BYOIP 的授权。请联系您的账户团队以启用它们。

要开始使用，请参阅 Regionalized IP Bindings。

R2 SQL 现在支持窗口函数、SELECT DISTINCT、集合操作和更多聚合，使得编写分析查询变得更加容易，而无需在其他地方预处理数据。

R2 SQL 是 Cloudflare 的无服务器分布式 SQL 引擎，用于查询存储在 R2 Data Catalog 中的 Apache Iceberg ↗ 表。

• 窗口函数 — ROW_NUMBER、RANK、DENSE_RANK、PERCENT_RANK、CUME_DIST、NTILE、LAG、LEAD、FIRST_VALUE、LAST_VALUE、NTH_VALUE，以及带有 OVER (...) 子句的聚合，包括 PARTITION BY 和显式窗口范围（frames）
• QUALIFY — 根据窗口函数结果过滤行
• DISTINCT — SELECT DISTINCT、DISTINCT ON (...) 以及聚合上的 DISTINCT 修饰符（例如 COUNT(DISTINCT ...)）
• 集合操作 — UNION、UNION ALL、INTERSECT 和 EXCEPT
• 分组扩展 — GROUPING SETS、ROLLUP 和 CUBE
• 精确聚合 — MEDIAN、PERCENTILE_CONT、ARRAY_AGG 和 STRING_AGG

SELECT customer_id, region,
       ROW_NUMBER() OVER (PARTITION BY region ORDER BY total_amount DESC) AS rank_in_region
FROM my_namespace.sales_data

SELECT customer_id, region, total_amount
FROM my_namespace.sales_data
QUALIFY ROW_NUMBER() OVER (PARTITION BY region ORDER BY total_amount DESC) <= 3

SELECT customer_id FROM my_namespace.sales_data
EXCEPT
SELECT customer_id FROM my_namespace.archived_sales

不支持具名 WINDOW 子句 — 请在每个调用点内联 OVER (...) 规范。有关完整语法参考，请参阅 SQL 参考。有关支持的功能和性能指南，请参阅限制与最佳实践。

Cloudflare 仪表板中的 **Routes（路由）**页面现在在单个表格中显示您所有连接器的路由——包括 Cloudflare Mesh 和 Cloudflare Tunnel 路由，以及 Cloudflare WAN 和 Magic Transit 静态路由，而不是每个产品分别显示独立的路由视图。

在统一的 Routes 页面中，您可以：

• 通过交互式地图可视化您的网络，该地图显示了您的目的地如何流向您的连接器——包括由多个连接器提供相同前缀服务的等价多路径（ECMP）路由。选择一个节点以过滤表格以显示其后面的路由。
• 在单个表格中查看每条路由，及其目的地、类型、连接器、优先级和来源，并进行过滤或排序以找到您需要的内容。
• 创建、编辑和删除路由（支持任何受支持的类型），而无需离开页面。添加 Cloudflare WAN 或 Magic Transit 静态路由时，您现在可以通过连接器名称选择下一跳，而无需输入其 IP。
• 在专用选项卡中管理虚拟网络。
• 测试路由，以便在提交更改之前查看目的地解析为哪个连接器和下一跳。

要找到它，请前往仪表板侧边栏中的 Networking（网络） > Routes（路由）。

您现有的路由、API 和配置保持不变——这是一个将它们聚集在一个地方的仪表板体验。了解如何添加路由和管理虚拟网络。

Durable Objects 现在支持两个针对亚太地区的新位置提示：apac-ne（东北亚）和 apac-se（东南亚）。当您希望在亚太地区内进行更细粒度的托管放置，而不是使用更宽泛的 apac 提示时，请使用 apac-ne 或 apac-se。

像使用任何其他 locationHint 一样使用这些新提示：

// 东北亚（日本、韩国等）
const stubNE = env.MY_DURABLE_OBJECT.get(id, { locationHint: "apac-ne" });

// 东南亚（新加坡、印度尼西亚等）
const stubSE = env.MY_DURABLE_OBJECT.get(id, { locationHint: "apac-se" });

如果您的用户分布在整个亚太地区，现有的 apac 提示仍是正确的选择。只有当您的流量明显集中在某一个子区域，且您希望将该受众的往返时间降至最低时，才使用 apac-ne 或 apac-se。默认行为以及我们通常建议的做法是，除非绝对需要，否则不添加位置提示，这将在尽可能靠近发起请求的地方创建 Durable Object 以减少延迟。

与所有位置提示一样，这些都是尽力而为的建议。Cloudflare 会将 Durable Object 放置在附近的数据中心，而不一定是提示的确切位置。

如需查看支持的提示的完整列表，请参阅数据位置 — 提供位置提示。

现在，通过 connect() 或出站 WebSocket 创建的活动出站连接在持续期间，Durable Objects 将保持存活。此前，即使对象具有打开的出站连接，Durable Object 也会在 70-140 秒无入站流量后被逐出，而这在使用 TCP 或出站 WebSocket 从大型语言模型 (LLM) 流式传输响应时是一种常见模式。

通过此更改，每个活动的出站连接都可以防止被逐出。一旦所有出站连接关闭，在 Durable Object 被逐出之前将适用标准的 70-140 秒空闲窗口。

如果您正在 Cloudflare 上构建智能体（Agent），这一点尤为重要。在调用模型时从 LLM 流式传输 Token 的智能体，或者通过出站连接执行长时间运行的任务的智能体，现在会在该连接持续期间保持存活，而不是在中途被逐出。

限制：

• 每个出站连接最多可使 Durable Object 保持存活 15 分钟。15 分钟后，该连接将不再防止逐出（连接本身将继续运行），并恢复标准逐出规则。
• Durable Object 现有的每个账户实例限制仍然适用。

欲了解更多信息，请参阅 Durable Object 的生命周期。

AI 智能体（agent）现在可以直接向 Cloudflare 部署 Workers，而无需用户先进行注册、打开基于浏览器的 OAuth 流程、点击仪表板或创建 API 令牌（API token）。当智能体尝试在没有 Cloudflare 凭证的情况下进行部署时，Wrangler 可以指示其使用 --temporary 重新运行，然后将 Worker 部署到临时预览账户中。

要在您的智能体中尝试此操作，请更新到 Wrangler 4.102.0 或更高版本，确保您已退出登录（wrangler logout），然后让您的智能体构建某些内容并将其部署到 Cloudflare。该智能体应当遵循 Wrangler 的输出并使用 --temporary 标志进行部署。

wrangler deploy --temporary

临时部署将保持在线 60 分钟。在此窗口期间，智能体可以验证 Worker、重新部署更改，并返回在线 Worker URL 和认领 URL。打开认领 URL 允许您登录或创建 Cloudflare 账户，并将临时账户转为永久账户。

临时预览账户目前支持有限的一组产品，包括 Workers、Workers Static Assets、Workers KV、D1、Durable Objects、Hyperdrive、Queues 和 SSL/TLS 证书。有关支持的产品、限制和认领行为，请参阅认领部署（临时账户）。

有关更多背景信息，请参阅 Temporary Cloudflare Accounts for Agents ↗。

exec() 现已用于 Containers。使用 this.ctx.container.exec() 在正在运行的 Container 中启动进程、流式传输标准输入和输出、检查退出状态码以及向每个进程发送信号。

在继承 Container 的类中，或在另一个 Durable Object 中通过 this.ctx.container 调用 exec()。关联的 Container 必须已在运行。

此示例在需要时启动 Container，然后读取其 Node.js 版本：

import { Container } from "@cloudflare/containers";

export class MyContainer extends Container {
	async readVersion() {
		if (!this.ctx.container.running) {
			await this.start();
		}

		const process = await this.ctx.container.exec(["node", "--version"]);
		const output = await process.output();
		const decoder = new TextDecoder();

		return {
			exitCode: output.exitCode,
			stdout: decoder.decode(output.stdout),
			stderr: decoder.decode(output.stderr),
		};
	}
}

import { Container } from "@cloudflare/containers";

export class MyContainer extends Container {
	async readVersion() {
		if (!this.ctx.container.running) {
			await this.start();
		}

		const process = await this.ctx.container.exec(["node", "--version"]);
		const output = await process.output();
		const decoder = new TextDecoder();

		return {
			exitCode: output.exitCode,
			stdout: decoder.decode(output.stdout),
			stderr: decoder.decode(output.stderr),
		};
	}
}

命令数组直接启动可执行文件，没有隐式的 shell。如果需要管道、重定向或变量展开，请显式调用 shell。

一个 RPC 方法可以在一次调用者到 Durable Object 的往返中协调多个 exec() 调用。它还可以传递面向字节的 ReadableStream 输入或返回具有流量控制的流式输出。

有关选项和流式传输示例，请参阅执行命令。

作为一个按需付费（pay-as-you-go）客户，您可以从 Cloudflare 创建 PlanetScale Postgres 和 MySQL 数据库，并通过您的 Cloudflare 账户结算 PlanetScale 数据库的使用费用。Cloudflare 合约客户将能够在 7 月份将 PlanetScale 的使用额度添加到其合约中，因此如果有兴趣，请联系您的 Cloudflare 账户团队。

从 Cloudflare 仪表板创建 PlanetScale 数据库，以体验针对区域数据访问进行了优化的全球分布式 Workers。

从 Cloudflare 创建的 PlanetScale 数据库通过 Hyperdrive 与 Workers 协同工作。Hyperdrive 管理数据库连接池和查询缓存，因此您可以将 PlanetScale 用作 Workers 应用程序的集中式关系数据库，而无需更改数据库驱动程序、对象关系映射 (ORM) 库或 SQL 工具。

PlanetScale 的使用情况将在每个计费周期以美元总额的形式显示在您的 Cloudflare 发票上，价格遵循 PlanetScale 的标准定价 ↗。您可以通过 PlanetScale 的仪表板 ↗自检每个数据库的计费使用情况。

当您从 Cloudflare 仪表板创建 PlanetScale 数据库时，您将获得相同的 PlanetScale 开发人员体验，包括开发分支、查询洞察以及针对 Agent 的 Model Context Protocol (MCP) 服务端支持。

要开始使用，请参阅 PlanetScale Postgres and MySQL with Hyperdrive。

您现在可以直接从 Cloudflare 仪表板配置 Artifacts 命名空间、仓库和令牌。

Artifacts 是兼容 Git 的存储，允许您将仓库存储在 Cloudflare 上，并使用标准 Git 工作流与它们进行交互。

您可以查看和创建命名空间，它们是仓库的顶级容器：

您可以查看、创建、派生和搜索命名空间内的仓库：

您可以打开仓库以查看其文件并复制其 Git 远程 URL。

您还可以直接从仪表板配置令牌，以将 Git 访问权限范围限定为单个仓库，包括用于 clone、fetch 和 pull 工作流的只读令牌，或者当客户端需要推送更改时所需的写入令牌。

要开始使用，请转到 Cloudflare 仪表板 ↗，然后选择 Storage & databases（存储和数据库） > Artifacts。

如果您已加入 Artifacts Beta 测试，您可以使用该仪表板来设置 Artifacts。如果您想加入 Beta 测试，请填写申请表 ↗。