# @arkstack/scheduler 中文文档

规范地址：https://npmcn.com/package/%40arkstack/scheduler/

版本：0\.22\.2
npm 元数据更新时间：2026-11-07T14:00:11.058Z
中文译文更新时间：2026-11-06T21:18:25.857Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40arkstack/scheduler
原文对照：https://npmcn.com/package/%40arkstack/scheduler/?lang=original
项目主页：https://arkstack.toneflix.net/guide/scheduling
源码仓库：https://github.com/arkstack-hq/arkstack

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

- 包体积（解压后）：40.3 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：@arkstack/jobs ^0\.22\.2，@arkstack/cache ^0\.22\.2，@h3ravel/musket ^2\.2\.13，@arkstack/contract ^0\.22\.2
- 首次发布：2026-07-09T06:16:16.140Z
- 最新版本发布：2026-11-07T14:00:10.616Z
- 近 30 天下载量：2328（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 55 个）

## 中文简介

Arkstack的任务调度:流畅的频率,克龙,重叠/一服务器锁,钩,和调度:运行/工作/列表命令.

## 安装

```sh
npm install @arkstack/scheduler
```

也可以使用：`pnpm add @arkstack/scheduler`、`yarn add @arkstack/scheduler`、`bun add @arkstack/scheduler`

## README

# @ arkstack/ 排程器

[![@arkstack/scheduler](https://img.shields.io/npm/dt/@arkstack/scheduler?style=flat-square&label=@arkstack/scheduler&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F@arkstack/scheduler)](https://www.npmjs.com/package/@arkstack/scheduler)

任务时间安排 [阿克斯达克](https://arkstack.toneflix.net/). 在代码中流利地定义预定任务,而不是管理一大批cron条目——单一的系统cron条目驱动一切.

## 安装

```sh
pnpm add @arkstack/scheduler
ark publish --package @arkstack/scheduler   # writes src/routes/console.ts
```

完整的应用程序模板包括它和一个 `src/routes/console.ts` 已经.

## 定义您的日程

单位 `src/routes/console.ts`数字 :

```ts
import { Schedule } from '@arkstack/scheduler'

Schedule.command('cache:prune').hourly()

Schedule.call(async () => {
  await pruneTempFiles()
})
  .dailyAt('01:30')
  .withoutOverlapping()

Schedule.job(new SendDigest()).weeklyOn(1, '08:00')

Schedule.exec('backup.sh').daily().onOneServer()
```

| 任务类型 | 运行 |
| --- | --- |
| `Schedule.command(name, args?)` | Arkstack CLI 命令 (`ark <name>`(中文(简体) ) |
| `Schedule.call(fn)` | 回电 |
| `Schedule.job(job)` | 已排队的任务( 通过 `@arkstack/jobs`(中文(简体) ) |
| `Schedule.exec(cmd, args?)` | 一个 shell 命令 |

## 运行它

调度员每分钟评估一次到期任务. 在生产中,加上 **一个** cron 条目 :

```
* * * * * cd /path/to/app && npx ark schedule:run >> /dev/null 2>&1
```

在开发期间,经营前景工人:

```sh
ark schedule:work    # evaluates the schedule every minute until stopped
ark schedule:list    # list tasks with their next run time
```

## 节奏

```ts
Schedule.command('x').everyMinute()
Schedule.command('x').everyFiveMinutes() // */5 * * * *
Schedule.command('x').everyThirtyMinutes()
Schedule.command('x').hourly()
Schedule.command('x').hourlyAt(15)
Schedule.command('x').daily()
Schedule.command('x').dailyAt('13:00')
Schedule.command('x').twiceDaily(1, 13)
Schedule.command('x').weekly()
Schedule.command('x').weeklyOn(1, '8:00') // Monday 08:00
Schedule.command('x').monthly()
Schedule.command('x').monthlyOn(15, '17:00')
Schedule.command('x').quarterly()
Schedule.command('x').yearly()
Schedule.command('x').cron('*/10 9-17 * * 1-5') // raw cron
```

每周的限制,上面有时间层:

```ts
Schedule.command('x').weekdays().at('9:00')
Schedule.command('x').weekends().hourly()
Schedule.command('x').mondays()
Schedule.command('x').days([1, 4]) // Monday & Thursday
```

设置评价表达式的时区 :

```ts
Schedule.command('x').dailyAt('09:00').timezone('America/New_York')
```

## 制约因素

```ts
Schedule.command('x')
  .daily()
  .when(async () => await featureEnabled('reports')) // run only when truthy
  .skip(() => isHoliday()) // skip when truthy
  .environments('production', 'staging') // limit by APP_ENV
  .between('09:00', '17:00') // only within a daily window
```

`unlessBetween('22:00', '06:00')` 运行 _外部_ 窗口( 处理过夜区域) .

## 重叠, 单服务器和背景

```ts
Schedule.command('report:build').everyFiveMinutes().withoutOverlapping()
Schedule.exec('backup.sh').daily().onOneServer()
Schedule.exec('long-import.sh').daily().runInBackground()
```

`withoutOverlapping()` 财务报告和审定财务报表 `onOneServer()` 通过协调 `@arkstack/cache`,因此它们可以跨进程和服务器工作. 配置共享缓存存储( N)`redis` 或者说 `database`用于 `onOneServer()` ; 没有缓存, 调度器会回到进程本地锁定.

## 钩子

```ts
Schedule.command('report:build')
  .daily()
  .before(() => logger.info('building report'))
  .onSuccess(() => notifyOk())
  .onFailure((error) => notifyFailed(error))
  .after(() => logger.info('done'))
```

## API 密码

-   `Schedule.command / call / job / exec` 登记任务,返回 a `ScheduledEvent` 用来锁链.
-   `Schedule.events()` 编号 : `Schedule.dueEvents(date?)` 检查已登记/应予处理的事件.
-   `ScheduledEvent` ——活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活, `timezone`, (中文(简体) ), `when`, (中文(简体) ), `skip`, (中文(简体) ), `environments`, (中文(简体) ), `between`, (中文(简体) ), `unlessBetween`, (中文(简体) ), `withoutOverlapping`, (中文(简体) ), `onOneServer`, (中文(简体) ), `runInBackground`, (中文(简体) ), `before`编号 :`after`编号 :`onSuccess`编号 :`onFailure`, (中文(简体) ), `description`, (中文(简体) ), `name`) (中文(简体) ).
-   图标 : `schedule:run`, (中文(简体) ), `schedule:work`, (中文(简体) ), `schedule:list`。 。 。 .

Cron评价由 [克罗纳](https://github.com/hexagon/croner)见 [调度指南](https://arkstack.toneflix.net/guide/scheduling) 完全通过.

## 许可证

麻省理工学院

## 常见问题

### @arkstack/scheduler 是什么？

Arkstack的任务调度:流畅的频率,克龙,重叠/一服务器锁,钩,和调度:运行/工作/列表命令\.

### 如何安装 @arkstack/scheduler？

在项目目录运行 npm install @arkstack/scheduler，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@h3ravel/musket（^2\.2\.13）、@arkstack/contract（^0\.22\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @arkstack/scheduler 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/arkstack\_\_scheduler 是否存在。

### @arkstack/scheduler 支持 ESM 还是 CommonJS？

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

### @arkstack/scheduler 可以商用吗？

@arkstack/scheduler 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @arkstack/scheduler 的下载量有多少？

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

### @arkstack/scheduler 还在维护吗？

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