gocron秒级Cron表达式完全手册:6字段语法、快捷写法与常见场景示例清单

原创2026-10-26 16:46:181,396 阅读

gocron秒级Cron表达式完全手册:6字段语法、快捷写法与常见场景示例清单

gocron 是一个分布式定时任务管理系统,它的任务调度基于秒级 Cron 表达式(6 字段语法),比传统 Linux crontab 多了一个"秒"字段,支持最短到秒级的任务频率。本文将带你完整掌握 gocron Cron 表达式的 6 字段语法、快捷写法和常见场景示例清单,并介绍实时预览、时区设置与 AI 自然语言生成等实用功能。

为什么是秒级 Cron 表达式?

传统 Linux crontab 最小粒度是分钟,无法满足"每 20 秒检查一次接口"这类高频场景。gocron 采用 6 字段秒级 Cron 表达式,第一个字段就是秒,让你可以:

  • ⚡ 配置秒级高频任务,如 */20 * * * * *(每 20 秒一次)
  • 🎯 精确控制执行时间点,如 0 30 21 * * *(每晚 21:30:00 整)
  • 🔍 保存前实时预览接下来的执行时间和未来 7 天分布热图,避免"表达式写错、任务跑偏"

预览能力由后端统一解析(internal/service/cron_preview.go),与实际调度引擎使用同一个 cron 库,保证"所见即所得"。

6 字段语法:秒 分 时 天 月 周

gocron 的表达式格式固定为:

秒 分 时 天 月 周
字段 位置 取值范围 说明
秒 第 1 位 0-59 每一秒触发(秒级任务的灵魂)
分 第 2 位 0-59 分钟
时 第 3 位 0-23 小时
天 第 4 位 1-31 日期
月 第 5 位 1-12 月份
周 第 6 位 0-6 星期,0=周日,6=周六

💡 与标准 5 字段 Unix cron 的关键区别:第一个字段是秒。如果误把 5 字段表达式填进去,会被引擎按"秒 分 时 天 月"误读,导致任务在错误时间执行。gocron 的 AI 生成接口会强制校验 6 字段(internal/routers/task/nl_to_cron.go)。

另外,gocron 兼容 5 段写法(省略周字段时自动补 *),例如 0 30 9 * * 表示每天 09:30:00 执行。

字段值与组合规则:通配、范围、步进、列表

每个字段都支持以下 4 种组合方式,用英文逗号分隔多项:

写法 含义 示例
* 任意值 * * * * * * 每秒执行
*/N 每 N 个单位 */20 * * * * * 每 20 秒
A-B 范围 0 0 9-18 * * * 每天 9 点到 18 点每小时整
A,B,C 列表 0 0 9,12,18 * * * 每天 9、12、18 点整
A-B/step 范围内步进 0 0 9-18/2 * * * 9 点到 18 点每隔 2 小时
组合 列表+范围混合 0 30 9 * * 1-5 工作日 9:30

常用速记:

0 * * * * *          # 每分钟的第 0 秒执行
0 */5 * * * *        # 每 5 分钟一次
*/20 * * * * *       # 每 20 秒一次
0 0 9 * * 1-5        # 工作日早上 9 点整

快捷写法:@ 描述符一览

不想记 6 个字段?gocron 内置了一组 @ 快捷描述符,语义更直观:

快捷写法 说明 等价 6 字段表达式
@yearly 每年执行一次(1月1日 0点) 0 0 0 1 1 *
@monthly 每月执行一次(1号 0点) 0 0 0 1 * *
@weekly 每周执行一次(周日 0点) 0 0 0 * * 0
@daily 每天 0 点执行一次 0 0 0 * * *
@midnight 每天午夜执行(同 @daily) 0 0 0 * * *
@hourly 每小时第 0 分 0 秒执行 0 0 * * * *
@every 30s 每隔 30 秒执行 无(固定间隔)
@every 1m20s 每隔 1 分 20 秒执行 无(固定间隔)
@every 3h5m10s 每隔 3 小时 5 分 10 秒执行 无(固定间隔)
@reboot 调度器启动时执行一次 无(启动触发)

⚠️ @reboot 注意:启用高可用时它会在 leader 节点上执行,每次重启或主备切换后都会再跑一次,请确保命令是幂等的。

⚠️ @every vs */N 的区别:@every 30s 是"上一次执行完计时"的固定间隔;*/30 * * * * * 是"每个 30 秒刻度"的对齐触发。需要和系统时间对齐时用后者。

常见场景示例清单:直接抄作业

按使用频率整理的高频场景清单(完整示例见 docs/zh/guide/scheduled-tasks.md):

场景 表达式
每 20 秒巡检一次接口 */20 * * * * *
每分钟采集一次监控数据 0 * * * * *
每天早上 9:30 发日报 0 30 9 * * *
工作日早 9 点启动业务脚本 0 0 9 * * 1-5
每天晚上 21:30 备份数据库 0 30 21 * * *
每周六晚 23 点清理临时文件 0 0 23 * * 6
每周一凌晨 3 点全量同步 0 0 3 * * 1
每月 1 号零点出月报 0 0 0 1 * *
每天 9-18 点每小时汇报 0 0 9-18 * * *
每月最后一天后结算(下月1号0点) 0 0 0 1 * *

在任务列表页,你可以直接看到每个任务基于 6 字段 Cron 表达式计算出的下次执行时间:

gocron秒级Cron任务列表与下次执行时间预览

表达式写错怎么办:实时预览与一周热图

gocron 任务编辑页内置了 Cron 预览:边输入边解析,保存前就能看到接下来 N 次执行时间和未来 7 天的执行分布热图,非法表达式会即时提示错误而不会污染控制台。

热图对 * * * * * *(每秒一次)这类超高频表达式做了迭代上限保护,7 天内触发次数过多时会自动截断展示,不影响服务性能。

多时区场景:CRON_TZ 前缀

如果你的服务器部署在海外或团队跨时区协作,可以在表达式前加时区前缀:

CRON_TZ=Asia/Shanghai 0 30 9 * * *

规则(见 internal/service/cron_preview.go 的 resolveSpecTimezone 逻辑):

  1. 未指定时区 → 使用服务器本地时区
  2. 表达式自带 CRON_TZ= 或 TZ= 前缀 → 以前缀为准
  3. 显式传入 timezone 参数 → 覆盖表达式中的前缀

AI 辅助:自然语言直接生成 Cron

不会背表达式?gocron 内置了 AI 转换能力(internal/routers/task/nl_to_cron.go):在任务编辑页输入"工作日早上9点半发日报",AI 会生成 0 30 9 * * 1-5 并立即用预览接口校验合法性,生成结果可直接填入。

调度器整体状态与任务执行情况可在调度面板中查看:

gocron调度器状态与秒级Cron任务运行监控

常见错误与排查清单

报错/现象 原因 解决办法
expected 5 or 6 fields 字段数量不是 5 或 6 个 检查空格分隔,标准 cron 5 字段需补 1 位秒字段
unrecognized @ 描述符拼写错误 对照上文快捷写法表
unknown timezone 时区名不存在(如 Mars/Phobos) 使用 IANA 标准时区名,如 Asia/Shanghai
任务在"错误时间"执行 把 5 字段 Unix cron 当成了 6 字段 第一个字段是秒,整体右移一位
@every 30s 写成了 @every 30 缺少时间单位 必须带 s/m/h 单位

排查口诀:先看字段数 → 再看秒字段 → 最后看时区。

小结

掌握 gocron 秒级 Cron 表达式只需记住三件事:

  1. 6 字段:秒 分 时 天 月 周,秒在最前,这是与标准 cron 最大的区别
  2. 快捷写法:@daily、@hourly、@every 30s 等描述符比长表达式更直观
  3. 先预览再保存:编辑页的实时预览 + 一周热图,能帮你提前发现 90% 的配置错误

配合任务超时、失败重试和单实例运行等能力,秒级 Cron 表达式可以覆盖从秒级巡检到年度结算的全部调度场景。更多细节可参考 docs/zh/guide/scheduled-tasks.md 中的定时任务文档。

登录后查看全文
gocron