Workflows 常见陷阱

# 常见问题与调试 ## 常见错误 ### "Step Timeout" (步骤超时) **原因：** 步骤执行超过了 10 分钟的默认超时或配置的超时时间。 **解决方案：** 使用 `step.do('long operation', {timeout: '30 minutes'}, async () => {...})` 设置自定义超时，或在 wrangler.jsonc 中增加 CPU 限制（最大 5 分钟 CPU 时间）。 ### "waitForEvent Timeout" (事件等待超时) **原因：** 在超时周期内未收到事件（默认 24 小时，最大 365 天）。 **解决方案：** 使用 try-catch 包裹以优雅地处理超时并执行默认行为。 ### "Non-Deterministic Step Names" (非确定性步骤名称) **原因：** 在步骤名称中使用 `Date.now()` 等动态值会导致重放问题。 **解决方案：** 使用 `event.instanceId` 等确定性值作为步骤名称。 ### "State Lost in Variables" (变量状态丢失) **原因：** 使用模块级或局部变量存储状态，在休眠时会丢失。 **解决方案：** 从 `step.do()` 返回值，这些值会自动持久化：`const total = await step.do('step 1', async () => 10)` ### "Non-Deterministic Conditionals" (非确定性条件判断) **原因：** 在步骤外的条件判断中使用非确定性逻辑（如 `Date.now()`）。 **解决方案：** 将非确定性操作移入步骤内：`const isLate = await step.do('check', async () => Date.now() > deadline)` ### "Large Step Returns Exceeding Limit" (步骤返回值超限) **原因：** 步骤返回数据超过 1 MiB。 **解决方案：** 将大数据存储在 R2 中并仅返回引用：`{ key: 'r2-object-key' }` ### "Step Exceeded CPU Limit But Ran for < 30s" (步骤 CPU 超限但运行时间不足 30 秒) **原因：** 混淆了 CPU 时间（活跃计算）和挂钟时间（包含 I/O 等待）。 **解决方案：** 网络请求、数据库查询和休眠不计入 CPU 时间。30 秒限制指的是 30 秒的活跃处理时间。 ### "Idempotency Violation" (幂等性违规) **原因：** 步骤操作非幂等，导致重试时产生重复扣费或动作。 **解决方案：** 在执行前检查操作是否已完成（例如：检查客户是否已扣费）。 ### "Instance ID Collision" (实例 ID 冲突) **原因：** 重用实例 ID 导致冲突。 **解决方案：** 使用带时间戳的唯一 ID：`await env.MY_WORKFLOW.create({ id: `${userId}-${Date.now()}`, params: {} })` ### "Instance Data Disappeared After Completion" (实例数据在完成后消失) **原因：** 已完成/出错的实例会在保留期后自动删除（免费版 3 天 / 付费版 30 天）。 **解决方案：** 在工作流完成前将关键数据导出到 KV/R2/D1。 ### "Missing await on step.do" (缺少 await) **原因：** 忘记 await step.do() 导致触发即忘行为。