个人记录项目遇到的day.js中文不生效案列总结

个人经验总结，记录开发过程中遇到的疑难问题及解决方案
官方antd也有说明此类问题：
https://5x.ant.design/docs/react/faq-cn#%E4%B8%BA%E4%BB%80%E4%B9%88%E6%97%B6%E9%97%B4%E7%B1%BB%E7%BB%84%E4%BB%B6%E7%9A%84%E5%9B%BD%E9%99%85%E5%8C%96-locale-%E8%AE%BE%E7%BD%AE%E4%B8%8D%E7%94%9F%E6%95%88

1. Ant Design DatePicker 显示英文而非中文

问题现象

• DatePicker 组件显示英文星期（Su, Mo, Tu...）和月份（Feb, Mar...）
• 已正确配置 dayjs.locale('zh-cn') 和 Ant Design 的 ConfigProvider locale
• 其他组件的中文显示正常

错误的排查方向

1. ❌ 检查 dayjs.locale() 调用顺序
2. ❌ 检查 ConfigProvider 的 locale 配置
3. ❌ 在组件外层再包一层 ConfigProvider
4. ❌ 检查 dayjs 插件的 extend 顺序
5. ❌ 清除 Vite 缓存（rm -rf node_modules/.vite）

根本原因

pnpm 依赖解析导致存在多个 dayjs 实例

项目直接依赖: dayjs@1.11.13
antd/rc-picker 依赖: dayjs >= 1.x → pnpm 安装了 1.11.19

两个版本的 dayjs 代码完全相同，但因为是不同的实例：

• 项目代码调用 dayjs.locale('zh-cn') 设置的是 1.11.13 实例
• rc-picker（DatePicker 底层库）使用的是 1.11.19 实例（仍为英文）

诊断命令

# 查看 dayjs 被哪些包依赖
pnpm why dayjs

# 查看实际安装的 dayjs 版本
pnpm list dayjs --depth=3

# 查看 node_modules 中的 dayjs 实例
find node_modules -name "dayjs" -type d | head -20

解决方案

在 package.json 中添加 pnpm.overrides 强制统一版本：

{
  "pnpm": {
    "overrides": {
      "dayjs": "1.11.13"
    }
  }
}

然后重新安装依赖：

rm -rf node_modules pnpm-lock.yaml
pnpm install

关键教训

1. 版本号相近不代表没问题 - 1.11.13 和 1.11.19 代码相同，但多实例导致状态不共享
2. pnpm 的严格依赖隔离是双刃剑 - 避免了幽灵依赖，但也可能导致多实例问题
3. locale 设置是实例级别的 - 不同实例的 locale 状态互相独立
4. 先查依赖树，再改业务代码 - 遇到"配置正确但不生效"的问题，优先检查依赖

2. pnpm 多实例问题通用解决方案

问题特征

• 配置明明正确，但就是不生效
• 同一个库的不同功能表现不一致
• 在某些组件中正常，在其他组件中异常

诊断步骤

# 1. 查看问题库的依赖关系
pnpm why <package-name>

# 2. 查看实际安装版本
pnpm list <package-name> --depth=5

# 3. 检查是否有多个版本
ls -la node_modules/.pnpm | grep <package-name>

解决方案对比

pnpm.overrides 配置示例

{
  "pnpm": {
    "overrides": {
      "dayjs": "1.11.13",
      "lodash": "4.17.21",
      "react": "18.3.1"
    }
  }
}

.npmrc 相关配置

# 提升所有依赖到根 node_modules（不推荐，会失去 pnpm 优势）
shamefully-hoist=true

# 只提升特定包
public-hoist-pattern[]=*dayjs*

# 严格模式（默认）
strict-peer-dependencies=true

3. Vite 缓存问题

问题现象

• 修改代码后页面没有更新
• 热更新失效
• 构建产物与源码不一致

解决方案

# 清除 Vite 缓存
rm -rf node_modules/.vite

# 清除并重启
rm -rf node_modules/.vite && pnpm dev

# 完全清理（核弹级）
rm -rf node_modules/.vite dist .cache

注意事项

• Vite 缓存位于 node_modules/.vite
• 修改 vite.config.ts 后缓存会自动失效
• 但修改依赖版本后缓存可能不会自动更新

4. 依赖版本问题排查清单

遇到"配置正确但不生效"的问题时，按以下顺序排查：

第一步：检查依赖树

pnpm why <问题库>
pnpm list <问题库> --depth=5

第二步：检查是否有多实例

ls -la node_modules/.pnpm | grep <问题库>
find node_modules -name "<问题库>" -type d

第三步：确认版本兼容性

• 查看问题库的 CHANGELOG
• 检查是否有 breaking changes
• 确认项目其他依赖的版本要求

第四步：尝试统一版本

{
  "pnpm": {
    "overrides": {
      "<问题库>": "<指定版本>"
    }
  }
}

第五步：重新安装

rm -rf node_modules pnpm-lock.yaml
pnpm install

5. 常见的多实例问题库

以下库容易出现多实例问题，需要特别注意：