# @aws-blocks/bb-cron-job 中文文档

规范地址：https://npmcn.com/package/%40aws-blocks/bb-cron-job/

版本：0\.4\.0
npm 元数据更新时间：2026-11-02T10:25:21.403Z
中文译文更新时间：2026-11-07T13:38:48.564Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws-blocks/bb-cron-job
原文对照：https://npmcn.com/package/%40aws-blocks/bb-cron-job/?lang=original
项目主页：https://github.com/aws-devtools-labs/aws-blocks/tree/main/packages/bb-cron-job#readme
源码仓库：https://github.com/aws-devtools-labs/aws-blocks

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：159 kB，56 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：constructs ^10\.0\.0，aws-cdk-lib ^2\.257\.0
- 首次发布：2026-06-15T23:39:36.857Z
- 最新版本发布：2026-11-02T10:25:21.027Z
- 近 30 天下载量：63155（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

计划任务执行由 EventBridge 调度器和 Lambda 支持.

## 安装

```sh
npm install @aws-blocks/bb-cron-job
```

也可以使用：`pnpm add @aws-blocks/bb-cron-job`、`yarn add @aws-blocks/bb-cron-job`、`bun add @aws-blocks/bb-cron-job`

## README

# @aws-blocks/bb-cron-job (英语)

计划任务执行由 EventBridge 调度器和 Lambda 支持.

> 设计与模拟等价细节 : [设计](https://npmcn.com/package/%40aws-blocks/bb-cron-job/DESIGN.md)

## 快速引用

**共同业务 • 配置**

| 你想怎样 | 如何配置 |
| --- | --- |
| 每N分钟运行一次 | `schedule: 'rate(5 minutes)'` |
| 每时每刻运行 | `schedule: 'rate(1 hour)'` |
| 协调世界时9点每天运行 | `schedule: 'cron(0 9 * * ? *)'` |
| 每天早上9点在太平洋运行 | `schedule: 'cron(0 9 * * ? *)', timezone: 'America/Los_Angeles'` |
| 将数据传递给处理器 | `input: { mode: 'full' }` |
| 禁用直到手动触发 | `enabled: false` |

**关键词 :** cron, 调度, 计时器, 周期性, 重复性, 速率, 事件桥, 背景, 间隔

## 快速启动

```typescript
import { Scope } from '@aws-blocks/core';
import { CronJob } from '@aws-blocks/bb-cron-job';

const scope = new Scope('my-app');

const cleanup = new CronJob(scope, 'cleanup', {
  schedule: 'rate(1 hour)',
  handler: async (event) => {
    console.log(`Running cleanup at ${event.scheduledTime}`);
    await deleteExpiredRecords();
  },
});
```

## 何时使用

-   运行定期清理任务( 过期会话、 陈旧数据)
-   生成预定报告
-   在计时器上变暖缓存
-   系统之间的数据同步
-   定期健康检查或监测

## 不使用时

-   因事件或用户动作而引发的一次性同步任务 使用 `AsyncJob`
-   对数据变化的反应 – 相关建筑区使用事件订阅

## 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `schedule` | `string` | (必须) | Cron 或 速率表达式(见下文附表表达式) |
| `handler` | `(event: CronJobEvent<T>) => Promise<void>` | (必须) | 每次引用时要执行的功能 。 一定是天真无能. |
| `enabled` | `boolean` | `true` | 调度是否活动 |
| `description` | `string` | —— 说 | 可读的工作说明 |
| `timezone` | `string` | `'UTC'` | 用于克龙表达式的IANA时区(例如, `'America/Los_Angeles'`(中文(简体) ) |
| `input` | `T` | —— 说 | 静态有效载荷在每次引用时都会传递给操作员 |
| `compute` | `ComputeProvider<'serverless'>` | 瞄准镜的计算 | 无服务器 `Compute` 运行操作器( 参见运行在它自己的计算上) |

## 运行在自己的计算上

默认情况下, 处理器会运行在其范围上的计算, 这就是应用程序的默认 计算,除非范围设置一个(`new Scope(id, { parent, compute })`) (中文(简体) ). 传出 a 无服务器 `Compute` 赋予工作自己的功能,例如更多的记忆 或比API更长的超时:

```typescript
import { Compute, CronJob } from '@aws-blocks/blocks';

const reports = new Compute(scope, 'reports', { type: 'serverless', memory: 2048, maxTimeoutSeconds: 900 });

new CronJob(scope, 'monthly-report', {
  schedule: 'cron(0 3 1 * ? *)',
  compute: reports,
  handler: async () => { /* … */ },
});
```

仅a `serverless` 计算可以运行 CronJob 目前,因为时间表 直接引用计算函数。 通过一个 `container` 计算是一个类型 错误,而从范围中继承的容器计算失败。 当地, 每一个工作都会在dev服务器中运行 不管它的计算结果是什么.

## 调度表达式

### 速率表达式

简单的基于间隔的时间表 :

```
rate(1 minute)
rate(5 minutes)
rate(1 hour)
rate(12 hours)
rate(1 day)
rate(7 days)
```

### 线性表达式

AWS 事件Bridge cron格式( 6个字段) : `cron(minute hour day-of-month month day-of-week year)`

```
cron(0 9 * * ? *)       → daily at 9:00 AM
cron(0 */2 * * ? *)     → every 2 hours
cron(30 9 ? * MON-FRI *) → weekdays at 9:30 AM
cron(0 0 1 * ? *)       → first day of every month at midnight
```

使用 `?` 月一日或周一日(一个必须是 `?`) (中文(简体) ).

## 处理器事件

处理者收到 `CronJobEvent<T>` 改为:

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `scheduledTime` | `string` | ISO 8601 预定援引时间的印章 |
| `jobName` | `string` | CronJob的合格身份证明 |
| `input` | `T` | 在 CronJob 上配置的静态输入( Name`undefined` 未提供输入时) |

## 错误常数

```typescript
import { CronJobErrors } from '@aws-blocks/bb-cron-job';

CronJobErrors.InvalidSchedule  // schedule expression is not a valid cron or rate format
CronJobErrors.InvalidTimezone  // timezone string is not a valid IANA timezone
```

两个出错都在施工时间被抛出(故障快速验证).

## 实例

### 带有时区( Timezone) 的 Cron 时间表

```typescript
const dailyReport = new CronJob(scope, 'daily-report', {
  schedule: 'cron(0 9 * * ? *)',
  timezone: 'America/Los_Angeles',
  description: 'Generate and email daily analytics report at 9 AM Pacific',
  handler: async (event) => {
    const data = await analytics.query({ date: event.scheduledTime });
    await email.send('team@example.com', 'Daily Report', formatReport(data));
  },
});
```

### 输入

```typescript
new CronJob<{ keys: string[] }>(scope, 'cache-warmer', {
  schedule: 'rate(5 minutes)',
  input: { keys: ['top-products', 'featured'] },
  handler: async (event) => {
    for (const key of event.input.keys) {
      await warmCache(key);
    }
  },
});
```

### 已禁用的工作( 仅限操作)

```typescript
const migration = new CronJob(scope, 'data-migration', {
  schedule: 'rate(1 day)',
  enabled: false,
  handler: async () => {
    await migrateRecords();
  },
});
```

### 操作器访问其他建筑块

```typescript
const store = new KVStore(scope, 'sessions');

const sessionCleanup = new CronJob(scope, 'session-cleanup', {
  schedule: 'rate(1 hour)',
  handler: async () => {
    const now = Date.now();
    for await (const session of store.scan()) {
      if (session.expiresAt < now) {
        await store.delete(session.key);
      }
    }
  },
});
```

### 一个处理器的多列表

```typescript
const syncHandler = async (event: CronJobEvent<{ mode: string }>) => {
  if (event.input.mode === 'incremental') await syncIncremental();
  else await syncFull();
};

new CronJob<{ mode: string }>(scope, 'sync-hourly', {
  schedule: 'rate(1 hour)',
  input: { mode: 'incremental' },
  handler: syncHandler,
});

new CronJob<{ mode: string }>(scope, 'sync-daily', {
  schedule: 'cron(0 9 * * ? *)',
  input: { mode: 'full' },
  handler: syncHandler,
});
```

## 最佳做法

-   **同上:** EventBridge提供至少一次交货。 设计处理器可以容忍重复引用.
-   **速率表达式** 简单间隔; **cron 表达式** 准确的时间.
-   **同时处决:** 如果处理器运行的时间长于调度间隔,则下一个引用开始,而前一个仍在运行. 设计重叠或执行应用程序级别锁定 `KVStore`。 。 。 .
-   **处理失败 :** Handler例外由Lambda的内置Aync引用再试政策(用指数回放2个回放)进行再试. 重复排出后,错误会被登录到 Cloud Watch.

## 地方发展

在本地 dev 模式下, CronJob 运行进度表 :

-   费率附表的使用 `setInterval`
-   Cron 时刻表计算下一个有时区支持和使用的起火时间 `setTimeout`
-   当工作点火时控制台登录 : `[CronJob:{id}] triggered at {timestamp}`
-   何时 `enabled: false`,该调度不自动运行
-   处理失败者登录时警告 AWS 会重试

## AWS 部署

自动规定 :

-   **事件桥表 :** 一个 `AWS::Scheduler::Schedule` 每个 CronJob 实例
-   **共享兰布达:** 瞄准共享的Lambda(与API处理器和AsyncJob相同). 每一个工作都不要献身于Lambda.
-   **IAM角色:** 每层事件 Bridge 调度器角色 `lambda:InvokeFunction` 允许。 其信托政策仅限于该堆帐户和区域中的时间表(`aws:SourceAccount` + 键 `aws:SourceArn` 匹配 `schedule-group/*`) (中文(简体) ).
-   **计划名称 :** 从CronJob的 `fullId` (转至64个字符)

## 密钥与 AsyncJob 的区分

克龙乔布是一个 **纯基础设施申报** ——构造器定义了调度和处理器. 没有运行时间方法 `submit()` 或者说 `submitBatch()`。处理器自动运行在时间表上.

|  | 克龙乔布 | 阿辛克职业 |
| --- | --- | --- |
| 触发 | 时间(克伦/率) | 程序化( E)`submit()`(中文(简体) ) |
| 运行时间方法 | 无 | `submit()`, (中文(简体) ), `submitBatch()` |
| 使用大小写 | 定期重复的任务 | 一次性事件驱动的工作 |
| AWS 服务 | 事件桥排程器 | SQS + 蓝巴达 |

## 常见问题

### @aws-blocks/bb-cron-job 是什么？

计划任务执行由 EventBridge 调度器和 Lambda 支持\.

### 如何安装 @aws-blocks/bb-cron-job？

在项目目录运行 npm install @aws-blocks/bb-cron-job，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.0\.0）、aws-cdk-lib（^2\.257\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-blocks/bb-cron-job 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws-blocks/bb-cron-job 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aws-blocks/bb-cron-job 可以商用吗？

@aws-blocks/bb-cron-job 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-blocks/bb-cron-job 的下载量有多少？

根据 npm 官方下载统计，@aws-blocks/bb-cron-job 在 2026/10/07 – 2026/11/05 这 30 天内被下载 63,155 次，日均约 2,105 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws-blocks/bb-cron-job 还在维护吗？

最新版本 0\.4\.0 发布于 2026/11/02（5 天前）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/06/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。