Intl.DateTimeFormat按用户时区显示业务时间的实现

按用户时区显示业务时间，关键不是手动加减小时，而是把“时间点”和“展示规则”分开：后端返回带 Z 或明确偏移的时间点，前端创建 Intl.DateTimeFormat 时显式传入用户的 IANA 时区，例如 Asia/Shanghai，再由运行时处理偏移与夏令时。

官方文档：https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat

如果不传 timeZone，格式化器会使用当前运行环境的默认时区。服务端渲染、浏览器和测试环境可能因此显示不同结果。

先分清三个独立对象

业务数据库保存的是一个时间点，用户配置保存的是展示时区，语言设置决定年月日顺序、数字和文字。把三者混成一个字符串，常见后果是重复换算或把没有偏移的本地时间误当成 UTC。

创建可复用的格式化器

同一列表中不要为每一行重复创建格式化器。以 locale、timeZone 和显示选项作为缓存键，复用 Intl.DateTimeFormat 实例。下面保留最小实现，业务量大时可把缓存放到模块层。

const formatterCache = new Map();

function getFormatter(locale, timeZone) {
  const key = `${locale}|${timeZone}`;
  if (!formatterCache.has(key)) {
    // 显式传入时区，避免依赖浏览器或SSR服务器的默认设置
    formatterCache.set(key, new Intl.DateTimeFormat(locale, {
      timeZone,
      dateStyle: "medium",
      timeStyle: "short",
      hour12: false,
    }));
  }
  return formatterCache.get(key);
}

function formatBusinessTime(isoInstant, user) {
  // isoInstant 必须包含 Z 或明确偏移，确保它表示唯一时间点
  const instant = new Date(isoInstant);
  if (Number.isNaN(instant.getTime())) {
    throw new TypeError("无效的业务时间");
  }
  return getFormatter(user.locale, user.timeZone).format(instant);
}

dateStyle、timeStyle 适合常规界面；账单号、日志键或导出字段若要求固定机器格式，应单独定义协议格式，不要把本地化结果再送回后端解析。

检查实际采用的配置

resolvedOptions() 会返回初始化后真正使用的 locale、calendar、numberingSystem、timeZone 和小时制等信息。它适合在诊断面板或测试断言中确认环境行为。需要把日期的某一部分放进不同 DOM 节点时，使用 formatToParts()，不要通过正则拆格式化后的字符串。

const formatter = getFormatter("zh-CN", "Europe/Berlin");
const options = formatter.resolvedOptions();

// 记录解析后的配置，而不是猜测运行时采用了什么
console.log(options.locale, options.timeZone, options.hourCycle);

const parts = formatter.formatToParts(new Date("2026-09-26T08:30:00Z"));
// formatToParts 保留 literal 分隔符，适合结构化渲染
const hour = parts.find((part) => part.type === "hour")?.value;

处理输入和兼容边界

字符串 2026-09-26 08:30:00 没有时区信息，不应在浏览器中直接解析，因为它无法说明原始时间点。接口应返回 ISO 8601 且包含 Z 或偏移。用户时区来自账户配置时，要允许构造器对无效标识抛出 RangeError，并回退到经过产品定义的默认时区，而不是静默使用设备时区。

• SSR 和客户端都传同一 locale、timeZone 与选项，减少水合文本差异。
• 缓存格式化器时把所有影响输出的选项纳入键，不只缓存时区。
• 展示使用 IANA 时区标识，不保存固定的 UTC+8 代替地区规则。
• 测试覆盖普通日期和夏令时切换附近的时间点，但断言业务含义，不硬编码设备默认时区。

常见问题

如何读取用户设备当前时区？可用 new Intl.DateTimeFormat().resolvedOptions().timeZone，但它只代表运行环境设置，不一定等于账户选择。

Intl.DateTimeFormat 会修改 Date 吗？不会。它读取同一个时间点并生成指定时区和语言下的展示字符串。