gocron秒级Cron表达式完全手册:6字段语法、快捷写法与常见场景示例清单
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 预览:边输入边解析,保存前就能看到接下来 N 次执行时间和未来 7 天的执行分布热图,非法表达式会即时提示错误而不会污染控制台。
- 预览接口:internal/routers/task/cron_preview.go
- 输入保护:单行、最长 128 字符,防止换行注入和超长表达式攻击
热图对 * * * * * *(每秒一次)这类超高频表达式做了迭代上限保护,7 天内触发次数过多时会自动截断展示,不影响服务性能。
多时区场景:CRON_TZ 前缀
如果你的服务器部署在海外或团队跨时区协作,可以在表达式前加时区前缀:
CRON_TZ=Asia/Shanghai 0 30 9 * * *
规则(见 internal/service/cron_preview.go 的 resolveSpecTimezone 逻辑):
- 未指定时区 → 使用服务器本地时区
- 表达式自带
CRON_TZ=或TZ=前缀 → 以前缀为准 - 显式传入 timezone 参数 → 覆盖表达式中的前缀
AI 辅助:自然语言直接生成 Cron
不会背表达式?gocron 内置了 AI 转换能力(internal/routers/task/nl_to_cron.go):在任务编辑页输入"工作日早上9点半发日报",AI 会生成 0 30 9 * * 1-5 并立即用预览接口校验合法性,生成结果可直接填入。
调度器整体状态与任务执行情况可在调度面板中查看:
常见错误与排查清单
| 报错/现象 | 原因 | 解决办法 |
|---|---|---|
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 表达式只需记住三件事:
- 6 字段:
秒 分 时 天 月 周,秒在最前,这是与标准 cron 最大的区别 - 快捷写法:
@daily、@hourly、@every 30s等描述符比长表达式更直观 - 先预览再保存:编辑页的实时预览 + 一周热图,能帮你提前发现 90% 的配置错误
配合任务超时、失败重试和单实例运行等能力,秒级 Cron 表达式可以覆盖从秒级巡检到年度结算的全部调度场景。更多细节可参考 docs/zh/guide/scheduled-tasks.md 中的定时任务文档。

