尧图网站建设 
Cloudflare Cron Triggers 配置完全指南wrangler.jsonc 调度、Green Compute 与环境化 Cron 实战【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsCron 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 提供配置补全与校验nameWorker 名称部署到 Cloudflare 后作为脚本标识main入口文件Worker 的scheduled处理器就导出于此详见后文compatibility_date兼容性日期新项目建议填写当前日期triggers.cronscron 表达式字符串数组一个 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, 1Sunday) * * * * *支持的特殊字符*任意值,列表如0,30 * * * *-范围如9-17/步进如*/5LLast最后一天 / 最后一个星期几WWeekday最近的工作日#第 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 表示 Sunday7 表示 Saturday。Green ComputeBeta碳感知调度Green Compute 允许将 cron 调度到电网碳排放强度较低的时段执行实现低碳感知执行。这是配置文件中placement字段与triggers配合使用的场景{ name: eco-cron-worker, triggers: { crons: [0 2 * * *] }, placement: { mode: smart // Runs during low-carbon periods } }两种模式对比模式行为smart碳感知调度可能延迟最多 24 小时以寻找最优执行窗口默认不配置 placement标准调度按 cron 表达式准时执行无延迟工作原理Cloudflare 会推迟执行直到所在区域电网的碳强度grid carbon intensity更低时再运行从计划时间起最大延迟 24 小时适合对执行时间弹性要求较高的批处理任务。适用场景夜间数据处理与 ETL 管道Nightly data processing and ETL pipelines周报/月报生成Weekly/monthly report generation数据库备份与维护Database backups and maintenance分析数据聚合Analytics aggregationML 模型训练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一次性 OAuthCI/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.md0 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.mdexport default { async scheduled( controller: ScheduledController, env: Env, ctx: ExecutionContext, ): Promisevoid { 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?cron02***scheduledTime1704067200000其中cron为必填参数空格用编码scheduledTime可选默认为当前时间。注意该测试端点在生产的 Worker 上同样可用需在fetch处理器中拦截/__scheduled路径或校验来源头防止被外部任意触发见 gotchas.md 的 Security Concerns 一节。由于投递语义是 at-least-once重复执行可能带来重复副作用重复扣费、重复邮件推荐用 KV 记录cron-scheduledTime作为执行 ID 实现幂等去重并在检测到重复时调用controller.noRetry()幂等示例见 patterns.md。仓库中还提供了 API 数据同步、数据库清理、报表生成、健康检查、队列集成、Durable Objects 分布式锁、Python handlerclass Default(WorkerEntrypoint)等完整的 cron-triggers/patterns.md 示例可供参考。限制与配额速查以下限制汇总自 cron-triggers/README.md 与 cron-triggers/gotchas.md限制项免费版付费版说明每 Worker 触发器数3不限每个 Worker 可配置的最大 cron 调度数CPU 时间10ms50ms超时可使用ctx.waitUntil()或 Workflows 承载重任务执行保证At-least-onceAt-least-once可能重复需幂等处理传播延迟最长 15 分钟最长 15 分钟变更全球生效所需时间最小间隔1 分钟1 分钟无法配置更频繁的调度执行精度±1 分钟±1 分钟执行时间可能略有漂移延伸阅读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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cloudflare Cron Triggers 配置完全指南：wrangler.jsonc 调度、Green Compute 与环境化 Cron 实战
Cloudflare Cron Triggers 配置完全指南wrangler.jsonc 调度、Green Compute 与环境化 Cron 实战【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsCron 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 提供配置补全与校验nameWorker 名称部署到 Cloudflare 后作为脚本标识main入口文件Worker 的scheduled处理器就导出于此详见后文compatibility_date兼容性日期新项目建议填写当前日期triggers.cronscron 表达式字符串数组一个 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, 1Sunday) * * * * *支持的特殊字符*任意值,列表如0,30 * * * *-范围如9-17/步进如*/5LLast最后一天 / 最后一个星期几WWeekday最近的工作日#第 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 表示 Sunday7 表示 Saturday。Green ComputeBeta碳感知调度Green Compute 允许将 cron 调度到电网碳排放强度较低的时段执行实现低碳感知执行。这是配置文件中placement字段与triggers配合使用的场景{ name: eco-cron-worker, triggers: { crons: [0 2 * * *] }, placement: { mode: smart // Runs during low-carbon periods } }两种模式对比模式行为smart碳感知调度可能延迟最多 24 小时以寻找最优执行窗口默认不配置 placement标准调度按 cron 表达式准时执行无延迟工作原理Cloudflare 会推迟执行直到所在区域电网的碳强度grid carbon intensity更低时再运行从计划时间起最大延迟 24 小时适合对执行时间弹性要求较高的批处理任务。适用场景夜间数据处理与 ETL 管道Nightly data processing and ETL pipelines周报/月报生成Weekly/monthly report generation数据库备份与维护Database backups and maintenance分析数据聚合Analytics aggregationML 模型训练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一次性 OAuthCI/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.md0 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.mdexport default { async scheduled( controller: ScheduledController, env: Env, ctx: ExecutionContext, ): Promisevoid { 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?cron02***scheduledTime1704067200000其中cron为必填参数空格用编码scheduledTime可选默认为当前时间。注意该测试端点在生产的 Worker 上同样可用需在fetch处理器中拦截/__scheduled路径或校验来源头防止被外部任意触发见 gotchas.md 的 Security Concerns 一节。由于投递语义是 at-least-once重复执行可能带来重复副作用重复扣费、重复邮件推荐用 KV 记录cron-scheduledTime作为执行 ID 实现幂等去重并在检测到重复时调用controller.noRetry()幂等示例见 patterns.md。仓库中还提供了 API 数据同步、数据库清理、报表生成、健康检查、队列集成、Durable Objects 分布式锁、Python handlerclass Default(WorkerEntrypoint)等完整的 cron-triggers/patterns.md 示例可供参考。限制与配额速查以下限制汇总自 cron-triggers/README.md 与 cron-triggers/gotchas.md限制项免费版付费版说明每 Worker 触发器数3不限每个 Worker 可配置的最大 cron 调度数CPU 时间10ms50ms超时可使用ctx.waitUntil()或 Workflows 承载重任务执行保证At-least-onceAt-least-once可能重复需幂等处理传播延迟最长 15 分钟最长 15 分钟变更全球生效所需时间最小间隔1 分钟1 分钟无法配置更频繁的调度执行精度±1 分钟±1 分钟执行时间可能略有漂移延伸阅读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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考