构建你的第一个 Workflow

打开终端并运行 create cloudflare (C3) CLI 工具创建 Worker 项目：

npm create cloudflare@latest -- my-workflow

yarn create cloudflare my-workflow

pnpm create cloudflare@latest my-workflow

进行设置时，请选择以下选项：

• 对于 What would you like to start with?，选择 Hello World example。
• 对于 Which template would you like to use?，选择 Worker only。
• 对于 Which language do you want to use?，选择 TypeScript。
• 对于 Do you want to use git for version control?，选择 Yes。
• 对于 Do you want to deploy your application?，选择 No（部署前我们还会做一些修改）。

进入新项目目录：

cd my-workflow

创建新文件 src/workflow.ts：

import { WorkflowEntrypoint, WorkflowStep } from "cloudflare:workers";
import type { WorkflowEvent } from "cloudflare:workers";

type Params = { name?: string };
type IPResponse = { result: { ipv4_cidrs: string[] } };

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
	async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
		const data = await step.do("fetch data", async () => {
			const response = await fetch(
				"https://api.cloudflare.com/client/v4/ips",
			);
			return await response.json<IPResponse>();
		});

		await step.sleep("pause", "20 seconds");

		const result = await step.do(
			"process data",
			{ retries: { limit: 3, delay: "5 seconds", backoff: "linear" } },
			async () => {
				return {
					name: event.payload.name ?? "World",
					ipCount: data.result.ipv4_cidrs.length,
				};
			},
		);

		return result;
	}
}

Workflow 扩展 WorkflowEntrypoint 并实现 run 方法。此代码还将 Params 类型作为类型参数传递，以便触发 Workflow 的事件具有类型。

step 对象是 Workflows API 的核心。它提供在 Workflow 中定义持久步骤的方法：

• step.do(name, callback) - 执行代码并持久化结果。如果 Workflow 被中断或重试，它从最后一个成功步骤恢复，而不是重新运行已完成的工作。回调返回可序列化数据，包括 JavaScript Workflows 中用于大型二进制输出的 ReadableStream<Uint8Array>。
• step.sleep(name, duration) - 暂停 Workflow 指定时长（例如 "10 seconds"、"1 hour"）。

如果返回流，请返回新的、未锁定的 ReadableStream<Uint8Array>。不支持 BYOB 流和 BYOB 读取器。

你可以向 step.do() 传递重试配置以自定义故障处理方式。请参阅完整 step API 了解流要求、限制以及 sleepUntil 和 waitForEvent 等附加方法。

决定是否将代码拆分为独立步骤时，问自己：「如果只有一部分失败，我希望所有代码重新运行吗？」独立步骤非常适合用于调用外部 API、查询数据库或从存储读取文件等操作——如果后续步骤失败，Workflow 可以使用已获取的数据从该点重试，避免冗余 API 调用或数据库查询。

有关如何定义 Workflow 逻辑的更多指导，请参阅 Workflows 规则。

打开 wrangler.jsonc（Workers 项目和 Workflow 的 Wrangler 配置文件），添加 workflows 配置：

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "my-workflow",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"observability": {
		"enabled": true
	},
	"workflows": [
		{
			"name": "my-workflow",
			"binding": "MY_WORKFLOW",
			"class_name": "MyWorkflow"
		}
	]
}

"$schema" = "node_modules/wrangler/config-schema.json"
name = "my-workflow"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-17"

[observability]
enabled = true

[[workflows]]
name = "my-workflow"
binding = "MY_WORKFLOW"
class_name = "MyWorkflow"

class_name 必须与你的导出 class 匹配，binding 是你在代码中访问 Workflow 的变量名（如 env.MY_WORKFLOW）。

如果希望同一 Workflow 按 recurring 间隔自动运行，在 Workflow 定义中添加 schedules：

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-workflow",
  "main": "src/index.ts",
  // Set this to today's date
  "compatibility_date": "2026-08-17",
  "workflows": [
    {
      "name": "my-workflow",
      "binding": "MY_WORKFLOW",
      "class_name": "MyWorkflow",
      "schedules": ["0 * * * *"]
    }
  ]
}

"$schema" = "node_modules/wrangler/config-schema.json"
name = "my-workflow"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-17"

[[workflows]]
name = "my-workflow"
binding = "MY_WORKFLOW"
class_name = "MyWorkflow"
schedules = [ "0 * * * *" ]

每个匹配的 cron 表达式会自动创建新的 Workflow 实例，因此你无需顶层 triggers.crons 和单独的 scheduled 处理程序来运行 Workflow 特定的 recurring 任务。

调度的实例在 event.schedule 上包含匹配的 cron 表达式和调度触发时间。

配置 Workflow 调度时请使用最新 Wrangler 版本。如果本地 Wrangler schema 尚不识别 schedules，请在部署前更新 Wrangler。

你也可以在 Workflow 内通过 this.env 访问绑定（binding）（如 KV、R2 或 D1）。有关 Workers 内绑定的更多信息，请参阅 绑定 (env)。

现在，为绑定生成类型：

npx wrangler types

这将创建包含 MY_WORKFLOW 绑定的 Env 类型的 worker-configuration.d.ts 文件。

将 src/index.ts 替换为 fetch 处理程序，以启动和检查 Workflow 实例：

export { MyWorkflow } from "./workflow";

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const instanceId = url.searchParams.get("instanceId");

		if (instanceId) {
			const instance = await env.MY_WORKFLOW.get(instanceId);
			return Response.json(await instance.status());
		}

		const instance = await env.MY_WORKFLOW.create();
		return Response.json({ instanceId: instance.id });
	},
} satisfies ExportedHandler<Env>;

启动本地开发服务器：

npx wrangler dev

要启动 Workflow 实例，打开新终端窗口并运行：

curl http://localhost:8787

将自动生成 instanceId：

{ "instanceId": "abc-123-def" }

使用返回的 instanceId 检查状态：

curl "http://localhost:8787?instanceId=abc-123-def"

Workflow 将依次执行各步骤。约 20 秒（sleep 时长）后将完成。

部署 Workflow：

npx wrangler deploy

使用相同的 curl 命令针对已部署 URL 在生产环境测试。你也可以通过 Workers、Wrangler 或 Cloudflare 仪表板触发生产环境中的 workflow 实例。

部署后，你也可以使用 CLI 检查 Workflow 实例：

npx wrangler workflows instances describe my-workflow latest

instances describe 的输出显示：

• 每个步骤的状态（成功、失败、运行中）
• 步骤发出的任何状态。对于流式输出，CLI 显示预览或摘要而非完整内容。
• 任何 sleep 状态，包括 Workflow 何时唤醒
• 与每个步骤关联的重试
• 错误，包括异常消息