core-js 中的 ECMAScript Date 兼容层：模块划分、修复原理与入口使用指南

导读

本文以 core-js 仓库中的 ECMAScript: Date 文档 为主体，系统梳理 core-js 对 ECMAScript 标准 Date 相关方法的实现与兼容修复。你将了解到：core-js 把 Date 相关能力拆分为哪些独立模块、每个模块修复了哪些引擎缺陷、各方法的 TypeScript 签名与行为约定，以及如何通过 core-js/es|stable|actual|full/date 等入口按需引入。配合仓库源码（modules 与 internals 目录）中的实现证据，本文会从"怎么用"深入到"为什么这样修"。

---

一、文档定位：core-js 的 Date 兼容模块全景

Date 是 ECMAScript 内建对象中历史包袱较重的一个：早期引擎（如 IE8-、PhantomJS、老版本 WebKit）在 toISOString、toString、toJSON 等方法的实现上存在明显的规范偏差，而 Annex B 遗留方法（getYear、setYear、toGMTString）在不同引擎间的行为也不一致。

core-js 将 Date 相关的兼容工作划分为两类：

• ES5 特性及修复：es.date.to-string、es.date.now、es.date.to-iso-string、es.date.to-json、es.date.to-primitive；
• Annex B 遗留方法：es.date.get-year、es.date.set-year、es.date.to-gmt-string。

这种按模块粒度拆分的设计，使开发者可以只引入自己需要的修复，避免一次性引入整个 Date polyfill。

---

二、ES5 Date 核心方法：签名、修复点与源码实现

1. Date.now()：静态方法（es.date.now）

文档给出的签名如下：

static now(): number;

在 modules/es.date.now.js 中，实现极简——它通过内部工具 function-uncurry-this 反柯里化 Date.prototype.getTime，然后作用于一个新构造的 Date 实例：

var thisTimeValue = uncurryThis($Date.prototype.getTime);

$({ target: 'Date', stat: true }, {
  now: function now() {
    return thisTimeValue(new $Date());
  }
});

源码注释明确标注 // TODO: Remove from core-js@4，说明在 core-js 4 中这类在现代引擎中已无兼容负担的模块将被移除。

2. Date.prototype.toISOString()（es.date.to-iso-string）

toISOString(): string;

这是 core-js 修复力度最大的 Date 方法之一。入口模块 modules/es.date.to-iso-string.js 直接复用内部实现 internals/date-to-iso-string.js，并通过对比 Date.prototype.toISOString !== toISOString 决定是否强制替换，注释明确指出 PhantomJS / 老版本 WebKit 的实现存在缺陷。

内部实现揭示了两个关键修复点：

1. 年份位数补齐：对于超出 4 位的年份（负数或大于 9999），规范要求带符号且补足 6 位；core-js 用 padStart 实现：

var sign = year < 0 ? '-' : year > 9999 ? '+' : '';
return sign + padStart(abs(year), sign ? 6 : 4, 0) + ...

2. 非法日期抛 RangeError：当时间值为 NaN 时必须抛出 RangeError('Invalid time value')，而不是返回异常字符串：

if (!$isFinite(thisTimeValue(this))) throw new $RangeError('Invalid time value');

完整输出格式为 YYYY-MM-DDTHH:mm:ss.sssZ（UTC 时间），源码逐字段拼接并统一 padStart 到固定位数。

3. Date.prototype.toJSON()（es.date.to-json）

toJSON(): string;

modules/es.date.to-json.js 通过 fails 工具做运行时能力探测来决定是否启用 polyfill：

var FORCED = fails(function () {
  return new Date(NaN).toJSON() !== null
    || Date.prototype.toJSON.call({ toISOString: function () { return 1; } }) !== 1;
});

实现遵循规范的两步流程：先把 this 转为对象，再以 'number' hint 做 toPrimitive 转换；若结果是数字且非有限（NaN/±Infinity），返回 null，否则委托给 O.toISOString()：

var pv = toPrimitive(O, 'number');
return typeof pv == 'number' && !isFinite(pv) ? null : O.toISOString();

这正是 JSON.stringify(new Date(NaN)) 应序列化为 "null" 的原因所在。

4. Date.prototype.toString()（es.date.to-string）

toString(): string;

modules/es.date.to-string.js 修复的是"非法日期格式化"问题。规范要求 new Date(NaN).toString() 返回 'Invalid Date'，但部分老引擎输出其他字符串。core-js 通过探测决定是否注入修复：

if (String(new Date(NaN)) !== INVALID_DATE) {
  defineBuiltIn(DatePrototype, TO_STRING, function toString() {
    var value = thisTimeValue(this);
    return value === value ? nativeDateToString(this) : INVALID_DATE;
  });
}

这里用 value === value 自比较判断 NaN，合法日期仍走原生 toString，非法日期统一返回 'Invalid Date'。文档示例也验证了这一点：

new Date(NaN).toString(); // => 'Invalid Date'

5. Date.prototype[@@toPrimitive]（es.date.to-primitive）

@@toPrimitive(hint: 'default' | 'number' | 'string'): string | number;

modules/es.date.to-primitive.js 仅在原生对象缺少该符号方法时（!hasOwn(DatePrototype, TO_PRIMITIVE)）注入内部实现 internals/date-to-primitive.js：

module.exports = function (hint) {
  anObject(this);
  if (hint === 'string' || hint === 'default') hint = 'string';
  else if (hint !== 'number') throw new $TypeError('Incorrect hint');
  return ordinaryToPrimitive(this, hint);
};

要点：

• hint 为 'string' 或 'default' 时统一走字符串优先的 ordinaryToPrimitive；
• hint 为 'number' 时走数字优先；
• 传入其他 hint 值（如 'boolean'）直接抛出 TypeError('Incorrect hint')。

该方法是 +date、`${date}` 等隐式转换行为统一性的基础。

---

三、Annex B 遗留方法：getYear / setYear / toGMTString

这三个方法源自 Annex B（浏览器兼容性附加特性），不属于严格意义的 ES 核心，core-js 将其单独拆分为独立模块，便于按需加载。

1. Date.prototype.getYear()（es.date.get-year）

getYear(): int;

modules/es.date.get-year.js 的语义是返回"年 - 1900"。core-js 通过 fails 探测 IE8- 的非标准行为并强制替换：

var FORCED = fails(function () {
  return new Date(16e11).getYear() !== 120;
});

var getFullYear = uncurryThis(Date.prototype.getFullYear);

getYear: function getYear() {
  return getFullYear(this) - 1900;
}

实现直接委托给 getFullYear 再减去 1900，规避了老引擎对 2000 年前后年份的错误处理。

2. Date.prototype.setYear()（es.date.set-year）

setYear(year: int): number;

modules/es.date.set-year.js 是这些模块中逻辑最复杂的一个，它精确复刻规范中"0–99 视为 1900–1999"的怪癖：

var y = +year;
// NaN 校验
if (y !== y) return setFullYear(this, y);
var yi = toIntegerOrInfinity(y);
var yyyy = yi >= 0 && yi <= 99 ? yi + 1900 : yi;
return setFullYear(this, yyyy);

行为要点：

• 先通过 thisTimeValue(this) 校验 this 是合法日期对象；
• year 会被 +year 强转数字，NaN 直接透传给 setFullYear；
• 0 ≤ year ≤ 99 时自动加 1900（如 setYear(99) 相当于设置 1999 年），其余值原样传递；
• 返回值为更新后的时间戳（毫秒数），与 setFullYear 一致。

3. Date.prototype.toGMTString()（es.date.to-gmt-string）

toGMTString(): string;

modules/es.date.to-gmt-string.js 的实现堪称"一行兼容"——直接将 toGMTString 别名为标准化的 toUTCString：

$({ target: 'Date', proto: true }, {
  toGMTString: Date.prototype.toUTCString
});

这既保留了历史 API 名称的可用性，又确保了输出与现代规范一致。

---

四、Entry Points：按需引入的完整入口清单

文档给出了 Date 系列模块的完整入口矩阵（core-js(-pure) 表示 core-js 与 core-js-pure 两个发行包均可使用）：

core-js/es|stable|actual|full/date
core-js/es|stable|actual|full/date/to-string
core-js(-pure)/es|stable|actual|full/date/now
core-js(-pure)/es|stable|actual|full/date/get-year
core-js(-pure)/es|stable|actual|full/date/set-year
core-js(-pure)/es|stable|actual|full/date/to-gmt-string
core-js(-pure)/es|stable|actual|full/date/to-iso-string
core-js(-pure)/es|stable|actual|full/date/to-json
core-js(-pure)/es|stable|actual|full/date/to-primitive

入口语义说明：

• es：仅标准 ES 特性（不含 proposals 与 web 标准模块）；
• stable / actual / full：三档渐进式集合，stable 仅稳定特性，actual 增加已进入最近 stage 的特性，full 包含全部可用模块；
• core-js-pure：不污染全局对象的纯净版，适合库作者使用（对应 packages/core-js-pure）；
• 目录级入口：core-js/date（注意 to-string 与 now 没有单独的 core-js-pure 变体，按需引入时以 es/date 目录入口为主即可）。

实际使用示例（Node 环境）：

// 引入全部 Date 相关修复
import 'core-js/stable/date';

// 只修复 toISOString
import 'core-js/es/date/to-iso-string';

入口文件与上述模块的映射关系，可在仓库中逐一验证，例如 packages/core-js/es/date 目录下对应 to-string.js、now.js 等文件即按模块粒度转发。

---

五、测试佐证与实现依据

• toString 的 'Invalid Date' 行为：文档示例 new Date(NaN).toString() // => 'Invalid Date' 正是 modules/es.date.to-string.js 中探测与修复逻辑的直接体现；
• toISOString 的大年份补齐：internals/date-to-iso-string.js 用 fails 探测 new Date(-5e13 - 1).toISOString() 是否为 '0385-07-25T07:06:39.999Z'，确认负年份的符号与位数处理；
• toJSON 的 null 返回：modules/es.date.to-json.js 对非有限时间值返回 null，与 JSON.stringify 的序列化语义严格对应。

仓库的单元测试集中在 tests/unit-global 目录，相关文件（如 es.date.to-iso-string.js、es.date.to-json.js）覆盖了非法日期、年份边界、hint 转换等场景，可作为行为验证与回归测试的参考。

---

结语

core-js 对 Date 的兼容处理体现了一贯的设计哲学：模块粒度拆分 + 运行时能力探测（fails）+ 最小化修补。面对 ES5 修复（toString / now / toISOString / toJSON / @@toPrimitive）与 Annex B 遗留（getYear / setYear / toGMTString）两组能力，开发者既可以通过 core-js/es|stable|actual|full/date 目录入口整体引入，也可以按单个方法精确引入，在兼容性与包体积之间自由取舍。