Cron 表达式校验:库太宽容,4 段空串都照收
用 cron-parser 计算“下一次执行时间”时,空字符串和 4 段表达式都不会报错,而是被补成某个合法计划继续计算。如果入口不先检查段数,用户看到的可能是一个完全没打算配置的定时任务。
先给结论
cron 解析库的职责是“把表达式变成时间”,不是“判断这是不是你想要的表达式”。cron-parser 遇到不足 6 段的内容时,会在左边补默认字段,补完再解析;空串则直接替换成 0 * * * * *。所以校验要分两层:
- 入口先做结构校验,只接受标准 5 段或带秒 6 段;
- 范围、步长、
L、#等语法仍然交给库,报错原文透传。
可以直接在 cron 表达式解析工具 里对照本文的输出,页面完全在浏览器本地计算。
现象:空串和 4 段都能算出“下一次”
先不经过任何页面,直接调用库。下面的命令在门户项目目录执行,环境是 Node 24、cron-parser 当前安装版本:
node --input-type=module -e "
import { CronExpressionParser } from 'cron-parser'
const show = (expr) => {
const it = CronExpressionParser.parse(expr, {
currentDate: new Date('2026-11-19T00:00:00Z'),
tz: 'UTC'
})
console.log(JSON.stringify(expr), '->', it.next().toDate().toISOString())
}
show('')
show('0 9 * *')
show('0 9 * * 1')
show('0 9 * * 1 30')
"
实际输出:
| 表达式 | 输出 | 实际含义 |
|---|---|---|
'' | 2026-11-19T00:01:00.000Z | 从现在起每分钟执行 |
0 9 * * | 2026-12-09T00:00:00.000Z | 每月 9 日 00:00,不是每天 9 点 |
0 9 * * 1 | 2026-11-23T09:00:00.000Z | 每周一 09:00,符合预期 |
0 9 * * 1 30 | 抛错 Constraint error, got value 30 expected range 0-7 | 第 6 段被当成星期,不是年份 |
第一行和第四行最容易被忽略。空串没有报错,0 9 * * 也没有报错,但后者算出来的计划跟“每天 9 点”毫无关系。如果这个字符串来自配置文件、表单或接口参数,只把库的异常当成校验结果,就会把错误计划写进调度器。
根因:缺字段时在左边补默认值
打开 node_modules/cron-parser/dist/CronExpressionParser.js,处理字段的 #getRawFields 里有这样两段逻辑:
expression = expression || '0 * * * * *'
const atoms = expression.trim().split(/\s+/)
if (atoms.length > 6) {
throw new Error('Invalid cron expression, too many fields')
}
const defaults = ['0', '*', '*', '*', '*', '*']
if (atoms.length < defaults.length) {
atoms.unshift(...defaults.slice(0, defaults.length - atoms.length))
}
const [second, minute, hour, dayOfMonth, month, dayOfWeek] = atoms
两件事同时发生:
- 空串被替换成
0 * * * * *,所以永远解析得动; - 少于 6 段时不是从右边补,而是用
unshift从左边补。
补位方向决定了 4 段表达式的语义会整体错位。0 9 * * 补两个默认字段后变成:
0 * 0 9 * *
秒 分 时 日 月 周
于是 0 落在“日”,9 落在“月”,计划成了“每月 9 日 00:00”。这既不是标准的 5 段省略星期,也不是某些系统里的 4 段写法,只是一个补位后的巧合。
strict 模式会拒绝少于 6 段,但它同时要求日和周不能同时出现,和其他系统的用法并不一致。把 strict: true 直接打开,正常 5 段表达式也会被拒。这也是为什么门户没有依赖严格模式,而是在自己的入口做段数校验。
第一层校验:先数段数
门户的 analyzeCron 在调用库之前先做两件事:展开别名、检查段数。核心代码在 app/utils/cron-expr.ts:
const normalized = normalizeCronExpr(expr)
if (!normalized) {
return { ok: false, errorCode: 'empty', errorDetail: '', runs: [], shape }
}
const fields = normalized.split(/\s+/).filter(Boolean)
if (fields.length !== 5 && fields.length !== 6) {
return {
ok: false,
errorCode: 'fieldCount',
errorDetail: String(fields.length),
runs: [],
shape
}
}
段数检查放在别名展开之后,因为 @daily、@hourly 这类写法本身只有一个 token,不展开就会被误判成 1 段。normalizeCronExpr 先把它们映射成标准表达式:
| 别名 | 展开结果 |
|---|---|
@yearly / @annually | 0 0 1 1 * |
@monthly | 0 0 1 * * |
@weekly | 0 0 * * 0 |
@daily / @midnight | 0 0 * * * |
@hourly | 0 * * * * |
页面据此给出的是确定文案,而不是库内部的英文异常:
字段数为 4:标准 cron 需要 5 段(分 时 日 月 周)或 6 段(秒 分 时 日 月 周)
这里没有尝试“猜用户想要什么再补齐”。4 段可以来自标准 cron 少写周日,也可以来自 Quartz 少写年份,补错方向比报错更难排查。
第二层:库的语法报错原样透出
段数正确之后,范围与步长交给库:
try {
const iterator = CronExpressionParser.parse(normalized, {
currentDate: options.from ?? new Date(),
tz
})
// 依次取 5 次执行时间
} catch (error) {
return {
ok: false,
errorCode: 'syntax',
errorDetail: error instanceof Error ? error.message : String(error),
runs: [],
shape
}
}
比如在分钟字段写 61,页面显示:
表达式不合法:Constraint error, got value 61 expected range 0-59
这里刻意不重写库的语法规则。cron 的方言很多:L 表示月末,# 表示“第几个星期几”,不同实现对范围、步长、星期从 0 还是 1 开始都有差异。库更新后语法支持会变化,自己维护一套正则只会越来越偏。结构问题(段数)由页面负责,字段细节交给库,错误信息保留原文,用户搜索报错时也能对上。
五段与六段的字段顺序
两种写法都接受,但顺序不同,差一位就会得到完全不同的计划:
| 段数 | 顺序 | 示例 | 含义 |
|---|---|---|---|
| 5 段 | 分 时 日 月 周 | 0 9 * * 1-5 | 工作日 09:00 |
| 6 段 | 秒 分 时 日 月 周 | 30 0 9 * * 1-5 | 工作日 09:00:30 |
7 段表达式会被段数校验直接拒绝。有些调度器用第 7 段表示年份,cron-parser 这里不接受,页面也不会把它当成合法输入。同样,0 9 * * 1 30 的第 6 段不是年份,而是星期,库会报 expected range 0-7,这正是字段错位的典型表现。
六段里的秒字段还会影响页面上的自然语言描述。describeCron 只有在秒字段是 * 时才说“每秒执行一次”;秒字段是 0 时,实际是每分钟的第 0 秒执行,仍然归为“每分钟”。如果秒字段写成 */5 这类步长,形状判断回落到“自定义表达式”,但解析和时间计算照常进行——描述只是辅助,不参与校验。
时区:9 点是谁的 9 点
同一个表达式在不同时区算出的绝对时间不同。门户把 IANA 时区名传给库,再用 dayjs 按目标时区格式化:
const iterator = CronExpressionParser.parse('0 9 * * *', {
currentDate: new Date('2026-11-19T00:00:00Z'),
tz: 'Asia/Shanghai'
})
console.log(iterator.next().toDate().toISOString())
从同一个 UTC 起点计算,结果如下:
| 时区 | 下一次 09:00 的 UTC 时间 |
|---|---|
Asia/Shanghai | 2026-11-19T01:00:00.000Z |
UTC | 2026-11-19T09:00:00.000Z |
Europe/Berlin(2026-03-28) | 2026-03-28T08:00:00.000Z |
Europe/Berlin(2026-03-29,夏令时开始) | 2026-03-29T07:00:00.000Z |
夏令时切换当天,柏林的 09:00 从 UTC+1 变成 UTC+2,绝对时间提前一小时。页面显示的始终是“目标时区的墙上时间 + 对应的绝对时刻”,避免运维把“每天 9 点备份”理解成服务器本地时间。
春季跳过的时刻还有另一个边界。30 2 * * * 在纽约 2026-03-08 这天,本地 02:30 不存在,库返回的是 07:30Z,即当地 03:30:
30 2 * * * America/New_York 2026-03-08T07:30:00.000Z
30 2 * * * America/New_York 2026-03-09T06:30:00.000Z
也就是说,跳过的时刻被顺延到切换后的第一个有效时刻,而不是整天不执行。不同调度器对这种情况的处理并不统一,涉及计费、备份、对账的任务应在目标环境里实测一次,不能只看网页结果。
还要注意:页面算得对,不代表执行器认时区。系统 crontab 通常跟随服务器时区,Kubernetes CronJob 用 timeZone 字段,Quartz 有自己的时区配置。把页面上的时区当成“表达式的一部分”写进文档,才能真正对齐。
首屏时间为什么不能直接渲染
工具页要显示“还有多久执行”,这个值依赖 Date.now()。服务端渲染和浏览器首次渲染的时间不可能完全相同,直接在第一帧算相对时间,容易出现服务端输出“2 分后”、浏览器输出“1 分后”的差异。门户用 ready 把这块内容推迟到挂载之后:
const ready = ref(false)
const nowMs = ref(0)
onMounted(() => {
nowMs.value = Date.now()
ready.value = true
setInterval(() => {
nowMs.value = Date.now()
}, 1000)
})
模板里是 v-if="ready && analysis.ok",服务端首屏不输出执行时间列表,挂载后再渲染并每秒更新。代价是首屏少一段内容,换来的是首帧稳定、倒计时不会停住。这个问题的通用排查思路写在 Nuxt 首屏不一致排查 里。
验证清单
下面这些输入可以直接在 /toolkit/cron 里逐条对照。页面输出以中文文案为准,库输出以 UTC 时间为准:
| 输入 | 页面表现 |
|---|---|
| 空字符串 | 请输入 cron 表达式 |
0 9 * * | 字段数为 4:标准 cron 需要 5 段…… |
0 9 * * 1 30 | 表达式不合法:... expected range 0-7 |
61 * * * * | 表达式不合法:... expected range 0-59 |
*/5 * * * * | 每 5 分钟执行一次 |
0 9 * * 1-5 | 每周 周一、周二、周三、周四、周五 的 09:00 执行 |
* * * * * * | 每秒执行一次 |
@daily | 每天 00:00 执行 |
需要验证库本身的行为时,用本文第一段命令;需要验证页面文案时,直接在输入框里改表达式,切换时区后再看列表。两条路径分开验证,才能区分“库算错了”和“页面描述错了”。
FAQ
为什么 @daily 能用,7 段表达式不行?
别名在段数校验之前就被展开成 5 段,所以能通过。7 段没有对应的标准语义,cron-parser 也会拒绝超过 6 段,页面在入口直接按段数报错,避免把年份字段误当成星期。
4 段表达式能不能自动补成“每天 9 点”?
不能可靠地补。4 段既可能是标准 cron 少写星期,也可能是别的系统少写秒字段,补位方向不同,结果完全不同。与其猜,不如明确要求 5 段或 6 段,让用户自己写清楚。
夏令时跳过的 2:30 会执行吗?
在 cron-parser 的当前实现里,会顺延到切换后的 03:30 执行,而不是跳过整天。实际调度器可能不同,关键任务要在目标环境验证。
L、# 这些扩展写法支持吗?
页面不承诺扩展语法,但不会预先拦截;库能解析就展示结果,解析失败就把原始报错给出来。真正执行前,仍要以目标调度器的文档和实测为准。
结语
cron 解析库的宽容是为了“尽量算出一个时间”,不是为了让配置更安全。入口多做一步段数检查,就能把空串、4 段、7 段这些“能解析但语义错位”的输入挡在外面;段数之外的范围和方言,继续交给库和原始报错。更多前端实现与排错记录整理在 前端开发 分类下。
评论
还没有评论,来说两句吧