从私有GitLab安装npm包时，包内出现node_modules的原因及解决方法

原因分析 #

• npm依赖扁平化策略触发降级：npm默认会把所有依赖提升到项目根目录的node_modules里，避免重复安装。但如果你的包依赖的某个包，和当前项目已安装的同包版本存在不可兼容的差异（比如语义化版本冲突：你的包要求^2.0.0，项目装了^1.5.0），npm就会放弃提升，在你的包目录下单独安装所需版本的依赖，形成嵌套的node_modules。
• 依赖声明类型不合理：如果你的包是工具库、UI组件这类需要依赖宿主项目环境的包，却把核心依赖放在dependencies里而不是peerDependencies，npm会默认在你的包目录下安装这些依赖，而不是复用项目已有的依赖。
• npm版本限制：npm 6及更早版本的依赖扁平化逻辑不够完善，遇到复杂依赖树时更容易出现嵌套安装的情况，而npm 7+对这部分做了优化。

解决办法 #

• 排查版本冲突：在安装你的包的项目里执行npm ls <你的包依赖的包名>，看看是否存在版本冲突。如果有，要么调整你的包的依赖版本范围（比如把^2.0.0改成>=1.5.0 <3.0.0），要么升级项目里的对应依赖版本，让两者兼容，这样npm就能把依赖提升到根目录。
• 改用peerDependencies声明依赖：把你的包package.json里dependencies中的依赖移到peerDependencies，并指定合理的版本范围。比如：

  {
    "peerDependencies": {
      "lodash": ">=4.0.0 <5.0.0"
    }
  }
  

  这样npm会要求宿主项目必须安装符合版本要求的依赖，不会在你的包目录下重复安装，同时也能明确告知用户你的包依赖的环境要求。
• 升级npm版本：如果项目还在使用npm 6或更早版本，升级到npm 7及以上版本，它的依赖解析逻辑能更好地处理版本兼容，减少嵌套安装的场景。
• 确认包发布配置：检查你的包的.npmignore文件或package.json里的files字段，确保发布的包没有包含node_modules（你已经确认GitLab上的包没问题，这一步可以快速核对下，避免后续发布出错）。

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