Cron 表达式详解:5 个字段、示例与常见陷阱
cron 表达式由分、时、日、月、星期五个字段组成,每个字段描述一组允许的值。当前时间与所有字段都匹配时任务才会运行,但日期和星期这两个字段有一个重要的例外。
ConvertBox发布
从左到右的五个字段
经典的 cron 表达式由五个用空格分隔的字段组成。cron 每分钟醒来一次,如果当前的分、时、日、月都落在对应字段所描述的集合里,就运行任务。表达式是套在时钟上的过滤器,而不是计算间隔的定时器。下文提到的各种意外行为,大多可以用这一区别来解释。
| 字段 | 允许的值 | 示例 |
|---|---|---|
| 分 | 0-59 | 30 表示在第 30 分钟 |
| 时 | 0-23 | 0 是午夜,13 是下午 1 点 |
| 日 | 1-31 | 15 表示 15 日 |
| 月 | 1-12 或 JAN-DEC | 7 或 JUL |
| 星期 | 0-6 或 SUN-SAT | 0 是星期日,多数实现也接受用 7 表示星期日 |
四个特殊字符:* , - /
每个字段可以写一个数字,也可以写由四种运算符构成的集合。它们还可以组合使用,例如 0-30/10 或 1,15,20-25。
| 字符 | 含义 | 在分钟字段中的示例 | 触发的分钟 |
|---|---|---|---|
| * | 所有值 | * | 0、1、2 … 59 |
| , | 列表 | 5,35 | 5 和 35 |
| - | 包含两端的范围 | 10-13 | 10、11、12、13 |
| / | 在范围内按步长取值 | */15 | 0、15、30、45 |
| - 与 / | 在指定范围内按步长取值 | 0-30/10 | 0、10、20、30 |
逐个字段读懂示例
阅读表达式时按从分钟到星期的顺序。初学者常犯的错误是把分钟字段留成 *:表达式 * 9 * * * 会从 09:00 到 09:59 每分钟运行一次,一共 60 次。
- 0 9 * * 1-5:星期一到星期五的 09:00。
- */15 9-17 * * 1-5:工作日 9 点到 17 点期间每 15 分钟一次。小时范围包含末尾的值,所以最后一次运行是 17:45,而不是 17:00。
- 0 */6 * * *:每天的 00:00、06:00、12:00 和 18:00。
- 5,35 * * * *:每小时两次,分别在第 5 分钟和第 35 分钟。
- 30 2 1 * *:每月 1 日的 02:30。
- 0 22 * * 0:每个星期日的 22:00。
- 0 0 1 1 *:每年一次,1 月 1 日午夜。
为什么 */7 和 31 日的行为出乎意料
步长的意思并不是每经过 N 个时间单位运行一次。它从字段范围的最小值开始挑选数值,字段转完一圈之后重新开始挑选。分钟字段中的 */7 匹配 0、7、14,一直到 56,然后又回到 0,于是每到整点之前会出现一个 4 分钟的间隔。小时字段中的 */5 匹配 0、5、10、15 和 20,所以跨过午夜的间隔是 4 小时。日期字段中的 */2 匹配奇数日,所以任务在 31 日运行之后,第二天 1 日又会运行。只有能整除范围的步长才会产生均匀的间隔,例如分钟用 5、10、15、20、30,小时用 2、3、4、6、8、12。
不存在的日期只是永远不会匹配。0 0 31 * * 只在有 31 日的七个月份里运行,其余五个月被悄悄跳过;30 日会跳过二月,29 日在二月只有闰年才运行。标准 cron 没有表示月末的符号。常见的变通做法是把任务安排在 28-31 日,并让命令先检查明天是不是 1 日,再决定是否执行实际工作。
日期和星期是“或”的关系
所有字段都必须匹配,这条原则有一个例外。当日期字段和星期字段都受到限制,也就是两者都不是 * 时,经典 cron 只要其中一个匹配就会运行任务。0 0 13 * 5 并不是 13 日星期五:它在每月 13 日运行,也在每个星期五运行。同样,0 9 1-7 * 1 并不表示第一个星期一,它在每月前七天的每一天运行,也在每个星期一运行。
当两个字段中有一个是 * 时,只有另一个字段对日程起限制作用,这才是大多数人预期的行为。如果确实需要两个条件同时成立,就在表达式里限制其中一个字段,在命令里判断另一个:安排 0 9 1-7 * *,并让脚本在今天不是星期一时直接退出。带扩展语法的调度器可以直接表达这种需求;在 Quartz 中,星期字段里的 MON#1 表示当月的第一个星期一。
时区与夏令时
表达式里不包含时区,时区由运行它的系统提供。传统的 Linux crontab 使用服务器的本地时间。GitHub Actions 的计划任务始终是 UTC。Kubernetes CronJob 使用集群控制器的时区,除非设置了 spec.timeZone。在 UTC 系统上,想在北京时间 09:00 运行的任务要减去 8 小时,写成 0 1 * * *。中国不实行夏令时,所以这个差值全年不变。
在实行夏令时的时区,还有两个额外的风险。春季拨快时钟的那一天有一个小时并不存在,安排在这一小时内的任务当天可能不会运行;秋季拨回的那一天有一个小时会出现两次,其中的任务可能运行两次。调度器如何处理这些情况取决于具体实现。按 UTC 安排任务,或者让任务避开本地时间的切换时段,可以同时避免这两个问题。
经典 cron、Quartz 与各平台的方言
cron 语法是一个家族,而不是一个统一的标准。五字段表达式在 Quartz 中无效,Quartz 表达式在 crontab 中也无效,所以从别处复制日程之前,要先确认平台使用的是哪一种方言。
本站的 cron 助手解析标准的五个字段。它把表达式转换成页面语言的一句话,并另外列出接下来五次运行的时间,时间按浏览器的时区显示;当这句话和这些日期都符合你的意图时,这个表达式对于运行在该时区的五字段调度器就是正确的。L、W、#、? 等扩展属于表中的各个平台,请查阅它们的文档。正则表达式可以确认一个字符串是否由五个以空格分隔的字段组成,这对输入校验很有用,也很容易在正则测试工具里试验,但它无法告诉你任务何时运行。
| 方言 | 字段数 | 需要了解的差异 |
|---|---|---|
| Unix crontab | 5 | 使用服务器本地时间;许多实现接受 @daily、@hourly 等简写 |
| Quartz | 6 或 7 | 秒在最前,年份在最后且可省略;两个日期字段之一必须用 ?;增加了 L、W 和 # |
| Spring @Scheduled | 6 | 秒在最前,没有年份字段 |
| AWS EventBridge | 6 | 分钟在最前,年份在最后,没有秒;两个日期字段之一必须用 ? |
| GitHub Actions | 5 | 始终是 UTC;最短间隔为每 5 分钟;负载高时运行可能延迟 |
| Kubernetes CronJob | 5 | 未设置 spec.timeZone 时使用控制器的时区 |