cron-task

cron-task 是这个工具暴露给用户的 CLI 命令；对应的 npm 包名是 @rongyan/cron-task，仓库地址是 https://github.com/rongyan6/cron-task。它基于 node-cron 管理本机定时任务。

它围绕下面这套使用方式设计：

• 默认按机器本地时区执行任务
• 配置文件固定放在 ~/.cron-task/cron-task.json
• 配置文件根节点就是数组，每一项就是一个任务
• 修改配置后通过 cron-task restart 生效
• 通过 CLI 管理守护进程、校验配置、查看任务和手动执行任务

安装

npm install -g @rongyan/cron-task

快速开始

1. 创建默认配置文件：

cron-task init

2. 编辑 ~/.cron-task/cron-task.json。

3. 启动守护进程：

cron-task start

4. 每次修改配置后，执行重启，让旧任务清理掉并应用新任务：

cron-task restart

配置格式

配置文件根节点必须是数组：

[
  {
    "name": "morning-report",
    "description": "工作日报，每个工作日 09:00 执行",
    "when": {
      "type": "weekly",
      "on": ["mon", "tue", "wed", "thu", "fri"],
      "at": "09:00"
    },
    "command": "node ~/scripts/report.js",
    "cwd": "~/work/reporting",
    "env": {
      "REPORT_CHANNEL": "ops"
    },
    "runOnStart": false
  },
  {
    "name": "cache-cleanup",
    "when": {
      "type": "everyMinutes",
      "interval": 30
    },
    "command": "node ~/scripts/cleanup.js"
  },
  {
    "name": "legacy-cron",
    "when": {
      "type": "cron",
      "expression": "0 */6 * * *"
    },
    "command": "echo custom cron expression",
    "timezone": "Asia/Shanghai"
  }
]

支持的调度类型

| when.type | 字段 | 示例 | | --- | --- | --- | | everyMinutes | interval | { "type": "everyMinutes", "interval": 15 } | | everyHours | interval，可选 atMinute | { "type": "everyHours", "interval": 6, "atMinute": 5 } | | hourly | 可选 atMinute | { "type": "hourly", "atMinute": 10 } | | daily | at，格式为 HH:MM | { "type": "daily", "at": "21:30" } | | weekly | on、at | { "type": "weekly", "on": ["mon", "fri"], "at": "08:15" } | | monthly | on、at | { "type": "monthly", "on": [1, 15], "at": "03:00" } | | cron | expression | { "type": "cron", "expression": "0 9 * * 1-5" } |

任务字段说明

| 字段 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | name | string | 必填 | 任务唯一名称 | | description | string | "" | 可选描述，会显示在 list 中 | | command | string | 必填 | 实际执行的 shell 命令 | | when | object | 必填 | 更易理解的调度配置对象 | | enabled | boolean | true | 设为 false 时任务保留在配置中，但不会被调度 | | timezone | string | "local" | 可用 "local" 或任意合法 IANA 时区 | | cwd | string | 当前进程目录 | 支持 ~ 展开 | | env | object | {} | 额外注入给任务进程的环境变量 | | allowOverlap | boolean | false | 默认不允许任务与下一次触发重叠执行 | | runOnStart | boolean | false | 守护进程启动后立即先执行一次 | | timeoutMs | number | 不限制 | 超时后先发 SIGTERM，再发 SIGKILL |

CLI 命令

cron-task init [--force] [--config <path>]
cron-task validate [--config <path>] [--json]
cron-task start [--config <path>] [--foreground]
cron-task stop
cron-task restart [--config <path>]
cron-task status [--json]
cron-task list [--config <path>] [--json]
cron-task run <task-name> [--config <path>]
cron-task logs [--lines <n>]
cron-task config-path
cron-task --help
cron-task --version

命令说明

• init：在 ~/.cron-task/cron-task.json 写入示例配置
• validate：校验配置结构，并输出生成后的 cron 表达式
• start：启动后台守护进程，调试时可加 --foreground
• stop：优雅停止守护进程，并清理 PID 文件
• restart：修改配置后的标准生效方式
• status：查看守护进程是否运行、加载了哪个配置、何时启动
• list：查看配置中的任务，以及 nextRun 等运行时状态
• run：立刻手动执行一个已配置任务
• logs：查看最近的守护进程日志

~/.cron-task 下的文件

cron-task 会在用户目录下维护一组运行文件：

• cron-task.json：用户配置
• cron-task.pid：守护进程 PID
• cron-task.state.json：运行状态和任务历史
• cron-task.log：守护进程日志

本地时区行为

如果任务没有声明 timezone，或者显式写成 "local"，cron-task 会通过 Intl.DateTimeFormat().resolvedOptions().timeZone 获取当前机器时区，并传给 node-cron。

也就是说，默认情况下写 09:00 就表示“当前机器本地时区的 09:00”。

推荐使用流程

cron-task validate
cron-task start
cron-task status
cron-task list

修改 ~/.cron-task/cron-task.json 后：

cron-task validate
cron-task restart

开发

npm install
npm run verify