名称: cloudflare-cron-triggers 描述: Cloudflare Cron Triggers用于定时执行Workers的触发器。适用于周期性任务、定时作业，或遇到处理器未找到、无效cron表达式、时区错误时使用。

关键词: cloudflare cron, cron triggers, scheduled workers, scheduled handler, periodic tasks, background jobs, scheduled tasks, cron expression, wrangler crons, scheduled event, green compute, workflow triggers, maintenance tasks, scheduled() handler, ScheduledController, UTC timezone 许可证: MIT

Cloudflare Cron Triggers

状态: 生产就绪 ✅ 最后更新: 2025-11-25 依赖: cloudflare-worker-base（用于Worker设置） 最新版本: wrangler@4.50.0, @cloudflare/workers-types@4.20251125.0

快速入门（5分钟）

1. 向您的Worker添加定时处理器

src/index.ts:

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（不能是scheduledHandler或onScheduled）
必须在默认导出对象中导出
必须使用ES模块格式（不是Service Worker格式）

2. 在Wrangler中配置Cron触发器

wrangler.jsonc:

{
  "name": "my-scheduled-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-23",
  "triggers": {
    "crons": [
      "0 * * * *"  // 每小时的第0分钟
    ]
  }
}

关键:

Cron表达式使用5个字段：分钟小时月日月周几
所有时间均为UTC时区（无时区转换）
更改需要最多15分钟在全球传播

3. 本地测试

# 启用定时测试
bunx wrangler dev --test-scheduled

# 在另一个终端，触发定时处理器
curl "http://localhost:8787/__scheduled?cron=0+*+*+*+*"

# 在wrangler dev终端查看输出

测试技巧:

/__scheduled端点仅在使用--test-scheduled标志时可用
可以在查询参数中传递任何cron表达式
Python Workers使用/cdn-cgi/handler/scheduled代替

4. 部署

npm run deploy
# 或
bunx wrangler deploy

部署后:

更改可能需要最多15分钟传播
检查仪表板：Workers & Pages > [您的Worker] > Cron Triggers
在日志选项卡查看历史执行

何时加载参考

当用户提及以下内容时立即加载:

cron-expressions-reference.md → “cron语法”, “调度格式”, “表达式”, “分钟小时日”, “每X分钟”
common-patterns.md → “示例”, “用例”, “模式”, “真实世界”, “数据库清理”, “报告生成”, “如何”
integration-patterns.md → “实现”, “Hono”, “多触发器”, “绑定”, “工作流”, “错误处理”
wrangler-config.md → “配置”, “wrangler.jsonc”, “多cron”, “环境特定”, “开发阶段生产”
testing-guide.md → “测试”, “本地开发”, “__scheduled”, “单元测试”, “curl”, “调试”

主动加载时:

构建新定时任务 → 加载integration-patterns.md
配置wrangler.jsonc → 加载wrangler-config.md
调试cron表达式 → 加载cron-expressions-reference.md
本地测试 → 加载testing-guide.md
查找示例 → 加载common-patterns.md

Cron表达式语法

五字段格式

* * * * *
│ │ │ │ │
│ │ │ │ └─── 周几（0-6，周日=0）
│ │ │ └───── 月（1-12）
│ │ └─────── 月日（1-31）
│ └───────── 小时（0-23）
└─────────── 分钟（0-59）

特殊字符

字符	含义	示例
`*`	每	`* * * * *` = 每分钟
`,`	列表	`0,30 * * * *` = 每小时的第0和30分钟
`-`	范围	`0 9-17 * * *` = 从9点到17点每小时
`/`	步长	`/15 * * *` = 每15分钟

常见模式

# 每分钟
* * * * *

# 每5分钟
*/5 * * * *

# 每15分钟
*/15 * * * *

# 每小时第0分钟
0 * * * *

# 每小时第30分钟
30 * * * *

# 每6小时
0 */6 * * *

# 每天午夜（00:00 UTC）
0 0 * * *

# 每天中午（12:00 UTC）
0 12 * * *

# 每天凌晨3:30 UTC
30 3 * * *

# 每周一上午9点 UTC
0 9 * * 1

# 每个工作日上午9点 UTC
0 9 * * 1-5

# 每周日午夜 UTC
0 0 * * 0

# 每月第一天午夜 UTC
0 0 1 * *

# 每天两次（6点和18点 UTC）
0 6,18 * * *

# 工作时间每30分钟（9点到17点 UTC，工作日）
*/30 9-17 * * 1-5

关键: 仅UTC时区

所有cron触发器在UTC时间执行
无时区转换可用
手动将本地时间转换为UTC
示例：9am PST = 5pm UTC（DST期间为下一天）

ScheduledController接口

interface ScheduledController {
  readonly cron: string;           // 触发此执行的cron表达式
  readonly type: string;           // 总是"scheduled"
  readonly scheduledTime: number;  // 计划执行时间的Unix时间戳（毫秒）
}

属性

`controller.cron`（字符串）

触发此执行的cron表达式。

export default {
  async scheduled(controller: ScheduledController, env: Env): Promise<void> {
    console.log(`Triggered by: ${controller.cron}`);
    // 输出："Triggered by: 0 * * * *"
  },
};

用例: 区分多个cron调度（见多cron触发器模式）。

`controller.type`（字符串）

对于cron触发的执行，总是返回"scheduled"。

if (controller.type === 'scheduled') {
  // 这是cron触发的执行
}

`controller.scheduledTime`（数字）

计划执行时间的Unix时间戳（自纪元以来的毫秒）。

export default {
  async scheduled(controller: ScheduledController): Promise<void> {
    const scheduledDate = new Date(controller.scheduledTime);
    console.log(`Scheduled for: ${scheduledDate.toISOString()}`);
    // 输出："Scheduled for: 2025-10-23T15:00:00.000Z"
  },
};

注意: 这是计划时间，不是实际执行时间。由于系统负载，实际执行可能稍有延迟（通常<1秒）。

执行上下文

export default {
  async scheduled(
    controller: ScheduledController,
    env: Env,
    ctx: ExecutionContext  // ← 执行上下文
  ): Promise<void> {
    // 使用ctx.waitUntil()用于应在完成后继续的异步操作
    ctx.waitUntil(logToAnalytics(env));
  },
};

`ctx.waitUntil(promise: Promise<any>)`

扩展执行上下文，以等待异步操作在处理器返回后完成。

用例:

记录到外部服务
分析跟踪
清理操作
非关键后台任务

export default {
  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext): Promise<void> {
    // 关键任务 - 必须在处理器退出前完成
    await processData(env);

    // 非关键任务 - 可以在后台完成
    ctx.waitUntil(sendMetrics(env));
    ctx.waitUntil(cleanupOldData(env));
    ctx.waitUntil(notifySlack({ message: 'Cron completed' }));
  },
};

重要: 第一个失败的waitUntil()将在仪表板日志中报告为状态。

集成模式

6个生产就绪cron模式:

独立Worker与Cron - 用于后台任务的单个定时函数（数据库清理、报告生成）
Hono + Cron组合 - HTTP端点 + 定时任务在一个Worker中，共享绑定和降低成本
多Cron触发器 - 使用controller.cron路由执行的不同任务的不同调度
访问绑定 - 在定时函数中使用D1、KV、R2、AI、Vectorize、Queues、Workflows、Durable Objects
与Workflows集成 - 在调度上触发复杂、长时间运行的多步工作流
错误处理最佳实践 - 全面的错误处理，包括重试逻辑、告警（Slack/邮件）、失败记录和监控

加载references/integration-patterns.md获取完整实现，包括代码示例、配置详情和最佳实践。

Wrangler配置

在wrangler.jsonc的triggers.crons数组中添加cron触发器。每个触发器需要cron表达式。支持多个cron（免费：最多3个，付费：更高限制）和针对开发/阶段/生产部署的环境特定配置。

加载references/wrangler-config.md获取完整配置示例，包括多触发器、环境特定调度、时区处理和移除步骤。

测试与开发

使用/__scheduled端点本地测试定时函数，通过运行bunx wrangler dev --test-scheduled，然后用curl "http://localhost:8787/__scheduled?cron=0+*+*+*+*"触发处理器（在cron表达式中用+代替空格）。

加载references/testing-guide.md获取完整测试策略，包括本地开发设置、单元测试示例、集成测试模式和产品监控技术。

绿色计算

仅在由可再生能源供电的数据中心运行cron触发器。

启用绿色计算

通过仪表板:

前往Workers & Pages
在账户详情部分，找到计算设置
点击更改
选择绿色计算
点击确认

适用于:

您账户中的所有cron触发器
减少碳足迹
无额外成本
在某些地区可能引入轻微延迟

工作原理:

Cloudflare将cron执行路由到绿色供电的数据中心
使用可再生能源：风能、太阳能、水电
通过电力购买协议（PPAs）和可再生能源证书（RECs）验证

预防已知问题

本技能预防6个记录的问题：

问题 #1: Cron更改未传播

错误: Cron触发器在wrangler.jsonc中更新但未执行

来源: Cloudflare 文档 - Cron Triggers

原因:

更改cron触发器需要最多15分钟在全球传播
Cloudflare网络需要时间更新边缘节点
无常规部署的即时传播

预防:

部署后等待15分钟再期望执行
检查仪表板：Workers & Pages > [Worker] > Cron Triggers
使用wrangler triggers deploy仅更改触发器

# 如果仅更改了触发器（不是代码），使用：
bunx wrangler triggers deploy

# 等待15分钟，然后在仪表板中验证

问题 #2: 处理器未导出

错误: Handler does not export a 'scheduled' method

来源: 常见部署错误

原因:

处理器未精确命名为scheduled
处理器未在默认导出对象中导出
使用Service Worker格式而不是ES模块格式

预防:

// ❌ 错误：处理器名称不正确
export default {
  async scheduledHandler(controller, env, ctx) { }
};

// ❌ 错误：不在默认导出中
export async function scheduled(controller, env, ctx) { }

// ✅ 正确：在默认导出中名为'scheduled'
export default {
  async scheduled(controller, env, ctx) { }
};

问题 #3: UTC时区混淆

错误: Cron在错误时间运行

来源: 用户期望与实际不符

原因:

所有cron触发器仅在UTC时间运行
无时区转换可用
用户期望本地时区

预防:

手动将本地时间转换为UTC：

// 想在PST 9am（UTC-8）运行？
// PST 9am = UTC 5pm（17:00）
{
  "triggers": {
    "crons": ["0 17 * * *"]  // PST 9am = UTC 5pm
  }
}

// 想在EST 6pm（UTC-5）运行？
// EST 6pm = UTC 11pm（23:00）
{
  "triggers": {
    "crons": ["0 23 * * *"]  // EST 6pm = UTC 11pm
  }
}

// 记住：DST更改影响转换！
// PST是UTC-8，PDT是UTC-7

工具:

问题 #4: 无效Cron表达式

错误: Cron未执行，无错误显示

来源: 静默验证失败

原因:

无效cron语法静默失败
验证在部署时发生，但可能不明显
常见错误：错误字段顺序、无效范围

预防:

# ❌ 错误：太多字段（6个而不是5个）
"crons": ["0 0 * * * *"]  # 有秒字段 - 不支持

# ❌ 错误：无效分钟范围
"crons": ["65 * * * *"]  # 分钟必须是0-59

# ❌ 错误：无效周几
"crons": ["0 0 * * 7"]  # 周几是0-6（周日用0）

# ✅ 正确：5个字段，有效范围
"crons": ["0 0 * * 0"]  # 周日午夜UTC

验证:

使用Crontab Guru验证表达式
检查wrangler部署输出中的错误
用--test-scheduled本地测试

问题 #5: 缺少ES模块格式

错误: Worker must use ES modules format

来源: 旧Service Worker格式

原因:

定时处理器需要ES模块格式
旧的Service Worker格式不支持
代码库中混合格式

预防:

// ❌ 错误：Service Worker格式
addEventListener('scheduled', (event) => {
  event.waitUntil(handleScheduled(event));
});

// ✅ 正确：ES模块格式
export default {
  async scheduled(controller, env, ctx) {
    await handleScheduled(controller, env, ctx);
  },
};

问题 #6: CPU时间限制超过

错误: CPU time limit exceeded

来源: 长时间运行的定时任务

原因:

默认CPU限制：30秒
长时间运行任务超过限制
无自动超时扩展

预防:

选项1: 在wrangler.jsonc中增加CPU限制

{
  "limits": {
    "cpu_ms": 300000  // 5分钟（标准计划最大）
  }
}

选项2: 使用Workflows处理长时间运行任务

// 而不是在cron中运行长时间任务：
export default {
  async scheduled(controller, env, ctx) {
    // 触发可以运行数小时的工作流
    await env.MY_WORKFLOW.create({
      params: { task: 'long-running-job' },
    });
  },
};

选项3: 分解为更小块

export default {
  async scheduled(controller, env, ctx) {
    // 批处理
    const batch = await getNextBatch(env.DB);

    for (const item of batch) {
      await processItem(item);
    }

    // 如果有更多工作，发送到队列进行下一批
    const hasMore = await hasMoreWork(env.DB);
    if (hasMore) {
      await env.MY_QUEUE.send({ type: 'continue-processing' });
    }
  },
};

总是做 ✅

使用精确处理器名称 - 必须是scheduled，不能是scheduledHandler或变体
使用ES模块格式 - 在默认对象中导出，不是addEventListener
转换为UTC - 所有cron时间都是UTC，从本地时区转换
等待15分钟 - Cron更改需要最多15分钟传播
首先本地测试 - 使用wrangler dev --test-scheduled
验证cron语法 - 使用Crontab Guru
优雅处理错误 - 记录、告警并可选重新抛出
使用ctx.waitUntil() - 用于非关键异步操作
考虑Workflows - 对于需要>30秒CPU时间的任务
监控执行 - 定期检查仪表板日志

从不做 ❌

从不假设本地时区 - 所有cron在UTC运行
从不使用6字段cron表达式 - Cloudflare使用5字段格式（无秒）
从不依赖即时传播 - 更改需要最多15分钟
从不使用Service Worker格式 - 必须使用ES模块格式
从不忘记错误处理 - 未捕获错误静默失败
从不运行CPU密集型任务而不增加限制 - 默认30秒限制
从不使用周几7 - 周日用0（仅0-6范围）
从不部署而不测试 - 始终首先用--test-scheduled测试
从不忽略执行日志 - 仪表板显示历史失败
从不硬编码调度进行测试 - 使用环境特定配置

常见用例

加载references/common-patterns.md获取10个真实世界cron模式，包括数据库清理、API数据收集、每日报告生成、缓存预热、监控与健康检查、数据同步、备份自动化、站点地图生成、Webhook处理和定时通知。

TypeScript类型

// 定时事件控制器
interface ScheduledController {
  readonly cron: string;
  readonly type: string;
  readonly scheduledTime: number;
}

// 执行上下文
interface ExecutionContext {
  waitUntil(promise: Promise<any>): void;
  passThroughOnException(): void;
}

// 定时处理器
export default {
  async scheduled(
    controller: ScheduledController,
    env: Env,
    ctx: ExecutionContext
  ): Promise<void>;
}

限制与定价

限制

功能	免费计划	付费计划
每个Worker的Cron触发器	3	更高（检查文档）
每次执行的CPU时间	10 ms（平均）	30秒（默认），5分钟（最大）
墙钟时间	30秒	15分钟
内存	128 MB	128 MB

定价

Cron触发器使用标准Workers定价：

Workers付费计划：需要$5/月
请求：$0.30每百万请求（前10M免费）
CPU时间：$0.02每百万CPU-ms（前30M免费）

Cron执行 = 1请求

示例:

Cron每小时运行（24次/天）
30天 × 24执行 = 720执行/月
平均50ms CPU时间每次执行

成本:

请求：720（远低于10M免费）
CPU时间：720 × 50ms = 36,000ms（低于30M免费）
总计：$5/月（仅订阅费）

高频率示例:

Cron每分钟运行（1440次/天）
30天 × 1440 = 43,200执行/月
仍低于免费层限制
总计：$5/月

故障排除

问题: Cron未执行

可能原因:

更改尚未传播（等待15分钟）
无效cron表达式
处理器未正确导出
Worker未部署

解决方案:

# 重新部署
bunx wrangler deploy

# 等待15分钟

# 检查仪表板
# Workers & Pages > [Worker] > Cron Triggers

# 检查日志
# Workers & Pages > [Worker] > Logs > Real-time Logs

问题: 处理器执行但失败

可能原因:

处理器中未捕获错误
CPU时间限制超过
缺少环境绑定
网络超时

解决方案:

export default {
  async scheduled(controller, env, ctx) {
    try {
      await yourTask(env);
    } catch (error) {
      // 记录详细错误
      console.error('Handler failed:', {
        error: error.message,
        stack: error.stack,
        cron: controller.cron,
        time: new Date(controller.scheduledTime),
      });

      // 发送告警
      ctx.waitUntil(sendAlert(error));

      // 重新抛出以标记为失败
      throw error;
    }
  },
};

检查仪表板日志中的错误详情。

问题: 错误执行时间

原因: UTC与本地时区混淆

解决方案:

将期望的本地时间转换为UTC：

// 想要PST 9am（UTC-8）？
// PST 9am = UTC 5pm（17:00）

{
  "triggers": {
    "crons": ["0 17 * * *"]
  }
}

工具:

世界时钟转换器
记住DST更改（PST vs PDT）

问题: 本地测试不工作

可能原因:

缺少--test-scheduled标志
错误端点（应为/__scheduled）
Python Worker（使用/cdn-cgi/handler/scheduled）

解决方案:

# 正确：启动时带标志
bunx wrangler dev --test-scheduled

# 在另一个终端
curl "http://localhost:8787/__scheduled?cron=0+*+*+*+*"

生产清单

将cron触发器部署到产品前：

[ ] 在Crontab Guru上验证cron表达式
[ ] 处理器在默认导出中精确命名为scheduled
[ ] 使用ES模块格式（不是Service Worker）
[ ] 本地时区已转换为UTC
[ ] 实现错误处理与记录
[ ] 配置失败告警
[ ] 如果需要，增加CPU限制（limits.cpu_ms）
[ ] 测试环境绑定
[ ] 用--test-scheduled本地测试
[ ] 在阶段环境中测试部署
[ ] 部署后等待15分钟传播
[ ] 在仪表板日志中验证执行
[ ] 配置监控和告警
[ ] 更新文档，包括调度详情

Cloudflare Cron Triggers

快速入门（5分钟）

1. 向您的Worker添加定时处理器

2. 在Wrangler中配置Cron触发器

3. 本地测试

4. 部署

何时加载参考

Cron表达式语法

五字段格式

特殊字符

常见模式

ScheduledController接口

属性

controller.cron（字符串）

controller.type（字符串）

controller.scheduledTime（数字）

执行上下文

ctx.waitUntil(promise: Promise<any>)

集成模式

Wrangler配置

测试与开发

绿色计算

启用绿色计算

预防已知问题

问题 #1: Cron更改未传播

问题 #2: 处理器未导出

问题 #3: UTC时区混淆

问题 #4: 无效Cron表达式

问题 #5: 缺少ES模块格式

问题 #6: CPU时间限制超过

总是做 ✅

从不做 ❌

常见用例

TypeScript类型

限制与定价

限制

定价

故障排除

问题: Cron未执行

问题: 处理器执行但失败

问题: 错误执行时间

问题: 本地测试不工作

生产清单

相关文档

`controller.cron`（字符串）

`controller.type`（字符串）

`controller.scheduledTime`（数字）

`ctx.waitUntil(promise: Promise<any>)`