《拿下奇怪的前端报错》：npm install卡住了一个钟- 从原理搞定安装的全链路问题

 相信前端的小伙伴稍微入行一段时间的，接触过不同的项目，就可能遇到过npm install卡住的情况，下面我就来分析下几种场景、定位的方法和解决办法。不再只是删除node_modules然后重来了，虽然它能解决80%的问题

1  npm install 的原理

1.1 读取 package.json 文件

读取项目根目录下的 package.json 文件，确认当前项目所依赖的模块及其版本。

1.2 解析依赖关系

基于依赖的版本信息解析出需要安装的具体版本，并处理依赖之间的版本冲突等问题，最终生成一个依赖树。

                 **注意如果有lock文件，会按照lock文件来

1.3. 下载模块

   根据解析的依赖树，npm 会从注册源头载所需的模块包。

                ** 如果本地缓存有，会读取本机的缓存

1.4. 安装模块

下载的模块会解压到 node_modules 目录下，并会处理依赖树中每个模块的依赖，确保每个模块都有其所需的依赖项。

1.5. 生成或更新 package-lock.json

安装完成后，npm 会更新或生成 package-lock.json 文件，以确保以后可以确定性地安装相同版本的依赖。

1.6. 执行生命周期钩子

有些包会在安装过程中触发钩子（如 preinstall, postinstall），执行额外的任务。

 从上面六个步骤就可以看到一些问题了，首先1很难会卡住但可能格式不对会报错，4,5也很难卡住但可能因为权限问题无法写入。于是可以从 2 3 6 来分析了

2  可能原因和解决办法

2.1 网络问题

问题描述： npm install 的过程中，需要从 npm 官方仓库或代理服务器上下载依赖包。如果网络不通畅，下载速度过慢，或者请求超时，可能会导致安装过程卡住，甚至失败。解决方法： 切换 npm 源，使用国内镜像源，如淘宝镜像：

# 注意啦，天大的事情啦！！淘宝源2023年底就换新域名啦！npm config set registry https://registry.npmmirror.com

使用代理工具如 VPN 来加速访问 npm 官方服务器。如果使用 yarn 作为包管理工具，yarn 在处理依赖时的缓存机制和下载速度有时会比 npm 快。

2.2 Node.js 版本不兼容

问题描述： 有些依赖包可能只支持某些特定版本的 Node.js 或 npm。如果当前使用的 Node.js 版本与依赖包要求的版本不兼容，可能会导致安装卡住或出错。解决方法： 切换到适配的 Node.js 版本。可以使用工具如 nvm (Node Version Manager) 来管理多个 Node.js 版本：

nvm install <version> nvm use <version>

需要注意的是，切换 Node.js 版本后，可能会有旧版本的依赖缓存残留在本地，建议清理缓存：

npm cache clean --force

2.3 缓存问题（最高概率）

问题描述： npm 有缓存机制，会将已经下载的依赖包存储在本地，以便以后再次安装时加快速度。但是，某些情况下（如版本切换、依赖包损坏），本地缓存可能会引起安装卡住或依赖冲突。解决方法： 清理 npm 缓存：

npm cache clean --force

如果怀疑是由于残留的 node_modules 目录导致问题，可以尝试删除 node_modules 并重新安装依赖：

# 我猜，这是大家做的最多，或者第一反应的办法rm -rf node_modules npm install

2.4 权限问题 

问题描述： 有时候，npm 可能因为权限不足而无法正常安装依赖包，特别是在全局安装 (-g) 时，容易遇到这种情况。解决方法： 避免使用 sudo npm install，这可能会导致文件权限混乱。可以通过更改 npm 的全局安装路径，避免使用全局权限安装：

npm config set prefix /user-path

或者使用 nvm 这样的工具，它会将 Node.js 和 npm 环境放在用户目录下，避免权限问题。

2.5 包冲突或依赖解析问题

问题描述： 当不同的依赖包需要的依赖项版本不兼容时，npm 可能会卡在解析依赖关系上。特别是在复杂的项目中，有大量依赖时，这种情况更容易发生。解决方法： 检查是否存在冲突依赖，手动修改 package.json 中的版本号，使其兼容。使用 npm ls 命令查看依赖树，确认是否有版本冲突或循环依赖。

这里尤其容易出现在存在lock文件的时候，或者存在多个lock文件的时候：

我曾经遇到过某个版本的某个包、在代理源那里没有！！！

2.6 过时的 npm 版本

问题描述： 较老版本的 npm 可能存在一些已知的性能问题或 bug，这可能会导致安装时出现卡顿现象。解决方法： 更新 npm 到最新版本：

npm install -g npm

2.7 系统资源不足 

问题描述： 当系统内存不足或者 CPU 资源紧张时，npm install 可能会卡住甚至崩溃。解决方法： 关闭不必要的后台程序，释放系统资源。可以尝试通过 Docker 或虚拟机等方式在隔离的环境中执行安装，避免系统资源冲突。

2.8 脚本问题

问题描述： 安装没开始或者一直不结束解决方法： 由于安装时会在之前调用preinstall，在之后调用postinstall脚本，移除掉脚本再看情况确保脚本能够及时退出进程而不至于挂起

在上述的情况中，silly idealTree buildDeps 和 卡住不动大概率就是网络和缓存问题，也在nodejs版本不对遇到过-但也是由于缓存原因引起的~这时候建议切换版本 **不然lock文件会有个超大的更新**

3 其它场景的处理

3.1 开启全部日志

npm install --verbose

3.2 使用替代工具

例如yarn或者pnpm，在本地开发时很不错，但因为要安装额外的工具，不建议生产用，毕竟多一个环节多一个出错概率

3.3 使用docker来提供node环境(***)

这是我比较推荐的啦~大家都不用装依赖了，每次来新员工，给他装好docker丢个镜像，然后把源码映射进去就可以了。

至于如何构建，可参考《拿下奇怪的前端报错》：nvm不可用报错`GLIBC_2.27‘‘GLIBCXX_3.4.20‘not Found？+ 使用docker构建多个前端项目实践-CSDN博客

我就是那样搭建了一个多项目-新老混合的jenkins流水线的啦~

最后祝大家写代码不卡壳，不然我也帮不到了。看完记得眺望远方休息下嘞

2cy

YU.H