Linux下VS Code执行npm install报ERESOLVE与EACCES依赖安装错误

适用环境：Linux系统、HP EliteBook 840 G3设备、VS Code终端操作场景

报错核心原因 #

• 触发ERESOLVE依赖解析失败的根本原因是npm 7.x以上版本默认开启严格peer依赖校验：项目根目录固定依赖为react@17.0.2，但项目引入的react-otp-input@2.4.0包声明的peer依赖仅匹配react@^16.2.0，版本校验不通过直接终止安装。这个问题和npm 8.12.1升级到8.13.2的小版本更新无关，所以升级npm后报错会复现。
• 执行全局npm更新时弹出EACCES权限拒绝，是因为/usr/local/lib/node_modules目录默认归属root用户，普通账号无该路径的写入、重命名权限导致。

操作步骤 #

1. 修复npm全局目录权限 #

先执行命令修正全局node_modules的归属，避免后续反复加sudo引发的文件权限异常：

sudo chown -R $USER:$USER /usr/local/lib/node_modules

执行完成后，后续所有全局npm操作不需要再加sudo，也不会触发权限报错。

2. 清理残留的失败安装文件 #

进入NH_Facility_Portal_V0项目根目录，执行以下命令清理之前安装失败产生的冗余文件：

# 删除残留依赖目录
rm -rf node_modules
# 删除旧版本锁文件
rm -f package-lock.json
# 清理npm本地缓存
npm cache clean --force

3. 执行依赖安装 #

注意：项目目录下的npm操作不要加sudo，否则会导致依赖文件归属root，后续项目启动、生成临时文件时会触发无权限错误，直接执行带兼容参数的安装命令即可：

npm install --legacy-peer-deps

说明：react-otp-input@2.4.0本身在React 17环境下没有运行时兼容问题，只是包的peer依赖声明没有及时更新React 17的版本支持，--legacy-peer-deps参数会沿用npm 6版本的宽松依赖解析逻辑，跳过严格的peer版本校验，不会影响项目正常运行。

可选配置（一劳永逸） #

如果不想每次安装依赖都手动加--legacy-peer-deps参数，可以执行全局配置命令永久生效：

npm config set legacy-peer-deps true

常见踩坑提示 #

• 不要通过升级npm小版本的方式尝试解决peer依赖冲突，这类冲突是依赖声明和校验规则共同导致的，和npm小版本bug无关
• 不要在项目目录下使用sudo执行npm操作，会引发一系列后续文件权限问题

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