npm install 慢/随机挂起/网络错误（ETIMEDOUT / ECONNRESET / hang forever）

症状

`npm install` 表现各异：

```

npm ERR! code ETIMEDOUT / ECONNRESET / fetch failed # 网络类报错

npm install 卡在某个包不动，CTRL+C 无效 # [npm/cli#4028](https://github.com/npm/cli/issues/4028)（226 comments）

npm install 很慢，但 curl 官方源却正常 # 慢在依赖解析/安全审计

```

特征：官方源 `registry.npmjs.org` 对国内网络时好时坏（CDN 节点波动）；

挂死场景 Windows 上尤其难杀（#4028 里进程杀不掉）；慢不一定在下载，可能在 audit。

同族但根因不同（别在本页死磕网络）：

- `EACCES` / `EPERM`（全局安装/缓存写入权限）→ 是权限问题不是网络问题，Permission denied 家族见 [脚本/文件权限](script-permission-denied.html)；

- `npm ping` 两源都正常但还是很慢 → 慢在 audit/解析环节，先关审计（`--no-audit --no-fund`）而不是换源。

原因

① 官方 registry 网络波动：国内访问 registry.npmjs.org 不稳定，下载/元数据请求超时重试；

② 安全审计拖慢：npm 默认装完 POST 到 `npm/v1/security/advisories/bulk` 做漏洞检查（[npm/cli#7383](https://github.com/npm/cli/issues/7383)，10 comments），

该请求在弱网下能把安装拖到几十秒；

③ 配置残留：~/.npmrc 里旧 registry / 代理设置冲突；

④ 挂死：底层 fetch 在弱网+重试组合下进入不可中断状态（#4028）。

解法

1. **先测再换源，别盲信教程**（网络每天都在变）：

`time npm ping --registry https://registry.npmjs.org` 与 `time npm ping --registry https://registry.npmmirror.com` 对比。

本机 2026-08-29 实测：ping 官方 1.7s / 镜像 0.8s，但装 typescript 官方 8.6s / 镜像 13.3s——

镜像不是永远更快，当前网络谁快用谁。

2. **换源**：一次性 `npm install --registry https://registry.npmmirror.com ...`；

持久化 `npm config set registry https://registry.npmmirror.com`（写入 ~/.npmrc），还原 `npm config set registry https://registry.npmjs.org`。

3. **慢先关 audit/fund**（低成本高收益）：`npm install --no-audit --no-fund`，或写入 ~/.npmrc 的 `audit=false fund=false`。

4. **调超时/重试**：`npm config set fetch-timeout 600000`、`fetch-retries 5`；

缓存问题先 `npm cache verify`，别上来就 `cache clean --force`（全量重下更慢）。

5. **挂死处理**：先确认是网络（`curl -I https://registry.npmjs.org` 计时）；

Windows 上 `taskkill /F /IM node.exe` 兜底；经常挂死考虑 pnpm/yarn（快速失败、缓存策略不同）。

6. **CI/项目级**：项目根放 `.npmrc` 配 registry 可随仓库走；CI 用 `--registry` 参数最明确。

7. **安全提醒**：~/.npmrc 常含登录 `_authToken`，贴日志/提 issue 前必须脱敏——本条目实测时就踩了这个坑（已脱敏）。

验证证据

- 本地实测（2026-08-29，WSL Ubuntu，node v22.22.1 / npm 9.2.0，校园网无代理）：

- 基线：`npm config get registry` = https://registry.npmjs.org/；

- ping 对比：官方 PONG 1483ms（总 1.7s）/ npmmirror PONG（总 0.8s）；

- 全量安装对比（隔离缓存，typescript，31MB node_modules）：官方源 8.6s / npmmirror 13.3s——当日镜像反而慢，实测否定「镜像必快」；

- 持久化：`npm config set registry https://registry.npmmirror.com` → `npm config get registry` 生效，~/.npmrc 出现 registry 行；验证后还原官方源；

- 事故记录：grep ~/.npmrc 时把 `_authToken` 带进了本地记录 → 立即脱敏为 `<REDACTED>`（教训见解法 7）。

- 实测复现日志（2026-08-29）