# @broberg/cron 中文文档

规范地址：https://npmcn.com/package/%40broberg/cron/

版本：0\.4\.0
npm 元数据更新时间：2026-10-30T18:06:57.419Z
中文译文更新时间：2026-11-08T16:48:19.960Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40broberg/cron
原文对照：https://npmcn.com/package/%40broberg/cron/?lang=original
项目主页：https://github.com/broberg-ai/components#readme
源码仓库：https://github.com/broberg-ai/components

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

- 包体积（解压后）：140 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-06-24T01:25:35.549Z
- 最新版本发布：2026-10-30T18:06:57.036Z
- 近 30 天下载量：2134（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

用于 cronjobs.webhouse.net 的自打服务客户端 — 注册 + 管理 HTTP cron 任务,覆盖 Bearer-athed /api/jobs API (创建/list/update/delete/pause/run) , 并设有每个 repo 范围标记和每个工作目标头保持服务器侧(从不在 URL o 中)

## 安装

```sh
npm install @broberg/cron
```

也可以使用：`pnpm add @broberg/cron`、`yarn add @broberg/cron`、`bun add @broberg/cron`

## README

# @broberg/克龙

输入的自助客户端 **(原始内容存档于2013-10-12). cronjobs.webhouse.net** ——舰队托管 HTTP-克龙. 在几个打字的电话中注册和管理预定的工作,而不是 点击 NextAuth 登录墙或手滚动调度器.

-   **无依无依.** 原始内容 `fetch` 誓以比丘 `/api/jobs` API,就这样 运行在节点,邦和边缘一样.
-   **服务 OpenAPI 生成的类型** (单位:千美元)`pnpm gen` → `src/schema.ts`),这样 客户端保持与合同的字节相匹配——一个 spec change 是类型错误.
-   **(原始内容存档于2018-03-27) (英语). Per-repo specific.** 范围 `CRONJOBS_API_TOKEN` 只有曾经看到和 触摸自己的repo工作(跨范围~404).
-   **秘密会留在服务器边.** 把目标秘密放在每份工作里 `headers` 条目; 它被存储在cron服务上,并逐字逐字传送到每个勾点上——从来没有在 uRL或日志. **但是,除非有F013号船, 船头被储存在 简写并返回 `GET /api/jobs`, (中文(简体) ), `/api/jobs/:id` 财务报告和审定财务报表 `/api/jobs/export`** ——任何能够接触工作的人都可以读取这个秘密. 使用一个 最小的特权, 短暂的象征.

> **还没有在npm.** v.1.0 靴子-pulish 等待克里斯蒂安去+ 信任的出版商(标准) `@broberg/*` 船道). 建造了针对现场的 合同; `cronjobs.webhouse.net/api/openapi.json` 是真理的来源.

```bash
pnpm add @broberg/cron
```

## 使用量

```ts
import { createCron } from "@broberg/cron";

// token defaults to process.env.CRONJOBS_API_TOKEN; baseUrl to cronjobs.webhouse.net
const cron = createCron();

// Register a job. Pass a stable `externalId` so re-running a deploy UPSERTS the
// same job (no duplicate) instead of creating a new one — this is also how you
// UPDATE a job (re-create with the same externalId), so you never track ids.
// The target secret rides in `headers` (object → stored JSON), never in the URL.
const job = await cron.createJob({
  name: "xrt81 push-tick",
  schedule: "*/10 * * * *", // every 10 minutes
  url: "https://xrt81.com/api/push/tick",
  method: "POST",
  headers: { Authorization: "Bearer <PUSH_TICK_SECRET>" },
  externalId: "xrt81:push-tick",
});

await cron.listJobs({ tag: "push" });
await cron.pauseJob(job.id);   // idempotent — no-op if already paused
await cron.resumeJob(job.id);
await cron.runJob(job.id);     // fire once now → Execution
await cron.getExecutions(job.id); // recent run history
await cron.deleteJob(job.id);
```

每个方法都会投出一个键入 `CronError` (单位:千美元)`{ status, code?, message, details? }`, (中文(简体) ), `code` ∈ `unauthorized | forbidden | not_found | validation_error | invalid_cron`(中文(简体) ) 在一个非2xxx响应, 所以一个失败的注册表出声.

### 嵌入符( 仅指画符)

```ts
// Requires a session/admin token (a scoped token gets 403). Omit `scope` for a
// full-access token (session only). The plaintext `key` is returned ONCE.
const { key } = await cron.mintKey({ name: "xrt81 production", scope: "xrt81" });
```

薄荷薄荷每repo活物的 管理符 **哥们** (一个已审计 优先路径);普通重置资产消耗了它们被提供的范围标记.

## 那些类型无法告诉你的事情

### 被拒绝的代号——客户从不遵循重定向(自0.4.0起,F041.4起)

**今天(2026年10月30日测量,在Cronjobs F017.1,sha 34094ce之后):** 每个 `/api/*` 用错误的符号打电话, 一个非`cj_` 符号或无信头答案 **`401`** 与 `{"error":{"code":"unauthorized","message":"Authentication required"}}` 没有 `Location`。你是一个正常的 `CronError` 与 `status: 401`。 。 。 .

**为何客户仍守着防线:** 直到修复,一个非 --`cj_` 符号或缺少的页眉 **`307 → /login`**最多0.2.0 客户跟踪 它,有一个 `200` 以 12 kB 登录 HTML 键入,然后返回输入的页面 `Job[]` —— 说 `jobs.length` 12057,这个数字看起来像一个答案(测量) 页:1 一个服务可以倒退,所以现在的客户端 **从不遵循方向**数字 :

-   重定向到登录页面 `CronError` 与真实 `status`, (中文(简体) ), `location`,并有一条信息说 信物丢失或不接受.
-   任意 **其他项目** 重新定向(例如a) `308` )随其状态投掷 目标——而且 **没有** 声称该标志是坏的.
-   A 类 `200` 他们的身体不是JSON扔 `cron_not_json` 命名内容类型和 ,而不是返回到您的类型.

### 时间戳是 ISO 字符串 (0. 4. 0 — 一个类型变化)

`lastRunAt`, (中文(简体) ), `nextRunAt`, (中文(简体) ), `createdAt`, (中文(简体) ), `updatedAt` 和执行时间 (单位:千美元)`startedAt`, (中文(简体) ), `completedAt`已经 **ISO-8601 字符串** 电线上,例如:. `"2026-10-30T17:00:00.628Z"`。服务本身的光谱 说"整数,Unix ms" 直至2026年10月30日(cronjobs a1b3a75将其固定),所以0.3.x和之前的打法为: `number` 而值总是字符串. **如果你对他们做了算术, 它已经是错误的;现在的类型是这样说的.** 分析 `new Date(job.lastRunAt)`。 。 。 .

### `externalId` 使用一个COLON - `repo:job-name`

舰队15个岗位中有13个跟着它 **两边都没什么正常的.** 因此,偏离不会失败——它沉默地 **创建重复的工作** 而不是更新你的意思.

> 从呼叫网站, _"高调错过"_ 财务报告和审定财务报表 _"更新"_ 看起来一模一样 仅 `201` 对 `200` 把他们分开,没人读过.

选会而住. 这个客户是故意的 **没有** 重写您的标识符: 默默地正常化某人的id, 就是你如何创建你试图防止的复制品 .

### `connectTimeout` 默认为 `null`这是故意的

两个不同的问题 `timeout` 独来独往地回答:

|  |  |
| --- | --- |
| `timeout` | 多长时间 **工作** 可能带 |
| `connectTimeout` | 我们等待回应多久 **开始** |

`fetch()` 解答时 _页眉_所以对于一个先计算后回答的工作来说, **工时对工头是工作时间** - 短暂的违约会杀死那些工作 只在您的端点迅速回复时设定它 .

在它真正适用收益的地方是真实的: 201 ms的好友吞噬性工作答案,和与 `timeout: 120000` 它在16秒的停电中被吊了整整两分钟, 燃烧了它在一次死亡尝试上的全部重试预算. **长时间的耐心使工作更加脆弱,而不是更坚韧.**

### 部分更新不再重现你留下的东西

现在应用服务器侧默认值 **仅在创建时**,所以一个最小的规格是安全的. `tags: undefined` 保留它们; `tags: []` 清除他们.

它并非总是如此,而虫子击中了我们推荐的准确模式——由Endical register by `externalId`,每个集成继续 **每次部署**。每次运行都静静地清除所有标记,重新设置超时/重试/时区,将 POST 任务变成 GET,以及 **{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}有人故意暂停了工作 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}我还不知道.**

固定上游. 仍然发送您的完整配置, 因此您的工作不取决于您无法从这里看到的服务器行为 .

## 这个客户还在吗?

```bash
npm run check:drift
```

获取已公布的合同、再生和比较. **三个结果,从来没有两个:**

|  | 退出 |  |
| --- | --- | --- |
| `✓` | 0 个 | 同步中 |
| `✗ DRIFTED` | 1个 | 以 `npm run gen` ——它命名了第一行不同 |
| `? COULD NOT ASK` | 2个 | 无法达到或解析 |

它作为一部分运行 `npm test`时 **漂流块和"不能问"不是.** 这种不对称是故意的: 一张在片状网络上红掉的支票是一张被关闭的支票, 而真正的漂移则被关闭。 交易是 一个无法接触的谱系是 _报告_ 而不是说 _已执行_ ——读出行,不要只读出出行代码.

**为什么它存在:** 在2026-08-28上,4个公共-API的更改在一天内就落地了,其中两个已经使这些类型错了——我们发现的唯一原因是对方有人选择写信给我们. 只有在一个人记得发送时才存在的信号不是信号.

## API 密码

-   `createCron(config?) → CronClient` —— 说 `config: { token?, baseUrl?, fetch? }`。 。 。 .
-   `createJob(spec)` (通过 `externalId`· `getJob(id)` • 妇女 `listJobs(filter?)` • 妇女 `deleteJob(id)` • 妇女 `pauseJob(id)` • 妇女 `resumeJob(id)` • 妇女 `toggleJob(id)` • 妇女 `runJob(id)` • 妇女 `getExecutions(id)` • 妇女 `getStatus(id)` • 妇女 `mintKey({name, scope?})`。 。 。 .
-   `CronError` ——倒入任何非-2xx(并被丢入缺失的活字牌/活字牌上).

拥有者+ [`broberg-ai/components`](https://github.com/broberg-ai/components) (原文:英文) **F041 (法语)**) (中文(简体) ). 弯曲 **服务** (镜形符牌,自用薄荷, (一) 能力) `cronjobs` 麻省理工学院.

## 常见问题

### @broberg/cron 是什么？

用于 cronjobs\.webhouse\.net 的自打服务客户端 — 注册 \+ 管理 HTTP cron 任务,覆盖 Bearer-athed /api/jobs API \(创建/list/update/delete/pause/run\) , 并设有每个 repo 范围标记和每个工作目标头保持服务器侧\(从不在 URL o 中\)

### 如何安装 @broberg/cron？

在项目目录运行 npm install @broberg/cron，或使用 pnpm add / yarn add / bun add。

### @broberg/cron 支持 TypeScript 吗？

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

### @broberg/cron 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @broberg/cron 可以商用吗？

@broberg/cron 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @broberg/cron 的下载量有多少？

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

### @broberg/cron 还在维护吗？

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