npm与yarn在WiFi环境下无限卡顿于包解析阶段的问题排查求助

问题现象 #

连接朋友家WiFi后，网页浏览、音乐播放等网络功能正常，但npm/yarn安装依赖时出现卡顿：

• 执行npm i lodash，永久卡在idealTree:test: sill idealTree buildDeps阶段
• 执行yarn add lodash，卡在[1/4] Resolving packages... ⠠ lodash阶段

已排除的问题：

• 连接手机热点可正常完成依赖安装，排除本地防火墙干扰
• 朋友的Windows电脑在同一网络下执行相同命令无异常，排除路由器防火墙限制

操作步骤：

mkdir test
cd test
npm init -y

附npm带计时参数的运行日志：

$ npm i lodash --timing
npm timing npm:load:whichnode Completed in 0ms
npm timing config:load:defaults Completed in 1ms
npm timing config:load:file:$HOME/.nvm/versions/node/v18.16.1/lib/node_modules/npm/npmrc Completed in 0ms
npm timing config:load:builtin Completed in 1ms
npm timing config:load:cli Completed in 0ms
npm timing config:load:env Completed in 0ms
npm timing config:load:file:/tmp/test/.npmrc Completed in 0ms
npm timing config:load:project Completed in 0ms
npm timing config:load:file:$HOME/.npmrc Completed in 1ms
npm timing config:load:user Completed in 1ms
npm timing config:load:file:$HOME/.nvm/versions/node/v18.16.1/etc/npmrc Completed in 1ms
npm timing config:load:global Completed in 1ms
npm timing config:load:setEnvs Completed in 0ms
npm timing config:load Completed in 5ms
npm timing npm:load:configload Completed in 5ms
npm timing npm:load:mkdirpcache Completed in 0ms
npm timing npm:load:mkdirplogs Completed in 1ms
npm timing npm:load:setTitle Completed in 0ms
npm timing config:load:flatten Completed in 1ms
npm timing npm:load:display Completed in 2ms
npm timing npm:load:logFile Completed in 2ms
npm timing npm:load:timers Completed in 1ms
npm timing npm:load:configScope Completed in 0ms
npm timing npm:load Completed in 11ms
npm timing arborist:ctor Completed in 1ms
npm timing idealTree:init Completed in 6ms
npm timing idealTree:userRequests Completed in 2ms

可能原因及调试步骤 #

1. 切换npm/yarn镜像源 #

默认registry在当前网络下可能存在解析或访问延迟：

• 查看当前npm源：npm config get registry
• 切换到官方源：npm config set registry https://registry.npmjs.org/
• 若仍有问题，可尝试当地常用镜像源（如欧洲节点https://registry.npmjs.eu/）
• Yarn操作同理：yarn config get registry、yarn config set registry https://registry.npmjs.org/

2. 重置DNS设置 #

当前WiFi的DNS可能无法正常解析npm registry域名：

• 手动将DNS改为公共服务，如Google的8.8.8.8/8.8.4.4或Cloudflare的1.1.1.1
• 修改后重启网络连接，再尝试安装依赖

3. 临时禁用IPv6 #

部分网络环境下IPv6解析异常会导致npm卡住：

• Linux系统临时禁用：sudo sysctl -w net.ipv6.conf.all.disable_ipv6=1
• macOS系统临时禁用：通过「系统设置-网络-高级-TCP/IP」关闭IPv6
• 测试安装正常后，再考虑是否永久调整IPv6设置

4. 清理残留代理设置 #

若之前配置过代理未清空，可能干扰网络请求：

• 查看npm代理：npm config get proxy、npm config get https-proxy
• 清空代理：npm config delete proxy、npm config delete https-proxy
• Yarn代理清理：yarn config delete proxy、yarn config delete https-proxy

5. 清除npm缓存并重试 #

缓存损坏可能导致安装流程异常：

• 强制清除缓存：npm cache clean --force
• 删除项目下的node_modules和package-lock.json文件
• 重新执行npm i lodash

6. 测试registry网络连通性 #

直接用curl验证registry访问是否正常，排查网络层面问题：

curl -v https://registry.npmjs.org/lodash

若返回正常JSON数据，说明网络无问题，需排查npm自身配置；若请求超时或失败，说明当前网络对registry存在访问限制。

内容的提问来源于stack exchange，提问作者Gabriel Furstenheim