无法安装react-awesome-query-builder，请求解决依赖冲突问题

问题描述 #

在Vdom-Oracle JET项目中执行命令 npm i react-awesome-query-builder --save 安装依赖时，触发ERESOLVE依赖树解析错误。核心矛盾在于项目使用的React版本为18.2.0，而react-awesome-query-builder依赖的@material-ui/core@4.12.4仅支持React ^16.8.0或17.0.0。使用--force参数可完成安装，但存在后续运行风险，需要更稳妥的解决方式。

错误日志 #

npm WARN config global `--global`, `--local` are deprecated. Use `--location=global` instead.
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: vdom-chart-sample@1.0.0
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   peer react@"^16.8.4 || ^17.0.1 || ^18.0.0" from react-awesome-query-builder@5.3.1
npm ERR!   node_modules/react-awesome-query-builder
npm ERR!     react-awesome-query-builder@"^5.3.1" from the root project
npm ERR!   peer react@">=16.0.0" from @ant-design/icons@4.7.0
npm ERR!   node_modules/@ant-design/icons
npm ERR!     @ant-design/icons@"^4.7.0" from the root project
npm ERR!     peer @ant-design/icons@"^4.0.0" from react-awesome-query-builder@5.3.1
npm ERR!     node_modules/react-awesome-query-builder
npm ERR!       react-awesome-query-builder@"^5.3.1" from the root project
npm ERR!   4 more (react-dom, @emotion/react, @emotion/styled, @fortawesome/react-fontawesome)
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!   peer @material-ui/core@"^4.12.3" from react-awesome-query-builder@5.3.1
npm ERR!   node_modules/react-awesome-query-builder
npm ERR!     react-awesome-query-builder@"^5.3.1" 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.
npm ERR!
npm ERR! See C:\Users\Rence Abishek\AppData\Local\npm-cache\eresolve-report.txt for a full report.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\Rence Abishek\AppData\Local\npm-cache\_logs\2022-09-07T12_45_29_407Z-debug-0.log

解决方案 #

1. 使用--legacy-peer-deps替代--force #

npm 7及以后版本默认启用严格的peer依赖校验，--legacy-peer-deps会切换回npm 6的宽松校验逻辑，跳过peer依赖冲突的强制检查，比--force更安全，不会强制覆盖现有依赖版本。
执行命令：

npm i react-awesome-query-builder --save --legacy-peer-deps

2. 等待依赖库官方兼容更新 #

检查react-awesome-query-builder的项目仓库，查看是否有计划升级依赖的@material-ui/core到支持React 18的版本（如Material UI v5，即@mui/material）。如果已有兼容React 18的正式版或测试版，直接安装对应版本即可。

3. 降级React到17.x版本 #

若项目未依赖React 18的专属特性，可考虑降级React及react-dom到17.x版本，匹配@material-ui/core@4.x的版本要求：

npm install react@^17.0.2 react-dom@^17.0.2 --save

降级后需全面测试现有功能，确保其他依赖未出现新的冲突。

4. 手动覆盖依赖版本（风险较高） #

通过npm的overrides字段强制指定依赖版本，但需注意@material-ui/core@4.x本身不支持React 18，可能存在运行时问题，仅作为备选方案。在package.json中添加：

"overrides": {
  "react-awesome-query-builder": {
    "@material-ui/core": "^4.12.4"
  }
}

添加后执行npm install完成安装。

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