npm 安装超时,先判断问题到底出在哪一层
执行 npm install 时,如果终端长时间停在 idealTree、fetch 或 http fetch,最后出现 ETIMEDOUT、ECONNRESET、socket hang up,不一定代表 npm 本身损坏。更常见的情况是:浏览器已经通过 Clash 正常打开网页,但终端里的 Node.js 进程仍然直连注册表;或者 npm 使用的代理端口与 Clash 当前监听的端口并不一致。此时反复删除 node_modules、清理缓存,往往只能增加排查成本,并不能修复网络路径。
先把问题拆成三条链路来看:第一条是域名解析,npm 需要把注册表域名解析为可访问的地址;第二条是HTTPS 连接,Node.js 必须完成 TCP 连接、TLS 握手并收到服务端响应;第三条是包下载与完整性校验,包括元数据、压缩包和依赖树中的多个子请求。只要其中任意一层没有经过预期的 Clash 路径,就可能出现「网页能开、npm 不能装」的结果。
默认情况下,npm 常用的注册表是 https://registry.npmjs.org/,但项目、公司脚本或历史配置也可能把它改成镜像站。不同注册表的可达性、TLS 行为和同步速度并不相同。因此,排查时不要只盯着 npm 最后一行错误,而要先确认当前注册表、代理配置和 Clash 日志是否彼此对应。
先检查 Clash 端口、模式与 npm 配置
打开 Clash 客户端的设置或内核信息页,确认代理核心正在运行,并记下混合端口的实际数值。很多配置把 HTTP 和 SOCKS5 分成两个端口,也有配置只提供一个混合端口;不能直接套用网上常见的 7890 或 7891。如果端口已经被其它程序占用,Clash 可能显示已启动,但终端连接到的却不是它。
接着检查当前模式。为了观察规则是否正确命中,建议先使用规则模式,而不是长期打开全局模式。选择一个可用节点后,在内核日志中准备观察注册表域名的连接记录。若日志中完全没有 npm 请求,通常说明终端没有使用该端口,或 DNS/TUN 路径没有接管;若日志出现请求但命中 DIRECT,则需要检查规则顺序与目标域名。
在终端查看 npm 当前保存的关键配置:
npm config get registry
npm config get proxy
npm config get https-proxy
npm config list
正常排查时,registry 应该是你明确选择的地址;proxy 与 https-proxy 则不应残留已经失效的旧端口、旧客户端或公司代理地址。如果输出中出现多个层级的配置,不要只修改项目目录里的 .npmrc,还要检查用户目录和全局配置,因为 npm 会合并这些来源。
| 现象 | 优先检查项目 | 常见处理方向 |
|---|---|---|
| 浏览器正常,npm 超时 | 终端是否使用代理 | 设置 npm 代理或启用 TUN |
| 所有域名都连接失败 | Clash 核心与节点 | 更换节点、确认端口监听 |
| 只有某个项目失败 | 项目内 .npmrc | 检查 registry、proxy 与证书配置 |
| 下载到一半断开 | 长连接稳定性与 DNS | 查看日志、切换节点或解析策略 |
| 出现证书错误 | HTTPS 代理与拦截软件 | 移除错误代理,避免关闭 TLS 校验 |
确认端口后,可以为 npm 显式设置 HTTP 代理。下面的地址只是结构示例,端口必须替换成 Clash 实际显示的混合端口:
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm config set registry https://registry.npmjs.org/
设置完成后,用 npm config get 再读一次,确认没有拼写错误。这里的 https-proxy 值通常仍然写成 http://,因为客户端是通过 HTTP CONNECT 请求让代理转发 HTTPS,而不是表示注册表本身使用明文连接。若你的 Clash 只提供 SOCKS5 端口,应根据 npm 与 Node.js 版本的支持情况使用对应格式;不确定时,优先使用兼容性更好的混合 HTTP 端口。
动手验证:让日志、curl 与 npm 逐层对上
不要一开始就重新安装大型项目。先关闭正在运行的安装进程,清理终端中可能遗留的错误环境变量,然后打开 Clash 的内核日志。再用一个轻量请求验证注册表能否返回响应:
curl -I --max-time 15 https://registry.npmjs.org/
npm ping --registry=https://registry.npmjs.org/
如果 curl 直接超时,而 Clash 日志没有任何相关记录,说明请求没有进入 Clash;如果日志显示命中了某个策略组但仍然超时,应检查节点质量、规则目标和 DNS。若 curl 能返回状态码,npm ping 也成功,却只有具体项目安装失败,那么问题更可能出在项目锁文件、某个依赖的下载地址,或项目配置覆盖了全局 npm 设置。
为了确认终端是否真的继承了代理,可以在当前 Shell 临时设置环境变量。它们只影响当前会话,不会永久修改系统网络:
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="socks5://127.0.0.1:7890"
Windows PowerShell 可使用对应的环境变量写法:
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5://127.0.0.1:7890"
再次执行测试时,观察日志中是否出现新的连接。如果设置环境变量后立刻恢复,说明原先的 Node.js 进程没有读取系统代理;这不是 Clash 规则失效,而是应用代理语义不同。相反,如果环境变量和 npm 配置都已经正确,但日志里仍然出现直连,可能是当前终端运行在容器、远程 SSH 会话或虚拟机中,它们并不共享宿主机的网络命名空间。
随后再运行一次较小范围的安装,例如在测试目录中安装一个常见的小型包。确认能够获取元数据后,再回到真实项目执行:
npm cache verify
npm install --verbose
--verbose 会输出更多请求信息,便于确认究竟是注册表超时,还是某个依赖跳转到了其它主机。不要把 verbose 输出中的完整令牌、私有仓库地址或企业域名直接公开;排障记录应先做脱敏处理。
规则、DNS 与 TUN:解决「有代理但没接管」
npm 请求的目标不一定只有一个主机。基础元数据通常来自注册表,但包的 tarball 地址、私有依赖、Git 依赖以及安装脚本还可能访问代码托管平台或企业内部服务。只给一个域名配置规则,不能保证整棵依赖树都走同一条路径。更稳妥的做法是先从日志里记录真实主机名,再为必要的域名建立精确规则。
rules:
- DOMAIN,registry.npmjs.org,NPM
- DOMAIN-SUFFIX,npmjs.org,NPM
# Add actual tarball or Git hosts after checking the kernel log
# - DOMAIN-SUFFIX,github.com,NPM
- MATCH,DIRECT
上面的 NPM 只是示例策略组名称,必须替换成你配置文件中真实存在的组。规则要放在宽泛的直连、关键词或地理规则之前,因为 Clash 规则通常遵循从上到下、命中即停的顺序。若注册表规则写在 GEOIP,CN,DIRECT 后面,或者被更早的 DOMAIN-KEYWORD 吸收,后面的精确规则就不会生效。
DNS 也会影响结果。开启 fake-ip、远程解析或 nameserver-policy 后,终端看到的地址可能与系统直接解析的结果不同。排查时不要只用浏览器里的 DNS 结果下结论,应以 Clash 内核日志中的域名、解析结果和最终策略为准。若出现第一次超时、第二次成功,或者切换节点后表现完全不同,可以暂时使用更稳定的 DNS 策略验证,再决定是否恢复复杂的分流配置。
如果 npm、Git、Docker、IDE 终端等多个程序都不读取系统代理,逐个设置环境变量会很繁琐。这时可以评估启用TUN 模式,让更多未主动支持代理的进程通过虚拟网卡进入 Clash。启用前要确认驱动权限正常,并关闭可能产生冲突的 VPN、其它虚拟网卡或网络加速器。TUN 并不等于自动解决所有问题:规则仍然决定流量去向,局域网、公司内网和明确应该直连的地址也应保留合理的直连规则。
在 TUN 开启后,建议先执行一次 npm ping,再观察注册表请求是否进入预期策略组。如果开启 TUN 后出现循环连接、局域网不可用或系统网络整体变慢,应先关闭 TUN 恢复网络,再逐项检查 DNS 劫持、路由表和其它网络工具,而不是继续叠加配置。
常见残留配置与最终修复顺序
若此前使用过代理软件,npm 可能保留旧的代理地址。可以先查看配置来源,再按需删除错误项:
npm config delete proxy
npm config delete https-proxy
npm config set registry https://registry.npmjs.org/
删除后,若你依靠环境变量或 TUN 接管流量,就不必再给 npm 写死端口;若你希望 npm 只通过 Clash 的 HTTP 端口访问,则重新设置正确的代理值。两种方式不要在多个层级重复配置,否则将来切换客户端时很容易忘记旧端口仍在生效。
还要区分网络错误与 npm 应用层错误。ETIMEDOUT、ECONNRESET 更接近连接、代理或节点问题;EAI_AGAIN 常见于 DNS 临时失败;而 401、403、404、429 则已经收到服务端响应,需要检查令牌、权限、包名、限流或私有仓库配置。不要为了绕过证书问题而设置 strict-ssl=false,这会削弱 HTTPS 校验,应该优先修复错误的中间代理、系统证书或企业网络拦截。
一个稳定的复盘顺序可以固定为:先确认 Clash 核心、节点和混合端口;再读取 npm 的 registry 与代理配置;随后用 curl、npm ping 做最小连接测试;接着打开内核日志核对规则、DNS 和策略组;最后才启用 TUN 或调整项目级 .npmrc。每完成一步就重新测试,并记录「改了什么、日志如何变化、错误从哪一层变成哪一层」,这样即使问题再次出现,也能快速回到有效状态。
相比只提供简单开关的代理工具,Clash 在 npm 场景中的价值不只是「让网页打开」,而是能通过规则、策略组和内核日志解释注册表请求究竟走了哪里;有些工具对终端代理支持有限,换一个 Node.js 版本或 Git 依赖就可能重新超时。若你希望把系统代理、命令行环境变量和 TUN 接管方式统一管理,Clash 会让这套排查流程更可验证,也更容易保留国内源和局域网的直连路径。