[ PROMPT_NODE_24046 ]
Cron Triggers API 参考
[ SKILL_DOCUMENTATION ]
# Cron 触发器 API
## 基础处理器
typescript
export default {
async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext): Promise {
console.log("Cron 执行时间:", new Date(controller.scheduledTime));
},
};
**JavaScript:** 相同的签名，无需类型定义
**Python:** `class Default(WorkerEntrypoint): async def scheduled(self, controller, env, ctx)`
## ScheduledController
typescript
interface ScheduledController {
scheduledTime: number; // 预定运行的 Unix 时间戳（毫秒）
cron: string; // 触发任务的表达式 (例如 "*/5 * * * *")
type: string; // 始终为 "scheduled"
noRetry(): void; // 防止失败时自动重试
}
**防止失败时重试:**
typescript
export default {
async scheduled(controller, env, ctx) {
try {
await riskyOperation(env);
} catch (error) {
// 不重试 - 失败是预期内/可接受的
controller.noRetry();
console.error("操作失败，不进行重试:", error);
}
},
};
**何时使用 noRetry():**
- 超出你控制范围的外部 API 故障（避免对故障服务进行持续请求）
- 速率限制错误（重试会立即再次失败）
- 检测到重复执行（幂等性检查失败）
- 可跳过的非关键操作（分析、缓存）
- 不会通过重试解决的验证错误
## 处理器参数
**`controller: ScheduledController`**
- 访问 cron 表达式和预定时间
**`env: Env`**
- 所有绑定：KV, R2, D1, 密钥, 服务绑定
**`ctx: ExecutionContext`**
- `ctx.waitUntil(promise)` - 延长异步任务的执行时间（日志记录、清理、外部 API 调用）
- 首次 `waitUntil` 失败会被记录在 Cron 事件中
## 多重调度
typescript
export default {
async scheduled(controller, env, ctx) {
switch (controller.cron) {
case "*/3 * * * *": ctx.waitUntil(updateRecentData(env)); break;
case "0 * * * *": ctx.waitUntil(processHourlyAggregation(env)); break;
case "0 2 * * *": ctx.waitUntil(performDailyMaintenance(env)); break;
default: console.warn(`未处理的 cron: ${controller.cron}`);
}
},
};
## ctx.waitUntil 用法
typescript
export default {
async scheduled(controller, env, ctx) {
const data = await fetchCriticalData(); // 关键路径
// 非阻塞后台任务
ctx.waitUntil(Promise.all([
logToAnalytics(data),
cleanupOldRecords(env.DB),
notifyWebhook(env.W
粤公网安备44030002003366号