GitHub Action构建React应用时npm ci步骤意外报错问题

• 本地运行正常、CI之前稳定今天突然失败的核心原因是npm版本差异：你本地使用的是npm v6及更早版本，近期GitHub Actions ubuntu-latest 运行器默认预装的npm升级到了v7+版本。npm v7开始默认开启严格的对等依赖（peerDependencies）版本校验，版本不满足时会直接抛出ERESOLVE错误终止安装；而npm v6遇到同类问题只会打印警告，不会中断安装流程。
• 具体依赖冲突点：项目中声明的react@^17.0.1、react-dom@^17.0.1版本，不满足引入的@mui/material@5.2.4、@mui/icons-material@5.2.4、@mui/base@5.0.0-alpha.60要求的最低对等依赖版本react@^17.0.2、react-dom@^17.0.2，触发了npm v7的严格校验拦截。

• 分别查看本地环境和GitHub Actions运行日志里的npm版本号，确认版本差是否存在
• 核对package.json中react、react-dom与MUI相关依赖的版本声明，确认版本匹配关系
• 检查本地node_modules、package-lock.json是否由旧版npm生成，是否存在未提交的lock文件变更

按推荐优先级从高到低排列：

• 方案1（长期规范方案）：升级项目内react、react-dom版本到符合MUI依赖要求的版本，将package.json里的react、react-dom版本号修改为^17.0.2，本地执行npm install重新生成package-lock.json后提交到仓库，后续CI执行npm ci即可正常完成依赖安装。
• 方案2（行为对齐方案，无侵入）：给CI中的npm安装命令添加--legacy-peer-deps参数，强制npm使用v6版本的依赖解析逻辑，跳过严格对等依赖校验，和你本地的安装行为保持完全一致。修改工作流中的安装步骤如下：

- name: Install NPM Packages
  run: npm ci --legacy-peer-deps

如果后续本地npm也升级到v7+版本，本地安装时添加相同参数即可保证两端行为一致。

• 方案3（临时兜底方案，不推荐长期使用）：在CI步骤中先将npm降级到v6版本，和你本地环境的npm版本完全对齐，修改安装步骤如下：

- name: Install NPM Packages
  run: |
    npm install -g npm@6
    npm ci

该方案仅做临时规避，后续npm v6停止维护后仍需处理实际的依赖版本冲突问题。

注意：不推荐使用--force参数强制安装，该参数会跳过所有依赖校验，可能引入隐性的版本不兼容问题导致运行时异常。

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