进阶 celld.dev 2026-10-11 10:08:47 · 47 阅读

第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-、LW、L-W 以及 W,星期字段支持 L 和 #。若两个日期字段均有限制,它们取并集,例如 0 0 1 * MON 会在每月 1 日和每周一触发。仅当使用字面量 * 时,日期字段才不受限制。 celld 会拒绝递减范围(如 SAT-SUN)及包含 * 的列表(如 1,*)。Cloudflare 接受这两种写法但结果令人意外。步长不能超过字段宽度,因此分钟字段的 */60 会报错。 执行 controller.scheduledTime 保存的是计划触发点而非执行开始时间,因此迟到的执行和重试指向同一分钟。celld 逐个执行单个脚本的处理器,并在下一个执行前处理完每个 waitUntil() 工作。若处理器耗时超过间隔,将延迟下一次触发。请将长耗时任务移至队列或 Workflow。 抛异常后,处理器在 4 秒后重试,每次失败后延迟翻倍。celld 在六次失败后或下一个触发点放弃重试,因此比退避时间更快的调度表不会重试。controller.noRetry() 可停止重试。所有权转移会导致待处理的重试丢失。 停机恢复后,celld 仅运行一次错过的触发点,跳过其余部分。可从 controller.scheduledTime 读取间隔,在应用代码中补齐进度。 持有保留单元所在的节点执行触发点,该节点可能会变更。服务绑定目标中的 triggers.crons 条目不会运行,celld 在加载此类目标时记录警告。 与 Cloudflare 的差异

celld 拒绝递减范围(如 SAT-SUN)及包含 * 的列表。 celld 针对每个触发点在集群中仅运行一次处理器。停机恢复后,仅运行一次错过的触发点,跳过其余部分。 celld 串行化单个脚本的处理器。若处理器调用 noRetry(),失败重试将持续至下一个触发点。 服务绑定目标无法运行自身的 Cron Triggers。

Cloudflare 兼容性页面 列出了运行时 API 及不支持的服务。

本篇用到的工具

评论 (0)