Cron Triggers 常见陷阱

# Cron 触发器常见陷阱 ## 常见错误 ### "时区问题" **问题:** Cron 运行时间与本地时区不符 **原因:** 所有 cron 均在 UTC 时间执行，不支持本地时区 **解决方案:** 手动将本地时间转换为 UTC **转换公式:** `utcHour = (localHour - utcOffset + 24) % 24` **示例:** - 9am PST (UTC-8) → `(9 - (-8) + 24) % 24 = 17` → `0 17 * * *` - 2am EST (UTC-5) → `(2 - (-5) + 24) % 24 = 7` → `0 7 * * *` - 6pm JST (UTC+9) → `(18 - 9 + 24) % 24 = 33 % 24 = 9` → `0 9 * * *` **夏令时:** 夏令时变更时需手动调整，或在不受夏令时影响的时间段进行调度（例如本地时间凌晨 2 点至 4 点通常是安全的） ### "Cron 未执行" **原因:** 缺少 `scheduled()` 导出、语法无效、传播延迟（<15分钟）或超出计划限制 **解决方案:** 验证导出是否存在，在 crontab.guru 验证语法，部署后等待 15 分钟以上，检查计划限制 ### "重复执行" **原因:** 至少一次交付机制 **解决方案:** 在 KV 中跟踪执行 ID - 参见下方的幂等性模式 ### "执行失败" **原因:** CPU 超限、未捕获的异常、网络超时、绑定错误 **解决方案:** 使用 try-catch，AbortController 超时，使用 `ctx.waitUntil()` 处理长耗时操作，或使用工作流处理繁重任务 ### "本地测试不工作" **问题:** `/__scheduled` 端点返回 404 或未触发处理器 **原因:** 缺少 `scheduled()` 导出、wrangler 未运行或端点格式不正确 **解决方案:** 1. 验证 `scheduled()` 已导出: typescript export default { async scheduled(controller, env, ctx) { console.log("Cron 已触发"); }, }; 2. 启动开发服务器: bash npx wrangler dev 3. 使用正确的端点格式（将空格 URL 编码为 `+`）: bash # 正确 curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*" # 错误 (会失败) curl "http://localhost:8787/__scheduled?cron=*/5 * * * *" 4. 更新 Wrangler: bash npm install -g wrangler@latest ### "waitUntil() 任务未完成" **问题:** `ctx.waitUntil()` 中的后台任务静默失败或未执行 **原因:** Promise 被拒绝但未处理错误，或处理器在 Promise 完成前返回 **解决方案:** 始终 await 或处理 waitUntil promise 中的错误: typescript export default { async scheduled(controller, env, ctx) { // 坏习惯: 静默失败 ctx.waitUntil(riskyOperation()); // 好习惯: 显式错误处理 ctx.waitUntil( riskyOperation().c