Cron 表达式校验:库太宽容,4 段空串都照收

2026-11-19 前端开发 有希 37 views

用 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 * * 12026-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

两件事同时发生:

  1. 空串被替换成 0 * * * * *,所以永远解析得动;
  2. 少于 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 / @annually0 0 1 1 *
@monthly0 0 1 * *
@weekly0 0 * * 0
@daily / @midnight0 0 * * *
@hourly0 * * * *

页面据此给出的是确定文案,而不是库内部的英文异常:

字段数为 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/Shanghai2026-11-19T01:00:00.000Z
UTC2026-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 段这些“能解析但语义错位”的输入挡在外面;段数之外的范围和方言,继续交给库和原始报错。更多前端实现与排错记录整理在 前端开发 分类下。

Comments

Sign in to join the discussion

No comments yet — be the first to say something

Related Articles