Cloudflare Workflows 完整指南：生产就绪的服务器端工作流解决方案

cloudflare-workflows by jezweb/claude-skills

341 周安装量

650 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/jezweb/claude-skills --skill cloudflare-workflows

自动化云服务开发运维

🇨🇳中文介绍

Cloudflare Workflows

状态：生产就绪 ✅（自 2025 年 4 月起 GA） 最后更新：2026-01-09 依赖项：cloudflare-worker-base（用于 Worker 设置） 最新版本：wrangler@4.58.0, @cloudflare/workers-types@4.20260109.0

近期更新（2025 年）：

2025 年 4 月：Workflows GA 发布 - waitForEvent API、Vitest 测试、CPU 时间指标、4,500 个并发实例
2025 年 10 月：实例创建速度提升 10 倍（100/秒），并发数增加到 10,000
2025 年限额：最大步骤数 1,024，状态持久化 1MB/步（每个实例 100MB-1GB），事件负载 1MB，CPU 时间最长 5 分钟
测试：cloudflare:test 模块，包含 introspectWorkflowInstance、disableSleeps、mockStepResult、mockEvent 修饰符
平台：等待中的实例不计入并发数，保留期 3-30 天，子请求 50-1,000

快速开始（5 分钟）

# 1. 创建项目脚手架
npm create cloudflare@latest my-workflow -- --template cloudflare/workflows-starter --git --deploy false
cd my-workflow

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

# 3. 创建工作流 (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 */ });
  }
}

# 4. 部署和测试
npm run deploy
npx wrangler workflows instances list my-workflow

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

问题 #1：本地开发中 waitForEvent 超时后忽略事件

错误：在 waitForEvent() 超时后发送的事件在后续的 waitForEvent() 调用中被忽略环境：仅限本地开发（wrangler dev）- 在生产环境中正常工作来源：GitHub Issue #11740

原因：miniflare 中的一个 bug，已在生产环境中修复（2025 年 5 月），但未移植到本地模拟器。超时后，该实例的事件队列会损坏。

在生产/预发布环境中测试 waitForEvent 超时场景，而非本地开发
避免在预期会发生超时的情况下链式调用多个 waitForEvent()

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    for (let i = 0; i < 3; i++) {
      try {
        const evt = await step.waitForEvent(`wait-${i}`, {
          type: 'user-action',
          timeout: '5 seconds'
        });
        console.log(`Iteration ${i}: Received event`);
      } catch {
        console.log(`Iteration ${i}: Timeout`);
      }
    }
  }
}
// 在 wrangler dev 中：
// - 迭代 1：✅ 接收到事件
// - 迭代 2：⏱️ 超时（预期）
// - 迭代 3：❌ 未接收到事件（BUG - 事件已发送但被忽略）

状态：已知 bug，等待 miniflare 修复。

问题 #2：getPlatformProxy() 因 Workflow 绑定而失败

错误：MiniflareCoreError [ERR_RUNTIME_FAILURE]: The Workers runtime failed to start 消息：Worker 的绑定引用了具有命名入口点的服务，但该服务没有此入口点来源：GitHub Issue #9402

原因：来自 wrangler 包的 getPlatformProxy() 不支持 Workflow 绑定（类似于其处理 Durable Objects 的方式）。这会阻碍 Next.js 集成和本地 CLI 脚本。

选项 1：在使用 getPlatformProxy() 时注释掉 workflow 绑定
选项 2：为 CLI 脚本创建单独的、不包含 workflows 的 wrangler.cli.jsonc
选项 3：直接通过已部署的 worker 访问 workflow 绑定，而非通过代理

// 变通方案：为 CLI 脚本使用单独的配置 // wrangler.cli.jsonc（无 workflows） { "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2025-01-20" // workflows 被注释掉 }

// 在脚本中使用： import { getPlatformProxy } from 'wrangler'; const { env } = await getPlatformProxy({ configPath: './wrangler.cli.jsonc' });

状态：已知限制，计划修复（类似于 DOs 的方式过滤 workflows）。

问题 #3：立即重定向后 Workflow 实例丢失（本地开发）

错误：返回了实例 ID，但查询时显示 instance.not_found 环境：仅限本地开发（wrangler dev）- 在生产环境中正常工作来源：GitHub Issue #10806

原因：在 workflow.create() 之后立即返回重定向会导致请求在 workflow 初始化完成之前“软中止”（开发环境中的单线程执行）。

预防措施：使用 ctx.waitUntil() 确保 workflow 初始化在重定向前完成：

export default {
  async fetch(req: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const workflow = await env.MY_WORKFLOW.create({ params: { userId: '123' } });

    // ✅ 确保 workflow 初始化完成
    ctx.waitUntil(workflow.status());

    return Response.redirect('/dashboard', 302);
  }
};

状态：在最近的 wrangler 版本中已修复（2025 年 9 月后），但仍建议使用变通方案以确保兼容性。

问题 #4：Vitest 测试在 CI 环境中不可靠

错误：[vitest-worker]: Timeout calling "resolveId" 环境：CI/CD 流水线（GitLab、GitHub Actions）- 本地工作正常来源：GitHub Issue #10600

原因：@cloudflare/vitest-pool-workers 在 CI 容器中存在资源限制问题，对 workflow 测试的影响大于其他 worker 类型。

在 vitest 配置中增加 testTimeout：

export default defineWorkersConfig({ test: { testTimeout: 60_000 // 默认值：5000ms } });
检查 CI 资源限制（CPU/内存）
如果不测试存储隔离，请使用 isolatedStorage: false
对于关键 workflows，考虑测试已部署的实例而非使用 vitest

状态：已知问题，正在调查（内部：WOR-945）。

问题 #5：本地开发中未实现 Instance restart() 和 terminate()

错误：调用 instance.restart() 或 instance.terminate() 时出现 Error: Not implemented yet 环境：仅限本地开发（wrangler dev）- 在生产环境中工作来源：GitHub Issue #11312

原因：实例管理 API 尚未在 miniflare 中实现。此外，即使 workflow 处于休眠状态，实例状态仍显示为 running。

预防措施：在生产或预发布环境中测试实例生命周期管理（暂停/恢复/终止），直到本地开发支持添加为止。

const instance = await env.MY_WORKFLOW.get(instanceId);

// ❌ 在 wrangler dev 中失败
await instance.restart();    // 错误：尚未实现
await instance.terminate();  // 错误：尚未实现

// ✅ 在生产环境中工作

状态：已知限制，本地开发支持暂无时间表。

问题 #6：I/O 操作必须在 step.do() 回调内部进行

错误："Cannot perform I/O on behalf of a different request" 来源：Cloudflare 运行时行为

原因：尝试在一个请求上下文中使用来自另一个请求处理程序的 I/O 对象。

预防措施：始终在 step.do() 回调内部执行 I/O 操作：

// ❌ 错误 - I/O 在 step 外部
const response = await fetch('https://api.example.com/data');
const data = await response.json();

await step.do('use data', async () => {
  return data;  // 这将失败！
});

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

问题 #7：NonRetryableError 在开发与生产环境中的行为不同

错误：带有空消息的 NonRetryableError 在开发模式下会导致重试，但在生产环境中工作正常环境：开发环境特定的 bug 来源：GitHub Issue #10113

原因：空错误消息在 miniflare 和生产运行时之间的处理方式不同。

预防措施：始终为 NonRetryableError 提供消息：

// ❌ 在开发环境中重试，在生产环境中退出
throw new NonRetryableError('');

// ✅ 在两个环境中都退出
throw new NonRetryableError('Validation failed');

状态：已知问题，已记录变通方案。

问题 #8：休眠时内存中的状态丢失

错误：在 step.do() 外部声明的变量在休眠/休眠后重置为初始值来源：Cloudflare Workflows 规则

原因：当引擎检测到没有待处理的工作时，Workflows 会休眠。所有内存中的状态在休眠期间都会丢失。

预防措施：仅使用从 step.do() 返回的状态 - 其他所有内容都是临时的：

// ❌ 错误 - 内存变量在休眠时丢失
let counter = 0;
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    counter = await step.do('increment', async () => counter + 1);
    await step.sleep('wait', '1 hour'); // ← 在此处休眠，内存状态丢失
    console.log(counter); // ❌ 将是 0，而不是 1！
  }
}

// ✅ 正确 - 来自 step.do() 返回值的状态会持久化
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    const counter = await step.do('increment', async () => 1);
    await step.sleep('wait', '1 hour');
    console.log(counter); // ✅ 仍然是 1
  }
}

问题 #9：非确定性的步骤名称会破坏缓存

错误：步骤不必要地重新运行，性能下降来源：Cloudflare Workflows 规则

原因：步骤名称充当缓存键。使用 Date.now()、Math.random() 或其他非确定性值会导致每次运行都生成新的缓存键。

预防措施：使用静态的、确定性的步骤名称：

// ❌ 错误 - 非确定性步骤名称
await step.do(`fetch-data-${Date.now()}`, async () => {
  return await fetchExpensiveData();
});
// 每次执行都创建新的缓存键 → 步骤总是重新运行

// ✅ 正确 - 确定性步骤名称
await step.do('fetch-data', async () => {
  return await fetchExpensiveData();
});
// 相同的缓存键 → 在重启/重试时重用结果

问题 #10：在 step.do() 外部使用 Promise.race/any 会导致不一致

错误：不同的 Promise 在重启时解析，行为不一致来源：Cloudflare Workflows 规则

原因：步骤外部的非确定性操作在重启时会再次运行，可能导致不同的结果。

预防措施：将所有非确定性逻辑保持在 step.do() 内部：

// ❌ 错误 - 在 step 外部进行竞争
const fastest = await Promise.race([fetchA(), fetchB()]);
await step.do('use result', async () => fastest);
// 重启时：竞争再次运行，不同的 Promise 可能获胜

// ✅ 正确 - 在 step 内部进行竞争
const fastest = await step.do('fetch fastest', async () => {
  return await Promise.race([fetchA(), fetchB()]);
});
// 重启时：使用缓存结果，行为一致

问题 #11：副作用在重启时重复

错误：workflow 重启后出现重复的日志、指标或操作来源：Cloudflare Workflows 规则

原因：如果 workflow 在执行过程中重启，step.do() 外部的代码会执行多次。

预防措施：将日志记录、指标和其他副作用放在 step.do() 内部：

// ❌ 错误 - 副作用在 step 外部
console.log('Workflow started'); // ← 重启时记录多次
await step.do('work', async () => { /* work */ });

// ✅ 正确 - 副作用在 step 内部
await step.do('log start', async () => {
  console.log('Workflow started'); // ← 记录一次（已缓存）
});

问题 #12：非幂等操作可能重复

错误：步骤超时后出现重复扣款、重复数据库写入来源：Cloudflare Workflows 规则

原因：步骤会单独重试。如果 API 调用成功但步骤在返回之前超时，重试将再次调用 API。

预防措施：使用存在性检查来保护非幂等操作：

// ❌ 错误 - 未检查即扣款
await step.do('charge', async () => {
  return await stripe.charges.create({ amount: 1000, customer: customerId });
});
// 如果步骤在扣款成功后超时，重试会再次扣款！

// ✅ 正确 - 首先检查是否存在扣款记录
await step.do('charge', async () => {
  const existing = await stripe.charges.list({ customer: customerId, limit: 1 });
  if (existing.data.length > 0) return existing.data[0]; // 幂等
  return await stripe.charges.create({ amount: 1000, customer: customerId });
});

step.do() - 执行工作

step.do<T>(name: string, config?: WorkflowStepConfig, callback: () => Promise<T>): Promise<T>

name - 步骤名称（用于可观测性）
config（可选）- 重试配置（重试次数、超时、退避）
callback - 执行工作的异步函数

返回： 回调函数返回的值（必须是可序列化的）

const result = await step.do('call API', { retries: { limit: 10, delay: '10s', backoff: 'exponential' }, timeout: '5 min' }, async () => {
  return await fetch('https://api.example.com/data').then(r => r.json());
});

关键点 - 序列化：

✅ 允许：字符串、数字、布尔值、数组、对象、null
❌ 禁止：函数、Symbol、循环引用、undefined
如果返回值不可 JSON 序列化，则抛出错误

step.sleep() - 相对休眠

step.sleep(name: string, duration: WorkflowDuration): Promise<void>

name - 步骤名称
duration - 数字（毫秒）或字符串："second"、"minute"、"hour"、"day"、"week"、"month"、"year"（接受复数形式）

await step.sleep('wait 5 minutes', '5 minutes');
await step.sleep('wait 1 hour', '1 hour');
await step.sleep('wait 2 days', '2 days');
await step.sleep('wait 30 seconds', 30000);  // 毫秒

注意： 恢复 workflows 的优先级高于新实例。休眠不计入步骤限制。

step.sleepUntil() - 休眠到特定日期

step.sleepUntil(name: string, timestamp: Date | number): Promise<void>

name - 步骤名称
timestamp - Date 对象或 UNIX 时间戳（毫秒）

await step.sleepUntil('wait for launch', new Date('2025-12-25T00:00:00Z'));
await step.sleepUntil('wait until time', Date.parse('24 Oct 2024 13:00:00 UTC'));

step.waitForEvent() - 等待外部事件（GA 于 2025 年 4 月）

step.waitForEvent<T>(name: string, options: { type: string; timeout?: string | number }): Promise<T>

name - 步骤名称
options.type - 要匹配的事件类型
options.timeout（可选）- 最大等待时间（默认：24 小时，最大：30 天）

返回： 通过 instance.sendEvent() 发送的事件负载

export class PaymentWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    await step.do('create payment', async () => { /* Stripe API */ });

    const webhookData = await step.waitForEvent<StripeWebhook>(
      'wait for payment confirmation',
      { type: 'stripe-webhook', timeout: '1 hour' }
    );

    if (webhookData.status === 'succeeded') {
      await step.do('fulfill order', async () => { /* fulfill */ });
    }
  }
}

// Worker 向 workflow 发送事件
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    if (req.url.includes('/webhook/stripe')) {
      const instance = await env.PAYMENT_WORKFLOW.get(instanceId);
      await instance.sendEvent({ type: 'stripe-webhook', payload: await req.json() });
      return new Response('OK');
    }
  }
};

try {
  const event = await step.waitForEvent('wait for user', { type: 'user-submitted', timeout: '10 minutes' });
} catch (error) {
  await step.do('send reminder', async () => { /* reminder */ });
}

interface WorkflowStepConfig {
  retries?: {
    limit: number;          // 最大尝试次数（允许 Infinity）
    delay: string | number; // 重试之间的延迟
    backoff?: 'constant' | 'linear' | 'exponential';
  };
  timeout?: string | number; // 每次尝试的最长时间
}

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

// 常量：30s, 30s, 30s
{ retries: { limit: 3, delay: '30 seconds', backoff: 'constant' } }

// 线性：1m, 2m, 3m, 4m, 5m
{ retries: { limit: 5, delay: '1 minute', backoff: 'linear' } }

// 指数（推荐）：10s, 20s, 40s, 80s, 160s
{ retries: { limit: 10, delay: '10 seconds', backoff: 'exponential' }, timeout: '5 minutes' }

// 无限重试
{ retries: { limit: Infinity, delay: '1 minute', backoff: 'exponential' } }

// 无重试
{ retries: { limit: 0 } }

强制 workflow 立即失败而不重试：

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

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    await step.do('validate input', async () => {
      if (!event.payload.userId) {
        throw new NonRetryableError('userId is required');
      }

      // 验证用户是否存在
      const user = await this.env.DB.prepare(
        'SELECT * FROM users WHERE id = ?'
      ).bind(event.payload.userId).first();

      if (!user) {
        // 终止性错误 - 重试无济于事
        throw new NonRetryableError('User not found');
      }

      return user;
    });
  }
}

何时使用 NonRetryableError：

✅ 身份验证/授权失败
✅ 不会改变的无效输入
✅ 资源不存在（404）
✅ 验证错误
❌ 网络故障（应重试）
❌ 速率限制（应使用退避重试）
❌ 临时服务中断（应重试）

捕获错误以继续 Workflow

通过捕获可选步骤错误来防止 workflow 失败：

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    await step.do('process payment', async () => { /* critical */ });

    try {
      await step.do('send email', async () => { /* optional */ });
    } catch (error) {
      await step.do('log failure', async () => {
        await this.env.DB.prepare('INSERT INTO failed_emails VALUES (?, ?)').bind(event.payload.userId, error.message).run();
      });
    }

    await step.do('update status', async () => { /* continues */ });
  }
}

let result;
try {
  result = await step.do('call primary API', async () => await callPrimaryAPI());
} catch {
  result = await step.do('call backup API', async () => await callBackupAPI());
}

配置绑定（wrangler.jsonc）：

{
  "workflows": [{
    "name": "my-workflow",
    "binding": "MY_WORKFLOW",
    "class_name": "MyWorkflow",
    "script_name": "workflow-worker"  // 如果 workflow 在不同的 Worker 中
  }]
}

从 Worker 触发：

const instance = await env.MY_WORKFLOW.create({ params: { userId: '123' } });
return Response.json({ id: instance.id, status: await instance.status() });

const instance = await env.MY_WORKFLOW.get(instanceId);
const status = await instance.status();  // { status: 'running'|'complete'|'errored'|'queued', error, output }
await instance.sendEvent({ type: 'user-action', payload: { action: 'approved' } });
await instance.pause();
await instance.resume();
await instance.terminate();

Workflows 自动持久化从 step.do() 返回的状态：

✅ 可序列化：

基本类型：string、number、boolean、null
数组、对象、嵌套结构

❌ 不可序列化：

函数、Symbol、循环引用、undefined、类实例

// ✅ 正确
const result = await step.do('fetch data', async () => ({
  users: [{ id: 1, name: 'Alice' }],
  timestamp: Date.now(),
  metadata: null
}));

// ❌ 错误 - 函数不可序列化
const bad = await step.do('bad', async () => ({ data: [1, 2, 3], transform: (x) => x * 2 }));  // 抛出错误！

跨步骤访问状态：

const userData = await step.do('fetch user', async () => ({ id: 123, email: 'user@example.com' }));
const orderData = await step.do('create order', async () => ({ userId: userData.id, orderId: 'ORD-456' }));
await step.do('send email', async () => sendEmail({ to: userData.email, subject: `Order ${orderData.orderId}` }));

内置指标（2025 年增强）

Workflows 自动跟踪：

实例状态：queued、running、complete、errored、paused、waiting
步骤执行：开始/结束时间、持续时间、成功/失败
重试历史：尝试次数、错误、延迟
休眠状态：workflow 何时唤醒
输出：来自步骤和 run() 的返回值
CPU 时间（GA 于 2025 年 4 月）：每个实例的活动处理时间，用于计费洞察

在仪表板中查看指标

通过 Cloudflare 仪表板访问：

Workers & Pages
选择你的 workflow
查看实例和指标

创建的实例总数
成功/错误率
平均执行时间
步骤级性能
CPU 时间消耗（2025 年功能）

const instance = await env.MY_WORKFLOW.get(instanceId);
const status = await instance.status();

console.log(status);
// {
//   status: 'complete' | 'running' | 'errored' | 'queued' | 'waiting' | 'unknown',
//   error: string | null,
//   output: { userId: '123', status: 'processed' }
// }

CPU 时间配置（2025 年）：

// wrangler.jsonc
{ "limits": { "cpu_ms": 300000 } }  // 最长 5 分钟（默认：30 秒）

限额（2025 年更新）

功能	Workers 免费版	Workers 付费版
每个 workflow 的最大步骤数	1,024	1,024
每个步骤的最大状态大小	1 MiB	1 MiB
每个实例的最大状态大小	100 MB	1 GB
最大事件负载大小	1 MiB	1 MiB
最大 sleep/sleepUntil 持续时间	365 天	365 天
最大 waitForEvent 超时时间	365 天	365 天
每个步骤的 CPU 时间	10 ms	30 秒（默认），5 分钟（最大）
每个步骤的持续时间（挂钟时间）	无限制	无限制
最大 workflow 执行次数	100,000/天	无限制
并发实例数	25	10,000（2025 年 10 月，从 4,500 提升）
实例创建速率	100/秒	100/秒（2025 年 10 月，快 10 倍）
最大排队实例数	100,000	1,000,000
每个实例的最大子请求数	50/请求	1,000/请求
保留期（完成状态）	3 天	30 天
最大 Workflow 名称长度	64 字符	64 字符
最大实例 ID 长度	100 字符	100 字符

关键注意事项：

step.sleep() 和 step.sleepUntil() 不计入 1,024 步限制
等待中的实例（休眠、重试或等待事件）不计入并发限制
实例创建速率提升 10 倍（2025 年 10 月）：每 10 秒 100 个 → 每秒 100 个
最大并发数增加（2025 年 10 月）：4,500 → 10,000 个并发实例
状态持久化限制提高（2025 年）：128 KB → 每个步骤 1 MiB，每个实例 100 MB - 1 GB
事件负载大小增加（2025 年）：128 KB → 1 MiB
可通过 wrangler.jsonc 配置 CPU 时间：{ "limits": { "cpu_ms": 300000 } }（最长 5 分钟）

需要 Workers 付费计划（$5/月）

Workflow 执行：

每月前 10,000,000 步执行：免费
之后：每百万步执行 $0.30

计为一步执行的情况：

每次 step.do() 调用
步骤的每次重试
step.sleep()、step.sleepUntil()、step.waitForEvent() 不计入

包含 5 个步骤、无重试的 workflow：5 步执行
包含 3 个步骤、其中 1 个步骤重试 2 次的 workflow：5 步执行（3 + 2）
每月 10M 个简单 workflows（每个 5 步）：((50M - 10M) / 1M) × $0.30 = $12/月

Vitest 测试（GA 于 2025 年 4 月）

Workflows 通过 cloudflare:test 模块支持完整的测试集成。

npm install -D vitest@latest @cloudflare/vitest-pool-workers@latest

vitest.config.ts：

import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';
export default defineWorkersConfig({ test: { poolOptions: { workers: { miniflare: { bindings: { MY_WORKFLOW: { scriptName: 'workflow' } } } } } } });

import { env, introspectWorkflowInstance } from 'cloudflare:test';

it('should complete workflow', async () => {
  const instance = await introspectWorkflowInstance(env.MY_WORKFLOW, 'test-123');

  try {
    await instance.modify(async (m) => {
      await m.disableSleeps();  // 跳过所有休眠
      await m.mockStepResult({ name: 'fetch data' }, { users: [{ id: 1 }] });  // 模拟步骤结果
      await m.mockEvent({ type: 'approval', payload: { approved: true } });  // 发送模拟事件
      await m.mockStepError({ name: 'call API' }, new Error('Network timeout'), 1);  // 强制错误一次
    });

    await env.MY_WORKFLOW.create({ id: 'test-123' });
    await expect(instance.waitForStatus('complete')).resolves.not.toThrow();
  } finally {
    await instance.dispose();  // 清理
  }
});

disableSleeps(steps?) - 立即跳过休眠
mockStepResult(step, result) - 模拟 step.do() 结果
mockStepError(step, error, times?) - 强制 step.do() 抛出错误
mockEvent(event) - 向 step.waitForEvent() 发送模拟事件
forceStepTimeout(step, times?) - 强制 step.do() 超时
forceEventTimeout(step) - 强制 step.waitForEvent() 超时

最后更新：2026-01-21 版本：2.0.

🇺🇸English

Cloudflare Workflows

Status : Production Ready ✅ (GA since April 2025) Last Updated : 2026-01-09 Dependencies : cloudflare-worker-base (for Worker setup) Latest Versions : wrangler@4.58.0, @cloudflare/workers-types@4.20260109.0

Recent Updates (2025) :

April 2025 : Workflows GA release - waitForEvent API, Vitest testing, CPU time metrics, 4,500 concurrent instances
October 2025 : Instance creation rate 10x faster (100/sec), concurrency increased to 10,000
2025 Limits : Max steps 1,024, state persistence 1MB/step (100MB-1GB per instance), event payloads 1MB, CPU time 5 min max
Testing : cloudflare:test module with introspectWorkflowInstance, disableSleeps, mockStepResult, mockEvent modifiers
Platform : Waiting instances don't count toward concurrency, retention 3-30 days, subrequests 50-1,000

Quick Start (5 Minutes)

# 1. Scaffold project
npm create cloudflare@latest my-workflow -- --template cloudflare/workflows-starter --git --deploy false
cd my-workflow

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

# 3. Create workflow (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 */ });
  }
}

# 4. Deploy and test
npm run deploy
npx wrangler workflows instances list my-workflow

CRITICAL : Extends WorkflowEntrypoint, implements run() with step methods, bindings in wrangler.jsonc

Known Issues Prevention

This skill prevents 12 documented errors with Cloudflare Workflows.

Issue #1: waitForEvent Skips Events After Timeout in Local Dev

Error : Events sent after a waitForEvent() timeout are ignored in subsequent waitForEvent() calls Environment : Local development (wrangler dev) only - works correctly in production Source : GitHub Issue #11740

Why It Happens : Bug in miniflare that was fixed in production (May 2025) but not ported to local emulator. After a timeout, the event queue becomes corrupted for that instance.

Prevention :

Test waitForEvent timeout scenarios in production/staging , not local dev
Avoid chaining multiple waitForEvent() calls where timeouts are expected

Example of Bug :

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    for (let i = 0; i < 3; i++) {
      try {
        const evt = await step.waitForEvent(`wait-${i}`, {
          type: 'user-action',
          timeout: '5 seconds'
        });
        console.log(`Iteration ${i}: Received event`);
      } catch {
        console.log(`Iteration ${i}: Timeout`);
      }
    }
  }
}
// In wrangler dev:
// - Iteration 1: ✅ receives event
// - Iteration 2: ⏱️ times out (expected)
// - Iteration 3: ❌ does not receive event (BUG - event is sent but ignored)

Status : Known bug, fix pending for miniflare.

Issue #2: getPlatformProxy() Fails With Workflow Bindings

Error : MiniflareCoreError [ERR_RUNTIME_FAILURE]: The Workers runtime failed to start Message : Worker's binding refers to service with named entrypoint, but service has no such entrypoint Source : GitHub Issue #9402

Why It Happens : getPlatformProxy() from wrangler package doesn't support Workflow bindings (similar to how it handles Durable Objects). This blocks Next.js integration and local CLI scripts.

Prevention :

Option 1 : Comment out workflow bindings when using getPlatformProxy()
Option 2 : Create separate wrangler.cli.jsonc without workflows for CLI scripts
Option 3 : Access workflow bindings directly via deployed worker, not proxy

// Workaround: Separate config for CLI scripts // wrangler.cli.jsonc (no workflows) { "name": "my-worker", "main": "src/index.ts", "compatibility_date": "2025-01-20" // workflows commented out }

// Use in script: import { getPlatformProxy } from 'wrangler'; const { env } = await getPlatformProxy({ configPath: './wrangler.cli.jsonc' });

Status : Known limitation, fix planned (filter workflows similar to DOs).

Issue #3: Workflow Instance Lost After Immediate Redirect (Local Dev)

Error : Instance ID returned but instance.not_found when queried Environment : Local development (wrangler dev) only - works correctly in production Source : GitHub Issue #10806

Why It Happens : Returning a redirect immediately after workflow.create() causes request to "soft abort" before workflow initialization completes (single-threaded execution in dev).

Prevention : Use ctx.waitUntil() to ensure workflow initialization completes before redirect:

export default {
  async fetch(req: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const workflow = await env.MY_WORKFLOW.create({ params: { userId: '123' } });

    // ✅ Ensure workflow initialization completes
    ctx.waitUntil(workflow.status());

    return Response.redirect('/dashboard', 302);
  }
};

Status : Fixed in recent wrangler versions (post-Sept 2025), but workaround still recommended for compatibility.

Issue #4: Vitest Tests Unreliable in CI Environments

Error : [vitest-worker]: Timeout calling "resolveId" Environment : CI/CD pipelines (GitLab, GitHub Actions) - works locally Source : GitHub Issue #10600

Why It Happens : @cloudflare/vitest-pool-workers has resource constraint issues in CI containers, affecting workflow tests more than other worker types.

Prevention :

Increase testTimeout in vitest config:

export default defineWorkersConfig({ test: { testTimeout: 60_000 // Default: 5000ms } });
Check CI resource limits (CPU/memory)
Use isolatedStorage: false if not testing storage isolation
Consider testing against deployed instances instead of vitest for critical workflows

Status : Known issue, investigating (Internal: WOR-945).

Issue #5: Instance restart() and terminate() Not Implemented in Local Dev

Error : Error: Not implemented yet when calling instance.restart() or instance.terminate() Environment : Local development (wrangler dev) only - works in production Source : GitHub Issue #11312

Why It Happens : Instance management APIs not yet implemented in miniflare. Additionally, instance status shows running even when workflow is sleeping.

Prevention : Test instance lifecycle management (pause/resume/terminate) in production or staging environment until local dev support is added.

const instance = await env.MY_WORKFLOW.get(instanceId);

// ❌ Fails in wrangler dev
await instance.restart();    // Error: Not implemented yet
await instance.terminate();  // Error: Not implemented yet

// ✅ Works in production

Status : Known limitation, no timeline for local dev support.

Issue #6: I/O Must Be Inside step.do() Callbacks

Error : "Cannot perform I/O on behalf of a different request" Source : Cloudflare runtime behavior

Why It Happens : Trying to use I/O objects created in one request context from another request handler.

Prevention : Always perform I/O within step.do() callbacks:

// ❌ Bad - I/O outside step
const response = await fetch('https://api.example.com/data');
const data = await response.json();

await step.do('use data', async () => {
  return data;  // This will fail!
});

// ✅ Good - I/O inside step
const data = await step.do('fetch data', async () => {
  const response = await fetch('https://api.example.com/data');
  return await response.json();
});

Issue #7: NonRetryableError Behaves Differently in Dev vs Production

Error : NonRetryableError with empty message causes retries in dev mode but works correctly in production Environment : Development-specific bug Source : GitHub Issue #10113

Why It Happens : Empty error messages are handled differently between miniflare and production runtime.

Prevention : Always provide a message to NonRetryableError:

// ❌ Retries in dev, exits in prod
throw new NonRetryableError('');

// ✅ Exits in both environments
throw new NonRetryableError('Validation failed');

Status : Known issue, workaround documented.

Issue #8: In-Memory State Lost on Hibernation

Error : Variables declared outside step.do() reset to initial values after sleep/hibernation Source : Cloudflare Workflows Rules

Why It Happens : Workflows hibernate when the engine detects no pending work. All in-memory state is lost during hibernation.

Prevention : Only use state returned from step.do() - everything else is ephemeral:

// ❌ BAD - In-memory variable lost on hibernation
let counter = 0;
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    counter = await step.do('increment', async () => counter + 1);
    await step.sleep('wait', '1 hour'); // ← Hibernates here, in-memory state lost
    console.log(counter); // ❌ Will be 0, not 1!
  }
}

// ✅ GOOD - State from step.do() return values persists
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    const counter = await step.do('increment', async () => 1);
    await step.sleep('wait', '1 hour');
    console.log(counter); // ✅ Still 1
  }
}

Issue #9: Non-Deterministic Step Names Break Caching

Error : Steps re-run unnecessarily, performance degradation Source : Cloudflare Workflows Rules

Why It Happens : Step names act as cache keys. Using Date.now(), Math.random(), or other non-deterministic values causes new cache keys every run.

Prevention : Use static, deterministic step names:

// ❌ BAD - Non-deterministic step name
await step.do(`fetch-data-${Date.now()}`, async () => {
  return await fetchExpensiveData();
});
// Every execution creates new cache key → step always re-runs

// ✅ GOOD - Deterministic step name
await step.do('fetch-data', async () => {
  return await fetchExpensiveData();
});
// Same cache key → result reused on restart/retry

Issue #10: Promise.race/any Outside step.do() Causes Inconsistency

Error : Different promises resolve on restart, inconsistent behavior Source : Cloudflare Workflows Rules

Why It Happens : Non-deterministic operations outside steps run again on restart, potentially with different results.

Prevention : Keep all non-deterministic logic inside step.do():

// ❌ BAD - Race outside step
const fastest = await Promise.race([fetchA(), fetchB()]);
await step.do('use result', async () => fastest);
// On restart: race runs again, different promise might win

// ✅ GOOD - Race inside step
const fastest = await step.do('fetch fastest', async () => {
  return await Promise.race([fetchA(), fetchB()]);
});
// On restart: cached result used, consistent behavior

Issue #11: Side Effects Repeat on Restart

Error : Duplicate logs, metrics, or operations after workflow restart Source : Cloudflare Workflows Rules

Why It Happens : Code outside step.do() executes multiple times if the workflow restarts mid-execution.

Prevention : Put logging, metrics, and other side effects inside step.do():

// ❌ BAD - Side effect outside step
console.log('Workflow started'); // ← Logs multiple times on restart
await step.do('work', async () => { /* work */ });

// ✅ GOOD - Side effects inside step
await step.do('log start', async () => {
  console.log('Workflow started'); // ← Logs once (cached)
});

Issue #12: Non-Idempotent Operations Can Repeat

Error : Double charges, duplicate database writes after step timeout Source : Cloudflare Workflows Rules

Why It Happens : Steps retry individually. If an API call succeeds but the step times out before returning, the retry will call the API again.

Prevention : Guard non-idempotent operations with existence checks:

// ❌ BAD - Charge customer without check
await step.do('charge', async () => {
  return await stripe.charges.create({ amount: 1000, customer: customerId });
});
// If step times out after charge succeeds, retry charges AGAIN!

// ✅ GOOD - Check for existing charge first
await step.do('charge', async () => {
  const existing = await stripe.charges.list({ customer: customerId, limit: 1 });
  if (existing.data.length > 0) return existing.data[0]; // Idempotent
  return await stripe.charges.create({ amount: 1000, customer: customerId });
});

Step Methods

step.do() - Execute Work

step.do<T>(name: string, config?: WorkflowStepConfig, callback: () => Promise<T>): Promise<T>

Parameters:

name - Step name (for observability)
config (optional) - Retry configuration (retries, timeout, backoff)
callback - Async function that does the work

Returns: Value from callback (must be serializable)

Example:

const result = await step.do('call API', { retries: { limit: 10, delay: '10s', backoff: 'exponential' }, timeout: '5 min' }, async () => {
  return await fetch('https://api.example.com/data').then(r => r.json());
});

CRITICAL - Serialization:

✅ Allowed: string, number, boolean, Array, Object, null
❌ Forbidden: Function, Symbol, circular references, undefined
Throws error if return value isn't JSON serializable

step.sleep() - Relative Sleep

step.sleep(name: string, duration: WorkflowDuration): Promise<void>

Parameters:

name - Step name
duration - Number (ms) or string: "second", "minute", "hour", "day", "week", "month", "year" (plural forms accepted)

Examples:

await step.sleep('wait 5 minutes', '5 minutes');
await step.sleep('wait 1 hour', '1 hour');
await step.sleep('wait 2 days', '2 days');
await step.sleep('wait 30 seconds', 30000);  // milliseconds

Note: Resuming workflows take priority over new instances. Sleeps don't count toward step limits.

step.sleepUntil() - Sleep to Specific Date

step.sleepUntil(name: string, timestamp: Date | number): Promise<void>

Parameters:

name - Step name
timestamp - Date object or UNIX timestamp (milliseconds)

Examples:

await step.sleepUntil('wait for launch', new Date('2025-12-25T00:00:00Z'));
await step.sleepUntil('wait until time', Date.parse('24 Oct 2024 13:00:00 UTC'));

step.waitForEvent() - Wait for External Event (GA April 2025)

step.waitForEvent<T>(name: string, options: { type: string; timeout?: string | number }): Promise<T>

Parameters:

name - Step name
options.type - Event type to match
options.timeout (optional) - Max wait time (default: 24 hours, max: 30 days)

Returns: Event payload sent via instance.sendEvent()

Example:

export class PaymentWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    await step.do('create payment', async () => { /* Stripe API */ });

    const webhookData = await step.waitForEvent<StripeWebhook>(
      'wait for payment confirmation',
      { type: 'stripe-webhook', timeout: '1 hour' }
    );

    if (webhookData.status === 'succeeded') {
      await step.do('fulfill order', async () => { /* fulfill */ });
    }
  }
}

// Worker sends event to workflow
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    if (req.url.includes('/webhook/stripe')) {
      const instance = await env.PAYMENT_WORKFLOW.get(instanceId);
      await instance.sendEvent({ type: 'stripe-webhook', payload: await req.json() });
      return new Response('OK');
    }
  }
};

Timeout handling:

try {
  const event = await step.waitForEvent('wait for user', { type: 'user-submitted', timeout: '10 minutes' });
} catch (error) {
  await step.do('send reminder', async () => { /* reminder */ });
}

WorkflowStepConfig

interface WorkflowStepConfig {
  retries?: {
    limit: number;          // Max attempts (Infinity allowed)
    delay: string | number; // Delay between retries
    backoff?: 'constant' | 'linear' | 'exponential';
  };
  timeout?: string | number; // Max time per attempt
}

Default: { retries: { limit: 5, delay: 10000, backoff: 'exponential' }, timeout: '10 minutes' }

Backoff Examples:

// Constant: 30s, 30s, 30s
{ retries: { limit: 3, delay: '30 seconds', backoff: 'constant' } }

// Linear: 1m, 2m, 3m, 4m, 5m
{ retries: { limit: 5, delay: '1 minute', backoff: 'linear' } }

// Exponential (recommended): 10s, 20s, 40s, 80s, 160s
{ retries: { limit: 10, delay: '10 seconds', backoff: 'exponential' }, timeout: '5 minutes' }

// Unlimited retries
{ retries: { limit: Infinity, delay: '1 minute', backoff: 'exponential' } }

// No retries
{ retries: { limit: 0 } }

Error Handling

NonRetryableError

Force workflow to fail immediately without retrying:

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

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    await step.do('validate input', async () => {
      if (!event.payload.userId) {
        throw new NonRetryableError('userId is required');
      }

      // Validate user exists
      const user = await this.env.DB.prepare(
        'SELECT * FROM users WHERE id = ?'
      ).bind(event.payload.userId).first();

      if (!user) {
        // Terminal error - retrying won't help
        throw new NonRetryableError('User not found');
      }

      return user;
    });
  }
}

When to use NonRetryableError:

✅ Authentication/authorization failures
✅ Invalid input that won't change
✅ Resource doesn't exist (404)
✅ Validation errors
❌ Network failures (should retry)
❌ Rate limits (should retry with backoff)
❌ Temporary service outages (should retry)

Catch Errors to Continue Workflow

Prevent workflow failure by catching optional step errors:

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    await step.do('process payment', async () => { /* critical */ });

    try {
      await step.do('send email', async () => { /* optional */ });
    } catch (error) {
      await step.do('log failure', async () => {
        await this.env.DB.prepare('INSERT INTO failed_emails VALUES (?, ?)').bind(event.payload.userId, error.message).run();
      });
    }

    await step.do('update status', async () => { /* continues */ });
  }
}

Graceful Degradation:

let result;
try {
  result = await step.do('call primary API', async () => await callPrimaryAPI());
} catch {
  result = await step.do('call backup API', async () => await callBackupAPI());
}

Triggering Workflows

Configure binding (wrangler.jsonc):

{
  "workflows": [{
    "name": "my-workflow",
    "binding": "MY_WORKFLOW",
    "class_name": "MyWorkflow",
    "script_name": "workflow-worker"  // If workflow in different Worker
  }]
}

Trigger from Worker:

const instance = await env.MY_WORKFLOW.create({ params: { userId: '123' } });
return Response.json({ id: instance.id, status: await instance.status() });

Instance Management:

const instance = await env.MY_WORKFLOW.get(instanceId);
const status = await instance.status();  // { status: 'running'|'complete'|'errored'|'queued', error, output }
await instance.sendEvent({ type: 'user-action', payload: { action: 'approved' } });
await instance.pause();
await instance.resume();
await instance.terminate();

State Persistence

Workflows automatically persist state returned from step.do():

✅ Serializable:

Primitives: string, number, boolean, null
Arrays, Objects, Nested structures

❌ Non-Serializable:

Functions, Symbols, circular references, undefined, class instances

Example:

// ✅ Good
const result = await step.do('fetch data', async () => ({
  users: [{ id: 1, name: 'Alice' }],
  timestamp: Date.now(),
  metadata: null
}));

// ❌ Bad - function not serializable
const bad = await step.do('bad', async () => ({ data: [1, 2, 3], transform: (x) => x * 2 }));  // Throws error!

Access State Across Steps:

const userData = await step.do('fetch user', async () => ({ id: 123, email: 'user@example.com' }));
const orderData = await step.do('create order', async () => ({ userId: userData.id, orderId: 'ORD-456' }));
await step.do('send email', async () => sendEmail({ to: userData.email, subject: `Order ${orderData.orderId}` }));

Observability

Built-in Metrics (Enhanced in 2025)

Workflows automatically track:

Instance status : queued, running, complete, errored, paused, waiting
Step execution : start/end times, duration, success/failure
Retry history : attempts, errors, delays
Sleep state : when workflow will wake up
Output : return values from steps and run()
CPU time (GA April 2025): Active processing time per instance for billing insights

View Metrics in Dashboard

Access via Cloudflare dashboard:

Workers & Pages
Select your workflow
View instances and metrics

Metrics include:

Total instances created
Success/error rates
Average execution time
Step-level performance
CPU time consumption (2025 feature)

Programmatic Access

const instance = await env.MY_WORKFLOW.get(instanceId);
const status = await instance.status();

console.log(status);
// {
//   status: 'complete' | 'running' | 'errored' | 'queued' | 'waiting' | 'unknown',
//   error: string | null,
//   output: { userId: '123', status: 'processed' }
// }

CPU Time Configuration (2025):

// wrangler.jsonc
{ "limits": { "cpu_ms": 300000 } }  // 5 minutes max (default: 30 seconds)

Limits (Updated 2025)

Feature	Workers Free	Workers Paid
Max steps per workflow	1,024	1,024
Max state per step	1 MiB	1 MiB
Max state per instance	100 MB	1 GB
Max event payload size	1 MiB	1 MiB
Max sleep/sleepUntil duration	365 days	365 days
Max waitForEvent timeout	365 days	365 days
CPU time per step	10 ms	30 sec (default), 5 min (max)
Duration (wall clock) per step	Unlimited

CRITICAL Notes:

step.sleep() and step.sleepUntil() do NOT count toward 1,024 step limit
Waiting instances (sleeping, retrying, or waiting for events) do NOT count toward concurrency limits
Instance creation rate increased 10x (October 2025): 100 per 10 seconds → 100 per second
Max concurrency increased (October 2025): 4,500 → 10,000 concurrent instances
State persistence limits increased (2025): 128 KB → 1 MiB per step, 100 MB - 1 GB per instance
Event payload size increased (2025): 128 KB → 1 MiB
CPU time configurable via wrangler.jsonc: { "limits": { "cpu_ms": 300000 } } (5 min max)

Pricing

Requires Workers Paid plan ($5/month)

Workflow Executions:

First 10,000,000 step executions/month: FREE
After that: $0.30 per million step executions

What counts as a step execution:

Each step.do() call
Each retry of a step
step.sleep(), step.sleepUntil(), step.waitForEvent() do NOT count

Cost examples:

Workflow with 5 steps, no retries: 5 step executions
Workflow with 3 steps, 1 step retries 2 times: 5 step executions (3 + 2)
10M simple workflows/month (5 steps each): ((50M - 10M) / 1M) × $0.30 = $12/month

Vitest Testing (GA April 2025)

Workflows support full testing integration via cloudflare:test module.

Setup

npm install -D vitest@latest @cloudflare/vitest-pool-workers@latest

vitest.config.ts:

import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';
export default defineWorkersConfig({ test: { poolOptions: { workers: { miniflare: { bindings: { MY_WORKFLOW: { scriptName: 'workflow' } } } } } } });

Introspection API

import { env, introspectWorkflowInstance } from 'cloudflare:test';

it('should complete workflow', async () => {
  const instance = await introspectWorkflowInstance(env.MY_WORKFLOW, 'test-123');

  try {
    await instance.modify(async (m) => {
      await m.disableSleeps();  // Skip all sleeps
      await m.mockStepResult({ name: 'fetch data' }, { users: [{ id: 1 }] });  // Mock step result
      await m.mockEvent({ type: 'approval', payload: { approved: true } });  // Send mock event
      await m.mockStepError({ name: 'call API' }, new Error('Network timeout'), 1);  // Force error once
    });

    await env.MY_WORKFLOW.create({ id: 'test-123' });
    await expect(instance.waitForStatus('complete')).resolves.not.toThrow();
  } finally {
    await instance.dispose();  // Cleanup
  }
});

Test Modifiers

disableSleeps(steps?) - Skip sleeps instantly
mockStepResult(step, result) - Mock step.do() result
mockStepError(step, error, times?) - Force step.do() to throw
mockEvent(event) - Send mock event to step.waitForEvent()
forceStepTimeout(step, times?) - Force step.do() timeout
forceEventTimeout(step) - Force step.waitForEvent() timeout

Official Docs : https://developers.cloudflare.com/workers/testing/vitest-integration/

Cloudflare Workflows 完整指南：生产就绪的服务器端工作流解决方案

🇨🇳中文介绍

Cloudflare Workflows

快速开始（5 分钟）

相关 Skills

已知问题预防

问题 #1：本地开发中 waitForEvent 超时后忽略事件

问题 #2：getPlatformProxy() 因 Workflow 绑定而失败

问题 #3：立即重定向后 Workflow 实例丢失（本地开发）

问题 #4：Vitest 测试在 CI 环境中不可靠

问题 #5：本地开发中未实现 Instance restart() 和 terminate()

问题 #6：I/O 操作必须在 step.do() 回调内部进行

问题 #7：NonRetryableError 在开发与生产环境中的行为不同

问题 #8：休眠时内存中的状态丢失

问题 #9：非确定性的步骤名称会破坏缓存

问题 #10：在 step.do() 外部使用 Promise.race/any 会导致不一致

问题 #11：副作用在重启时重复

问题 #12：非幂等操作可能重复

步骤方法

step.do() - 执行工作

step.sleep() - 相对休眠

step.sleepUntil() - 休眠到特定日期

step.waitForEvent() - 等待外部事件（GA 于 2025 年 4 月）

WorkflowStepConfig

错误处理

NonRetryableError

捕获错误以继续 Workflow

触发 Workflows

状态持久化

可观测性

内置指标（2025 年增强）

在仪表板中查看指标

编程式访问

限额（2025 年更新）

定价

Vitest 测试（GA 于 2025 年 4 月）

设置

内省 API

测试修饰符

相关文档

🇺🇸English

Cloudflare Workflows

Quick Start (5 Minutes)

Known Issues Prevention

Issue #1: waitForEvent Skips Events After Timeout in Local Dev

Issue #2: getPlatformProxy() Fails With Workflow Bindings

Issue #3: Workflow Instance Lost After Immediate Redirect (Local Dev)

Issue #4: Vitest Tests Unreliable in CI Environments

Issue #5: Instance restart() and terminate() Not Implemented in Local Dev

Issue #6: I/O Must Be Inside step.do() Callbacks

Issue #7: NonRetryableError Behaves Differently in Dev vs Production

Issue #8: In-Memory State Lost on Hibernation

Issue #9: Non-Deterministic Step Names Break Caching

Issue #10: Promise.race/any Outside step.do() Causes Inconsistency

Issue #11: Side Effects Repeat on Restart

Issue #12: Non-Idempotent Operations Can Repeat

Step Methods

step.do() - Execute Work

step.sleep() - Relative Sleep

step.sleepUntil() - Sleep to Specific Date

step.waitForEvent() - Wait for External Event (GA April 2025)

WorkflowStepConfig

Error Handling

NonRetryableError

Catch Errors to Continue Workflow

Triggering Workflows

State Persistence

Observability

Built-in Metrics (Enhanced in 2025)

View Metrics in Dashboard

Programmatic Access

Limits (Updated 2025)

Pricing

Vitest Testing (GA April 2025)

Setup

Introspection API

Test Modifiers

Related Documentation

最新 Skills