用途:为 Cloudflare Workers 配置按 cron 表达式周期性执行的定时任务,例如维护作业、数据同步和报表生成。需依赖 cloudflare-worker-base 完成 Worker 基础搭建。
主要能力:
- scheduled 处理函数:必须命名为 scheduled,放入 default export,使用 ES modules 格式,接收 ScheduledController、env、ctx。
- ScheduledController:提供 cron(触发的表达式)、type(固定 "scheduled")、scheduledTime(计划执行的 Unix 毫秒时间戳)。
- ctx.waitUntil():让日志、分析、清理等非关键异步操作在返回后继续执行;首个失败的 waitUntil 会作为状态写入日志。
- 可在处理函数中访问全部 Worker 绑定,包括 D1、R2、KV、AI、Queue、Workflow 与 Secrets。
必要用法:
- wrangler 配置中通过 triggers.crons 声明表达式,例如 "0 * * * *"。
- 本地测试:npx wrangler dev --test-scheduled,再请求 curl "http://localhost:8787/__scheduled?cron=0++++";Python Workers 使用 /cdn-cgi/handler/scheduled。
- 部署:npx wrangler deploy;支持通过 env 区分环境,部署时用 --env 指定。
- 空数组 "crons": [] 可移除全部定时触发。
重要限制:
- 表达式为 5 字段(分 时 日 月 周),仅使用 UTC,无时区转换。
- 配置变更全球生效最多需 15 分钟。
- 免费套餐每个 Worker 最多 3 个 cron 触发器,付费套餐更高(具体上限以官方为准)。
- 定时处理函数受 CPU 限制,长任务建议改由 Workflows 触发。
- 支持 Green Compute 以减少碳足迹,可能带来轻微区域延迟。
资料未提供具体收费标准、完整 API 参考与全部已知问题清单。