node-cron 完全指南：从基础到高级特性

node-cron 完全指南：从基础到高级特性

【免费下载链接】node-cron Cron for NodeJS. 项目地址: https://gitcode.com/gh_mirrors/no/node-cron

🌟 为什么选择 node-cron？

你还在为 Node.js 定时任务发愁吗？还在手动编写复杂的定时器逻辑吗？node-cron 作为一款专为 Node.js 设计的 Cron（定时任务）工具，让你轻松实现各种定时任务调度，从简单的每秒执行到复杂的周期性任务，一文带你彻底掌握！

读完本文你将获得：

• 快速上手 node-cron 的基本使用方法
• 掌握 Cron 表达式的语法规则
• 学会高级特性如多任务管理和错误处理
• 了解性能优化和最佳实践

🚀 安装与基础使用

安装步骤

通过 npm 即可快速安装 node-cron：

npm install cron

第一个定时任务

创建一个简单的每秒执行一次的任务，代码示例如下：

examples/basic.mjs

import { CronJob } from '../dist/index.js';

console.log('Before job instantiation');
const job = new CronJob('* * * * * *', function () {
	const d = new Date();
	console.log('Every second:', d);
});
console.log('After job instantiation');
job.start();

这段代码创建了一个每秒钟执行一次的任务，打印当前时间。其中 '* * * * * *' 是 Cron 表达式，表示每秒执行。

⏰ Cron 表达式详解

基本语法

node-cron 支持 6 个字段的 Cron 表达式（比标准 Cron 多了秒级精度），格式如下：

秒 分 时 日 月 星期

各字段的取值范围：

字段	允许值
秒 (second)	0-59
分 (minute)	0-59
时 (hour)	0-23
日 (day)	1-31
月 (month)	1-12 或名称缩写
星期 (week)	0-7 或名称缩写 (0和7都表示周日)

特殊字符

• *：匹配该字段的所有可能值
• ,：分隔多个值，如 1,3,5
• -：指定范围，如 1-5
• /：指定步长，如 */10 表示每10个单位

常用示例

每10分钟执行一次：

examples/every_10_minutes.mjs

import { CronJob } from '../dist/index.js';

console.log('Before job instantiation');
const job = new CronJob('0 */10 * * * *', function () {
	const d = new Date();
	console.log('Every Tenth Minute:', d);
});
console.log('After job instantiation');
job.start();

表达式 0 */10 * * * * 表示在每小时的第 0 秒、每 10 分钟执行一次。

🛠️ 高级特性

多任务管理

node-cron 支持同时管理多个定时任务，示例如下：

examples/multiple_jobs.mjs

import { CronJob } from '../dist/index.js';

console.log('Before job instantiation');
const job = new CronJob('*/5 * * * * *', function () {
	const d = new Date();
	console.log('First:', d);
});

const job2 = new CronJob('*/8 * * * * *', function () {
	const d = new Date();
	console.log('Second:', d);
});
console.log('After job instantiation');
job.start();
job2.start();

这段代码创建了两个任务，一个每5秒执行一次，另一个每8秒执行一次。

任务控制方法

CronJob 实例提供了丰富的方法来控制任务：

• start()：启动任务
• stop()：停止任务
• setTime()：修改任务执行时间
• nextDate()：获取下一次执行时间
• lastDate()：获取上一次执行时间

错误处理

可以通过 errorHandler 参数来捕获任务执行中的错误：

const job = new CronJob(
  '* * * * * *',
  () => {
    // 可能会出错的代码
    throw new Error('Something went wrong');
  },
  null,
  true,
  'America/Los_Angeles',
  null,
  false,
  null,
  null,
  null,
  (err) => {
    console.error('Job error:', err);
  }
);

⚡ 性能优化与最佳实践

避免长时间运行的任务

如果任务执行时间较长，建议设置 waitForCompletion: true，避免任务重叠执行：

const job = new CronJob(
  '*/5 * * * * *',
  async () => {
    // 长时间运行的异步任务
    await longRunningTask();
  },
  null,
  true,
  'America/Los_Angeles',
  null,
  false,
  null,
  null,
  true // 等待当前任务完成后再执行下一次
);

合理设置阈值

使用 threshold 参数控制错过执行期限的任务是否执行：

const job = new CronJob(
  '* * * * * *',
  () => {
    console.log('Task executed');
  },
  null,
  true,
  'America/Los_Angeles',
  null,
  false,
  null,
  null,
  null,
  null,
  500 // 阈值设为500ms
);

使用命名任务

为任务命名，便于日志记录和调试：

const job = new CronJob(
  '* * * * * *',
  () => {
    console.log('Task executed');
  },
  null,
  true,
  'America/Los_Angeles',
  null,
  false,
  null,
  null,
  null,
  null,
  null,
  'my-task' // 任务名称
);

📚 资源与文档

官方文档

完整的 API 文档和更多示例，请参考：

README.md

源码目录结构

• 核心代码：src/
  • CronJob 类：src/job.ts
  • CronTime 类：src/time.ts
  • 工具函数：src/utils.ts
  • 类型定义：src/types/
• 示例代码：examples/
• 测试代码：tests/

🤝 参与贡献

如果你发现 bug 或有功能需求，欢迎提交 issue 或 PR。贡献指南请参考：

CONTRIBUTING.md

🔖 许可证

node-cron 使用 MIT 许可证，详情请见：

LICENSE

---

希望本文能帮助你更好地理解和使用 node-cron。如果你觉得本文有用，请点赞、收藏并关注我们，获取更多关于 Node.js 开发的优质内容！下期我们将介绍 node-cron 在生产环境中的部署和监控方案，敬请期待！

【免费下载链接】node-cron Cron for NodeJS. 项目地址: https://gitcode.com/gh_mirrors/no/node-cron