解决NPM构建过程中的peer依赖冲突问题

问题现象 #

开发模式下项目运行正常，但执行npm run build时触发两类错误：

• TypeScript类型错误：error TS2786: 'Chart' cannot be used as a JSX component. Its type 'typeof Chart' is not a valid JSX element type.（涉及react-google-charts的Chart组件）
• npm依赖解析错误（ERESOLVE）：

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! 
npm ERR! While resolving: @material-ui/core@4.12.4
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   react@"^18.0.0" from the root project
npm ERR!   peer react@"^17.0.0 || ^18.0.0" from @mui/utils@5.14.19
npm ERR!   node_modules/@mui/utils
npm ERR!     @mui/utils@"^5.14.19" from @mui/material@5.14.19
npm ERR!     node_modules/@mui/material
npm ERR!       @mui/material@"^5.14.19" from the root project
npm ERR!       1 more (@mui/icons-material)
npm ERR!     @mui/utils@"^5.14.19" from @mui/system@5.14.19
npm ERR!     node_modules/@mui/system
npm ERR!       @mui/system@"^5.14.19" from @mui/material@5.14.19
npm ERR!       node_modules/@mui/material
npm ERR!         @mui/material@"^5.14.19" from the root project
npm ERR!         1 more (@mui/icons-material)
npm ERR!     2 more (@mui/private-theming, @mui/base)
npm ERR!   15 more (react-router-dom, @emotion/react, react-native-web, ...)
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0 || ^17.0.0" from @material-ui/core@4.12.4
npm ERR! node_modules/@material-ui/core
npm ERR!   @material-ui/core@"^4.12.4" from the root project
npm ERR!   peer @material-ui/core@"^4.0.0" from @material-ui/icons@4.11.3
npm ERR!   node_modules/@material-ui/icons
npm ERR!     @material-ui/icons@"^4.11.3" from the root project
npm ERR! 
npm ERR! Conflicting peer dependency: react@17.0.2
npm ERR! node_modules/react
npm ERR!   peer react@"^16.8.0 || ^17.0.0" from @material-ui/core@4.12.4
npm ERR!   node_modules/@material-ui/core
npm ERR!     @material-ui/core@"^4.12.4" from the root project
npm ERR!     peer @material-ui/core@"^4.0.0" from @material-ui/icons@4.11.3
npm ERR!     node_modules/@material-ui/icons
npm ERR!       @material-ui/icons@"^4.11.3" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

当前package.json配置 #

{
  "name": "react-app",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview",
    "preinstall": "npm install --package-lock-only --ignore-scripts && npx npm-force-resolutions",
    "start": "electron ."
  },
  "dependencies": {
    "@emotion/react": "^11.5.0",
    "@emotion/styled": "^11.5.0",
    "@material-ui/core": "^4.12.4",
    "@material-ui/icons": "^4.11.3",
    "@mui/icons-material": "^5.14.19",
    "@mui/material": "^5.14.19",
    "electron": "^27.1.3",
    "html2canvas": "^1.3.1",
    "jspdf": "^2.5.1",
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "react-native-web": "^0.19.9",
    "react-router-dom": "^6.2.1"
  },
  "devDependencies": {
    "@types/react": "^17.0.0",
    "@types/react-dom": "^17.0.0",
    "@typescript-eslint/eslint-plugin": "^5.10.0",
    "@typescript-eslint/parser": "^5.10.0",
    "@vitejs/plugin-react": "^4.1.0",
    "eslint": "^8.3.0",
    "eslint-plugin-react-hooks": "^4.6.0",
    "eslint-plugin-react-refresh": "^0.4.3",
    "typescript": "^4.6.5",
    "vite": "^5.0.0"
  }
}

已尝试的无效操作 #

• 重新安装依赖、清理npm缓存
• 使用--force或--legacy-peer-deps参数执行npm install
• 尝试抑制TypeScript错误，但构建仍无法完成

有效解决方案 #

1. 统一Material UI版本，移除不兼容的旧包 #

@material-ui/core v4仅支持React 16/17，与当前React 18冲突，且项目同时安装了@mui/material v5（新的Material UI包），需彻底移除旧包：

npm uninstall @material-ui/core @material-ui/icons

后续项目仅使用@mui/material和@mui/icons-material（v5版本原生支持React 18）

2. 更新React类型定义到匹配版本 #

当前@types/react和@types/react-dom为v17，与React 18不匹配，导致TS类型校验错误：

npm install -D @types/react@^18.2.0 @types/react-dom@^18.2.0

3. 清理并重新安装依赖 #

删除残留的旧依赖和锁文件，确保依赖版本完全匹配：

rm -rf node_modules package-lock.json
npm install

4. 确保react-google-charts兼容React 18 #

若使用的react-google-charts版本过旧，更新到最新版以支持React 18：

npm install react-google-charts@latest

5. 检查TypeScript配置（可选） #

确保tsconfig.json中React相关配置正确：

• jsx设置为react-jsx（适配React 18的自动JSX转换）
• lib数组包含dom、es2020等必要环境

原理说明 #

• 移除@material-ui v4包彻底解决了React版本的peer依赖冲突
• 更新@types/react到v18修复了类型定义不匹配导致的TS错误（包括Chart组件无法识别为JSX元素的问题）
• 清理依赖后重新安装确保所有依赖版本一致，避免缓存或残留文件干扰

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