cloudflare-workflows

用途

Cloudflare Workflows 用于构建持久化（durable）的工作流，适合需要长时间运行、分步执行、等待外部事件或定时恢复的任务。该能力自 2025 年 4 月正式可用（GA），状态为 Production Ready。它依赖 cloudflare-worker-base 进行 Worker 设置。

主要能力

步骤执行：通过 step.do() 执行工作，支持重试配置与超时。
休眠：step.sleep() 相对休眠，step.sleepUntil() 休眠到指定时间点。
事件等待：step.waitForEvent() 等待外部事件（GA 于 2025 年 4 月加入），可设置超时。
自动重试与状态持久化：步骤可单独重试，状态通过 step.do() 返回值持久化。
测试：使用 cloudflare:test 模块，配合 introspectWorkflowInstance、disableSleeps、mockStepResult、mockEvent 等修饰符进行 Vitest 测试。
平台指标：2025 年 4 月 GA 时提供 CPU 时间指标、4,500 并发实例；2025 年 10 月实例创建速率提升 10 倍（100/秒），并发提升至 10,000。

使用方式

快速开始（约 5 分钟）：

脚手架项目：

npm create cloudflare@latest my-workflow -- --template cloudflare/workflows-starter --git --deploy false
cd my-workflow

配置 wrangler.jsonc：

{
  "name": "my-workflow",
  "main": "src/index.ts",
  "compatibility_date": "2025-11-25",
  "workflows": [{
    "name": "my-workflow",
    "binding": "MY_WORKFLOW",
    "class_name": "MyWorkflow"
  }]
}

创建工作流（src/index.ts）：

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

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    const result = await step.do('process', async () => { /* work */ });
    await step.sleep('wait', '1 hour');
    await step.do('continue', async () => { /* more work */ });
  }
}

部署与测试：

npm run deploy
npx wrangler workflows instances list my-workflow

关键点：继承 WorkflowEntrypoint，实现 run() 并使用 step 方法，在 wrangler.jsonc 中配置绑定。

步骤方法

step.do(name, config?, callback)：执行工作，返回可序列化值。允许 string、number、boolean、Array、Object、null；禁止 Function、Symbol、循环引用、undefined。
step.sleep(name, duration)：相对休眠，duration 可为毫秒数或字符串（second、minute、hour、day、week、month、year，接受复数形式）。
step.sleepUntil(name, timestamp)：休眠到指定 Date 或 UNIX 时间戳（毫秒）。
step.waitForEvent(name, { type, timeout? })：等待外部事件，默认超时 24 小时，最大 30 天；通过 instance.sendEvent() 发送事件。

WorkflowStepConfig

interface WorkflowStepConfig {
  retries?: {
    limit: number;
    delay: string | number;
    backoff?: 'constant' | 'linear' | 'exponential';
  };
  timeout?: string | number;
}

默认：{ retries: { limit: 5, delay: 10000, backoff: 'exponential' }, timeout: '10 minutes' }。

适用场景

需要分步执行、可重试、可休眠的长时间任务。
需要等待外部事件（如支付回调、用户提交）再继续的流程。
需要状态持久化、在重启或重试后保持一致性的工作流。

限制与已知问题

2025 年限制：最大步骤数 1,024；每步状态持久化 1MB（每实例 100MB–1GB）；事件负载 1MB；CPU 时间最大 5 分钟。等待中的实例不计入并发；保留期 3–30 天；子请求 50–1,000。

该技能记录了 12 个已知错误及预防方案，包括：

本地开发中 waitForEvent 超时后跳过事件（仅 wrangler dev，生产正常）。
getPlatformProxy() 不支持 Workflow 绑定。
本地开发中立即重定向后工作流实例丢失。
Vitest 测试在 CI 环境不可靠。
本地开发未实现 instance.restart() 与 terminate()。
I/O 必须放在 step.do() 回调内。
NonRetryableError 在开发与生产行为不同，需提供消息。
休眠后内存状态丢失，只能使用 step.do() 返回值。
非确定性步骤名破坏缓存，需使用静态名称。
在 step.do() 外使用 Promise.race/any 导致不一致。
重启时副作用重复，需放入 step.do()。
非幂等操作可能重复，需加存在性检查。

最新版本：wrangler@4.58.0，@cloudflare/workers-types@4.20260109.0。