npm ERR! network 报错怎么解决？registry 换源与代理排查完全指南

现象：npm install 卡住或报网络错误

国内网络环境下的经典三连：

npm ERR! network request to https://registry.npmjs.org/xxx failed
npm ERR! network This is a problem related to network connectivity.
npm ERR! network ETIMEDOUT / ECONNRESET / ERR_SOCKET_CONNECTION_TIMEOUT

多数情况 npm 直连官方 registry（registry.npmjs.org，境外 CDN）速度慢或超时，偶尔还伴随 certificate 报错。解法按顺序试，大部分在第 1 步就解决。

第一步：切换到国内镜像源（解决 90% 的场景）

# 查看当前源
npm config get registry
# 切换到 npmmirror（原淘宝镜像）
npm config set registry https://registry.npmmirror.com
# 验证
npm config get registry
# https://registry.npmmirror.com

npmmirror 与官方源同步频率是分钟级，日常开发完全够用。改完直接重跑 npm install 验证。

临时用一次（不改全局配置，比如要发布包时）：

npm install --registry=https://registry.npmmirror.com

第二步：清缓存（换源后还报错时）

npm 的本地缓存可能存着失败的响应：

npm cache clean --force
npm cache verify        # 顺带校验
npm install

第三步：排查代理残留

如果你（或同事/某工具）曾配置过 HTTP 代理，换了网络环境后代理失效，npm 会继续往一个不通的代理发请求——症状和直连超时一模一样：

npm config list         # 看有没有 proxy / https-proxy / registry 异常
npm config delete proxy
npm config delete https-proxy
# 环境变量里的代理也会影响（HTTP_PROXY/HTTPS_PROXY/NO_PROXY）
env | grep -i proxy

常见踩坑：在公司配了代理回家忘了删、Clash/V2Ray 开了系统代理但 npm 不认系统代理（npm 只认自己的 config 和环境变量）。Clash 类工具的正确用法：开 TUN 模式（全局接管）或给 npm 配上本地代理端口（通常 proxy=http://127.0.0.1:7890）。

第四步：package-lock 陷阱

package-lock.json 里记录的是下载时用的源地址（resolved 字段）。如果 lock 文件是在别人机器上用不同源生成的，里面的 resolved 可能指向你访问不了的地址：

# 看一眼 lock 里的 resolved 指向
grep -m3 '"resolved"' package-lock.json
# 如果指向你有问题的源：删 lock 重装（注意会升级依赖版本，团队项目需重新提交 lock）
rm package-lock.json node_modules -rf
npm install

团队协作注意：lock 文件要提交进 git；换源决策应该是团队统一的（或用 .npmrc 提交进仓库——见下文）。

长期方案：项目级 .npmrc

在项目根目录放一个 .npmrc，提交进 git，团队成员克隆后自动使用同一源：

registry=https://registry.npmmirror.com

提交前想想：如果团队要往 npm 发布包，发布时需要临时 --registry=https://registry.npmjs.org（npmmirror 是只读镜像）。

高频追问

yarn / pnpm 也慢，同样换源吗？

是，各自的配置体系：

yarn config set registry https://registry.npmmirror.com
pnpm config set registry https://registry.npmmirror.com

pnpm 还支持读取项目 .npmrc（与 npm 共享）。

换源后某些包还是从官方源下载？

部分包的 resolved 指向 GitHub Releases 或包自带的下载地址（如 puppeteer 的 Chromium、sharp 的预编译二进制）——这些不走 registry。针对性解法：设置对应的环境变量镜像（如 PUPPETEER_DOWNLOAD_BASE_URL）或安装时跳过（PUPPETEER_SKIP_DOWNLOAD=true）。

npmmirror 会丢包或版本不全吗？

不会。它是官方 registry 的同步镜像（分钟级同步），版本完整性有保证。极少数刚发布的包有分钟级延迟。

怎么判断是 npm 的问题还是我网络的问题？

curl -I https://registry.npmmirror.com   # 200 = 镜像可达
curl -I https://registry.npmjs.org       # 看官方源是否可达

镜像可达而官方不可达 → 换源即可；两者都不可达 → 检查本机网络/DNS/防火墙。

本文由 ToolVault 工具匣 提供。部署与命令行相关工具：Linux 命令速查、Dockerfile 生成器、HTTP 状态码速查。访问 首页 查看更多开发者工具。