npm 装 React 组件报 ERESOLVE：继续查 react-dom 的 peer 依赖链

项目使用 React 16，安装组件包时 npm 报 ERESOLVE unable to resolve dependency tree。组件声明的 React 范围看起来允许 16，错误却提到 React 17。这时不要只比较组件与 React 的两行版本范围，继续看它要求的 react-dom，以及那个版本对 React 的要求。

npm 7 起默认处理并安装 peerDependencies。一个范围较宽的组件可能同时接受 React 16、17 和对应的渲染器，但依赖树中被选择的 react-dom 版本，未必兼容项目已有的 React。本文处理这种间接 peer 冲突；版本范围确实互不相容的包，则需要另外选择兼容版本。

错误最后几行可能才是冲突点

下面是历史版本组合的简化错误示例，用于解释依赖链，不是新项目的推荐版本：

Found: react@16.14.0
peer react@"^0.14.9 || >=15.3.0" from react-bootstrap@0.32.4
Could not resolve dependency:
peer react@"17.0.2" from react-dom@17.0.2
peer react-dom@"^0.14.9 || >=15.3.0" from react-bootstrap@0.32.4

React 16.14.0 满足组件的第一条范围，不能由此证明整个依赖树兼容。这里选择了 react-dom 17.0.2，而它要求 React 17.0.2；冲突出在这一步。组件允许一大段范围，不表示这段范围中的任意 React 与任意 react-dom 都能交叉组合。

保留完整 ERESOLVE 信息，按“当前选择的包—要求它的包—它又要求的 peer”向下读。不要只截取 Found: react，也不要把日志中的旧版本组合照搬到当前项目。

核对项目是否明确声明渲染器

在实际项目目录查看已安装的版本与 manifest：

npm --version
npm ls react react-dom

安装失败后，现有 node_modules 可能还是此前的状态，所以还要核对 package.json 与锁文件中的直接依赖、选择版本和要求范围。npm ls 显示的结果不能代替对失败解析链的阅读。

若这是浏览器应用，本来就需要 react-dom，而项目只直接声明了 React，应根据实际 React 版本及相关包的 peer 要求，明确选择兼容的 react-dom。旧项目维持 React 16 时，不应让渲染器无约束地选择到 React 17；计划升级时则应一起评估应用代码、组件库与渲染器，不能只为了安装成功跨一个大版本。

库项目的依赖声明方式还涉及对使用者的 peer 契约，不应照搬应用的 dependencies 布局。在 workspace 中，也应确认究竟是哪一个包使用并声明这些依赖，不能只在根目录添加版本来掩盖包自身的缺口。

修版本组合，再按同一规则生成锁文件

修改前保存 package.json、锁文件和项目 npm 配置，使用团队确定的 npm 版本。在核对各方声明后，调整确实需要的直接依赖，再按项目原安装流程更新锁文件，检查差异是否只包含预期的解析变化。

如果补上兼容的 react-dom 后还报冲突，继续读新的具体 peer 链；另一个组件可能对 React 或渲染器有更窄的要求。仅靠这条路径不能保证所有 ERESOLVE 都解决，遇到互斥范围时，需要更新或替换相应包。

--legacy-peer-deps 会在构建依赖树时忽略 peerDependencies 契约，--force 也不能证明版本组合在运行时兼容。不要把绕过检查的安装成功当成解决了这个问题。若项目已有经评估的临时兼容策略，应单独记录其边界，并让锁文件生成与 CI 安装使用相同规则。

删除锁文件或 npm 缓存不会解释为什么选中了不兼容的渲染器，还会扩大依赖变更范围。应保留已知选择，核对具体版本，而不是不断从最新版本重新猜一遍。

验收包含安装和页面运行

在隔离工作目录中，以确定的版本和配置验证安装或 npm ci，确认不再出现这条 peer 冲突。npm ci 会清理并重新安装 node_modules，不要在存有未备份手工修改的目录中使用它。

随后执行项目已有构建与关键组件渲染检查，确认 React、渲染器和组件 API 都兼容。恢复时一起还原依赖声明、锁文件及本次配置，按原流程恢复依赖；只还原 package.json 而保留新锁文件，可能重新制造不一致。