encore-cron

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Encore Cron Jobs

Encore 定时任务

Instructions

指令

CronJob

declaration in Encore.ts ties a schedule to an existing

api(...)

endpoint. The endpoint runs at the chosen cadence. Declare the

CronJob

at package level — not inside a function.

typescript

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,
});

Encore.ts 中的

CronJob

声明会将一个调度计划与现有的

api(...)

端点关联起来。该端点会按照设定的频率运行。请在 package 层级声明

CronJob

，不要将其放在函数内部。

typescript

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,
});

Schedule Formats

调度格式

Field	Example	Description
`every`	`"1h"` , `"30m"` , `"6h"`	Simple interval. Must divide 24h evenly — `"7h"` is invalid.
`schedule`	`"0 9 * * 1"`	Standard cron expression (5 fields, UTC).

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

Common cron expressions

常见 cron 表达式

Cron	Meaning
`"0 * * * *"`	Every hour, on the hour
`"0 2 * * *"`	Daily at 02:00 UTC
`"0 0 * * 0"`	Weekly on Sunday at midnight UTC
`"0 4 15 * *"`	04:00 UTC on the 15th of each month

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

Important behaviour

重要行为

Cron jobs do not execute when running locally with
encore run
. Only deployed environments fire crons.
The cron endpoint should be
```
expose: false
```
so it can't be triggered externally — only the cron scheduler should call it.
All times in
```
schedule
```
are UTC. Convert from local time when designing the schedule.
The endpoint must already exist at module load — declare it before the
```
CronJob
```
.

**使用
```
encore run
```
在本地运行时，Cron 任务不会执行。**只有已部署的环境才会触发 cron。
Cron 端点应设置为
```
expose: false
```
，以防止从外部触发——只能由 cron 调度器调用。
```
schedule
```
中的所有时间均使用 UTC。设计调度计划时，需要从本地时间转换。
端点必须已存在于模块加载阶段——请先声明端点，再声明
```
CronJob
```
。

Guidelines

指南

Use
```
every
```
for "run on a regular interval" (must divide 24h).
Use
```
schedule
```
for specific times of day or days of week.
Keep endpoint logic idempotent: a cron may fire late or be retried in a redeploy window.
For event-driven background work (not time-driven), use the
```
encore-pubsub
```
skill instead.

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