企业官网建设流程全解析

Cloudflare Cron Triggers 配置完全指南：wrangler.jsonc 调度、Green Compute 与环境化 Cron 实战

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

Cron Triggers 允许你在 Cloudflare 全球网络上按 cron 表达式定时触发 Worker 执行，适合夜间数据同步、报表生成、数据库清理等周期性任务。本文以skills/.curated/cloudflare-deploy/references/cron-triggers/configuration.md为核心骨架，结合仓库内 cron-triggers 参考文档 与 wrangler 配置参考，系统讲解 wrangler.jsonc 中的 triggers.crons 配置、Green Compute 碳感知调度、多环境 schedule、REST API 管理触发器以及校验与排错要点。读完本文，你将能独立完成一个 cron Worker 从配置、部署到 API 管理的完整闭环。

Cron Triggers 核心特性一览

在深入配置之前，先明确 Cloudflare Cron Triggers 的五个关键行为（见 cron-triggers/README.md）：

• 仅按 UTC 执行：所有调度都基于 UTC 时间，不支持本地时区，配置前必须先做时区换算；
• 5 字段 cron 语法：采用 Quartz 调度器的扩展语法，支持L、W、#等特殊字符；
• 全局传播延迟：部署或修改触发器后，全球生效最长需要 15 分钟；
• 至少一次投递（At-least-once）：极端情况下可能出现重复执行，业务侧需具备幂等性；
• 可选 Green Compute：支持低碳时段的碳感知调度，适用于时间弹性较大的批处理任务。

此外，Cron Triggers 可以与 Workflows 集成，用于触发长时多步骤任务；Worker 在运行期间仅占用空闲计算资源（underutilized periods）。

wrangler.jsonc 基础配置：声明 Cron 触发器

Cron Triggers 的声明入口是 Worker 的 wrangler 配置文件（推荐使用 wrangler.jsonc，从 Wrangler v3.91.0 起提供 schema 校验支持，见 wrangler/configuration.md）。

一个最小可用的配置示例如下：

{ "$schema": "./node_modules/wrangler/config-schema.json", "name": "my-cron-worker", "main": "src/index.ts", "compatibility_date": "2025-01-01", // Use current date for new projects "triggers": { "crons": [ "*/5 * * * *", // Every 5 minutes "0 */2 * * *", // Every 2 hours "0 9 * * MON-FRI", // Weekdays at 9am UTC "0 2 1 * *" // Monthly on 1st at 2am UTC ] } }

各字段说明：

• $schema：指向本地 wrangler 的 JSON Schema 文件，让 IDE 提供配置补全与校验；
• name：Worker 名称，部署到 Cloudflare 后作为脚本标识；
• main：入口文件，Worker 的scheduled处理器就导出于此（详见后文）；
• compatibility_date：兼容性日期，新项目建议填写当前日期；
• triggers.crons：cron 表达式字符串数组，一个 Worker 可同时声明多条调度。免费套餐每 Worker 最多 3 个触发器，付费套餐不限数量（见 gotchas.md 的限制表）。

Cron 表达式格式与特殊字符

Cron Triggers 使用5 字段的 Quartz 风格语法，结构为：

┌─────────── minute (0-59) │ ┌───────── hour (0-23) │ │ ┌─────── day of month (1-31) │ │ │ ┌───── month (1-12, JAN-DEC) │ │ │ │ ┌─── day of week (1-7, SUN-SAT, 1=Sunday) * * * * *

支持的特殊字符：

• *（任意值）
• ,（列表，如0,30 * * * *）
• -（范围，如9-17）
• /（步进，如*/5）
• L（Last，最后一天 / 最后一个星期几）
• W（Weekday，最近的工作日）
• #（第 N 个星期几）

常用调度示例（引自 cron-triggers/README.md）：

*/5 * * * * # Every 5 minutes 0 * * * * # Hourly 0 2 * * * # Daily 2am UTC (off-peak) 0 9 * * MON-FRI # Weekdays 9am UTC 0 0 1 * * # Monthly 1st midnight UTC 0 9 L * * # Last day of month 9am UTC 0 10 * * MON#2 # 2nd Monday 10am UTC */10 9-17 * * MON-FRI # Every 10min, 9am-5pm weekdays

注意 day-of-week 的取值与多数 Unix crontab 不同：Cloudflare 采用1 表示 Sunday，7 表示 Saturday。

Green Compute（Beta）：碳感知调度

Green Compute 允许将 cron 调度到电网碳排放强度较低的时段执行，实现低碳感知执行。这是配置文件中placement字段与triggers配合使用的场景：

{ "name": "eco-cron-worker", "triggers": { "crons": ["0 2 * * *"] }, "placement": { "mode": "smart" // Runs during low-carbon periods } }

两种模式对比：

工作原理：

• Cloudflare 会推迟执行，直到所在区域电网的碳强度（grid carbon intensity）更低时再运行；
• 从计划时间起，最大延迟 24 小时；
• 适合对执行时间弹性要求较高的批处理任务。

适用场景：

• 夜间数据处理与 ETL 管道（Nightly data processing and ETL pipelines）
• 周报/月报生成（Weekly/monthly report generation）
• 数据库备份与维护（Database backups and maintenance）
• 分析数据聚合（Analytics aggregation）
• ML 模型训练（ML model training）

不适用场景：

• 对时间敏感的操作（有 SLA 要求）
• 面向用户、需要立即执行的功能
• 实时监控与告警
• 有严格时间窗口的合规任务

需要说明的是，placement字段本身在 wrangler 中是一个独立配置项（见 wrangler/configuration.md 的 Placement 一节）："smart"模式通常表示将 Worker 运行在靠近数据源（如 D1、Durable Objects）的位置以降低延迟，而在这里与 cron 配合时则体现为碳感知调度能力；默认不配置时 Worker 按标准方式分布运行。

环境特定调度：多环境 Cron 配置

实际项目中，生产、预发、开发环境的调度频率往往不同。wrangler 支持在env字段中按环境覆盖triggers：

{ "name": "my-cron-worker", "triggers": { "crons": ["0 */6 * * *"] // Prod: every 6 hours }, "env": { "staging": { "triggers": { "crons": ["*/15 * * * *"] // Staging: every 15min } }, "dev": { "triggers": { "crons": ["*/5 * * * *"] // Dev: every 5min } } } }

上面的配置中：顶层（默认环境）每 6 小时运行一次作为生产调度；staging 每 15 分钟一次；dev 每 5 分钟一次。部署时用npx wrangler deploy --env staging或--env dev指定目标环境。

这与 wrangler 的环境字段继承规则一致（见 wrangler/configuration.md 的 Field Inheritance 一节）：name、main、compatibility_date、routes、triggers是可继承字段，而vars、KV/D1/R2 等绑定属于不可继承字段，需要在每个环境下单独定义。

管理触发器：删除全部与保留现有

对triggers字段的操作有两种常见需求：

• 删除所有触发器：将crons置为空数组：

{ "triggers": { "crons": [] } }

• 保留现有触发器、仅修改其他配置：直接省略整个"triggers"字段，这样部署时不会改动已存在的 cron 调度。

部署与生效时间

配置完成后即可通过 Wrangler 部署：

# Deploy with config crons npx wrangler deploy # Deploy specific environment npx wrangler deploy --env production # View deployments npx wrangler deployments list

⚠️ 重要：触发器变更后最长需要15 分钟才会在全球传播生效。排查“cron 未执行”问题时，需确认是否处于传播窗口内（见 gotchas.md）。

部署前需要先完成身份认证，可运行npx wrangler whoami检查；本地开发可用wrangler login（一次性 OAuth），CI/CD 环境则设置CLOUDFLARE_API_TOKEN环境变量（见 SKILL.md）。

通过 REST API 管理触发器

除了配置文件，还可以通过 Cloudflare REST API 动态管理 Worker 的调度触发器（脚本schedules接口）。

获取当前触发器列表：

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules" \ -H "Authorization: Bearer {api_token}"

更新触发器（覆盖式写入）：

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules" \ -H "Authorization: Bearer {api_token}" \ -H "Content-Type: application/json" \ -d '{"crons": ["*/5 * * * *", "0 2 * * *"]}'

清空全部触发器：

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/workers/scripts/{script_name}/schedules" \ -H "Authorization: Bearer {api_token}" \ -H "Content-Type: application/json" \ -d '{"crons": []}'

三个示例中{account_id}、{script_name}、{api_token}分别替换为你的账户 ID、Worker 脚本名和 API Token。

组合多个 Worker 应对复杂调度

当单个 Worker 的调度需求过于复杂时，官方推荐拆分到多个 Worker，每个 Worker 只承担一种频率的职责：

// worker-frequent.jsonc { "name": "data-sync-frequent", "triggers": { "crons": ["*/5 * * * *"] } } // worker-daily.jsonc { "name": "reports-daily", "triggers": { "crons": ["0 2 * * *"] }, "placement": { "mode": "smart" } } // worker-weekly.jsonc { "name": "cleanup-weekly", "triggers": { "crons": ["0 3 * * SUN"] } }

多 Worker 拆分带来的收益：

• 每个 Worker 拥有独立的 CPU 限制，避免相互挤占配额；
• 独立错误隔离，一个 Worker 失败不影响其他调度；
• 可为不同任务配置不同的 Green Compute 策略；
• 职责单一，更易于维护和调试。

校验与常见配置错误

语法校验：

• 可借助 crontab.guru 这类交互式校验器测试 cron 表达式；
• Wrangler 在部署时会对 cron 语法做校验，但不会捕获逻辑错误（例如表达式是否符合你的真实意图）。

常见错误（引自 configuration.md 与 gotchas.md）：

• 0 0 * * *表示每天 UTC 零点运行，而不是你的本地时区零点——务必先做 UTC 换算；
• */60 * * * *是非法表达式（分钟字段最大 59），按小时执行应写作0 * * * *；
• 0 2 31 * *只在有 31 天的月份才会运行；
• 调试本地执行时，/__scheduled端点要求 URL 编码：空格用+代替，如curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*"，未编码的原始空格会导致触发失败。

配套能力：scheduled 处理器与本地测试

配置文件中的triggers只是声明调度，实际执行逻辑需要 Worker 导出scheduled处理器（详见 cron-triggers/api.md）：

export default { async scheduled( controller: ScheduledController, env: Env, ctx: ExecutionContext, ): Promise<void> { console.log("Cron:", controller.cron); console.log("Time:", new Date(controller.scheduledTime)); ctx.waitUntil(asyncTask(env)); // Non-blocking }, };

ScheduledController提供scheduledTime（计划执行的 Unix 毫秒时间戳）、cron（触发本执行的表达式）和noRetry()（阻止失败后自动重试）。ctx.waitUntil()可延长执行以承载异步任务，但需注意给传入的 Promise 做错误处理，避免静默失败。

本地开发时通过 wrangler 的__scheduled端点模拟触发：

npx wrangler dev curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*" curl "http://localhost:8787/__scheduled?cron=0+2+*+*+*&scheduledTime=1704067200000"

其中cron为必填参数（空格用+编码），scheduledTime可选，默认为当前时间。注意该测试端点在生产的 Worker 上同样可用，需在fetch处理器中拦截/__scheduled路径或校验来源头，防止被外部任意触发（见 gotchas.md 的 Security Concerns 一节）。

由于投递语义是 at-least-once，重复执行可能带来重复副作用（重复扣费、重复邮件），推荐用 KV 记录cron-scheduledTime作为执行 ID 实现幂等去重，并在检测到重复时调用controller.noRetry()（幂等示例见 patterns.md）。仓库中还提供了 API 数据同步、数据库清理、报表生成、健康检查、队列集成、Durable Objects 分布式锁、Python handler（class Default(WorkerEntrypoint)）等完整的 cron-triggers/patterns.md 示例可供参考。

限制与配额速查

以下限制汇总自 cron-triggers/README.md 与 cron-triggers/gotchas.md：

延伸阅读

• cron-triggers/README.md —— 概览、快速上手与常见调度示例
• cron-triggers/api.md —— ScheduledController、noRetry()、waitUntil 与测试模式
• cron-triggers/patterns.md —— 多 cron 路由、幂等、监控与 Durable Objects 协调示例
• cron-triggers/gotchas.md —— 时区问题、重复执行、安全加固与测试最佳实践
• wrangler/configuration.md —— wrangler.jsonc 全部字段与环境继承规则

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills