在 JavaScript 中处理时区而不抓狂

将每个时间戳以 UTC 瞬时值的形式存储和传输，格式遵循 ISO 8601（例如 2026-05-22T08:00:00Z），将 IANA 时区标识符（例如 America/New_York）单独存放在一个字段中，并仅在显示时才将其转换为本地时间——永远不要存储没有时区信息的挂钟时间。这条单一规则能够预防绝大多数 JavaScript 时区 Bug，无论你使用 Date、Intl、第三方库还是新的 Temporal API，它都同样适用。

本指南涵盖以下内容：为什么内置的 Date 对象让时区处理如此痛苦；无论使用何种工具都能解决问题的持久性规则；如何使用 Intl.DateTimeFormat 正确格式化日期；随着 Temporal 在 ES2026 中正式落地，它带来了哪些变化；截至 2026 年 6 月，生产环境中应选用哪个库；以及那些最难复现的夏令时边界 Bug。

为什么 JavaScript 的 Date 让人抓狂

Date 对象存在三个结构性缺陷，其中第三个是时区问题的致命所在。第一，它是可变的：setMonth、setFullYear 等方法会就地修改原始对象，因此将 Date 传入函数可能会悄无声息地影响所有其他调用方。第二，其编号规则不一致——月份从零开始（一月是 0，十二月是 11），而日期从一开始——这会产生月份差一的 Bug，且往往能通过代码审查。

第三，也是影响最深远的一点：Date 没有真正的时区支持。它只能表示 UTC 时刻或宿主机器本地时区的时刻，仅此而已——没有任何方式能够按你预期的那样构造或操作”处于 America/New_York 时区的 Date”。TC39 提案文本对此直言不讳：历史悠久的 ECMAScript Date 对象存在诸多挑战，包括缺乏不可变性、缺乏时区支持、缺乏对仅需日期或仅需时间场景的支持，以及令人困惑、不符合人体工程学的 API。

宿主时区渲染正是同一段代码在柏林开发者机器上显示正确日期、而在洛杉矶用户端显示错误日期的原因。以下是一个可用 Node 运行的 8 行复现示例：

// repro.js — 运行方式: TZ=America/Los_Angeles node repro.js
//          再次运行: TZ=Europe/Berlin node repro.js
const instant = new Date("2026-03-15T23:30:00Z"); // 一个固定的 UTC 时刻
console.log(instant.toLocaleDateString());
// TZ=America/Los_Angeles → "3/15/2026"  (本地时间 16:30，仍是 15 日)
// TZ=Europe/Berlin       → "3/16/2026"  (本地时间 00:30，已是 16 日)

同一个时刻，仅因宿主时区不同，就得到了两个不同的日历日期。由于编写代码的人的机器处于某个固定时区，这个 Bug 对他们来说完全不可见。这种宿主时区日期 Bug 正是”在我机器上能跑”这类经典缺陷的典型代表。

修复时区问题的持久性规则（与任何库无关）

无论使用哪种 API 或库，以下规则都能防止时区 Bug。它们才是真正的解决方案；后续介绍的工具只是应用这些规则的不同方式。

1. 以 UTC 格式存储和传输时间瞬时值。 将时间戳持久化为带有 Z 后缀的 ISO 8601 格式（2026-05-22T08:00:00Z）或 epoch 值。UTC 是无歧义的，永远不会偏移。
2. 将 IANA 时区标识符单独存放在一个字段中。 像 Europe/London 这样的时区标识符携带了仅凭偏移量无法表达的夏令时规则。存储标识符，而非 +01:00 这样的原始偏移量。
3. 仅在边界处——即显示时——转换为本地时间。 在存储、传输和业务逻辑层面始终保持 UTC，只在视图层进行本地化处理。
4. 区分绝对时间瞬时值与某时区的挂钟时间。 日志条目或”创建时间”是一个时间瞬时值；某人日历上的会议是绑定到特定时区的挂钟时间。它们是不同的数据类型，必须以不同的方式建模。
5. 将未来事件存储为带时区的时间，而非固定的 UTC 瞬时值。 这是几乎没有人明确指出的规则。如果用户在 America/New_York 时区安排了两年后上午 9:00 的会议，而该地区后来修改了夏令时规则，那么今天冻结的 UTC 时间戳将解析出错误的挂钟时间。存储时区标识符后，可以在事件到来时重新计算时刻。

最后这条规则有权威来源支撑。Temporal 所采用的标准序列化格式 RFC 9557（互联网扩展日期/时间格式，于 2024 年 4 月发布）的存在，正是因为——正如 Igalia 所指出的——Temporal 需要一种标准方式来序列化带有时区和日历信息的时间戳，但广泛使用的惯例（例如在时间戳后附加 IANA 时区名称）从未经过正式标准化。MDN 给出了关于偏移量与命名时区的操作性规则：如果有可用的命名时区，应避免使用偏移量标识符。即使某个地区始终使用单一偏移量，使用命名标识符也更为稳妥，以防该地区未来对偏移量进行政治性调整。

使用 Intl.DateTimeFormat 实现本地化显示

如需立即实现正确的本地化显示，请使用带有显式 timeZone 选项的 Intl.DateTimeFormat。它是唯一能正确处理命名时区的内置方法，在所有现代浏览器和 Node 中均可使用，并与 Date 和 Temporal 无缝配合。

const instant = new Date("2026-03-15T23:30:00Z");

new Intl.DateTimeFormat("en-US", {
  timeZone: "America/New_York",
  dateStyle: "full",
  timeStyle: "short",
}).format(instant);
// "Sunday, March 15, 2026 at 7:30 PM"

显式传入 timeZone 正是使这段代码安全的关键：你不再受宿主时区的摆布。为不同用户渲染同一时刻，只需修改一个字符串。这正是”在边界处转换”规则的代码体现——在整个流程中保持 UTC 瞬时值，让 Intl 在视图层完成本地化。

Temporal：内置于语言中的时区修复方案

Temporal 是期待已久的 Date 替代方案，到 2026 年它已成为现实。经过 9 年的开发，在 2026 年 3 月的 TC39 会议上，Temporal 正式达到 Stage 4，成为 ECMAScript 2026 的一部分。提案仓库直接确认了这一状态：该提案目前处于 Stage 4，将被合并到 ECMA-262 和 ECMA-402 标准中，本仓库也将随之归档。

Temporal 用一组不可变的、用途专一的类型命名空间取代了 Date。你最常用到的三种类型：

• Temporal.Instant — 精确的时间点（纳秒级时间戳），不含日历或时区信息。用于规则 1 中的 UTC 时间瞬时值。
• Temporal.ZonedDateTime — 时间瞬时值加 IANA 时区加日历。MDN 将其描述为精确时间与挂钟时间之间的桥梁：它同时表示历史上的某个精确时刻和本地挂钟时间。它是唯一感知时区的 Temporal 类型。用于带时区的未来事件（规则 5）。
• Temporal.PlainDate / Temporal.PlainTime — 不含任何时区信息的日历日期或时钟时间，适用于生日、商店营业时间等场景。

算术运算是不可变的——每次操作都返回一个新值——时区之间的转换是显式的：

const callAmsterdam = Temporal.ZonedDateTime.from(
  "2026-04-24T15:00:00[Europe/Amsterdam]"
);
const callNewYork = callAmsterdam.withTimeZone("America/New_York");
callNewYork.toString();
// "2026-04-24T09:00:00-04:00[America/New_York]"

Temporal 还修复了 Date 的一个危险陷阱：对 Temporal 对象使用比较运算符会按设计抛出 TypeError，因为在没有 valueOf() 的情况下，使用算术运算符的表达式（如 plainDate1 > plainDate2）会退化为等同于 plainDate1.toString() > plainDate2.toString() 的字符串比较。应改用 Temporal.compare() 或 .equals()——Temporal.compare() 根据底层时间瞬时值对两个带时区的值进行排序，因此会将纽约上午 9:30 和伦敦下午 2:30 视为相等；而 .equals() 会将它们报告为不同，因为它还会比较时区和日历。完整类型列表请参阅 MDN Temporal 参考文档。

Temporal 的浏览器和运行时支持情况（截至 2026 年 6 月）

Temporal 正在落地，但尚未全面普及。原生支持已在 Firefox 139 中实现——Firefox 139 于 2025 年 5 月成为首个默认支持 Temporal 的浏览器，随后 Chrome 144 于 2026 年 1 月跟进。Edge 基于相同的 Chromium 引擎，Node.js 也已支持：Node.js 26 于 2026 年 5 月 5 日发布，搭载 V8 14.6 和 Undici 8，无需任何标志或实验性设置即可使用 Temporal。这是 JavaScript 历史上首次将一流的日期/时间 API 直接内置于运行时。

缺口在于 Safari，它尚未支持 Temporal——这正是 MDN 将 Temporal 标记为”尚未达到 Baseline”的原因。对于需要跨浏览器兼容的生产代码，你仍然需要 polyfill。目前有两个选择：@js-temporal/polyfill（由提案维护者维护）和 temporal-polyfill（由 FullCalendar 团队开发的更小、更快的替代方案，为其余浏览器提供跨浏览器兼容性）。它们在提案仓库中的官方状态为 alpha/beta，而非稳定的 1.0 版本，因此在上线前请锁定版本并充分测试。在将其纳入预算前，请在 Bundlephobia 上核实 gzip 压缩后的包体积；已发布的数据差异较大。

当前生产环境应选用哪个库

如果你无法在所有目标环境中依赖原生 Temporal——而大多数生产应用在 Safari 支持并移除 polyfill 之前都无法做到——请选用以下工具之一。截至 2026 年 6 月的推荐方案：

date-fns 一列中最重要的准确性陷阱如下：时区支持在主版本之间发生了变化——从 v4 开始，date-fns 对时区提供一流支持，通过 @date-fns/tz 和 @date-fns/utc 包提供。v4 的方案是来自 @date-fns/tz（v1.5.0）的 TZDate 类和 tz() 辅助函数。旧版 date-fns-tz 包（v3.2.0）针对 date-fns v3，其官方文档明确说明——如果你需要 date-fns v4 之前版本的时区支持，请使用该包。切勿混用。

真正会踩坑的夏令时边界案例

夏令时会产生两种故障模式，而大多数代码库对这两种情况的测试都严重不足。秋季”拨回”时，某个本地小时会出现两次，因此 01:05 这样的挂钟时间是有歧义的。春季”拨前”时，某个本地小时根本不存在，因此 02:05 这样的时间是无效的。

Temporal 对这两种情况都有确定性的处理方式。它使用 disambiguation: "compatible" 行为进行解析：对于时间跳过的转换，使用两个可能时刻中较晚的那个；对于时间重复的转换，使用两个可能时刻中较早的那个。输出结果如下：

// 拨回：2024-11-03 纽约时间 01:05 出现两次
Temporal.ZonedDateTime.from("2024-11-03T01:05:00[America/New_York]").toString();
// "2024-11-03T01:05:00-04:00[America/New_York]"  (默认：较早的时刻)
Temporal.ZonedDateTime.from("2024-11-03T01:05:00[America/New_York]",
  { disambiguation: "later" }).toString();
// "2024-11-03T01:05:00-05:00[America/New_York]"  (第二次出现)

// 拨前：2024-03-10 纽约时间 02:05 不存在
Temporal.ZonedDateTime.from("2024-03-10T02:05:00[America/New_York]").toString();
// "2024-03-10T03:05:00-04:00[America/New_York]"  (默认：向前跳过一小时)

对于跳过的小时，你也可以传入 disambiguation: "reject" 来抛出异常，而不是静默解析——当预订落在不存在的时间上时，这种方式更为合适，因为你宁愿提示用户，也不愿猜测。而使用 Date 时，这一切都不会自动处理，Bug 只会在观察夏令时的时区用户身上出现，且仅在一年中发生时区切换的那两天才会触发。

时区缺陷之所以难以修复，正是因为它们在开发者自己的时区中无法复现。倒计时显示为负数、事件卡片显示错误日期、预订落在夏令时边界的错误一侧——但这些只发生在用户端，而非编写代码的机器上。会话回放（Session replay）往往是弥合这一差距的唯一可行手段：在用户环境中捕获的会话回放，能让身处 Europe/Berlin 的开发者亲眼看到 America/Los_Angeles 用户所看到的那个错误日期，而无需凭空想象。

下一步

解决时区 Bug 的良方不是某个库——而是以 UTC 存储时间瞬时值、随附 IANA 时区标识符、仅在显示时转换、以及将未来事件建模为带时区时间这些开发纪律。先应用这些规则，再选择工具：在支持的环境中使用原生 Temporal，在不支持的环境中使用 polyfill，其余情况使用 Luxon 或 date-fns v4 配合 @date-fns/tz。从审查代码库中某个存储了不带时区的挂钟时间的地方开始——那个字段几乎可以肯定就是你下一个”差一天”Bug 的藏身之处。

常见问题

为什么我的日期对某些用户显示错了一天，但对我自己却是正确的？

JavaScript 的 Date 只存储 UTC 瞬时值，而 toLocaleDateString 等方法会在宿主机器的时区中渲染它。同一个固定时刻，例如 2026-03-15T23:30:00Z，在 America/Los_Angeles 下渲染为 3 月 15 日（本地时间 16:30），但在 Europe/Berlin 下渲染为 3 月 16 日（本地时间 00:30）。代码本身是正确的；日历日期之所以不同，是因为渲染时区不同。这正是该 Bug 在开发者自己的时区中永远无法复现的原因。

我应该将未来的会议时间存储为 UTC 时间戳吗？

不应该。应将未来事件存储为绑定到 IANA 时区的挂钟时间，例如 2026-05-22T09:00:00 并附带 America/New_York，而不是存储为固定的 UTC 瞬时值。如果该地区在事件日期之前修改了夏令时规则，今天计算出的 UTC 时间戳将解析出错误的挂钟时间，而带时区的值则可以重新计算。UTC 瞬时值适用于日志和过去的事件，而非未来的预约。

date-fns-tz 和 @date-fns/tz 有什么区别？

它们针对不同的主版本，不可互换。旧版 date-fns-tz 包（v3.2.0）仅为 date-fns v3 提供时区支持。从 date-fns v4 开始，时区处理迁移到了独立的 @date-fns/tz 包（v1.5.0），该包提供 TZDate 类和 tz 辅助函数。如果你使用的是 date-fns 4.x，请使用 @date-fns/tz；将两者混用于错误的主版本是导致转换错误的常见原因。

2026 年能在生产环境中使用 Temporal API 吗？

可以部分使用。截至 2026 年 6 月，Temporal 已作为 Stage 4 提案纳入 ECMAScript 2026，并在 Firefox 139+、Chromium 144+（Chrome 和 Edge）以及 Node.js 26+ 中原生支持。Safari 尚未支持，这也是 MDN 将 Temporal 标记为“尚未达到 Baseline”的原因。在受控的常青浏览器或服务器环境中可以直接原生使用；对于需要广泛浏览器兼容的场景，仍需使用 @js-temporal/polyfill 或 temporal-polyfill，两者均处于 alpha 或 beta 状态，因此请锁定版本并先进行充分测试。