Cron 触发器

Cron 触发器允许用户将 cron 表达式映射到 Worker，使用 scheduled() 处理程序，使 Workers 能够按计划执行。

Cron 触发器非常适合运行周期性任务，例如维护或调用第三方 API 以收集最新数据。由 Cron 触发器调度的 Workers 将在利用率较低的机器上运行，以充分利用 Cloudflare 的容量并高效路由流量。

Cron 触发器按 UTC 时间执行。

要响应 Cron 触发器，必须向 Worker 添加 "scheduled" 处理程序。

export default {
	async scheduled(controller, env, ctx) {
		console.log("cron processed");
	},
};

interface Env {}
export default {
	async scheduled(
		controller: ScheduledController,
		env: Env,
		ctx: ExecutionContext,
	) {
		console.log("cron processed");
	},
};

from workers import WorkerEntrypoint

class Default(WorkerEntrypoint):
    async def scheduled(self, controller, env, ctx):
        # All four parameters (self, controller, env, ctx) are required
        print("cron processed")

请参考以下其他示例编写代码：

• 设置 Cron 触发器
• 多个 Cron 触发器

更新 Worker 代码以包含 "scheduled" 事件后，必须更新 Worker 项目配置。

如果 Worker 由 Wrangler 管理，Cron 触发器应仅通过 Wrangler 配置文件 管理。

请参考以下 Cron 触发器配置示例：

{
	"triggers": {
		// Schedule cron triggers:
		// - At every 3rd minute
		// - At 15:00 (UTC) on first day of the month
		// - At 23:59 (UTC) on the last weekday of the month
		"crons": [
			"*/3 * * * *",
			"0 15 1 * *",
			"59 23 LW * *"
		]
	}
}

[triggers]
crons = [ "*/3 * * * *", "0 15 1 * *", "59 23 LW * *" ]

您还可以在 Wrangler 配置文件 中为每个环境 设置不同的 Cron 触发器。您需要将 triggers 数组放在所选环境下。例如：

{
	"env": {
		"dev": {
			"triggers": {
				"crons": [
					"0 * * * *"
				]
			}
		}
	}
}

[env.dev.triggers]
crons = [ "0 * * * *" ]

要在 Cloudflare 仪表板中添加 Cron 触发器：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 在 Overview（概览） 中，选择您的 Worker > Settings（设置） > Triggers（触发器） > Cron Triggers（Cron 触发器）。

Cloudflare 支持五字段 cron 表达式，以及大多数类似 Quartz scheduler ↗ 的 cron 语法扩展：

设置 Cron 触发器时可能有用的一些常见时间间隔：

• * * * * *

  • 每分钟

• */30 * * * *

  • 每 30 分钟

• 45 * * * *

  • 每小时的第 45 分钟

• 0 17 * * sun 或 0 17 * * 1

  • 星期日 17:00（UTC）

• 10 7 * * mon-fri 或 10 7 * * 2-6

  • 工作日 07:10（UTC）

• 0 15 1 * *

  • 每月第一天 15:00（UTC）

• 0 18 * * 6L 或 0 18 * * friL

  • 每月最后一个星期五 18:00（UTC）

• 59 23 LW * *

  • 每月最后一个工作日 23:59（UTC）

使用 Wrangler 和 wrangler dev，或 Cloudflare Vite plugin 测试 Cron 触发器。这会暴露 /cdn-cgi/handler/scheduled 路由，可用于通过 HTTP 请求进行测试。如果使用 Cloudflare Vite Plugin，请确保对以下命令使用正确的 vite 端口（Vite 默认为 5173）。

curl "http://localhost:8787/cdn-cgi/handler/scheduled"

默认情况下，端点以文本形式返回 scheduled 处理程序结果。要返回 JSON 格式的结构化 scheduled 处理程序结果，请传递 ?format=json。

curl "http://localhost:8787/cdn-cgi/handler/scheduled?format=json"

{
  "outcome": "ok",
  "noRetry": false
}

当 scheduled 处理程序调用 controller.noRetry() 时，noRetry 字段为 true。

要模拟不同的 cron 模式，可以传递 cron 查询参数。

curl "http://localhost:8787/cdn-cgi/handler/scheduled?cron=*+*+*+*+*"

（可选）您还可以传递 time 查询参数以覆盖 scheduled 事件监听器中的 controller.scheduledTime。

curl "http://localhost:8787/cdn-cgi/handler/scheduled?cron=*+*+*+*+*&time=1745856238000"

要查看 Cron 触发器的执行历史，请查看 Cron Events（Cron 事件）：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 在 Overview（概览） 中，选择您的 Worker。

3. 选择 Settings（设置）。

4. 在 Trigger Events（触发事件） 下，选择 View events（查看事件）。

Cron Events 存储 Cron 计划事件最近 100 次调用。Workers Logs 也会记录 Cron 触发器的调用日志，保留期更长并提供过滤和查询界面。如果您对访问 Cron Events 的 API 感兴趣，请使用 Cloudflare 的 GraphQL Analytics API。

有关更多信息，请参阅指标和分析。

要通过仪表板删除已部署 Worker 上的 Cron 触发器：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择您的 Worker。

3. 前往 Triggers（触发器） > 选择要删除的 Cron 触发器旁的三点图标 > Delete（删除）。

如果 Worker 由 Wrangler 管理，Cron 触发器应仅通过 Wrangler 配置文件 管理。

使用 Wrangler 部署 Worker 时，任何先前的 Cron 触发器都会被 triggers 数组中指定的触发器替换。

• 如果 crons 属性为空数组，则删除所有 Cron 触发器。
• 如果 triggers 或 crons 属性为 undefined，则保留当前已部署的 Cron 触发器。

{
	"triggers": {
		// Remove all cron triggers:
		"crons": []
	}
}

[triggers]
crons = [ ]

请参阅限制了解每个 Worker 的 Cron 触发器最大数量。

启用 Green Compute 后，Cron 触发器将仅在由纯可再生能源供电的数据中心内的 Cloudflare 接入点运行。如果组织已采购足够的可再生能源以覆盖其总体能源使用，则可以声称由 100% 可再生能源供电。

可再生能源可以通过多种方式购买，包括现场发电（风力涡轮机、太阳能电池板）、通过称为购电协议（PPA）的合同协议直接从可再生能源生产商购买，或以可再生能源证书（REC、IREC、GoO）形式从能源信用市场购买。

Green Compute 可在账户级别配置：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 在 Account details（账户详情） 部分，找到 Compute Setting（计算设置）。

3. 选择 Change（更改）。

4. 选择 Green Compute（绿色计算）。

5. 选择 Confirm（确认）。

• Triggers - 查看 Cron 触发器的 Wrangler 配置文件语法。
• 了解如何在 ES modules 语法 中访问 Cron 触发器以获得优化体验。