⚡

Cloudflare工作流开发 cloudflare-workflows

Cloudflare工作流开发技能是指在Cloudflare云平台上设计、实现和管理长期运行的工作流服务。它支持多步骤自动化流程，包括自动重试、状态持久化、事件驱动触发等，适用于服务器less应用、微服务编排、任务调度等场景。关键词：Cloudflare Workflows、云工作流、服务器less、自动化、微服务、长期执行、事件驱动、状态持久化。

Serverless 0 次安装 0 次浏览 更新于 3/7/2026

name: cloudflare-workflows description: Cloudflare Workflows 用于持久长期执行。用于多步骤工作流、重试、状态持久化，或遇到 NonRetryableError、执行失败错误。

关键词：cloudflare workflows、工作流工人、持久执行、工作流步骤、WorkflowEntrypoint、step.do、step.sleep、工作流重试、NonRetryableError、工作流状态、wrangler workflows、工作流事件、长期任务、step.sleepUntil、step.waitForEvent、工作流绑定 license: MIT metadata: version: “3.0.0” wrangler_version: “4.50.0” workers_types_version: “4.20251126.0” last_verified: “2025-12-27” errors_prevented: 5 templates_included: 8 references_included: 8 agents_included: 3 commands_included: 4 scripts_included: 5

Cloudflare 工作流

状态: 生产就绪 ✅ | 最后验证: 2025-12-27 | 版本: 3.0.0

依赖项: cloudflare-worker-base（用于 Worker 设置）

内容: 快速开始 • 命令 • 代理 • 核心概念 • 关键规则 • 常见错误 • 常见模式 • 何时加载参考 • 限制

快速开始（10 分钟）

1. 创建工作流

使用 Cloudflare Workflows 启动模板：

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

您将获得:

  • WorkflowEntrypoint 类模板
  • 触发工作流的 Worker
  • 完整的 wrangler.jsonc 配置

2. 基本工作流结构

src/index.ts:

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

type Env = {
  MY_WORKFLOW: Workflow;
};

type Params = {
  userId: string;
  email: string;
};

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    const { userId, email } = event.payload;

    // 步骤 1：执行带有自动重试的工作
    const result = await step.do('process user', async () => {
      return { processed: true, userId };
    });

    // 步骤 2：等待下一部步骤
    await step.sleep('wait 1 hour', '1 hour');

    // 步骤 3：继续工作流
    await step.do('send email', async () => {
      return { sent: true, email };
    });

    return { completed: true, userId };
  }
}

// Worker 以触发工作流
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const instance = await env.MY_WORKFLOW.create({
      params: { userId: '123', email: 'user@example.com' }
    });

    return Response.json({
      id: instance.id,
      status: await instance.status()
    });
  }
};

模板: 见 templates/basic-workflow.ts 获取完整示例

3. 配置 wrangler.jsonc

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

模板: 见 templates/wrangler-workflows-config.jsonc

4. 部署

npm run deploy

命令

用于工作流开发的交互式斜杠命令：

命令 描述 使用时机
/workflow-setup 新工作流项目的完整向导 开始新项目，需要完整设置
/workflow-create 工作流类的快速脚手架 向现有项目添加工作流
/workflow-debug 带有错误模式的交互式调试 故障排除工作流问题
/workflow-test 本地和远程测试工作流 验证工作流行为

使用示例:

/workflow-setup   # 完整引导设置向导
/workflow-create  # 快速工作流脚手架
/workflow-debug   # 调试工作流问题
/workflow-test    # 测试工作流执行

代理

用于复杂工作流任务的自主代理：

代理 描述 触发器
workflow-debugger 自动检测并修复配置/运行时错误 “debug workflow”、“fix workflow errors”
workflow-optimizer 分析性能、成本和可靠性 “optimize workflow”、“improve performance”
workflow-setup-assistant 自主项目脚手架 “setup workflow”、“create first workflow”

关键能力:

  • 调试器: 6 阶段分析，自动修复 I/O 上下文、序列化、导出问题
  • 优化器: 成本分析、可靠性评分、可操作建议
  • 设置助手: 项目检测、自动脚手架、验证

脚本

scripts/ 目录中的自动化脚本：

脚本 目的
validate-workflow-config.sh 验证 wrangler.jsonc 配置
test-workflow.sh 创建和测试工作流实例
benchmark-workflow.sh 测量性能和成本
generate-workflow.sh 从模板搭建新工作流
check-workflow-limits.sh 根据 Cloudflare 限制验证

使用:

./scripts/validate-workflow-config.sh           # 检查配置
./scripts/test-workflow.sh my-workflow          # 测试工作流
./scripts/benchmark-workflow.sh my-workflow 10  # 基准测试 10 次运行
./scripts/generate-workflow.sh MyWorkflow       # 生成脚手架
./scripts/check-workflow-limits.sh src/workflows/my-workflow.ts

核心概念

WorkflowEntrypoint

每个工作流必须扩展 WorkflowEntrypoint：

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    // 工作流逻辑在此
  }
}

关键点:

  • Env: 环境绑定（KV、D1 等）
  • Params: 创建工作流实例时传递的类型化负载
  • event: 包含 id、payload、timestamp
  • step: 持久执行的方法

步骤方法

所有工作流工作必须在步骤中完成以确保持久性：

// step.do - 执行带有自动重试的工作
await step.do('step name', async () => {
  return { result: 'data' };
});

// step.sleep - 等待指定时长
await step.sleep('wait', '1 hour');

// step.sleepUntil - 等待直到时间戳
await step.sleepUntil('wait until', Date.now() + 3600000);

// step.waitForEvent - 等待外部事件
const event = await step.waitForEvent('payment received', 'payment.completed', {
  timeout: '30 minutes'
});

关键: 所有 I/O（fetch、KV、D1、R2）必须发生在 step.do() 回调内部！

参考: 见 references/workflow-patterns.md 获取所有模式

关键规则

始终做 ✅

✅ 所有 I/O 在 step.do() 内部执行 - 持久性必需 ✅ 使用命名步骤 - 便于调试 ✅ 从步骤返回 JSON 可序列化数据 - 状态持久性必需 ✅ 使用 step.sleep() 进行延迟 - 不要使用 setTimeout() ✅ 显式处理错误 - 在步骤回调中使用 try/catch ✅ 对永久故障使用 NonRetryableError - 停止重试

工作流模式: 见 references/workflow-patterns.md 获取：

  • 顺序工作流
  • 并行执行
  • 事件驱动工作流
  • 计划工作流
  • 人工介入工作流

永远不要做 ❌

❌ 永远不要在 step.do() 外部执行 I/O - 会导致 “I/O 上下文” 错误 ❌ 永远不要使用 setTimeout() 或 setInterval() - 改用 step.sleep() ❌ 永远不要返回不可序列化数据 - 函数、Promise 等会失败 ❌ 永远不要硬编码超时 - 使用工作流配置 ❌ 永远不要忽略 NonRetryableError - 表示永久故障

前 5 名关键错误

错误 #1: I/O 上下文错误 ⚠️

错误:

无法代表不同请求执行 I/O

原因: 在 step.do() 回调外部执行 I/O

解决方案:

// ❌ 错误
const data = await fetch('https://api.example.com');
await step.do('use data', async () => {
  return data; // 错误！
});

// ✅ 正确
const data = await step.do('fetch data', async () => {
  const response = await fetch('https://api.example.com');
  return await response.json();
});

错误 #2: 序列化错误

错误:

无法序列化工作流状态

原因: 从步骤返回非 JSON 可序列化数据

解决方案:

// ❌ 错误
await step.do('process', async () => {
  return { fn: () => {} }; // 函数不可序列化
});

// ✅ 正确
await step.do('process', async () => {
  return { result: 'data' }; // JSON 可序列化
});

错误 #3: NonRetryableError 未抛出

错误: 工作流在永久故障上无限重试

解决方案:

import { NonRetryableError } from 'cloudflare:workers';

await step.do('validate', async () => {
  if (!isValid) {
    throw new NonRetryableError('Invalid input'); // 停止重试
  }
  return { valid: true };
});

错误 #4: WorkflowEvent 未找到

错误:

WorkflowEvent 'payment.completed' 未找到

原因: waitForEvent 和触发之间的事件名称不匹配

解决方案:

// 工作流等待事件
const event = await step.waitForEvent('wait payment', 'payment.completed', {
  timeout: '30 minutes'
});

// 触发事件时使用完全相同名称
await instance.trigger('payment.completed', { amount: 100 });

错误 #5: 工作流执行失败

错误:

工作流执行失败：步骤超时超出

原因: 步骤超出最大 CPU 时间（30 秒）

解决方案:

// ❌ 错误
await step.do('long task', async () => {
  for (let i = 0; i < 1000000; i++) {
    // 长计算
  }
});

// ✅ 正确 - 分解为更小步骤
for (let i = 0; i < 100; i++) {
  await step.do(`batch ${i}`, async () => {
    // 处理批次
  });
}

所有问题: 见 references/common-issues.md 获取完整文档

常见模式

顺序工作流

基本工作流，步骤按顺序执行。每个步骤在下一个开始前完成。

使用案例: 订单处理、用户入门、数据管道

加载 templates/basic-workflow.ts 获取完整示例

计划工作流

使用 step.sleep() 或 step.sleepUntil() 在步骤之间有延迟的工作流。

使用案例: 提醒序列、计划任务、延迟通知

加载 templates/scheduled-workflow.ts 获取完整示例

事件驱动工作流

使用 step.waitForEvent() 等待外部事件。始终设置超时并使用 NonRetryableError 处理：

const payment = await step.waitForEvent('wait payment', 'payment.completed', {
  timeout: '30 minutes'
});
if (!payment) throw new NonRetryableError('Payment timeout');

加载 templates/workflow-with-events.ts 获取完整示例

带有重试的工作流

使用 NonRetryableError 处理永久故障（如 404），常规 Error 处理临时故障（如 5xx）：

const data = await step.do('fetch', async () => {
  const response = await fetch(url);
  if (!response.ok) {
    if (response.status === 404) throw new NonRetryableError('Not found');
    throw new Error('Temporary failure'); // 将重试
  }
  return await response.json();
});

加载 templates/workflow-with-retries.ts 获取带有重试配置的完整示例

触发工作流

来自 Worker: 通过 env.MY_WORKFLOW.create() 创建实例，使用 instance.status() 获取状态，使用 instance.trigger() 触发事件。

来自 Cron: 使用 scheduled() 处理程序按计划创建工作流实例。

加载 templates/worker-trigger.ts 获取完整 Worker 触发示例 加载 templates/scheduled-workflow.ts 获取完整 Cron 触发示例

何时加载参考

references/common-issues.md: 遇到 I/O 上下文、序列化、NonRetryableError、事件命名或超时错误时；故障排除工作流失败。

references/workflow-patterns.md: 构建复杂编排、审批工作流、幂等性模式或断路器模式时。

references/wrangler-commands.md: 需要 CLI 命令管理工作流实例、调试卡住的工作流或监控生产环境时。

references/production-checklist.md: 准备部署，需要部署前验证、设置监控/错误处理时。

references/limits-quotas.md: 达到实例/步骤/负载限制时，优化成本，设计高容量工作流时。

references/2025-features.md: 使用事件系统、增强重试、实例生命周期控制或最新 Workflows 功能时。

references/metrics-analytics.md: 设置监控、自定义指标、外部日志集成或工作流仪表板时。

references/troubleshooting.md: 复杂调试场景、卡住实例、系统诊断、性能问题时。

templates/: basic-workflow.ts（顺序）、scheduled-workflow.ts（延迟/睡眠）、workflow-with-events.ts（waitForEvent）、workflow-with-retries.ts（自定义重试）、worker-trigger.ts（Worker 触发）、wrangler-workflows-config.jsonc（Wrangler 配置）、parallel-execution-workflow.ts（批处理并行处理）、circuit-breaker-workflow.ts（弹性外部调用）

Wrangler 命令

关键命令: wrangler workflows create、wrangler workflows instances list/describe/terminate、wrangler deploy

加载 references/wrangler-commands.md 获取包含所有工作流管理命令、监控工作流和调试卡住实例的完整 CLI 参考。

状态持久化

工作流自动在步骤间持久化状态。无需手动状态管理：

export class StatefulWorkflow extends WorkflowEntrypoint {
  async run(event, step) {
    // 步骤 1 的结果自动持久化
    const result1 = await step.do('step 1', async () => {
      return { data: 'value' };
    });

    // 即使工作流在此处崩溃，步骤 1 不会重新运行
    await step.sleep('wait', '1 hour');

    // 步骤 2 可以使用步骤 1 的结果（睡眠后仍可用）
    await step.do('step 2', async () => {
      console.log(result1.data); // 'value' - 已持久化！
    });
  }
}

关键点:

  • 步骤结果自动持久化
  • 已完成步骤永不重新运行（即使在崩溃/重启后）
  • 状态在整个工作流生命周期可用

限制

资源 限制
步骤 CPU 时间 30 秒
工作流持续时间 30 天
步骤负载大小 128 KB
工作流负载大小 128 KB
每个工作流的步骤数 1,000
并发实例数 每个工作流 1,000
事件负载大小 128 KB

解决方法:

  • 大数据：存储在 KV/R2 中，在步骤中传递键
  • 长 CPU：分解为更小步骤
  • 许多步骤：考虑子工作流

定价

  • 持续时间: $0.02 每百万 GB-s（与 Workers 相同）
  • 请求: $0.15 每百万（工作流创建 + 步骤执行）
  • 状态存储: 包含（无额外成本）
  • 睡眠: 免费（睡眠期间无 CPU 使用）

示例成本（100 万工作流运行）：

  • 每个 5 步 = 500 万请求 = $0.75
  • 每步 10ms = 50GB-s = $0.001
  • 总计: 约 $0.75 每百万工作流

故障排除

“I/O 上下文” 错误

解决方案: 将所有 I/O 移动到 step.do() 回调中 → 见 references/common-issues.md #1

“序列化错误”

解决方案: 从步骤只返回 JSON 可序列化数据 → 见 references/common-issues.md #2

工作流无限重试

解决方案: 对永久故障抛出 NonRetryableError → 见 references/common-issues.md #3

“WorkflowEvent 未找到”

解决方案: 确保事件名称完全匹配 → 见 references/common-issues.md #4

“步骤超时超出”

解决方案: 将长计算分解为更小步骤 → 见 references/common-issues.md #5

生产清单

10 点部署前清单: I/O 上下文隔离、JSON 序列化、NonRetryableError 使用、事件名称一致性、步骤时长限制、错误处理、重试配置、超时、工作流命名和监控。

加载 references/production-checklist.md 获取带有详细解释、代码示例、验证步骤和部署工作流的完整清单。

官方文档

工作流: https://developers.cloudflare.com/workflows/ • API 参考: https://developers.cloudflare.com/workflows/reference/ • 示例: https://developers.cloudflare.com/workflows/examples/ • 博客: https://blog.cloudflare.com/cloudflare-workflows/