npm依赖树冲突修复：本地修改npm包及@nestjs/passport兼容问题

在学习nest.js的过程中，执行npm install --save-dev @types/bcrypt @types/passport @types/passport-jwt命令时抛出ERESOLVE依赖解析错误，错误日志如下：

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: @nestjs/passport@8.2.1
npm ERR! Found: passport@0.6.0
npm ERR! node_modules/passport
npm ERR!   passport@"^0.6.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer passport@"^0.4.0 || ^0.5.0" from @nestjs/passport@8.2.1
npm ERR! node_modules/@nestjs/passport
npm ERR!   @nestjs/passport@"^8.2.1" from the root project
npm ERR!
npm ERR! Conflicting peer dependency: passport@0.5.3
npm ERR! node_modules/passport
npm ERR!   peer passport@"^0.4.0 || ^0.5.0" from @nestjs/passport@8.2.1
npm ERR!   node_modules/@nestjs/passport
npm ERR!     @nestjs/passport@"^8.2.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.

问题根因排查 #

• 当前项目安装的@nestjs/passport版本为8.2.1，该版本package.json中声明的passport peer依赖范围为"^0.4.0 || ^0.5.0"，不支持已安装的passport@0.6.0版本
• 官方源码已更新peer依赖范围，新增了对passport@^0.6.0的支持，但对应变更尚未发布到npm正式版本

问题解答 #

1. 正式版本发布前的临时解决方案 #

按优先级从高到低可选择以下方案：

• 方案一：使用overrides强制指定依赖版本（npm 7+支持）
  在项目根目录的package.json中添加如下配置，强制@nestjs/passport对passport的引用匹配0.6.0版本，跳过对应peer依赖范围校验：

  {
    "overrides": {
      "@nestjs/passport": {
        "passport": "^0.6.0"
      }
    }
  }
  

  保存后删除node_modules目录和package-lock.json文件，重新执行npm install即可。该方案仅对当前项目生效，不会修改全局npm配置，是最推荐的临时方案。
• 方案二：使用--legacy-peer-deps参数临时绕过校验
  执行安装命令时追加--legacy-peer-deps参数，让npm使用v6版本的依赖解析逻辑，忽略peer依赖版本冲突校验：

  npm install --save-dev @types/bcrypt @types/passport @types/passport-jwt --legacy-peer-deps
  

  不建议执行npm config set legacy-peer-deps true做全局配置，容易给其他本地项目埋下依赖隐患。
• 方案三：降级passport到兼容版本
  将项目内安装的passport版本降到@nestjs/passport@8.2.1支持的0.5.x区间，等官方发布兼容0.6版本的正式版后再升级passport即可，缺点是无法使用passport 0.6版本的新特性。

2. 手动修改node_modules下package.json不生效的原因 #

npm执行依赖解析时，不会直接读取node_modules目录下已安装包的package.json作为解析依据：

• 执行npm install相关命令时，npm会优先从本地缓存、npm远程仓库拉取对应版本包的官方元信息（含peer依赖声明），结合锁文件package-lock.json和项目根目录package.json的声明完成依赖树构建
• 手动修改node_modules里的文件，既不会更新package-lock.json中记录的依赖元信息，也不会修改npm缓存中存储的@nestjs/passport@8.2.1版本的原始依赖声明，npm解析时仍会用原始的peer依赖范围做校验，自然会抛出相同错误
• 就算修改后暂时绕过校验，后续只要重新执行npm install，node_modules里的修改内容就会被覆盖回官方原始版本，修改会直接丢失。

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