dayjs.locale(locale) 不生效？如何正确加载并切换语言包？

Question

**Day.js `dayjs.locale(locale)` 不生效？常见原因与解法** 调用 `dayjs.locale('zh-cn')` 后日期格式未切换，多因语言包未正确引入。Day.js 默认仅加载英文（en）locale，其他语言需**显式导入并注册**： ✅ 正确做法： ```js import dayjs from 'dayjs'; import 'dayjs/locale/zh-cn'; // 先导入语言包（ESM/CJS均需） dayjs.locale('zh-cn'); // 再设置——必须在导入后调用！ ``` ⚠️ 常见陷阱： - 忘记 `import 'dayjs/locale/zh-cn'`，仅调用 `.locale()` 无效； - 在模块顶层多次调用 `.locale()` 但未确保导入顺序； - 使用 CDN 时未通过 `<script></script>

Answer 1

```html

一、现象层：为何调用 dayjs.locale('zh-cn') 后界面仍显示英文？

这是前端开发者最常遇到的“静默失效”问题：控制台无报错、代码逻辑看似完整，但 dayjs().format('LL') 依然输出 January 1, 2025 而非 2025年1月1日。本质并非 API 错误，而是 Day.js 的按需加载设计哲学导致语言包未被激活。

二、机制层：Day.js Locale 的注册与激活双阶段模型

Day.js 采用「分离式国际化」架构：

1. 注册（Registration）：通过 import 'dayjs/locale/zh-cn' 将 locale 对象挂载到内部 dayjs.locales 映射表；
2. 激活（Activation）：调用 dayjs.locale('zh-cn') 设置全局默认 locale 或实例 locale。

二者缺一不可，且顺序不可逆——未注册即激活将 fallback 到 en 并静默忽略。

三、排查层：系统性诊断路径（含代码验证）

检查项	验证代码	预期输出
语言包是否已注册？	console.log(dayjs.locales['zh-cn'])	应为 Object（含 months/weekdays 等字段），否则未导入
当前激活 locale 是什么？	console.log(dayjs.locale())	应返回 'zh-cn'，若为 'en' 则激活失败

四、解法层：全场景兼容方案（ESM / CJS / CDN / TypeScript）

✅ ESM（推荐）：

import dayjs from 'dayjs';
import 'dayjs/locale/zh-cn'; // 必须在 locale() 前
import 'dayjs/locale/ja';    // 可链式导入多语言
dayjs.locale('zh-cn');

✅ CDN 方式（需 script 标签顺序）：

<script src="https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dayjs@1/locale/zh-cn.js"></script>
<script>dayjs.locale('zh-cn');</script>

五、进阶层：高级陷阱与工程化实践

• Tree-shaking 冲突：Vite/Webpack 中若配置了 sideEffects: false，需显式声明 locale 文件为有副作用："sideEffects": ["**/locale/*.js"]；
• 动态 locale 切换：避免全局污染，建议使用实例级 locale：const cnDayjs = dayjs.bind(null, { locale: 'zh-cn' });；
• TypeScript 类型补全：安装 @types/dayjs 并在 src/types/dayjs.d.ts 中添加：declare module 'dayjs/locale/zh-cn';

六、验证层：自动化回归测试片段

describe('Day.js zh-cn locale', () => {
  it('should format date in Chinese', () => {
    expect(dayjs('2025-01-01').format('LL')).toBe('2025年1月1日');
  });
  it('should localize weekday', () => {
    expect(dayjs('2025-01-01').format('dddd')).toBe('星期三');
  });
});

七、架构层：Mermaid 流程图揭示执行时序关键点

flowchart TD
  A[import dayjs] --> B[import 'dayjs/locale/zh-cn']
  B --> C[dayjs.locales['zh-cn'] = {...}]
  C --> D[dayjs.locale('zh-cn')]
  D --> E[dayjs.locale() === 'zh-cn']
  E --> F[format 使用中文映射]
  G[仅调用 dayjs.locale] -.->|跳过B/C| H[fallback to 'en']

```