Jest测试Emotion缓存与MUI X日期时间选择器失败问题排查

本次@MUI生态报错的处理步骤 #

• 先校验依赖一致性：直接执行对应包管理器的依赖查询命令，排查@emotion/cache是否存在多实例、版本低于11.10.0的问题：
  • npm 环境执行：npm ls @emotion/cache
  • yarn 环境执行：yarn why @emotion/cache
  • pnpm 环境执行：pnpm why @emotion/cache
    MUI全系列组件对@emotion相关包的版本要求为不低于11.10.0，且整个项目内只能存在一个版本的@emotion/cache实例，多实例、版本过低都会触发无明确堆栈的模糊报错，和描述的现象完全吻合。
• 执行干净重装：如果查到版本不匹配或者多实例问题，直接删除本地node_modules文件夹、对应包管理器的锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml），安装经过兼容验证的固定版本组合：
  npm install @emotion/react@11.11.4 @emotion/cache@11.11.0 @emotion/styled@11.11.5 @mui/material@5.15.15 @mui/x-date-pickers@6.20.0
  安装完成后重跑测试用例，验证报错是否消失。
• 测试环境特殊适配：如果是在Jest/Vitest单元测试环境触发报错，直接在测试初始化配置文件中补充MUI样式引擎的mock配置，避免测试环境未正确加载Emotion运行时触发异常。

前端依赖版本兼容问题通用排查流程 #

• 先收敛问题范围：新增依赖后出现的问题，先回退代码到新增依赖前的可正常运行版本，再逐次升级单个依赖，定位触发冲突的具体包组合，禁止同时批量升级/新增依赖，避免扩大排查范围。
• 不要忽略安装阶段的peerDependencies警告：安装依赖时控制台输出的peer依赖不兼容提示直接对应绝大多数版本兼容问题，按照提示调整对应依赖版本即可提前规避问题，不要加--force或者--legacy-peer-deps强行安装。
• 优先参考官方兼容矩阵：所有主流开源库都会在官方文档明确标注自身peer依赖的版本要求，不要盲目安装latest版本，跨大版本升级前必须先过一遍官方迁移文档。
• 固定版本避免非预期升级：团队协作项目直接通过锁文件固定全量依赖版本，非必要不要使用^/~这类松散版本范围声明，避免依赖发布新版本后自动升级引入隐性兼容问题。

内容的提问来源于stack exchange，提问作者Hunor