📦 Node Cron

Node Cron 使用 cron npm 包（npm install cron）实现 Node.js 中的秒级精度定时任务。触发 cron 作业，node-cron，调度任务，cron 表达式，cron 模式，调度作业，npm install cron，CronJob，CronTime。

快速开始

import { CronJob } from 'cron';
const job = new CronJob(
  '0 /5    ', // 每 5 分钟运行一次
  () => console.log('每 5 分钟运行一次'),
  null, // onComplete
  true, // 立即开始
  'Asia/Shanghai' // 时区
);

或使用对象形式：

const job = CronJob.from({
  cronTime: '0 0 9   1', // 每周一 9 点
  onTick: () => sendReport(),
  start: true,
  timeZone: 'Asia/Shanghai'
});
job.stop(); // 停止作业
job.start(); // 恢复作业

Cron 模式 该库使用 6 个字段（秒级精度），与标准的 5 个字段 Unix cron 不同： 秒 分钟 小时 日期 月份 周 0-59 0-59 0-23 1-31 1-12 0-7 语法 令牌 含义 任意值（每秒/分钟等） 1,3,5 值列表 1-5 范围（包括） /5 每 N 步 名称 使用前 3 个字母表示月份/星期几（不区分大小写）： "jan,mar,dec", "mon,wed,fri" 星期几：0 或 7 表示星期日。

常见示例 表达式 含义 /10 每 10 秒 0 每分钟的第 0 秒 0 0 每小时的第 0 分钟 0 0 9 每天 9 点 0 30 9 1-5 周一至周五 9 点 30 分 0 0 0 1 每月 1 日 0 点

CronJob 类 构造函数参数 参数 必需 描述 cronTime 是 Cron 模式字符串、Date 或 Luxon DateTime onTick 是 回调函数 onComplete 作业停止时调用 start 自动开始，默认为 false timeZone IANA 区域字符串（例如 'Asia/Shanghai'） context onTick 的 this 上下文 runOnInit 初始化时立即运行 onTick waitForCompletion 如果为 true，跳过回调仍在运行的 tick errorHandler 捕获 onTick 中的异常 name 作业标识符，用于调试 threshold 超时容忍度（毫秒），默认为 250

请勿同时传递 utcOffset 和 timeZone -- 它们冲突。

关键方法 CronJob.from(obj) （静态）-- 使用命名参数创建 job.start() / job.stop() -- 开始/停止作业 job.nextDate() -- 下一次执行时间（Luxon DateTime） job.nextDates(n) -- 下 N 次执行时间数组 job.lastDate() -- 上一次执行时间 job.setTime(cronTime) -- 更改调度 job.addCallback(fn) -- 添加另一个 onTick 回调

只读属性 job.isActive -- 作业是否正在运行 job.isCallbackRunning -- onTick 是否正在执行

独立实用程序

import  as cron from 'cron';
// 该 cron 表达式什么时候下次触发？
const dt = cron.sendAt('0 0   ');
console.log(dt.toISO());
// 到下次执行还有多少毫秒？
const ms = cron.timeout('0 0   ');
// 验证表达式
const { valid, error } = cron.validateCronExpression('0 0   ');

注意事项 月份为 1-12，而不是 0-11。从 v2 升级需要在所有月份值上加 1。 星期几 0 表示星期日（7 也可以）。 6 个字段（包括秒）-- 与标准的 5 个字段 Unix cron 不同。 使用 waitForCompletion: true 来防止异步回调重叠。

异步 onTick 将异步工作直接包装 -- waitForCompletion 防止重叠运行：

const job = CronJob.from({
  cronTime: '/30     *',
  onTick: async () => {
    await fetchData();
    await processData();
  },
  waitForCompletion: true,
  start: true
});

完整 API 参考文档请参阅 references/api_reference.md，包括 CronTime 类、所有方法签名和迁移说明。