Luxon 3.x 版本演进全解析:从 CHANGELOG 到源码的日期时间库升级指南

原创2026-09-20 16:54:492,273 阅读
文章标签:开发工具

Luxon 3.x 版本演进全解析:从 CHANGELOG 到源码的日期时间库升级指南

Luxon 是一个面向 JavaScript 的日期与时间处理库,采用不可变(immutable)设计,完整支持时区、国际化与 ISO 8601 规范。本文以仓库根目录的 CHANGELOG.md 为骨架,逐版本梳理 Luxon 从 1.x 到 3.7.2 的关键变更,并结合 src/ 下的核心实现与 test/ 下的测试用例,讲解每个新 API 的用法、设计动机与底层原理,帮助你判断升级路径并快速上手新特性。

3.7.x:格式化与解析能力的集中升级

3.7.0(2025-07-09)是当前仓库 package.json 所标注版本(3.7.2)的里程碑式更新,带来了大量面向日常格式化与解析的实用功能。

Duration 人性化输出:showZeros 与 removeZeros

3.7.0 为 Duration#toHuman 新增 showZeros 选项,并新增 Duration#removeZeros 方法。

  • toHuman({ showZeros: false }):默认 showZeros 为 true,会保留所有曾使用过的单位(即使为 0);设为 false 后,值为 0 的单位将从人类可读输出中剔除。其实现位于 src/duration.js:const showZeros = opts.showZeros !== false;,随后在遍历单位时对 val === 0 && !showZeros 的单位返回 null 跳过。
const dur = Duration.fromObject({ months: 1, weeks: 0, hours: 5, minutes: 6 });
dur.toHuman(); //=> '1 month, 0 weeks, 5 hours, 6 minutes'
dur.toHuman({ showZeros: false }); //=> '1 month, 5 hours, 6 minutes'
  • removeZeros():直接返回一个移除了所有零值单位的新 Duration,例如 Duration.fromObject({ years: 2, days: 0, hours: 0, minutes: 0 }).removeZeros().toObject() 得到 { years: 2 }。实现同样位于 src/duration.js,通过 removeZeroes(this.values) 清理内部值对象;注意当所有单位都为零时,它会返回一个空对象 {},对应测试见 test/duration/units.test.js。与 showZeros: false 的"仅隐藏输出"不同,removeZeros 是真正改变 Duration 内部结构的操作。

配套测试覆盖了 showZeros: false、showZeros: undefined(保持默认行为)、跨语言输出以及 quarter/month 混合单位等场景,见 test/duration/format.test.js。

相对时间四舍五入:DateTime#toRelative 的 rounding 选项

3.7.0 为 DateTime#toRelative 新增 rounding 选项,用于控制数字舍入方向。可取值包括 "trunc"(向零截断,默认)、"expand"(远离零)、"round"、"floor"、"ceil"。

底层实现在 src/datetime.js 的 diffRelative 函数中:const rounding = isUndefined(opts.rounding) ? "trunc" : opts.rounding;,最终交给 src/impl/util.js 的 roundTo(number, digits, rounding) 完成实际舍入;其中 "expand" 会对正数向上、负数向下(远离零),非法值会抛出 RangeError("Value rounding ... is out of range")。

DateTime.now().minus({ minutes: 3 }).toRelative({ rounding: "ceil" });
// 结合 round 与 padding 等参数,可精细控制相对时间的展示粒度

完整参数还包括 unit、round(默认 true)、padding(毫秒级缓冲,用于阈值内向上取整)与 locale,详见 src/datetime.js 的 JSDoc。

ISO 输出的 precision 选项

3.7.0 为 toISO()、toISODate()、toISOTime() 等 ISO 格式化方法加入 precision 选项,允许按 "years"、"months"、"days"、"hours"、"minutes"、"seconds"、"milliseconds" 截断输出,例如 DateTime.now().toISO({ precision: 'day' }) 输出 '2017-04-22Z'、toISO({ precision: 'minute' }) 输出 '2017-04-22T20:47Z'。

实现位于 src/datetime.js:toISODate 与 toISOTime 均通过 switch (precision) 在到达指定精度时提前 return;当 precision 与 suppressSeconds/suppressMilliseconds 同时使用时,precision 决定输出中包含的最大单位,而秒/毫秒若为 0 仍会被抑制。测试见 test/datetime/format.test.js,其中非法精度(如 "ms"、"xxx")会抛出 InvalidUnitError,null 会抛出 TypeError。

时长格式化的 signMode 选项

Duration#toFormat 新增 signMode 选项,取值 'negative'(默认)、'all'、'negativeLargestOnly',控制负号的呈现方式,见 src/duration.js:

Duration.fromObject({ days: 6, seconds: 2 }).toFormat("d s", { signMode: "all" }); //=> "+6 +2"
Duration.fromObject({ days: -6, seconds: -2 }).toFormat("d s", { signMode: "all" }); //=> "-6 -2"
Duration.fromObject({ days: -6, seconds: -2 }).toFormat("d s", { signMode: "negativeLargestOnly" }); //=> "-6 2"

其核心实现在 src/impl/formatter.js:negativeLargestOnly 时仅最大单位带负号,其余单位通过 signDisplay = "never" 隐藏符号;all 模式则使用 signDisplay = "always" 强制每个单位都显示符号。实现还处理了一个边界:当最大单位舍入为 0 时,普通 "auto" 符号显示会丢掉负号,因此代码通过负零(-0)技巧保留符号。

解析与健壮性改进

  • 允许在格式字符串中转义单引号:现在可以用反斜杠转义单引号,使单引号可以作为字面量出现在格式化输出中,而不是始终作为文本分隔符。
  • 小写 t 与 z 分隔符:ISO 字符串解析现在接受小写 t 作为日期与时间之间的分隔符,接受小写 z 作为偏移量标记(此前仅接受大写 T/Z)。解析逻辑集中在 src/impl/regexParser.js,该文件以"regex + extractor"配对方式处理各类 ISO 变体。
  • 拒绝非有限数字:此前仅拒绝 NaN,现在 Infinity、-Infinity 等非有限数字也会被拒绝。相关校验见 src/impl/util.js 的 asNumber:typeof value === "boolean" || value === "" || !Number.isFinite(numericValue) 时抛出 InvalidArgumentError。
  • ja 语言环境优化:改进了 Info.months 与 Info.monthsFormat 在日语 locale 下的输出质量。

此外 3.7.0 还完善了 Interval 的文档,并为文档站点加入了暗色主题(对应仓库中的 site/plugins/dark-theme-toggle.css 与 site/plugins/dark-theme-toggle.js)。

ES6 打包修复(3.7.1 / 3.7.2)

3.7.1 与 3.7.2(均为 2025-07-09)紧跟着修复了 ES6 打包(build/es6/luxon.mjs)的问题:3.7.1 回退了 3.7.0 引入的一个 ES6 打包变更,3.7.2 又修正了 ES6 打包本身。这与 package.json 中 exports 字段(import 指向 ./build/es6/luxon.mjs,require 指向 ./build/node/luxon.js)直接相关——ESM 消费者依赖这条路径,打包错误会直接影响 import { DateTime } from "luxon" 的使用。

3.6.x:区间端点与 Intl 兼容性

  • Interval.lastDateTime(3.6.0):返回区间结束前的最后一个时刻(即 end.minus(1)),实现见 src/interval.js。与已有的 start、end 等端点访问器配合,可以更方便地表达"包含末端"的区间语义。
  • 多时区计算修复(3.6.0):修复了同时使用多个时区时可能出现的错误时区换算。
  • minimalDays 回退(3.6.1):当 Intl.WeekInfo 不再提供 minimalDays 时提供回退逻辑,保证基于 Intl 的本地化周计算在环境差异下仍可用。
  • 缓存键修复(3.6.1):修复了当名称使用 "constructor" 等 JavaScript 关键字时各类缓存失效的问题——这类属性名会与 Object.prototype 上的同名成员冲突,导致缓存命中异常。

3.5.0:性能与严格模式

  • 多项整体性能改进,覆盖解析、格式化等热点路径。
  • throwOnInvalid 现在会让构造函数在年份非法时直接抛错。该全局开关由 Settings.throwOnInvalid 控制,配合 DateTime 的无效值(Invalid)机制使用——默认情况下非法日期构造出的是带 isValid: false 的对象而非异常,开启后则改为立即抛错,适合对数据合法性要求严格的场景。

3.4.x:本地化周与回归修复

  • 本地化周支持(3.4.4,#1454):引入基于 Intl 的区域化周概念,允许按目标 locale 计算"周"的起始日与一年中的周编号,相关能力可从 Info 与周相关方法中调用。
  • Node 自定义 inspect(3.4.4,#1526):为 Node.js 的 util.inspect 提供友好的自定义展示,调试时直接打印 DateTime/Duration 对象即可获得可读信息。
  • Interval.splitAt 排序修复(3.4.4,#1524):修复了按多个切点分割区间时的排序错误。
  • 3.4.0 的系列修复:改进了输入 zone 的类型检查、伊斯兰月份列表,以及 normalize() 对负数输入的处理。3.4.1–3.4.3 则陆续修复了 3.4.0 引入的回归(#1482、#1488、#1493、#1496)。

3.3.0:自定义时区格式化与解析增强

  • 修复 Interval#count 的 off-by-one 错误(#1308)。
  • 支持自定义 zone 的格式化(#1377):自定义 Zone 子类现在可以参与 toFormat 等格式化流程,此前只有内置 zone 可以。
  • 修复窄空格解析(#1369):正确处理 Intl 格式化输出中常见的窄空格(narrow no-break space)。
  • 处理公元 100 年的闰年问题(#1390):修复了跨公元 100 年边界时的日期计算。
  • 允许只解析一个偏移量:现在 DateTime.fromFormat 可以只从字符串中解析偏移信息,配合 setZone 使用可以构造出对应偏移的时刻。

3.2.x:安全与 Intl 集成

  • RFC-2822 正则漏洞修复(3.2.1):fromRFC2822 使用的正则表达式此前存在可被恶意输入利用的性能漏洞(ReDoS),3.2.1 重写了匹配逻辑。这是涉及安全的重要升级,建议使用该解析方法的用户尽快升级。
  • BCP 47 标签中的 -x- 扩展(3.2.1):更稳健地处理带私有扩展(如 en-US-x-foo)的语言标签。
  • timeZone 作为 Intl 选项(3.2.0):toLocaleString 等方法的 options 现在可直接传 timeZone,无需预先 setZone。
  • 跨闰年的月末 diff 修复(#1340):修复了 DateTime#diff 在跨越闰年时对"月末"的处理偏差。
  • Interval.toLocaleString()(#1320):新增区间的人类可读本地化输出,例如 [2022-01-01T00:00:00, 2022-01-02T00:00:00) 可格式化为符合 locale 习惯的文本。

3.1.x 与 3.0.x:配置能力的分水岭

两位数年份解析阈值(3.1.1)

新增 Settings.twoDigitCutoffYear,用于控制两位年份(如 "22")在解析时被解释为 20 世纪还是 21 世纪的临界年份,默认基于当前年份推算。例如解析 "01-02-03" 这类不完整年份时,该设置决定其归属世纪。

Duration 重缩放(3.1.0)

新增 Duration.rescale,将 Duration 按单位层级重新规整——例如 { seconds: 90 } 会重排为 { minutes: 1, seconds: 30 },使内部存储的单位分布更"规整",便于格式化输出。

3.0.0 的破坏性变更

  • "default" 作为 zone 选项:允许显式指定 "default" 来使用 Settings.defaultZone 配置的默认时区;同时 "system" 的语义被收紧为"真正指系统时区"(breaking change)。这改变了此前 "system" 可能被默认 zone 覆盖的行为,升级到 3.x 时需检查代码中对 "system" 的使用。

3.0.x 的格式化与矩阵能力

  • DateTime.expandFormat(3.0.2):将包含 Intl 宏 token(如 "DATETIME_FULL")的格式字符串展开为具体的 token 序列,便于检查或二次加工。
  • DateTime.parseFormatForOpts(3.0.1):根据 toLocaleString 的 options 反推可用于 fromFormat 的格式串,实现"同一份 options 既用于格式化又用于解析"。
  • Duration 自定义转换矩阵(3.0.2):Duration 支持传入自定义的"单位换算矩阵"(custom conversion matrix),允许按业务自定义单位间的换算比例(如自定义"工作日"长度)。这也是后续 Duration#shiftTo、rescale 等能力的基础。
  • 修复 quarters 的 diff(3.0.4,#1279)并在包中导出 package.json(#1239)。

2.x 关键里程碑:ESM、ISO 扩展与人性化输出

ISO 时区扩展解析(2.4.0)

支持解析带 IANA 时区扩展的 ISO 字符串,如 2022-05-08T20:42:00.000-04:00[America/New_York],方括号内的时区名会直接决定结果 zone;同时为 toISO()/toISOTime() 增加 extendedZone 选项,可在输出中追加 [America/New_York] 形式的扩展。这一能力是 3.x 之前最有价值的特性之一,让 ISO 字符串在保留偏移的同时携带精确时区语义。

ESM 支持与工具方法(2.3.x–2.5.0)

  • 2.5.0 起支持 ESM 风格 Node 导入,并放宽 ISO 时长字符串的位数上限。
  • Duration#toHuman()(2.3.0):将时长输出为人类可读列表(如 "1 year, 6 days"),是 3.7 中 showZeros 的基础。
  • DateTime#toUnixInteger()(2.3.1)与 DateTime.fromSeconds/toSeconds(1.8.1):补齐 Unix 时间戳(整数秒)的进出接口。
  • toSQL/toSQLTime 的 includeOffsetSpace 选项(2.3.1):控制 SQL 格式中偏移前的空格。
  • 2.3.0 对 toISO()、toISODate()、toISOTime()、toSQLDate() 做了大幅性能优化,并修复负年份的日期补零。
  • uu/uuu token(2.1.0):支持解析 ISO 字符串中的亚毫秒级小数秒。
  • fromFormat 偏移与 zone 并存时的消歧(2.2.0):同时提供偏移和 zone 时,允许偏移在歧义时刻(如 DST 回拨时段)中挑选正确时刻。
  • Duration.shiftTo() 浮点 bug 修复(2.2.0)与 ISO 时长小数元素支持(2.1.0)。

1.x 到 2.0 的升级

2.0.0 是一次破坏性大版本,官方为 1.x 用户准备了专门的升级说明,对应仓库文档见 docs/upgrading.md。升级前应重点核对:构造函数与工厂方法的 zone 语义、格式化默认值、Duration 负数表示等行为差异。

从 1.x 看 Luxon 的工程演进脉络

CHANGELOG 中 1.x 部分(1.6.0–1.28.0)同样值得追溯,它揭示了 Luxon 核心能力的成型过程:

  • 相对时间:DateTime#toRelative 与 toRelativeCalendar 于 1.9.0 引入,是 3.7 中 rounding 选项的前身。
  • ISO 解析与格式化的持续打磨:1.21.0 加入 quarter 解析、1.17.1 拒绝 ISO 日期输入中的 0 段、1.13.2 修复大于 999 年的 ISO 格式化补零、1.11.3 允许 ISO 字符串中的 24:00。
  • 时区正确性:1.12.1 修复跨月 diff、1.12.1 记忆化 IANA zone 创建、1.19.3 缓存偏移值——这些修复沉淀为 3.x 稳定的时区计算基础。
  • 宏 token 与 Intl 集成:1.18.0 支持宏 token 解析、1.17.0 新增 DATETIME_MED_WITH_WEEKDAY 预设、1.13.0 支持 numberSystem。
  • 类型安全:1.17.0 起 DateTime.min/max 对错误参数类型抛错,1.8.3 保证 isDateTime/isDuration 始终返回布尔值。

如何验证与跟进这些变更

仓库为每个版本特性都配有对应测试,你可以通过本地运行验证:

npm test          # 运行 jest 全量测试(含覆盖率)
npm run jest      # 仅运行测试,不采集覆盖率

构建多目标产物(Node CJS、ESM、浏览器 global、AMD)的命令为 npm run build(底层调用 tasks/buildAll.js),3.7.1/3.7.2 的打包修复正是针对其中的 ESM 产物 build/es6/luxon.mjs。

升级建议速查

  • 从 1.x 升 2.x:先通读 docs/upgrading.md,重点核对 zone 与格式化语义。
  • 从 2.x 升 3.x:注意 "system" zone 语义收紧(3.0.0)与 twoDigitCutoffYear(3.1.1)等新配置的默认行为。
  • 使用 fromRFC2822:务必升级到 3.2.1+ 以规避正则漏洞。
  • 需要更精细的输出控制:3.7.0 的 precision、rounding、signMode、showZeros/removeZeros 组合可以满足绝大多数格式化需求,且均有完整测试覆盖,可放心迁移。
登录后查看全文
luxon