Luxon 3.x 版本演进全解析:从 CHANGELOG 到源码的日期时间库升级指南
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/uuutoken(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 # 仅运行测试,不采集覆盖率
- Duration 格式化相关:
showZeros/removeZeros/signMode的用例集中在 test/duration/format.test.js 与 test/duration/units.test.js。 - DateTime ISO 精度:见 test/datetime/format.test.js,覆盖
toISO/toISODate/toISOTime的precision截断与非法值抛错。 - 相对时间舍入:见 test/datetime/relative.test.js。
构建多目标产物(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组合可以满足绝大多数格式化需求,且均有完整测试覆盖,可放心迁移。