encore-cron

Encore Cron 作业

说明

在 Encore.ts 中，CronJob 声明会将一个计划关联到现有的 api(...) 端点。该端点会按所选频率运行。在包级别声明 CronJob，不要在函数内部声明。

import { CronJob } from "encore.dev/cron";
import { api } from "encore.dev/api";

// 1. The endpoint to call (typically internal: expose: false)
export const aggregateDailyOrders = api(
  { expose: false },
  async (): Promise<void> => {
    // Aggregation logic
  }
);

// 2. Package-level cron declaration
const _ = new CronJob("aggregate-daily-orders", {
  title: "Aggregate orders for the previous day",
  schedule: "0 2 * * *",  // 02:00 UTC every day
  endpoint: aggregateDailyOrders,
});

计划格式

字段	示例	描述
every	"1h"、"30m"、"6h"	简单间隔。必须能整除 24h——"7h" 无效。
schedule	"0 9 * * 1"	标准 cron 表达式（5 个字段，UTC）。

常见 cron 表达式

Cron	含义
"0 * * * *"	每小时整点
"0 2 * * *"	每日 UTC 02:00
"0 0 * * 0"	每周日 UTC 午夜
"0 4 15 * *"	每月 15 日 UTC 04:00

重要行为

• 使用 encore run 在本地运行时不会执行 Cron 作业。 只有已部署的环境才会触发 cron。
• Cron 端点应设置为 expose: false，以免被外部触发——只有 cron 调度器可以调用它。
• schedule 中的所有时间均为 UTC。设计计划时，请将本地时间转换为 UTC。
• 模块加载时，端点必须已存在——请在 CronJob 之前声明端点。

指南

• 对于“按固定间隔运行”，使用 every（间隔必须能整除 24h）。
• 对于一天中的特定时间或一周中的特定日期，使用 schedule。
• 确保端点逻辑幂等：cron 可能延迟触发，也可能在重新部署期间重试。
• 对于事件驱动的后台工作（非时间驱动），请改用 encore-pubsub skill。