JavaScript Intl API 完全指南：原生方案替代 moment.js 和 numeral.js

moment.js 在 2020 年正式进入维护模式，官方推荐迁移到更现代的替代方案。然而到 2026 年，npm 上 moment.js 的周下载量仍然超过 2500 万次——大量项目还在为一个已经停止积极开发的库付出包体积和性能的代价。事实上，JavaScript 内置的 Intl API（Internationalization API）早已覆盖了 moment.js 90% 以上的常见用法，而且零依赖、零体积、性能更好。如果你还在项目中引入 300KB 的 moment.js 来格式化一个日期，这篇文章会彻底改变你的做法。

🔧 一、为什么该抛弃 moment.js 了

1.1 moment.js 的三大硬伤

moment.js 曾经是 JavaScript 日期处理的事实标准，但它有几个无法回避的问题：

体积臃肿。moment.js 压缩后约 72KB（gzipped 约 23KB），加上 locale 文件会更大。如果你只是用它做 moment().format('YYYY-MM-DD')，相当于为了拧一颗螺丝搬来一整套工具箱。

可变对象设计。moment.js 的 Date 对象是可变的，这意味着 moment() 调用会修改原对象，这在并发场景和 React 状态管理中是巨大的隐患：

// ❌ moment.js 的可变性陷阱
const a = moment('2026-01-01');
const b = a.add(30, 'days');
console.log(a.format('YYYY-MM-DD')); // "2026-01-31" — a 也被改了！
console.log(a === b); // true — 同一个对象引用

时区处理依赖外部数据。moment.js 的时区支持需要额外引入 moment-timezone（又一个 10MB+ 的包），而 Intl API 原生支持 IANA 时区名称。

1.2 Intl API 的核心优势

⚡ 关键结论： 如果你的项目不需要兼容 IE11（2026 年了，应该不需要了），Intl API 是最优解。零依赖意味着零供应链风险、零版本冲突、零安全漏洞。

1.3 实际迁移收益

以一个典型的 React 项目为例，从 moment.js 迁移到 Intl API 后：

• 打包体积减少 60-80KB（gzipped），对于移动端首屏加载影响显著
• 渲染性能提升约 30%（Intl API 由浏览器引擎原生实现，比 JS 解析快得多）
• 消除了 moment is not defined 的 SSR 兼容问题

📊 二、核心 API 实战详解

2.1 Intl.DateTimeFormat：日期时间格式化

Intl.DateTimeFormat 是替代 moment.js format() 方法的核心 API。它的构造函数接受两个参数：locale 和 options。

// ✅ 基本日期格式化
const date = new Date('2026-05-31T14:30:00');

// 中文完整日期
const fmt = new Intl.DateTimeFormat('zh-CN', {
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  weekday: 'long',
  hour: '2-digit',
  minute: '2-digit',
  hour12: false
});
console.log(fmt.format(date));
// "2026年5月31日星期六 14:30"

// 英文格式
const enFmt = new Intl.DateTimeFormat('en-US', {
  year: 'numeric',
  month: 'short',
  day: 'numeric'
});
console.log(enFmt.format(date)); // "May 31, 2026"

// ISO 格式（用 formatToParts 获取精确控制）
const parts = new Intl.DateTimeFormat('en-CA', {
  year: 'numeric',
  month: '2-digit',
  day: '2-digit'
}).formatToParts(date);
// en-CA 默认输出 YYYY-MM-DD 格式
const isoDate = `${parts[0].value}-${parts[2].value}-${parts[4].value}`;
console.log(isoDate); // "2026-05-31"

formatToParts() 方法是 Intl API 的杀手级特性——它返回一个包含每个格式化片段的数组，你可以精确控制输出格式，而不需要记忆 moment.js 的 YYYY-MM-DD HH:mm:ss 格式化占位符。

时区处理是另一个亮点。moment.js 需要 400KB+ 的 moment-timezone 数据，而 Intl API 原生支持：

// ✅ 原生时区转换，零额外依赖
const now = new Date();

const shanghai = new Intl.DateTimeFormat('zh-CN', {
  timeZone: 'Asia/Shanghai',
  year: 'numeric',
  month: '2-digit',
  day: '2-digit',
  hour: '2-digit',
  minute: '2-digit',
  second: '2-digit',
  hour12: false
}).format(now);

const tokyo = new Intl.DateTimeFormat('ja-JP', {
  timeZone: 'Asia/Tokyo',
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  hour: '2-digit',
  minute: '2-digit'
}).format(now);

const newYork = new Intl.DateTimeFormat('en-US', {
  timeZone: 'America/New_York',
  dateStyle: 'full',
  timeStyle: 'long'
}).format(now);

console.log(`上海: ${shanghai}`);
console.log(`東京: ${tokyo}`);
console.log(`New York: ${newYork}`);
// 三个时区同时显示，无需任何第三方库

💡 提示： dateStyle 和 timeStyle 是较新的快捷选项，值为 'full'、'long'、'medium'、'short'，可以大幅简化 options 配置。但注意它们不能与具体的 year/month/day 选项混用。

2.2 Intl.NumberFormat：数字、货币与单位格式化

这是替代 numeral.js 和 accounting.js 的原生方案。数字格式化在数据可视化、电商后台、财务系统中使用频率极高。

// ✅ 货币格式化
const price = 1234567.89;

// 人民币
console.log(new Intl.NumberFormat('zh-CN', {
  style: 'currency',
  currency: 'CNY'
}).format(price)); // "¥1,234,567.89"

// 美元（带分组）
console.log(new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'narrowSymbol'
}).format(price)); // "$1,234,567.89"

// 日元（无小数位）
console.log(new Intl.NumberFormat('ja-JP', {
  style: 'currency',
  currency: 'JPY'
}).format(price)); // "￥1,234,568"

// ✅ 百分比格式化
const ratio = 0.8567;
console.log(new Intl.NumberFormat('zh-CN', {
  style: 'percent',
  minimumFractionDigits: 1,
  maximumFractionDigits: 1
}).format(ratio)); // "85.7%"

// ✅ 数字单位（ES2020+）— 替代自定义的 "万/亿" 格式化函数
const followers = 15800;
console.log(new Intl.NumberFormat('zh-CN', {
  notation: 'compact',
  compactDisplay: 'short'
}).format(followers)); // "1.6万"

const population = 1425893465;
console.log(new Intl.NumberFormat('zh-CN', {
  notation: 'compact',
  compactDisplay: 'long'
}).format(population)); // "14亿"

notation: 'compact' 配合中文 locale 的效果非常惊艳——它会自动使用"万"、"亿"等中文计数单位，完全替代了你之前手写的 formatWan() 函数。

Intl.NumberFormat 的 format() 方法性能极好，因为它是浏览器原生实现。在一个简单的性能测试中，格式化 10 万次数字：

📌 记住： Intl.NumberFormat 实例是可复用的。创建一次，反复调用 format() 方法即可。不要在循环中重复 new Intl.NumberFormat()。

2.3 Intl.RelativeTimeFormat：相对时间

“3 分钟前”、"2 天后"这类相对时间显示，之前需要依赖 timeago.js 或 moment.js 的 fromNow() 方法。Intl API 提供了原生方案：

// ✅ 相对时间格式化
const rtf = new Intl.RelativeTimeFormat('zh-CN', {
  numeric: 'auto',
  style: 'long'
});

console.log(rtf.format(-3, 'minute'));   // "3分钟前"
console.log(rtf.format(-1, 'hour'));     // "1小时前"
console.log(rtf.format(-2, 'day'));      // "2天前"
console.log(rtf.format(3, 'month'));     // "3个月后"
console.log(rtf.format(-1, 'year'));     // "去年"

// ✅ 配合 Date 计算智能相对时间
function timeAgo(date, locale = 'zh-CN') {
  const now = Date.now();
  const diff = now - date.getTime();
  const seconds = Math.floor(diff / 1000);
  const minutes = Math.floor(seconds / 60);
  const hours = Math.floor(minutes / 60);
  const days = Math.floor(hours / 24);
  const months = Math.floor(days / 30);
  const years = Math.floor(days / 365);

  const rtf = new Intl.RelativeTimeFormat(locale, {
    numeric: 'auto'
  });

  if (years > 0) return rtf.format(-years, 'year');
  if (months > 0) return rtf.format(-months, 'month');
  if (days > 0) return rtf.format(-days, 'day');
  if (hours > 0) return rtf.format(-hours, 'hour');
  if (minutes > 0) return rtf.format(-minutes, 'minute');
  return rtf.format(-seconds, 'second');
}

// 使用示例
const fiveMinAgo = new Date(Date.now() - 5 * 60 * 1000);
console.log(timeAgo(fiveMinAgo)); // "5分钟前"

const threeDaysAgo = new Date(Date.now() - 3 * 24 * 60 * 60 * 1000);
console.log(timeAgo(threeDaysAgo)); // "3天前"
console.log(timeAgo(threeDaysAgo, 'en-US')); // "3 days ago"

🚀 三、高级用法与工程化实践

3.1 Intl.Segmenter：文本分词

Intl.Segmenter 是 ES2022 引入的 API，用于按单词、句子或字符分割文本。它对中文文本处理尤其重要——中文没有空格分隔，传统的 split('') 方法无法正确处理 Unicode 组合字符。

// ✅ 中文文本分词（按字分割）
const seg = new Intl.Segmenter('zh-CN', { granularity: 'word' });
const text = '国际标准化组织制定的Unicode标准';

const segments = [...seg.segment(text)];
const words = segments
  .filter(s => s.isWordLike)
  .map(s => s.segment);

console.log(words);
// ["国际化", "标准", "组织", "制定", "的", "Unicode", "标准"]

// ✅ 字符计数（正确处理 emoji 和组合字符）
const charSeg = new Intl.Segmenter('zh-CN', { granularity: 'grapheme' });
const emoji = '👨‍👩‍👧‍👦🇨🇳 Hello!';
const charCount = [...charSeg.segment(emoji)].length;
console.log(charCount); // 10（正确：家庭 emoji + 国旗 emoji + 7 个字符）

// 对比错误做法
console.log(emoji.length); // 20（错误：把 surrogate pair 当两个字符）

⚠️ 警告： 永远不要用 string.length 来计算用户可见的字符数。对于包含 emoji、组合字符和 CJK 文本的字符串，length 返回的值与用户看到的字符数完全不同。始终使用 Intl.Segmenter。

3.2 Intl.ListFormat 与 Intl.PluralRules

// ✅ 列表格式化
const lf = new Intl.ListFormat('zh-CN', {
  style: 'long',
  type: 'conjunction'
});
console.log(lf.format(['张三', '李四', '王五']));
// "张三、李四和王五"

const lfEn = new Intl.ListFormat('en-US', { type: 'disjunction' });
console.log(lfEn.format(['Apple', 'Banana', 'Cherry']));
// "Apple, Banana, or Cherry"

// ✅ 复数规则（中文不需要，但英文/阿拉伯语等必须处理）
const pr = new Intl.PluralRules('en-US');
console.log(pr.select(0));  // "other"
console.log(pr.select(1));  // "one"
console.log(pr.select(2));  // "other"

const prAr = new Intl.PluralRules('ar');
console.log(prAr.select(0));  // "zero"
console.log(prAr.select(1));  // "one"
console.log(prAr.select(2));  // "two"
console.log(prAr.select(100)); // "other"

// ✅ 实际应用：智能复数显示
function itemCount(n, locale = 'zh-CN') {
  if (locale === 'zh-CN') return `${n} 个项目`;
  const pr = new Intl.PluralRules(locale);
  const form = pr.select(n);
  const labels = {
    one: `${n} item`,
    other: `${n} items`
  };
  return labels[form];
}

3.3 构建可复用的格式化工具层

在实际项目中，直接使用 Intl API 的原始写法会比较啰嗦。建议封装一层薄薄的工具函数：

// utils/formatter.js — 复用 Intl 实例，避免重复创建
const cache = new Map();

function getCached(key, factory) {
  if (!cache.has(key)) {
    cache.set(key, factory());
  }
  return cache.get(key);
}

export const format = {
  // 日期格式化
  date(date, locale = 'zh-CN', options = {}) {
    const key = `date:${locale}:${JSON.stringify(options)}`;
    return getCached(key, () =>
      new Intl.DateTimeFormat(locale, {
        year: 'numeric',
        month: '2-digit',
        day: '2-digit',
        ...options
      })
    ).format(date);
  },

  // 完整日期时间
  datetime(date, locale = 'zh-CN') {
    return this.date(date, locale, {
      year: 'numeric',
      month: '2-digit',
      day: '2-digit',
      hour: '2-digit',
      minute: '2-digit',
      hour12: false
    });
  },

  // 货币
  currency(amount, currencyCode = 'CNY', locale = 'zh-CN') {
    const key = `currency:${locale}:${currencyCode}`;
    return getCached(key, () =>
      new Intl.NumberFormat(locale, {
        style: 'currency',
        currency: currencyCode
      })
    ).format(amount);
  },

  // 紧凑数字（万/亿）
  compact(n, locale = 'zh-CN') {
    const key = `compact:${locale}`;
    return getCached(key, () =>
      new Intl.NumberFormat(locale, {
        notation: 'compact',
        compactDisplay: 'short'
      })
    ).format(n);
  },

  // 相对时间
  timeAgo(date, locale = 'zh-CN') {
    const diff = Date.now() - date.getTime();
    const absDiff = Math.abs(diff);
    const sign = diff > 0 ? -1 : 1;

    const units = [
      ['year', 365 * 24 * 3600_000],
      ['month', 30 * 24 * 3600_000],
      ['day', 24 * 3600_000],
      ['hour', 3600_000],
      ['minute', 60_000],
      ['second', 1000]
    ];

    for (const [unit, ms] of units) {
      if (absDiff >= ms) {
        const key = `rtf:${locale}`;
        const rtf = getCached(key, () =>
          new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })
        );
        return rtf.format(sign * Math.floor(absDiff / ms), unit);
      }
    }
    return '刚刚';
  }
};

// 使用示例
// format.date(new Date());              // "2026/05/31"
// format.currency(99.9, 'USD', 'en-US'); // "$99.90"
// format.compact(15800);                 // "1.6万"
// format.timeAgo(new Date(Date.now() - 3600000)); // "1小时前"

这个工具层只有约 50 行代码，覆盖了 90% 的格式化需求，而且通过 Map 缓存 Intl 实例，性能接近原生调用。

3.4 浏览器兼容性与 Polyfill

截至 2026 年，Intl API 在主流浏览器中的覆盖率已超过 97%。但如果你需要支持一些边缘场景：

💡 提示： 如果你需要支持 Safari 13 或更旧版本，可以使用 FormatJS 提供的 polyfill（@formatjs/intl-relativetimeformat）。但 polyfill 的体积远小于 moment.js，而且只需要按需引入缺失的部分。

⚠️ 四、常见坑点与避坑指南

4.1 locale 字符串的坑

// ❌ 错误：使用无效的 locale 不会报错，而是回退到默认值
new Intl.DateTimeFormat('zh_cn').format(date); // 不报错，但行为不确定

// ✅ 正确：使用标准 BCP 47 标签
new Intl.DateTimeFormat('zh-CN').format(date); // 中文-中国
new Intl.DateTimeFormat('zh-TW').format(date); // 中文-台湾
new Intl.DateTimeFormat('en-GB').format(date); // 英文-英国

4.2 时区名称必须是 IANA 格式

// ❌ 错误：使用缩写
new Intl.DateTimeFormat('zh-CN', { timeZone: 'CST' }).format(date);

// ✅ 正确：使用 IANA 时区名称
new Intl.DateTimeFormat('zh-CN', { timeZone: 'America/Chicago' }).format(date);

4.3 格式化的结果是字符串

// ❌ 错误：期望返回数字
const result = new Intl.NumberFormat('zh-CN').format(12345);
typeof result; // "string" — 不是数字！

// ✅ 正确：显示用途直接用，计算用途不要用
const displayPrice = new Intl.NumberFormat('zh-CN', {
  style: 'currency',
  currency: 'CNY'
}).format(price); // 用于显示

const calculatedPrice = price * 1.13; // 用于计算，不要用格式化后的字符串

4.4 性能优化：复用 Formatter 实例

// ❌ 错误：每次调用都创建新实例
function renderList(items) {
  return items.map(item =>
    new Intl.NumberFormat('zh-CN', { style: 'currency', currency: 'CNY' })
      .format(item.price)
  ).join('\n');
}

// ✅ 正确：创建一次，复用多次
const priceFormatter = new Intl.NumberFormat('zh-CN', {
  style: 'currency',
  currency: 'CNY'
});

function renderList(items) {
  return items.map(item => priceFormatter.format(item.price)).join('\n');
}

⚡ 关键结论： Intl 构造函数的开销主要在实例化阶段，format() 调用非常快。在渲染循环或高频调用场景中，务必复用 Formatter 实例。

🎯 总结

JavaScript Intl API 是 2026 年前端国际化和数据格式化的最佳方案。它零依赖、高性能、覆盖广，足以替代 moment.js、numeral.js、timeago.js 等一众第三方库。核心迁移策略：

• ✅ 用 Intl.DateTimeFormat 替代 moment().format()
• ✅ 用 Intl.NumberFormat + notation: 'compact' 替代自定义的万/亿格式化
• ✅ 用 Intl.RelativeTimeFormat 替代 timeago.js
• ✅ 用 Intl.Segmenter 替代手动字符计数
• ❌ 不要再为格式化功能引入第三方依赖
• ❌ 不要在循环中重复创建 Intl 实例

相关工具推荐：

• jsjson.com JSON 格式化工具 — 在线 JSON 处理
• jsjson.com 时间戳转换工具 — Unix 时间戳与日期互转
• FormatJS — 需要 polyfill 时的首选方案
• MDN Intl 文档 — 最权威的 API 参考