第9章 Cron Triggers 定时触发机制详解
DocumentationCron Triggers Cron Trigger 让 Worker 按计划运行。celld 将脚本的调度表保存在一个保留单元中,因此整个集群在每次触发时仅运行一次。关于 API 细节,请参阅 Cloudflare Cron Triggers 文档。 示例 Cron Trigger 示例每分钟记录一次计划时间。
index.js export default { async fetch(request, env) { return new Response("The cron runs once a minute.\n"); }, async scheduled(controller, env, ctx) { console.log("cron", controller.scheduledTime); }, };
wrangler.jsonc { "name": "cron", "main": "index.js", "compatibility_date": "2026-01-01", "triggers": { "crons": ["* * * * *"] } }
API Worker 需导出一个 scheduled(controller, env, ctx) 处理器。
controller.cron 保存表达式文本。 controller.scheduledTime 保存触发时间点(毫秒)。 controller.noRetry() 停止对失败触发点的重试。 ctx.waitUntil() 延长调用时长。celld 在下一次调用前会处理完这些工作。
调度
项目通过 triggers.crons 数组声明调度表。若表达式格式错误或未指定 main,celld deploy 会失败。celld 对表达式数量不设上限。
celld 读取 Cloudflare 的 cron 方言。表达式包含五个字段:分钟、小时、月内日、月份、星期。分辨率为 1 分钟,时区为 UTC。星期编号从星期日起为 1 至 7,因此 1-5 表示星期日至星期四。
每个字段支持通配符 *、具体值、范围 a-b、列表 a,b 以及步长 /n。月份和星期字段还支持任意大小写的三位字母名称,如 JAN 和 MON。月内日字段支持 L、L-
celld 拒绝递减范围(如 SAT-SUN)及包含 * 的列表。 celld 针对每个触发点在集群中仅运行一次处理器。停机恢复后,仅运行一次错过的触发点,跳过其余部分。 celld 串行化单个脚本的处理器。若处理器调用 noRetry(),失败重试将持续至下一个触发点。 服务绑定目标无法运行自身的 Cron Triggers。
Cloudflare 兼容性页面 列出了运行时 API 及不支持的服务。