深入 Temporal API：为什么 Date 对象注定被淘汰，新日期 API 如何设计

凌晨两点，日期边界出事

很多团队会遇到一个非常典型的故障：上线不到半年，某个跨时区业务在每天 UTC 零点左右开始出现零星报错。查到最后，发现是代码里写了一句类似 const today = new Date().toISOString().slice(0,10) 的逻辑。这个方法试图取“今天”的日期，但在 UTC 时间已经是新的一天、而本地时间仍是昨天的时候，它拿到了一个意料之外的值。

类似的代码在 JavaScript 项目中随处可见。它们不是没有测试，而是测试环境只在本地时区运行，很难暴露隐藏的时区问题。要彻底理解这个问题，我们需要重新审视 Date 对象的设计，以及一个正在改变这一切的提案——Temporal API。

Date 的困境：一个对象，两种时间

Date 对象从 1995 年诞生至今几乎没有大变过。它模仿了 Java 早期的 java.util.Date，又把大量职责塞进了同一个接口。表面上看，你可以在任意时刻创建它，读取年月日，做简单运算。但真正使用起来，处处是坑。

第一个坑是可变性。setHours、setDate 这类方法会直接修改对象本身。当同一个 Date 实例被传递到多个函数中，任何一处调用 setter 都会影响所有持有该引用的地方。这种副作用在项目规模变大后几乎无法追踪。

第二个坑是月份下标从 0 开始。new Date(2024, 0, 1) 是一月一日，new Date(2024, 11, 31) 是十二月三十一日。没有人觉得这合理，但每个人都在被迫习惯。

第三个坑，也是影响最深远的一个：Date 对象在内部存储绝对时刻，对外提供的读写方法却隐式绑定系统本地时区。这意味着同一个 Date 对象，在不同时区运行会得到不同的字符串输出，但它的内部毫秒数是相同的。这种“双面性”正是大量时区 bug 的根源。

// Date 的隐式时区陷阱：同一时刻，不同解析结果
const date = new Date("2024-06-01T00:00:00Z");
console.log(date.getDate()); // 在中国时区是 6 月 1 日
console.log(date.toISOString()); // 2024-06-01T00:00:00.000Z

// 但在旧金山时区，getDate() 可能返回 5 月 31 日

更糟的是字符串解析规则。不同浏览器对 new Date("2024-01-01") 与 new Date("2024/01/01") 的处理方式存在差异。前者通常被当作 UTC 时间，后者被当作本地时间，几乎没有一致的规范可循。

这些设计缺陷让日期处理成为 JavaScript 生态中依赖第三方库最重的领域之一。moment.js、dayjs、date-fns 各有拥趸，但核心问题一直存在：语言本身没有给出一个好的抽象。

Temporal 的设计：先类型分离，再精确计算

Temporal API 正是为了替代 Date 而生的 TC39 提案。它没有选择在 Date 上打补丁，而是从零设计了一套时间模型。阅读规范时会发现，整个设计的精髓在于一个词：分类。

时间有多个维度。一个绝对时刻，可以表示成 UTC 时间戳；也可以表示成“某个时区里的时间”；还可以表示成完全没有时区概念的日期。在旧体系中，这些概念共用 Date 一个类型；在新体系中，它们是不同的类型，分别命名。

下面这张表总结了 Temporal 的核心类型：

这种拆分初看会增加学习成本，但它让“时间”回到了它本来的样子。比如你有一个“每日早上 8 点执行”的定时任务，这个 8 点是墙上时间，它不应该因为服务器时区变化而跟着变。在旧写法里，你要小心处理操作系统时区；在 Temporal 里，你可以直接用 PlainTime.from("08:00") 来表达。

反过来，如果你想记录一个基础设施事件的发生时刻，你应该用 Instant，它不携带任何时区信息，只代表一个绝对点。数据库里的 timestamptz 字段和它是同一个思路。

用 Temporal 重写常见日期操作

我们来看一个最常见的跨时区场景：把一场纽约会议转换成东京时间。

// 传统 Date + Intl 方式，繁琐且容易错
const date = new Date("2024-06-01T09:00:00Z");
const formatter = new Intl.DateTimeFormat("en-US", {
  timeZone: "Asia/Tokyo",
  year: "numeric", month: "2-digit", day: "2-digit",
  hour: "2-digit", minute: "2-digit"
});
console.log(formatter.format(date));

// Temporal 方式
const meeting = Temporal.ZonedDateTime.from(
  "2024-06-01T09:00:00[America/New_York]"
);
const tokyoTime = meeting.withTimeZone("Asia/Tokyo");
console.log(tokyoTime.toString());

两种方式都能得到结果，但 Temporal 的语义亲近得多。withTimeZone 返回一个全新的 ZonedDateTime，原对象不受影响。字符串输出包含时区标识，方便调试和排错。

再来看计算时间差。Temporal 提供了 until 和 since 方法，可以直接得到 Duration 对象：

const start = Temporal.PlainDate.from("2024-06-01");
const end = Temporal.PlainDate.from("2024-07-10");
const diff = start.until(end);
console.log(diff.days); // 39

需要注意的是，until 的返回结果是 Duration，而不是一个数字。Duration 可以精确表示年、月、日、时、分、秒的混合长度，这在处理“一个月后”这种自然语言时特别方便。比如 Temporal.PlainDate.from("2024-01-31").add({ months: 1 }) 会得到 2 月 29 日（2024 年是闰年），而不是像 Date 那样自动跳到 3 月 2 日。

Temporal 如何纠正 Date 的顽疾

除了类型拆分，Temporal 在细节上做了大量纠偏。

不可变性是最直观的改变。所有 Temporal 对象的方法都不会修改原始对象，而是返回一个新实例。习惯函数式编程的开发者会感到很舒服，而在复杂业务逻辑中，这也能有效避免引用共享带来的副作用。

月份从 1 开始是另一个足以让人感动的调整。Temporal.PlainDate.from({ year: 2024, month: 1, day: 1 }) 就是元旦，不会再出现 getMonth() + 1 的补丁代码。

字符串解析也有了明确规范。Temporal 的 from 方法遵循 ISO 8601 / RFC 3339，并且根据目标类型来决定时区的处理方式。Instant.from("2024-06-01T00:00:00Z") 接受带 Z 的 UTC 字符串；PlainDate.from("2024-06-01") 只取日期部分，不会产生时区歧义。此外，Temporal 支持纳秒精度，对于日志分析和金融系统来说，这是一个真正的升级。

日历与时区：最容易被低估的复杂度

很多人以为时区问题只是加减几个小时的偏移量，实际上远没有那么简单。Temporal 把日历系统也作为一等公民。默认使用 ISO 8601 公历，同时可以通过 calendar 选项切换其他日历系统，比如伊斯兰历或希伯来历。这意味着你可以用同一套 API 处理不同地区的业务日历，不需要自己去实现换算。

更常见的复杂度来自夏令时。一个“每天上午 9 点”的定时任务，在夏令时切换的凌晨可能变成 10 点或 8 点。如果你用的是 Date，这种变化是隐式的，很难被观察到；而 Temporal 的 ZonedDateTime 把时区规则明确暴露出来，你可以通过 timeZone.getOffsetNanosecondsFor(instant) 来检查具体偏移，或者依赖 Temporal 在 add 时按日历时间处理来规避歧义。

这里还有一个工程上的坑：时区数据库是动态的。政府可能随时修改时区规则，这导致同样的代码在不同版本的 ICU 数据下可能产生不同结果。Temporal 本身不会解决这个问题，它只是让时区数据的使用变得更透明。生产环境里，最好保留原始时间戳，以便在时区规则变化后能够重新计算正确的时间。

迁移到 Temporal 的常见误区

作为新引入的 API，Temporal 在落地时有一些很容易走偏的方向。我总结了几个典型的误区：

• 误区一：把 Temporal 当作 Date 的简单替代品。两者类型体系完全不同，业务代码里现有 Date 操作不能直接替换，需要重新设计数据模型。
• 误区二：所有地方都用 ZonedDateTime。一个“每年 3 月 15 日”的规则属于 PlainDate；一个“下午 2 点 30 分”属于 PlainTime。过度使用 ZonedDateTime 反而会引入不必要的时区上下文，增加心智负担。
• 误区三：忽略不可变性的迁移成本。Date 的可变性虽然烦人，但确实也方便了类似 d.setDate(d.getDate()+1) 的写法。迁移时如果不改变代码组织方式，可能会因为频繁创建新对象带来性能上的不适应。

这些误区提醒我们：引入新技术不只是换 API，更是换一种思考方式。

什么样的项目适合现在迁移

Temporal 还在 Stage 3，并不是所有人都应该立刻投入重构。如果你的项目只是简单展示本地时间，或者已经用一个维护良好的库（比如 date-fns）覆盖了需求，那完全可以继续观望。

但下面这些情况，是开始使用 Temporal 的合适信号：

1. 系统服务多个时区的用户，且经常出现时区计算错误。
2. 需要处理纳秒级时间精度，比如网络延迟分析和日志排序。
3. 代码库里出现了大量字符串拼接、手动加减时区、临时 hack 来处理日期。
4. 已有第三方日期库因为体积或维护问题让你感到痛苦。

特别是最后一条。很多团队为了处理时区引入了 moment.js，结果整个包里最重的依赖就是它，还无法按需加载。Temporal 作为内建 API，一旦普及，很多第三方库就没有存在的必要了。但从现在到全面普及还有一段距离，所以迁移时需要务实。

落地建议：从边界开始，逐步替换

官方提供了 @js-temporal/polyfill，在 Node.js 和浏览器里都可以使用。你可以在项目根目录引入它，先把新写的时间逻辑建立在 Temporal 之上，再逐步改造旧代码。

一个比较顺的路径是：先替换“绝对时间戳”和“时区转换”这两个最容易出错的模块，因为它们对应的类型（Instant 和 ZonedDateTime）语义最清晰，带来的收益也最直接。等到这两块稳定后，再处理日历计算、Duration 等相对复杂的部分。

迁移过程中，有几点值得留意：

• 不要试图一次性替换所有 Date 代码。保持新旧逻辑隔离，方便回滚。
• 在关键边界写测试，尤其是夏令时切换、闰年、跨月运算。
• 统一团队约定的时间类型。比如 API 入参一律用 ISO 字符串，内部用 Temporal 类型，存储用 timestamp 或 ISO。

最后一个建议来自我的工程体验：任何日期时间库都不能真正替代对时间模型的理解。Temporal 给了我们一套更准确的表达工具，但它同样要求我们想清楚业务里哪些时间是墙钟时间（wall clock），哪些是绝对时刻。这层思考是不可省的。

结语

Date 对象不容易被立刻移除，但它的统治地位正在走向终结。Temporal API 不只是一个新 API，它是对 JavaScript 日期模型的一次重构。通过类型分离、不可变性、明确语义和完整日历支持，它把过去二十年里散落在各种库和业务代码里的约定，真正变成了语言的一部分。

对于开发者来说，现在正是理解 Temporal 的好时候。不用急着全面迁移，但值得把核心思路和类型体系摸透。等它在运行时环境里普及的那一天，我们手里的知识会立刻变成生产力和工程判断力。