登录/ 注册
 找回密码
 立即注册
关闭

CSDN热搜

程序园 精品问答 技术交流 资源下载
返回列表 发新帖
首页 › 业界区 › 安全 ›强制 pnpm 使用 IPv4 而不是 IPv6 的终极解决方案指南 ...

强制 pnpm 使用 IPv4 而不是 IPv6 的终极解决方案指南

扈季雅 2025-8-14 09:06:36
强制 pnpm 使用 IPv4 而不是 IPv6 的终极解决方案指南

一、问题背景与影响

1.1 为什么会出现 IPv6 问题？

随着 IPv6 的普及，许多域名（如 mirrors.cloud.tencent.com）会同时返回 IPv4（如 101.89.19.12） 和 IPv6（如 240e:95e:4001:1:38::11） 地址。当你的网络环境 不支持 IPv6 或 IPv6 连接不稳定 时，pnpm 默认优先尝试 IPv6 连接会导致以下问题：

  • 安装超时：pnpm install 卡在 Fetch Metadata 或 Downloading 阶段。
  • 错误提示：如 connect ETIMEDOUT、getaddrinfo ENOTFOUND 等。
  • 日志分析：通过 pnpm install --loglevel debug 可看到连接尝试的是 IPv6 地址。
1.2 如何验证 IPv6 问题？

运行以下命令测试：
  1. # 测试 IPv6 连接（可能超时）
  2. ping mirrors.cloud.tencent.com
  4. # 强制使用 IPv4（应正常响应）
  5. ping -4 mirrors.cloud.tencent.com
  7. # 查询域名的 DNS 解析结果
  8. nslookup mirrors.cloud.tencent.com
复制代码
输出示例：
  1. 非权威应答:
  2. 名称:    mirrors.cloud.tencent.com
  3. Addresses:  240e:95e:4001:1:38::11  # IPv6（可能不可用）
  4.              101.89.19.12           # IPv4（可用）
复制代码
二、解决方案详解

方法 1：通过 NODE_OPTIONS 强制 Node.js 优先 IPv4（推荐）

原理：pnpm 基于 Node.js，可通过环境变量调整 DNS 解析顺序。
适用场景：临时测试或快速修复，无需修改系统配置。
操作步骤：
  1. # Linux/macOS（终端临时生效）
  2. export NODE_OPTIONS="--dns-result-order=ipv4first"
  3. pnpm install
  5. # Windows PowerShell
  6. $env:NODE_OPTIONS="--dns-result-order=ipv4first"
  7. pnpm install
  9. # Windows CMD
  10. set NODE_OPTIONS=--dns-result-order=ipv4first
  11. pnpm install
复制代码
永久生效配置：


  • Linux/macOS：将 export NODE_OPTIONS="--dns-result-order=ipv4first" 添加到 ~/.bashrc 或 ~/.zshrc。
  • Windows：通过系统属性 → 环境变量添加 NODE_OPTIONS。
方法 2：修改 Hosts 文件固定 IPv4 地址

原理：绕过 DNS 解析，直接绑定域名到 IPv4。
适用场景：长期稳定使用，避免 DNS 返回 IPv6。
操作步骤：


  • 查询镜像的 IPv4 地址：
    1. nslookup mirrors.cloud.tencent.com
    复制代码
    记录输出的 IPv4 地址（如 101.89.19.12）。
  • 编辑 Hosts 文件：

    • Windows：

      • 以管理员身份打开记事本，编辑 C:\Windows\System32\drivers\etc\hosts。
      • 添加一行：
        1. 101.89.19.12 mirrors.cloud.tencent.com
        复制代码

    • Linux/macOS：
      1. sudo nano /etc/hosts
      复制代码
      添加相同内容后保存。

  • 刷新 DNS 缓存：

    • Windows：
      1. ipconfig /flushdns
      复制代码
    • macOS：
      1. sudo dscacheutil -flushcache
      复制代码
    • Linux：
      1. sudo systemd-resolve --flush-caches
      复制代码

方法 3：切换到纯 IPv4 的镜像源

原理：使用国内镜像源（如淘宝、华为云），默认优先 IPv4。
适用场景：国内开发者，兼顾速度和稳定性。
常用镜像源列表：

镜像源地址特点淘宝 npm 镜像https://registry.npmmirror.com国内最快，默认 IPv4阿里云镜像https://registry.npm.aliyun.com企业级稳定华为云镜像https://mirrors.huaweicloud.com/repository/npm/适合华为生态用户切换命令：
  1. pnpm config set registry https://registry.npmmirror.com
复制代码
验证是否生效：
  1. pnpm config get registry
复制代码
方法 4：调整系统 DNS 解析优先级

Windows 系统


  • 禁用 IPv6 DNS 解析：

    • 打开 控制面板 > 网络和 Internet > 网络和共享中心。
    • 点击当前网络 → 属性 → 取消勾选 Internet 协议版本 6 (TCP/IPv6)。
    • 或保留 IPv6 但调整 DNS 顺序：

      • 双击 IPv4 → 高级 → DNS 选项卡 → 将 IPv4 DNS 服务器移到顶部。


  • 使用 IPv4 专用 DNS：

    • 推荐 DNS：

      • 8.8.4.4（Google Public DNS IPv4）
      • 114.114.114.114（国内 114 DNS）


Linux/macOS 系统

编辑 /etc/gai.conf，取消注释以下行（强制 IPv4 优先）：
  1. precedence ::ffff:0:0/96  100
复制代码
然后重启网络：
  1. # Linux（Systemd）
  2. sudo systemctl restart NetworkManager
  4. # macOS
  5. sudo killall -HUP mDNSResponder
复制代码
方法 5：彻底禁用 IPv6（终极方案）

适用场景：网络环境完全不支持 IPv6，且其他方法无效。
Windows


  • 以管理员身份运行 CMD：
    1. netsh interface ipv6 set global state=disabled
    复制代码
  • 重启电脑生效。
Linux

编辑 /etc/sysctl.conf，添加：
  1. net.ipv6.conf.all.disable_ipv6 = 1
  2. net.ipv6.conf.default.disable_ipv6 = 1
复制代码
执行生效：
  1. sudo sysctl -p
复制代码
macOS
  1. networksetup -setv6off Wi-Fi  # 替换 Wi-Fi 为你的网络接口名
复制代码
三、验证解决方案是否生效

3.1 检查连接日志
  1. pnpm install --loglevel debug | grep -i "connect"
复制代码
正常输出应显示 IPv4 地址（如 101.89.19.12:443）。
3.2 测试网络连通性
  1. # 测试 IPv4 连接
  2. curl -v https://registry.npmmirror.com/node-opcua
  4. # 测试端口是否开放
  5. telnet 101.89.19.12 443
复制代码
3.3 使用 tcpdump 抓包分析（高级）
  1. # Linux/macOS
  2. sudo tcpdump -i any host 101.89.19.12 and port 443 -nn
复制代码
观察是否有 IPv6 流量（以 :: 开头的地址）。
四、常见问题解答

Q1：为什么修改 Hosts 后仍然无效？


  • 可能原因：

    • Hosts 文件权限不足（需管理员权限编辑）。
    • 系统 DNS 缓存未刷新（执行 ipconfig /flushdns 或重启网络）。
    • 镜像源更换了 IPv4 地址（需重新查询 nslookup）。

Q2：禁用 IPv6 会影响其他服务吗？


  • 影响范围：

    • 仅影响依赖 IPv6 的服务（如某些企业内部系统）。
    • 现代网站（如 Google、GitHub）均支持 IPv4，可正常访问。

Q3：如何恢复 IPv6？


  • Windows：
    1. netsh interface ipv6 set global state=enabled
    复制代码
  • Linux：
    1. sed -i 's/net.ipv6.conf.all.disable_ipv6 = 1/#net.ipv6.conf.all.disable_ipv6 = 1/' /etc/sysctl.conf
    2. sudo sysctl -p
    复制代码
五、总结与推荐

方法复杂度持久性适用场景NODE_OPTIONS★☆☆临时快速测试修改 Hosts★★☆持久长期稳定切换镜像源★☆☆持久国内用户首选调整 DNS 优先级★★★系统级全局修改禁用 IPv6★★★永久终极方案推荐流程：

  • 尝试 NODE_OPTIONS="--dns-result-order=ipv4first" pnpm install。
  • 若无效，切换到淘宝镜像 pnpm config set registry https://registry.npmmirror.com。
  • 仍有问题时，修改 Hosts 文件或禁用 IPv6。

通过以上方法，你可以彻底解决 pnpm 因 IPv6 导致的安装失败问题！
来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

使用道具 举报
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 立即注册
发帖
扈季雅
2025-8-14 09:06:36

0

粉丝关注

19

主题发布

板块介绍填写区域，请于后台编辑
微信扫一扫