npm install卡住

执行 npm install 长时间没有进度，通常与网络、代理、缓存、依赖解析或 Node.js/npm 版本有关。不要连续重复执行安装命令，应先通过详细日志确认卡在哪个阶段。

1. 打开详细日志

npm install --verbose

如果日志停留在下面的位置：

npm timing idealTree:userRequests Completed in 0ms

这只表示 npm 正在解析依赖树，真正原因还需要结合它前后的网络请求和报错判断。

也可以查看 npm 当前环境：

node -v
npm -v
npm config get registry
npm config get proxy
npm config get https-proxy

2. 检查 registry 是否可访问

先测试当前仓库：

npm ping

npm 官方 registry 为：

npm config set registry https://registry.npmjs.org/

网络访问官方源较慢时，也可以临时使用镜像：

npm config set registry https://registry.npmmirror.com/

安装完成后，可根据部署环境切回官方源。团队项目不建议随意提交个人网络环境相关的 registry 配置。

3. 检查错误的代理配置

曾经配置过代理，但代理服务已经关闭，也会导致安装一直等待：

npm config delete proxy
npm config delete https-proxy

如果公司网络必须经过代理，应填写实际可用的代理地址，而不是直接删除。

4. 验证 npm 缓存

优先使用缓存验证：

npm cache verify

只有确认缓存损坏时才强制清理：

npm cache clean --force

清理缓存会使后续依赖重新下载，因此不应作为第一步操作。

5. 根据锁文件重新安装

项目存在 package-lock.json 时，CI 或需要可重复安装的场景建议使用：

npm ci

如果怀疑 node_modules 状态异常，可以先移走或删除该目录，再执行 npm ci。不要随意删除 package-lock.json，否则可能引入不同版本的间接依赖。

6. 检查依赖和运行时版本

查看过期依赖：

npm outdated

如果项目较旧，应确认它支持当前 Node.js 版本。原生模块还可能依赖 Python、编译器或系统开发包，详细错误通常会出现在 verbose 日志末尾。

快速排查顺序

1. 使用 npm install --verbose 确认卡住位置。
2. 执行 npm ping 检查 registry。
3. 检查并修正代理配置。
4. 执行 npm cache verify。
5. 有锁文件时尝试 npm ci。
6. 核对 Node.js、npm 与项目依赖的兼容性。