报错现象
npm install（或 npm ci）失败时，终端通常会在结尾吐出几行 npm ERR!。不同原因对应的原文差别很大，先对号入座：
网络类：
```
npm ERR! code ECONNRESET
npm ERR! network request to https://registry.npmjs.org/xxx failed
npm ERR! code ETIMEDOUT
npm ERR! code ENOTFOUND
```
缓存与锁文件类：
```
npm ERR! code EINTEGRITY
npm ERR! sha512-xxxx integrity checksum failed
npm ERR! Unexpected end of JSON input while parsing near '...'
npm ERR! Cannot read properties of null (reading 'pickAlgorithm')
```
权限类：
```
npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /usr/local/lib/node_modules/xxx
npm ERR! errno -13
```
原生模块编译类：
```
gyp ERR! find Python
gyp ERR! stack Error: Could not find any Visual Studio installation to use
make: g++: Command not found
node-pre-gyp ERR! build error
```
版本类：
```
npm WARN EBADENGINE Unsupported engine { package: 'xxx',
required: { node: '>=XX' }, current: { node: 'vXX.x' } }
```
出现场景：本地新装依赖、拉取别人仓库后首次 npm install、CI 流水线构建、Docker 镜像构建。影响范围从"某台机器装不上"到"整个团队 CI 红一片"都有。间歇性成功（重试几次又能装）通常指向网络或镜像源，稳定失败通常指向版本、编译环境、权限、缓存。
可能原因
按实际遇到的比例从高到低：
1. 网络不通，或代理/VPN 配置缺失、被公司网关拦截
2. 镜像源配置错误、源不可达、私有源证书或 token 有问题
3. Node 与 npm 版本不匹配，或一台机器上装了多套 Node
4. 原生模块（C/C++ 扩展）缺少编译环境
5. 文件权限与属主问题，多由历史上用过 sudo npm install 造成
6. 本地 npm 缓存损坏，或 package-lock.json 与 package.json 不同步
逐条排查与解决
1. 网络问题
先判断是"完全出不去"还是"只有 npm 出不去"：
```bash
npm ping
curl -I https://registry.npmjs.org/
npm config get proxy
npm config get https-proxy
env | grep -i proxy
```
判断方法：curl 能返回 HTTP 状态码但 npm ping 失败，基本是 npm 没走代理；两者都失败，是出口网络或 DNS 问题。
配置代理（端口换成你自己代理的端口）：
```bash
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
```
也可以走环境变量，很多工具都认：
```bash
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
```
取消代理配置：
```bash
npm config delete proxy
npm config delete https-proxy
```
弱网环境把重试和超时调大：
```bash
npm config set fetch-retries 5
npm config set fetch-timeout 120000
```
DNS 异常时用 nslookup registry.npmjs.org 看解析结果，必要时换 DNS。
2. 镜像源问题
先看当前用的到底是哪个源：
```bash
npm config get registry
cat ~/.npmrc
cat ./.npmrc
npm config get globalconfig
```
npm 的配置优先级是：项目级 .npmrc > 用户级 ~/.npmrc > 全局 npmrc > npm 内置默认值。所以"我明明改过源"却仍报错时，八成是项目里有个 .npmrc 覆盖了。
临时指定源安装，不改全局配置：
```bash
npm install --registry=https://registry.npmmirror.com
```
常见镜像源地址以各家官方页面为准。
判断方法：报 404 Not Found - GET https://... 说明这个源里没有该包或同步延迟，换回官方源试；报 SELF_SIGNED_CERT_IN_CHAIN 是私有源用了自签证书。
私有源正确做法是把 CA 证书挂上，而不是关校验：
```bash
npm config set cafile /path/to/ca.pem
```
临时应急可以关校验，但用完记得恢复：
```bash
npm config set strict-ssl false
排查完恢复
npm config delete strict-ssl
```
私有源要鉴权时，在项目 .npmrc 里写：
```
//registry.example.com/:_authAI 词典：Token">Token=${NPM_TOKEN}
```
token 通过环境变量注入，不要明文提交到仓库。
3. Node / npm 版本问题
```bash
node -v
npm -v
which -a node
npm config get engine-strict
```
which -a node 列出多个路径，说明机器上装了多套 Node，PATH 顺序会导致"昨天还好今天就不行"。
EBADENGINE 默认只是警告，只有把 engine-strict 设为 true 才会中断安装。要复现和关闭：
```bash
npm config get engine-strict
npm config set engine-strict false
```
如果报错提到 lockfile 版本无法解析，通常是 npm 版本偏旧解析不了新版锁文件，升级 npm：
```bash
npm install -g npm@latest
```
更稳的做法是用版本管理器（nvm、fnm、volta 等）切到 LTS，并在项目里放 .nvmrc：
```bash
nvm install --lts
nvm use
```
具体支持矩阵以 Node 与 npm 官方文档当前版本为准。
4. 原生模块编译失败
带 C/C++ 扩展的包（图像、数据库驱动、加密相关比较常见）需要本机编译环境。
```bash
node -p "process.versions.modules"
node -p "process.platform + ' ' + process.arch"
npm config get python
python3 --version
which make g++ cc
```
process.versions.modules 是 ABI 版本，Node 大版本变了它就会变，缓存的二进制对不上时也会报错。
按系统补依赖：
```bash
Debian / Ubuntu
sudo apt-get update && sudo apt-get install -y build-essential python3
RHEL / CentOS 系
sudo yum groupinstall -y "Development Tools"
sudo yum install -y python3
macOS
xcode-select --install
Alpine（容器里常见）
apk add --no-cache python3 make g++
```
Windows 上需要 Visual Studio Build Tools 的 C++ 生成工具加 Python，并告诉 npm 用哪个版本：
```bash
npm config set msvs_version <你的VS版本>
```
版本对应关系以官方文档当前版本为准。
指定 Python 解释器：
```bash
npm config set python /usr/bin/python3
```
重编译已安装的模块：
```bash
npm rebuild
```
绕开预编译二进制、强制从源码编译：
```bash
npm install <包名> --build-from-source
```
有些包会去 GitHub Releases 下载预编译产物，这条路不走 npm 的 proxy 配置。如果日志里出现下载超时，给这些工具也配上网代理环境变量，或直接走源码编译。
想确认是不是编译脚本导致的失败：
```bash
npm install --ignore-scripts
```
能装完就是编译或安装脚本的问题。注意这种方式装出来的包部分功能不可用，只用于定位。
5. 权限问题
```bash
ls -ld node_modules
whoami
npm config get prefix
ls -ld "$(npm config get prefix)/lib/node_modules"
```
看到 EACCES 且路径是 /usr/local/lib/node_modules，说明全局目录归 root 所有，通常是以前用 sudo npm install -g 留下的坑。
不要继续用 sudo npm install 压过去，那只会让属主问题扩散到项目里。
修复 npm 缓存目录属主：
```bash
sudo chown -R "$(whoami)" ~/.npm
```
把全局安装目录改到用户目录：
```bash
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
```
项目里 node_modules 被 root 改过属主：
```bash
sudo chown -R "$(whoami)" node_modules
```
Windows 上常见 EPERM、EBUSY，多半是杀毒软件实时扫描或编辑器占用了 node_modules，关掉相关进程再装。
6. 缓存与锁文件问题
EINTEGRITY、Unexpected end of JSON input、pickAlgorithm 这类报错基本指向缓存内容和锁文件对不上。
```bash
npm cache verify
npm config get cache
```
彻底重建（先确认 package-lock.json 已提交或已备份）：
```bash
rm -rf node_modules
rm -f package-lock.json
npm cache clean --force
npm install
```
CI 环境应当用 npm ci，它要求锁文件和 package.json 严格一致：
```bash
npm ci
```
如果 npm ci 报锁文件不同步，先在本地 npm install 生成新的 package-lock.json 并提交。
都不管用时的兜底方案
打开详细日志，定位到底卡在哪个包：
```bash
npm install --loglevel verbose > npm-debug.log 2>&1
tail -n 100 npm-debug.log
```
在日志里搜 http fetch 和 error，能看到具体请求的包名和 URL。
单独装可疑包，缩小范围：
```bash
npm install <包名> --no-save --loglevel verbose
```
跑一次环境体检：
```bash
npm doctor
```
换干净目录做最小复现，排除当前项目配置干扰：
```bash
mkdir /tmp/npm-test && cd /tmp/npm-test
npm init -y
npm install <包名>
```
换网络（比如手机热点）、换 Node LTS 版本再试一次。
用容器复现，排除本机环境污染，镜像 tag 以官方文档当前版本为准：
```bash
docker run --rm -it -v "$PWD":/w -w /w node:lts bash
```
用另一个包管理器交叉验证，判断是包本身的问题还是 npm 环境的问题：
```bash
pnpm install
```
注意不同包管理器的锁文件不通用，只用于判断，不要混用。
确认是包自身缺陷后，到该包仓库提 issue，附上 node -v、npm -v、操作系统、完整日志和最小复现步骤。
如何预防再次发生
- 把
package-lock.json提交进仓库，CI 一律用npm ci而不是npm install - 用
.nvmrc、engines字段或版本管理器固定 Node 版本，Dockerfile 里固定基础镜像，具体 tag 以官方文档为准 - 项目根目录放
.npmrc统一 registry，团队配置一致；token 用环境变量占位，禁止提交明文 - 私有源用
cafile挂证书，不要长期关掉strict-ssl - 全局包统一装在用户目录，不用
sudo npm install - CI 缓存 key 带上锁文件哈希，锁文件变了自动重建缓存
- 给
fetch-retries、fetch-timeout设合理值，弱网和跨境网络下更稳 - 定期
npm cache verify，Node 大版本升级后重装node_modules - 把本文的排查顺序写进团队文档，新人遇到报错按序执行，少走弯路