解决 Cannot find module 'react-dom/client' 错误
问题描述
在使用 npm test 运行测试时，出现以下错误：
Cannot find module 'react-dom/client' from 'node_modules/@testing-library/react/dist/pure.js'
Required stack:
node_modules/@testing-library/react/dist/pure.js
node_modules/@testing-library/react/dist/index.js尽管已安装了所有必要的依赖包，包括重新安装 react-dom，问题仍然存在。
从用户提供的 package.json 可以看出：
- React 版本为 17.x
- @testing-library/react 版本为 13.x
- @testing-library/jest-dom 版本为 5.16.3
问题根源
这个错误的核心原因是 版本不兼容问题。根据 @testing-library/react 发布说明，版本 13+ 已停止对 React 17 及以下版本的支持。
React 18 引入了新的 react-dom/client API（如 createRoot），而 React 17 使用的是旧的 react-dom API（如 render）。当测试库版本 13+ 尝试使用新的 API，而项目中安装的仍然是 React 17 时，就会出现找不到模块的错误。
解决方案
方案一：降级测试库版本（推荐给现有 React 17 项目）
如果你的项目暂时无法升级到 React 18，最直接的解决方案是降级测试库版本：
npm install @testing-library/react@12.1.5 --save-dev或者更新 package.json 中的依赖版本：
{
"devDependencies": {
"@testing-library/react": "^12.1.5"
}
}然后重新安装依赖：
npm install方案二：升级到 React 18（推荐给新建项目）
如果你可以升级到 React 18，这是更长期和推荐的解决方案：
npm install react@18 react-dom@18同时需要更新测试库和其他相关依赖：
npm install @testing-library/react@latest --save-dev对于使用 React Redux 的项目，还需要按照 React Redux 官方指南更新 Provider 的使用方式。
方案三：清理缓存并更新依赖
有时候缓存问题可能导致依赖冲突，可以尝试以下步骤：
# 删除 node_modules 和 package-lock.json
rm -rf node_modules package-lock.json
# 清除 npm 缓存
npm cache clean --force
# 重新安装依赖
npm install
# 更新所有依赖到最新版本
npm update --force --legacy-peer-deps
# 安装最新的类型定义（TypeScript 项目）
npm install --save-dev @types/react@latest @types/react-dom@latestWARNING
使用 --legacy-peer-deps 和 --force 标志可能会绕过一些版本冲突检查，请在了解风险后使用。
预防措施
为了避免类似的版本兼容性问题：
- 定期更新依赖：使用
npm outdated检查过时的依赖 - 阅读发布说明：在升级主要版本前，务必阅读相关库的发布说明
- 使用版本锁定：对于生产项目，考虑使用精确版本号或锁文件
- 测试环境一致性：确保开发、测试和生产环境的依赖版本一致
版本兼容性参考表
| React 版本 | @testing-library/react 兼容版本 |
|---|---|
| React 16 | ^9.x - ^12.x |
| React 17 | ^12.x |
| React 18+ | ^13.x+ |
总结
Cannot find module 'react-dom/client' 错误通常是由于 React 版本与测试库版本不兼容导致的。根据项目需求选择降级测试库（兼容现有 React 17 项目）或升级 React 版本（面向未来）是最有效的解决方案。定期维护和更新项目依赖可以有效预防此类问题。