npm 与 pnpm 拉包超时:Clash 分流 npmjs(2026)
症状:不是 npm 坏了,而是一次安装被拆成了好几条路
在终端里跑 npm install 或 pnpm install,进度一直停在解析依赖、拉包清单,或者下载某个版本的 tarball;报错里可能有 ETIMEDOUT、ECONNRESET、TLS 握手卡住,或者什么错都不报,就是一直在重试。这时候要是简单归结为官方 registry 挂了、Node.js 版本不对,常常会漏掉更常见的真正原因:一次完整的安装会向很多不同的主机名发起 HTTPS 请求,这些请求在你的 Clash 规则里可能被不同的规则接走——有的走了代理,有的被 GEOIP 或范围很宽的关键字送回了直连,还有的因为自动选择中途换了节点,把一个大文件的下载切断了。浏览器能打开 npm 的网页,不代表命令行里的每个子请求都进了你以为的那个组;这和本站 Git 与 curl 的环境变量教程里讲的终端出口要一致是同一类问题,只是 npm 和 pnpm 发请求更频繁,主机名也更零散。
另一种常见的误会是只换了 registry 镜像地址:.npmrc 指向国内镜像后,元数据大多下载得挺顺,可 lockfile、旧缓存,或者镜像还没同步上游,都可能让个别 tarball 的地址又指回 registry.npmjs.org 或者它的 CDN 主机;这些主机要是没被同一个策略稳稳接住,就会出现绝大多数包秒装、偏偏一两个包怎么都装不上的情况。这里有意把npm registry 超时放回能看得见的多域名请求里讲:先靠日志弄清到底是哪一个在超时,再在 Clash 里针对 npmjs Clash 做分流和固定节点,而不是一味地加镜像源,或者把全局代理开了关、关了开。
能从日志里找出失败那一刻具体是哪个主机名;能说清 YAML 里 NPMJS 策略组排在 GEOIP/MATCH 前面还是后面;能让终端的 HTTPS_PROXY 和规则命中落到同一个入口——不管你是不是刚接触 Node.js 开发者 代理,这都是能反复照做的基本要求。
registry、元数据和 tarball:npm 和 pnpm 走的是同一套 HTTPS 流程
不管用的是官方 registry.npmjs.org 还是公司自建的私服,客户端的流程基本都是:先拿到包的版本列表和完整性哈希,再照解析出来的地址去下载 tarball。pnpm 会在按内容寻址的 store 里用硬链接复用文件,并发下载时日志也更乱,但要连哪些主机,仍然是 registry 返回的地址说了算,不会因为你用的是 pnpm 就对网络波动免疫。公司里如果还用 npm.pkg.github.com 这样的地址,那是另一个按域名分流的组,可以和 NPMJS 并排命名,但别用范围过宽的 DOMAIN-KEYWORD 把不相干的流量也扫进来。
调试时可以临时打开详细日志,比如 npm install --verbose,pnpm 也有对应的 verbose 选项,把每次 HTTPS 请求的 host 和 Clash 连接日志里的命中规则一一对上。你会发现:有时卡在解析 shrinkwrap 的阶段,有时卡在某个特别大的 tarball 下到一半——背后连的主机不一定一样。如果你只给 registry 主域名配了代理,tarball 却放在另一个后缀下、又被直连规则先匹配上,就会出现时有时无的 npm registry 超时:registry 明明 ping 得通,真正慢的是对象存储或 CDN 那个前缀。
为什么开着 Clash,npm registry 还是会超时
国内开发者常用的基础规则,会把目的地在国内的直连写在靠前的位置来省流量,浏览网页时这很合理;可 npm 解析出来的一部分主机名,在境外解析,或者跨境线路质量不稳,如果被本地的 GEOIP-CN、范围很宽的 IP 规则,或者订阅里下发的一大段直连规则先拿走,就会变成一半直连一半代理。再加上 npm 默认会同时发很多请求,看上去像偶尔出错,实际上是并发请求各走了不同的路。想让 pnpm 代理和 npm 一样稳,就得把日志里看到的 npmjs 那一串后缀单独放进一个专用策略组,并把对应的 DOMAIN-SUFFIX 或精确的 DOMAIN 规则放在所有宽泛兜底规则的前面——这和 国内直连与国外代理那篇教程讲的思路一样:具体的放前面,宽泛的放后面。
第二大干扰是检测间隔很短的 url-test:延迟数字是好看了,但大文件长时间下载需要一直保持同一个 TLS 会话的出口,它恰恰做不到。订阅如果不停地把 NPMJS 这一组流量在两条线之间来回切,在 TCP 层面看就是断开再重连,到了 npm 那边就成了卡住或者老是超时。所以这里说的固定节点,是一种验证办法和稳定的基准,不是叫你永远放弃备用线路——先锁定一个确认能用的出口,等症状缓解,再考虑把自动切换调得更保守一些。
Clash 配置框架:NPMJS 组加上排在最前的后缀规则
下面的 YAML 只是方便看懂的框架;实际要加哪些后缀,以你日志里出现过的 hostname 为准,范围太宽的关键字匹配要慎用,免得误伤。
proxy-groups:
- name: NPMJS
type: select
proxies:
- NODE-STABLE-1
- NODE-STABLE-2
- DIRECT
rules:
- DOMAIN-SUFFIX,npmjs.org,NPMJS
# Add only hosts you confirm via logs, e.g. tarball CDN:
# - DOMAIN-SUFFIX,example-cdn.npm.region,NPMJS
# MUST appear BEFORE broad CN / catch-all rules:
# - GEOIP,CN,DIRECT
# - MATCH,PROXY
如果上游订阅会把你手写的 rules 覆盖掉,就用 覆写与 prepend-rules,把置顶的那几行钉在每次刷新后都还在的位置;合并完一定打开 连接日志和规则匹配排查那篇对照着检查策略组名字是不是一字不差——很多写了规则却不生效的情况,原因就是指向了一个不存在的 proxy-group,或者大小写不一致。
终端这边:HTTPS_PROXY 和 npmrc 要指向同一个 Clash 入口
托盘上显示已代理,并不保证 Node 进程用的是同一个端口:npm 和 pnpm 读 HTTPS_PROXY/HTTP_PROXY 的方式和大多数命令行工具一样,但你的 shell 配置文件、IDE 内置终端、CI 容器可能各有各的环境变量。请在实际执行安装命令的那个会话里明确设置,比如指向本机的 mixed 端口(示例):
export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
npm install
想永久写进配置,可以用 npm config set proxy ... 和 npm config set https-proxy ...;pnpm 也有对应的字段,具体键名以最新文档为准。Windows 上更完整的做法可以看前面提到的 Git/curl 环境变量专篇;如果 Node 跑在 WSL 里、Clash 装在 Windows 主机上,路由和 IP 的写法请看 WSL2 与宿主代理,把网关地址对上,别照抄 macOS 的例子。在 Docker build 里装 npm 包又是另一条路,要参考 Docker 守护进程显式代理,别把这三种情况混成同一组 export。
什么时候开 TUN 就够了,什么时候还得写细规则
TUN 模式能把很多程序一起接管进内核的路由,少了很多某个终端漏了代理的琐碎设置;但在 fake-ip、公司 VPN 或者好几块虚拟网卡同时存在时,还是可能漏掉个别 HTTPS 请求,或者DNS 那边看到的不一致。npm 这种大量短连接再夹着大文件的负载,建议把 npmjs Clash 规则写得清楚、好检查:TUN 负责兜住漏网的,排在前面的 DOMAIN 规则负责说清楚意图——以后同事接手维护 subscription 时,不至于只能靠全局好像能装上来碰运气。
和国内镜像一起用时的分工
用 npmmirror 这类镜像能大大减少跨境下载的数据量,但它代替不了 Clash 分流:镜像的同步节奏、缓存没有时回源、旧 lockfile 里写死的地址,都可能把请求送回官方的主机名下面。比较合理的分工是镜像负责尽量命中缓存,Clash 负责日志里出现过的所有 npmjs 主机都走同一个出口;镜像域名在国内本来就稳的话,可以在 rules 里让它们留在直连组,免得绕两层,不过要以你自己用下来的情况为准,别照搬网上那种超长的域名表。
最简单的验证顺序(建议直接照着做)
- 缩小测试范围:找一个依赖不复杂的小项目反复安装,别一上来就拿巨大的 monorepo 测,容易误判。
- 打开 verbose,把失败前后那段日志里的主机名截出来,和 Clash 日志对着看。
- 新建一个 NPMJS(名字随便起)策略组,先手动锁定一个节点;在日志里确认整个安装过程命中的都是这个组。
- 置顶规则确认起作用之后,才去把镜像地址改回来,或者改并行下载数(线路一抖,pnpm 的高并发会让失败成倍增加)。
- 设了 HTTPS_PROXY 还是不走代理,就查一下是不是 NO_PROXY 把它排除了;内网 registry 和国内镜像域名按需要放行。
- 症状没了或者明显好转后,多观察一段时间,再考虑要不要放开固定节点。
常见问题
公司会解密 HTTPS 的话,还要注意什么?
公司网关如果把出去的 TLS 拆开检查,Node 就要额外信任一张 CA;这和 Clash 分流是两回事——先确认不是证书报错造成的握手卡死,再从策略角度讨论 npm registry 超时,不然 YAML 会改个没完。
CI 里能不能用同一套 NPMJS 规则?
可以,不过 CI 的构建机一般用不了你自己电脑上开的代理端口;比较常见的是在 Runner 的网络出口,或者自建的缓存代理那里统一处理出站,而不是假定每台临时机器都装着同一款图形客户端。思路还是一样:主机名清单对齐,出口保持一致。
Yarn / Bun 是否同理?
现在主流的 JS 包管理器抓包的方式都差不多:只要能从日志里列出主机名,就可以把对应的后缀并进 NPMJS,或者另开一个并列的组;别图省事全塞进一个范围很大的关键字组里。
请遵守所在地的法律法规和单位的网络出口管理规定;这里只是在你本来就有权访问 registry 的前提下,讨论怎么用 Clash 处理 npm registry 超时和 pnpm 代理相关的本地路由和会话稳定问题,不涉及任何绕过授权或攻击性的做法。
小结:把 npmjs 当成一组主机来分流
想换一款仍在维护的客户端,可以去下载页按平台挑选,安装包取自各客户端的官方 GitHub 发布页,页面上附了 SHA256。