cloudflare-cron-triggers

用途

Cloudflare Cron Triggers 用于让 Cloudflare Workers 按计划周期性执行代码，适用于周期性任务、定时作业等场景。它通过为 Worker 添加定时处理器，并在 Wrangler 配置中声明 cron 表达式来定义执行时间。

主要能力

为 Worker 添加名为 scheduled 的处理器，在指定时间自动执行。
支持在 wrangler.jsonc 的 triggers.crons 数组中配置一个或多个 cron 表达式。
提供 ScheduledController 接口，包含 cron（触发的表达式）、type（固定为 "scheduled"）、scheduledTime（计划执行的 Unix 毫秒时间戳）。
提供 ExecutionContext，可通过 ctx.waitUntil() 执行非关键异步操作（如日志、分析、清理）。
支持在定时函数中访问 D1、KV、R2、AI、Vectorize、Queues、Workflows、Durable Objects 等绑定。
支持 Green Compute，将 cron 执行路由到使用可再生能源的数据中心。

使用方式

在 Worker 的 src/index.ts 中导出 scheduled 处理器：

export default {
  async scheduled(
    controller: ScheduledController,
    env: Env,
    ctx: ExecutionContext
  ): Promise<void> {
    console.log('Cron job executed at:', new Date(controller.scheduledTime));
    console.log('Triggered by cron:', controller.cron);
    await doPeriodicTask(env);
  },
};

处理器必须命名为 scheduled，必须放在默认导出对象中，且必须使用 ES modules 格式。

在 wrangler.jsonc 中配置 cron 触发器：

{
  "name": "my-scheduled-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-23",
  "triggers": {
    "crons": [
      "0 * * * *"
    ]
  }
}

本地测试：

bunx wrangler dev --test-scheduled
curl "http://localhost:8787/__scheduled?cron=0+*+*+*+*"

/__scheduled 端点仅在启用 --test-scheduled 时可用。Python Workers 使用 /cdn-cgi/handler/scheduled。

部署：

npm run deploy
# 或
bunx wrangler deploy

部署后，cron 变更最多需要 15 分钟才能全局生效。可在仪表盘 Workers & Pages > [Your Worker] > Cron Triggers 查看，在 Logs 标签查看历史执行记录。

Cron 表达式语法

使用 5 字段格式：

* * * * *
│ │ │ │ │
│ │ │ │ └─── 星期 (0-6, 周日=0)
│ │ │ └───── 月 (1-12)
│ │ └─────── 日 (1-31)
│ └───────── 时 (0-23)
└─────────── 分 (0-59)

特殊字符：* 表示每，, 表示列表，- 表示范围，/ 表示步长。

常见示例：

* * * * *        # 每分钟
*/5 * * * *      # 每 5 分钟
*/15 * * * *     # 每 15 分钟
0 * * * *        # 每小时第 0 分钟
0 */6 * * *      # 每 6 小时
0 0 * * *        # 每天 UTC 午夜
0 12 * * *       # 每天 UTC 正午
30 3 * * *       # 每天 UTC 3:30
0 9 * * 1        # 每周一 UTC 9:00
0 9 * * 1-5      # 每个工作日 UTC 9:00
0 0 * * 0        # 每周日 UTC 午夜
0 0 1 * *        # 每月第一天 UTC 午夜
0 6,18 * * *     # 每天 UTC 6:00 和 18:00
*/30 9-17 * * 1-5 # 工作日 UTC 9:00-17:00 每 30 分钟

所有 cron 触发器仅按 UTC 时间执行，不支持时区转换，需手动将本地时间换算为 UTC。

适用场景

数据库清理、报告生成等后台任务。
HTTP 端点与定时任务共用一个 Worker（如 Hono + Cron 组合），共享绑定并降低成本。
使用 controller.cron 区分多个 cron 触发器，为不同任务设置不同计划。
在定时函数中访问 D1、KV、R2、AI、Vectorize、Queues、Workflows、Durable Objects 等绑定。
按计划触发复杂、长时间运行的多步骤 Workflows。
带重试逻辑、告警（Slack/邮件）、失败日志和监控的错误处理。

限制

cron 表达式仅支持 5 字段，不支持秒字段。
仅按 UTC 时间运行，无时区转换。
cron 变更最多需要 15 分钟全局生效。
必须使用 ES modules 格式，不支持 Service Worker 格式。
处理器必须精确命名为 scheduled。
星期范围为 0-6，周日用 0，不支持 7。
默认 CPU 时间限制为 30 秒，可通过 limits.cpu_ms 提高（Standard 计划最高 5 分钟），或使用 Workflows 处理长时间任务。
免费计划每个 Worker 最多 3 个 cron 触发器，付费计划上限更高（需查阅文档）。
内存限制 128 MB。
墙钟时间：免费计划 30 秒，付费计划 15 分钟。
定价：需 Workers 付费计划（$5/月）；请求 $0.30/百万次（10M 免费额度后）；CPU 时间 $0.02/百万 CPU-ms（30M 免费额度后）；每次 cron 执行计为 1 次请求。

已知问题预防

该技能可预防 6 类常见问题：cron 变更未生效（需等待最多 15 分钟）、处理器未导出（名称或格式错误）、UTC 时区混淆、无效 cron 表达式（静默失败）、缺少 ES modules 格式、CPU 时间超限。