Expo构建iOS应用遇NPM依赖冲突，如何用--legacy-peer-deps解决？

问题描述 #

使用Expo构建iOS移动应用时遭遇NPM依赖解析错误，开发阶段曾通过--legacy-peer-deps参数规避依赖冲突，询问构建场景是否可继续使用该参数，以及替代解决方案。

错误日志详情 #

[stderr] 
npm ERR! code ERESOLVE
[stderr] 
npm ERR! ERESOLVE 无法解析依赖
[stderr] 
npm ERR!
[stderr] 
npm ERR! 解析依赖时出错：@react-native-community/async-storage@1.12.1
[stderr] 
npm
[stderr] 
ERR!
[stderr] 
已找到：react@18.0.0
[stderr] 
npm ERR! node_modules/react
[stderr] 
npm ERR!   根项目依赖 react@"18.0.0"
[stderr] 
npm ERR!   @ant-design/cssinjs@1.6.1 的 peer 依赖要求 react@">=16.0.0"
[stderr] 
npm ERR!
[stderr] 
node_modules/@ant-design/cssinjs
[stderr] 
npm ERR!     antd@5.3.0 依赖 @ant-design/cssinjs@"^1.5.6"
[stderr] 
npm ERR!     node_modules/antd
[stderr] 
npm ERR!       根项目依赖 antd@"^5.3.0"
[stderr] 
npm ERR!   另有73个依赖包（如@ant-design/icons、@ant-design/react-slick等）依赖react
[stderr] 
npm ERR! 
[stderr] 
npm ERR! 无法解析的依赖：
[stderr] 
npm ERR! @react-native-community/async-storage@1.12.1 的 peer 依赖要求 react@"^16.8"
[stderr] 
npm ERR! node_modules/@react-native-community/async-storage
[stderr] 
npm ERR!   根项目依赖 @react-native-community/async-storage@"^1.12.1"
[stderr] 
npm ERR! 
[stderr] 
npm ERR! 冲突的peer依赖：react@16.14.0
[stderr] 
npm ERR! node_modules/react
[stderr] 
npm ERR!   @react-native-community/async-storage@1.12.1 的 peer 依赖要求 react@"^16.8"
[stderr] 
npm ERR!   node_modules/@react-native-community/async-storage
[stderr] 
npm ERR!     根项目依赖 @react-native-community/async-storage@"^1.12.1"
[stderr] 
npm ERR!
[stderr] 
npm ERR! 解决上游依赖冲突，或使用--force、--legacy-peer-deps参数重试命令
[stderr] 
npm ERR! 以接受可能存在问题的依赖解析结果。
[stderr] 
npm ERR! 
[stderr] 
npm ERR! 完整报告请查看：/Users/expo/.npm/eresolve-report.txt
[stderr] 
[stderr] 
npm ERR! 本次运行的完整日志可在以下路径查看：
[stderr] 
npm ERR!     /Users/expo/.npm/_logs/2023-04-19T00_02_50_805Z-debug-0.log
npm exited with non-zero code: 1

解决方案 #

1. 构建场景下是否可使用--legacy-peer-deps？ #

可以使用，但属于临时规避方案，不推荐长期依赖。该参数会跳过NPM的peer依赖版本校验，可能导致运行时出现兼容性问题（如组件渲染失败、API调用异常等），仅建议在紧急构建时临时使用。

2. 更稳妥的修复方法 #

升级@react-native-community/async-storage

该包的最新稳定版本已兼容React 18，执行以下命令更新：

npm install @react-native-community/async-storage@latest

若为Expo项目，优先考虑使用Expo官方提供的expo-secure-store或expo-file-system，它们与Expo生态兼容性更佳。

使用npm overrides强制兼容

在项目的package.json中添加overrides字段，强制让@react-native-community/async-storage适配当前的React 18版本：

"overrides": {
  "@react-native-community/async-storage": {
    "react": "^18.0.0"
  }
}

此方法仅针对特定包忽略peer依赖声明，比--legacy-peer-deps更精准，降低全局兼容性风险。

降级React版本（不推荐）

若暂时无法升级依赖，可将React版本降级至^16.14.0以满足@react-native-community/async-storage的peer依赖要求：

npm install react@^16.14.0

但此操作可能引发其他依赖（如antd 5.x）的兼容性问题，需谨慎测试。

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