Cloudflare Workflows API 完整实战指南：Step 编排、实例管理与多端触发（Workers API 深度解析）

Cloudflare Workflows API 完整实战指南：Step 编排、实例管理与多端触发（Workers API 深度解析）

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本篇技术指南以 Skills 仓库中skills/.curated/cloudflare-deploy技能所收录的 Cloudflare Workflows API 参考文档（api.md）为核心骨架，系统讲解 Cloudflare Workflows 的 Step 级编排 API、实例生命周期管理、多入口触发方式、错误处理与类型约束，并结合仓库内配套的configuration.md、patterns.md 与 gotchas.md 补全配置、限额与调试细节。读完本文，你将能够基于 Workers 运行时编写可自动重试、可持久化状态、可等待人工审批与外部事件的长时运行多步任务，并掌握 Wrangler CLI 与 REST API 两种实例运维方式。

一、Cloudflare Workflows 与 API 文档定位

Cloudflare Workflows 是一种"持久化多步应用"（durable multi-step application）方案，适用于需要在边缘执行长时运行任务的场景。正如 README.md 所归纳的，它的核心能力包括：按步链式执行并自动重试、在步骤之间持久化状态（分钟级到周级）、失败不丢失进度、等待外部事件/审批、以及不消耗计算资源的休眠（sleep）。在 SKILL.md 的决策树中，Workflows 被定位为"Long-running multi-step jobs"（长时运行的多步任务）的推荐方案，与 Durable Objects（有状态协调）、Queues（消息驱动）形成互补——后两者的参考同样收录在 durable-objects 与 queues 目录中。

核心概念只有四个：

• Workflow：继承WorkflowEntrypoint并实现run方法的类；
• Instance：一次独立的执行，拥有唯一 ID 与独立状态；
• Step：通过step.do()定义的最小可独立重试单元（API 调用、数据库查询、AI 调用等）；
• State：由 step 的返回值持久化，step 名称即缓存键。

二、Step 级 API：编排的最小单元

step对象在run(event, step)中作为第二参数注入，是 Workflows 编程模型的核心。api.md 给出了四类 Step API。

2.1 step.do()：执行一个步骤

step.do()用于注册一个可持久化、可重试的步骤。它有两种重载：只传步骤名与执行函数，或再传一个配置对象（retries、timeout）：

// step.do() const result = await step.do('step name', async () => { /* logic */ }); const result = await step.do('step name', { retries, timeout }, async () => {});

结合 configuration.md 的"Step Configuration"一节，retries与timeout的完整可配置项如下：

await step.do('api call', { retries: { limit: 10, // 默认: 5，或设置为 Infinity delay: '10 seconds', // 默认: 10000ms backoff: 'exponential' // constant | linear | exponential 三种退避策略 }, timeout: '30 minutes' // 单次尝试的超时（默认 10 分钟） }, async () => { const res = await fetch('https://api.example.com/data'); if (!res.ok) throw new Error('Failed'); return res.json(); });

要点说明：

• backoff 退避策略：constant（固定间隔）、linear（线性递增）、exponential（指数递增），按失败次数放大重试间隔；
• timeout 语义：是"单次尝试"的超时，而非整个步骤的总预算；
• 步骤的返回值会被自动持久化，供后续步骤使用——这也决定了"step 名 + 返回值"共同构成缓存键的机制。

除单步执行外，configuration.md 还给出了三种常见的步骤组织方式：

并行步骤（Parallel Steps）——用Promise.all并发执行相互独立的步骤：

const [user, settings] = await Promise.all([ step.do('fetch user', async () => this.env.KV.get(`user:${id}`)), step.do('fetch settings', async () => this.env.KV.get(`settings:${id}`)) ]);

条件步骤（Conditional Steps）——分支必须基于步骤输出等确定性值，禁止在步骤外使用Date.now()这类非确定逻辑：

const config = await step.do('fetch config', async () => this.env.KV.get('flags', { type: 'json' }) ); // ✅ 确定性分支（基于 step 输出） if (config.enableEmail) { await step.do('send email', async () => sendEmail()); } // ❌ 非确定性分支（Date.now 在 step 外使用）——BAD if (Date.now() > deadline) { /* BAD */ }

动态步骤（Loops）——根据前序步骤的输出动态生成步骤：

const files = await step.do('list files', async () => this.env.BUCKET.list()); for (const file of files.objects) { await step.do(`process ${file.key}`, async () => { const obj = await this.env.BUCKET.get(file.key); return processData(await obj.arrayBuffer()); }); }

注意：动态步骤名必须由确定性的输入（如file.key）推导，才能保证重放时可复用已持久化的结果。

2.2 step.sleep() / step.sleepUntil()：时间调度

sleep支持相对时间（字符串或毫秒数），sleepUntil支持绝对时间（时间戳或Date对象）：

// step.sleep() await step.sleep('description', '1 hour'); await step.sleep('description', 5000); // ms // step.sleepUntil() await step.sleepUntil('description', Date.parse('2024-12-31'));

Sleep 的完整能力（见 api.md "Sleep & Scheduling" 一节）：

// 相对 await step.sleep('wait 1 hour', '1 hour'); await step.sleep('wait 30 days', '30 days'); await step.sleep('wait 5s', 5000); // ms // 绝对 await step.sleepUntil('launch date', Date.parse('24 Oct 2024 13:00:00 UTC')); await step.sleepUntil('deadline', new Date('2024-12-31T23:59:59Z'));

两个关键语义：

• 时间单位：支持 second、minute、hour、day、week、month、year，单次上限365 天；
• 不计并发：处于休眠状态的实例不计入并发实例数限额（详见下文限额表），因此可以支撑"百万级"的等待型工作流。

2.3 step.waitForEvent()：等待外部事件

waitForEvent用于阻塞等待外部投递的事件（如 webhook 回调、人工审批）：

const data = await step.waitForEvent<PayloadType>('wait', {event: 'webhook-type', timeout: '24h'}); // 默认 24h，最大 365d try { const event = await step.waitForEvent('wait', { event: 'approval', timeout: '1h' }); } catch (e) { /* Timeout */ }

要点：

• 默认超时24 小时，最大365 天；
• 超时会抛出异常，必须用try-catch包裹以优雅降级（例如自动拒绝）；
• 事件的投递方使用instance.sendEvent()（见下文"实例管理"），type字段必须与waitForEvent中声明的事件类型一致。

三、实例管理（Instance Management）：完整生命周期 API

每个 Workflow 实例是一次独立的执行，api.md 给出了从创建、查询到控制的完整 API。

3.1 创建实例：create()

// 单实例创建（id 可省略，省略时自动生成） const instance = await env.MY_WORKFLOW.create({id: crypto.randomUUID(), params: { userId: 'user123' }}); // 自定义保留期（默认：免费版 3 天，付费版 30 天） const instance = await env.MY_WORKFLOW.create({ id: crypto.randomUUID(), params: { userId: 'user123' }, retention: '30 days' // 覆盖默认保留期 });

id参数可选，省略时平台自动生成；显式传入时可使用crypto.randomUUID()保证唯一性。retention用于覆盖实例完成后数据的保留时长。

3.2 批量创建：createBatch()

// 批量创建（最多 100 个，幂等：已存在的 ID 会被跳过） const instances = await env.MY_WORKFLOW.createBatch([{id: 'user1', params: {name: 'John'}}, {id: 'user2', params: {name: 'Jane'}}]);

createBatch的幂等语义意味着同一批 ID 重复提交不会产生重复实例，适合从队列批量消费等场景。

3.3 查询与状态：get() / status()

const instance = await env.MY_WORKFLOW.get('instance-id'); const status = await instance.status(); // {status: 'queued' | 'running' | 'paused' | 'errored' | 'terminated' | 'complete' | 'waiting' | 'waitingForPause' | 'unknown', error?, output?}

status()返回的status字段覆盖了实例生命周期的全部状态：queued（排队）、running（运行中）、paused（已暂停）、errored（出错）、terminated（已终止）、complete（已完成）、waiting（等待中，如 sleep/waitForEvent）、waitingForPause（等待暂停）、unknown（未知）。此外还附带可选的error与output字段。

3.4 控制操作：pause / resume / terminate / restart

await instance.pause(); await instance.resume(); await instance.terminate(); await instance.restart();

四个控制方法分别对应暂停、恢复、终止与重启，与 Wrangler CLI 和 REST API 的对应命令一一对应（见下文）。

3.5 发送事件：sendEvent()

await instance.sendEvent({type: 'approval', payload: { approved: true }}); // type 必须与 waitForEvent 声明的事件类型一致

sendEvent用于向处于waiting状态的实例投递事件，唤醒其waitForEvent。type必须匹配waitForEvent中的事件声明，这是人工审批链路（Human-in-the-Loop）的关键一环。

四、触发工作流（Triggering Workflows）：四个入口

api.md 给出了四种触发方式：Worker 请求、Queue 消息、Cron 定时任务、以及另一个 Workflow。

4.1 从 Worker 触发（HTTP 入口）

export default { async fetch(req, env) { const instance = await env.MY_WORKFLOW.create({id: crypto.randomUUID(), params: { userId: 'user123' }}); return Response.json({ id: instance.id }); } };

这也是最常见的用法：HTTP 请求到来时创建实例，立即返回实例 ID，长时任务在后台运行。

4.2 从 Queue 触发（消息驱动）

export default { async queue(batch, env) { for (const msg of batch.messages) { await env.MY_WORKFLOW.create({id: `job-${msg.id}`, params: msg.body}); } } };

每条队列消息对应一个实例，ID 采用job-${msg.id}保证确定性，重试投递时不会重复创建。

4.3 从 Cron 触发（定时任务）

export default { async scheduled(event, env) { await env.CLEANUP_WORKFLOW.create({id: `cleanup-${Date.now()}`, params: { timestamp: event.scheduledTime }}); } };

定时调度器触发scheduled处理器，把event.scheduledTime作为参数传入工作流。

4.4 从另一个 Workflow 触发（非阻塞）

export class ParentWorkflow extends WorkflowEntrypoint<Env, Params> { async run(event, step) { const child = await step.do('start child', async () => await this.env.CHILD_WORKFLOW.create({id: `child-${event.instanceId}`, params: {}}) ); } }

父工作流通过 step 创建子工作流实例——注意这是非阻塞的，父流程不会等待子流程完成。patterns.md 中将其归纳为"Parent-Child Workflows"编排模式。

五、错误处理（Error Handling）：可重试与不可重试

api.md 详细给出了三类错误处理策略。

5.1 NonRetryableError：声明"不要重试"

import { NonRetryableError } from 'cloudflare:workers'; await step.do('validate', async () => { if (!event.params.paymentMethod) throw new NonRetryableError('Payment method required'); const res = await fetch('https://api.example.com/charge', { method: 'POST' }); if (res.status === 401) throw new NonRetryableError('Invalid credentials'); // 不要重试 if (!res.ok) throw new Error('Retryable failure'); // 普通 Error 会重试 return res.json(); });

语义区分非常关键：

• 抛出NonRetryableError→ 立即终止该步骤，不消耗重试次数（如参数缺失、凭证无效、业务校验失败）；
• 抛出普通Error→ 按retries配置自动重试（如瞬时网络故障、5xx）。

5.2 捕获错误并继续（Catching Errors）

try { await step.do('risky op', async () => { throw new NonRetryableError('Failed'); }); } catch (e) { await step.do('cleanup', async () => {}); }

用try-catch包裹可能失败的步骤，在 catch 分支执行补偿/清理逻辑，是"waitForEvent 超时降级"等模式的基础。

5.3 幂等性（Idempotency）：防止重试副作用

由于步骤失败后会自动重试，任何有副作用（扣款、发邮件、写库）的操作都必须保证幂等：

await step.do('charge', async () => { const sub = await fetch(`https://api/subscriptions/${id}`).then(r => r.json()); if (sub.charged) return sub; // 已扣款，直接返回，避免重复扣款 return await fetch(`https://api/subscriptions/${id}`, {method: 'POST', body: JSON.stringify({ amount: 10.0 })}).then(r => r.json()); });

即"check-then-execute"（先查后写）模式：执行前先检查操作是否已完成。gotchas.md 将"Idempotency Violation"列为高频错误——步骤操作不幂等会导致重试时重复扣款或重复动作。

六、类型约束（Type Constraints）：Rpc.Serializable<T>

Workflow 的Params与 step 的返回值都必须满足Rpc.Serializable<T>约束，即必须可被序列化传输与持久化：

// ✅ 合法类型 type ValidParams = { userId: string; count: number; tags: string[]; metadata: Record<string, unknown>; }; // ❌ 非法类型 type InvalidParams = { callback: () => void; // 函数不可序列化 symbol: symbol; // Symbol 不可序列化 circular: any; // 不允许循环引用 }; // Step 返回值遵循同样的规则 const result = await step.do('fetch', async () => { return { userId: '123', data: [1, 2, 3] }; // ✅ 普通对象 });

允许的类型包括 string、number、boolean、数组、普通对象（Record<string, unknown>）等 JSON 兼容结构；函数、Symbol、循环引用均不可用。由于状态是靠 step 返回值持久化的，大对象（超过 1 MiB）应存入 R2/KV 并只返回引用（见下文 Best Practices）。

七、参数传递（Parameters）：Worker 传入 → Workflow 消费

7.1 从 Worker 传入

const instance = await env.MY_WORKFLOW.create({ id: crypto.randomUUID(), params: { userId: 'user123', email: 'user@example.com' } });

7.2 在 Workflow 内访问

async run(event: WorkflowEvent<Params>, step: WorkflowStep) { const userId = event.params.userId; // 业务参数 const instanceId = event.instanceId; // 实例 ID const createdAt = event.timestamp; // 创建时间 }

event对象除了承载params业务参数外，还提供instanceId与timestamp，它们都是确定性的，可安全用于步骤命名。

7.3 通过 CLI 触发并传参

npx wrangler workflows trigger my-workflow '{"userId":"user123"}'

CLI 触发以 JSON 字符串形式传入参数，与编程方式创建的实例行为一致。

八、Wrangler CLI：实例运维命令全集

api.md 汇总了 Workflows 相关的全部 Wrangler 命令：

# 用官方模板初始化项目 npm create cloudflare@latest my-workflow -- --template "cloudflare/workflows-starter" # 部署 npx wrangler deploy # 列出工作流 npx wrangler workflows list # 触发（携带 JSON 参数） npx wrangler workflows trigger my-workflow '{"userId":"user123"}' # 列出实例 npx wrangler workflows instances list my-workflow # 查看实例详情 npx wrangler workflows instances describe my-workflow instance-id # 控制实例：暂停 / 恢复 / 终止 npx wrangler workflows instances pause/resume/terminate my-workflow instance-id

命令行工作流为：workflows list（找到工作流）→workflows instances list（找到实例）→instances describe（查看状态/错误/输出）→instances pause/resume/terminate（干预执行）。这些命令与 3.4 节编程式控制 API 一一对应，便于调试与运维。

九、REST API：脱离 CLI 的远程管理

对于自动化运维或第三方集成，Cloudflare 提供 Workflows REST API（api.cloudflare.com/client/v4）：

# 创建实例 curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances" \ -H "Authorization: Bearer {token}" \ -d '{"id":"custom-id","params":{"userId":"user123"}}' # 查询状态 curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/status" \ -H "Authorization: Bearer {token}" # 发送事件（唤醒 waitForEvent） curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/events" \ -H "Authorization: Bearer {token}" \ -d '{"type":"approval","payload":{"approved":true}}'

注意占位符：{account_id}为账号 ID，{workflow_name}为 wrangler.jsonc 中配置的工作流名，{token}为具有 Workflows 权限的 API Token。三个端点分别对应创建实例、查询状态与发送事件，与编程式 API 功能对齐。

十、配套文档联动：配置、限额与实战模式

api.md 末尾链接了同一参考集的另外两份文档，它们与本 API 指南形成完整的知识闭环。

10.1 配置要点（configuration.md）

在 configuration.md 中，工作流在wrangler.jsonc中声明：

{ "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2025-01-01", // 新项目使用当前日期 "observability": { "enabled": true // 启用 Workflows 仪表盘 + 结构化日志 }, "workflows": [ { "name": "my-workflow", // 工作流名 "binding": "MY_WORKFLOW", // env 绑定名 "class_name": "MyWorkflow" // TS 类名 // "script_name": "other-worker" // 跨脚本调用时指向其他 Worker } ], "limits": { "cpu_ms": 300000 // 5 分钟上限（默认 30s） } }

关键点：

• binding决定代码中env.MY_WORKFLOW的命名；
• script_name用于跨脚本绑定——Worker B 通过{"workflows": [{"name": "billing-workflow", "binding": "BILLING", "script_name": "billing-worker"}]}调用 Worker A 定义的工作流；
• 工作流内部通过this.env访问 KV、D1、R2、Workers AI、Vectorize 等全部绑定；
• Pages Functions 也可通过service_bindings触发工作流（functions/_middleware.ts中env.MY_WORKFLOW.create(...)）；
• 一个 Worker 可声明多个工作流，每个类独立继承WorkflowEntrypoint并拥有自己的Params类型。

10.2 限额速查（gotchas.md）

gotchas.md 给出了与本 API 直接相关的限额表：

注意：处于waiting状态（step.sleep/step.waitForEvent引起）的实例不计入并发实例数限制，因此可以支撑海量休眠中的工作流。

10.3 高频错误与调试（gotchas.md 精选）

同一份文档还总结了本 API 使用中的高频错误：

• "Step Timeout"：步骤执行超过默认 10 分钟或自定义超时。解法：设置step.do('long operation', {timeout: '30 minutes'}, ...)，或在 wrangler.jsonc 中提高 CPU 上限（最大 5 分钟 CPU 时间）；
• "waitForEvent Timeout"：事件未在超时内到达。解法：try-catch包裹并优雅降级；
• "Non-Deterministic Step Names"：步骤名使用Date.now()等动态值导致重放问题。解法：改用event.instanceId等确定值；
• "State Lost in Variables"：用模块级/局部变量存状态，休眠后丢失。解法：通过step.do()返回值持久化；
• "Large Step Returns Exceeding Limit"：step 返回值超过 1 MiB。解法：大对象存入 R2，仅返回引用{ key: 'r2-object-key' }；
• "Step Exceeded CPU Limit But Ran for < 30s"：混淆了 CPU 时间与墙钟时间。网络请求、数据库查询、休眠不计入 CPU 时间；
• "Instance ID Collision"：复用实例 ID 导致冲突。解法：使用\${userId}-${Date.now()}`` 等唯一 ID；
• "Instance Data Disappeared After Completion"：实例在保留期（免费 3 天 / 付费 30 天）后自动删除。解法：完成前将关键数据导出到 KV/R2/D1；
• "Missing await on step.do"：遗漏await造成 fire-and-forget。解法：始终await step.do(...)。

10.4 实战模式（patterns.md）

patterns.md 给出了可直接套用的完整工作流：图像处理流水线（R2 读取 → Workers AI 生成描述 → waitForEvent 审批 → 发布）、用户生命周期（欢迎邮件 → sleep 7 天 → 检查转化 → 到期提醒）、数据管道（extract → transform → store → load 四步）、人工审批（Human-in-the-Loop，waitForEvent + 超时自动拒绝）等。其中"人工审批"模式完整演示了本 API 的核心组合：

export class ApprovalWorkflow extends WorkflowEntrypoint<Env, Params> { async run(event, step) { await step.do('create approval', async () => await this.env.DB.prepare('INSERT INTO approvals (id, user_id, status) VALUES (?, ?, ?)') .bind(event.instanceId, event.params.userId, 'pending').run()); try { const approval = await step.waitForEvent<{ approved: boolean }>('wait for approval', { event: 'approval-response', timeout: '48h' }); if (approval.approved) { await step.do('process approval', async () => {}); } else { await step.do('handle rejection', async () => {}); } } catch (e) { await step.do('auto reject', async () => await this.env.DB.prepare('UPDATE approvals SET status = ? WHERE id = ?') .bind('auto-rejected', event.instanceId).run()); } } }

该模式完整串联了本文讲解的三类 API：step.do()持久化状态、waitForEvent阻塞等待、sendEvent（由外部审批系统调用）唤醒、try-catch处理超时降级。

十一、编排模式与测试（patterns.md 补充）

11.1 四种编排模式

patterns.md 归纳了四种高阶编排模式，全部基于本文的 API 组合实现：

• Fan-Out（扇出）：step.do('list', ...)列出对象后，用Promise.all对每个对象并发执行step.do(\process ${i}`, ...)`；
• Parent-Child Workflows（父子工作流）：父流程 step 内env.CHILD_WORKFLOW.create(...)非阻塞地启动子流程；
• Race Pattern（竞速）：Promise.race让多个 step 竞争，取先完成者；
• Scheduled Workflow Chain（定时链）：Cron 触发 +step.sleep('wait 7 days', '7 days')实现"每日任务 + 7 天后跟进"的递归式调度。

11.2 测试工作流：Introspection API

patterns.md 还提供了基于@cloudflare/vitest-pool-workers的测试方案，可直接对实例进行内省与打桩：

// vitest.config.ts import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config'; export default defineWorkersConfig({ test: { poolOptions: { workers: { wrangler: { configPath: './wrangler.jsonc' } } } } });

import { introspectWorkflowInstance } from 'cloudflare:test'; const instance = await env.MY_WORKFLOW.create({ params: { userId: '123' } }); const introspector = await introspectWorkflowInstance(env.MY_WORKFLOW, instance.id); // 等待某一步完成 const result = await introspector.waitForStepResult({ name: 'fetch user', index: 0 }); // 打桩：替换某一步的返回结果 await introspector.modify(async (m) => { await m.mockStepResult({ name: 'api call' }, { mocked: true }); });

waitForStepResult与mockStepResult让你可以在不真实调用外部 API 的前提下验证步骤编排逻辑。

11.3 最佳实践清单（DO / DON'T）

✅ DO：

1. 步骤保持粒度：一个 API 调用一个 step（除非能证明幂等）；
2. 幂等性：先查后执行，使用幂等键；
3. 确定性的步骤名：使用静态名或基于 step 输出的名字；
4. 返回状态：通过 step 返回值持久化，而非变量；
5. 始终await step.do()，避免悬空的 Promise；
6. 确定性条件分支：基于event.payload或 step 输出；
7. 大对象外置存储：超过 1 MiB 存入 R2/KV，仅返回引用；
8. 批量创建：多实例用createBatch()。

❌ DON'T：

1. 单个巨型 step——破坏持久化与重试控制；
2. 把状态放在 step 之外——休眠后会丢失；
3. 修改事件——事件不可变，应返回新状态；
4. 在 step 之外使用Math.random()、Date.now()等非确定逻辑；
5. 在 step 之外做副作用——重启后可能重复执行；
6. 使用非确定性的步骤名——会破坏结果缓存；
7. 忽略超时——waitForEvent会抛异常，务必 try-catch；
8. 复用实例 ID——保留期内必须唯一。

十二、结语：API 全景回顾

回顾 api.md 的完整脉络，Cloudflare Workflows API 由四层构成：

• Step 层：step.do/step.sleep/step.sleepUntil/step.waitForEvent，负责编排、调度与事件等待；
• 实例层：create/createBatch/get/status/pause/resume/terminate/restart/sendEvent，负责全生命周期管理；
• 触发层：Worker fetch、Queue、Cron、父工作流四种入口；
• 运维层：Wrangler CLI 与 REST API 双通道，覆盖创建、查询、控制与事件投递。

配合仓库内的 configuration.md（配置与绑定）、patterns.md（实战模式与测试）与 gotchas.md（限额与调试），即可在 Workers 生态中构建可靠的长时运行多步应用。

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills