强制 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 问题？
运行以下命令测试：
# 测试 IPv6 连接（可能超时）
ping mirrors.cloud.tencent.com
# 强制使用 IPv4（应正常响应）
ping -4 mirrors.cloud.tencent.com
# 查询域名的 DNS 解析结果
nslookup mirrors.cloud.tencent.com输出示例：
非权威应答:
名称: mirrors.cloud.tencent.com
Addresses: 240e:95e:4001:1:38::11 # IPv6（可能不可用）
101.89.19.12 # IPv4（可用）二、解决方案详解
方法 1：通过 NODE_OPTIONS 强制 Node.js 优先 IPv4（推荐）
原理：pnpm 基于 Node.js，可通过环境变量调整 DNS 解析顺序。
适用场景：临时测试或快速修复，无需修改系统配置。
操作步骤：
# Linux/macOS（终端临时生效）
export NODE_OPTIONS="--dns-result-order=ipv4first"
pnpm install
# Windows PowerShell
$env:NODE_OPTIONS="--dns-result-order=ipv4first"
pnpm install
# Windows CMD
set NODE_OPTIONS=--dns-result-order=ipv4first
pnpm install永久生效配置：
- Linux/macOS：将
export NODE_OPTIONS="--dns-result-order=ipv4first"添加到~/.bashrc或~/.zshrc。 - Windows：通过系统属性 → 环境变量添加
NODE_OPTIONS。
方法 2：修改 Hosts 文件固定 IPv4 地址
原理：绕过 DNS 解析，直接绑定域名到 IPv4。
适用场景：长期稳定使用，避免 DNS 返回 IPv6。
操作步骤：
查询镜像的 IPv4 地址：
nslookup mirrors.cloud.tencent.com记录输出的 IPv4 地址（如
101.89.19.12）。编辑 Hosts 文件：
Windows：
- 以管理员身份打开记事本，编辑
C:\Windows\System32\drivers\etc\hosts。 添加一行：
101.89.19.12 mirrors.cloud.tencent.com
- 以管理员身份打开记事本，编辑
Linux/macOS：
sudo nano /etc/hosts添加相同内容后保存。
刷新 DNS 缓存：
Windows：
ipconfig /flushdnsmacOS：
sudo dscacheutil -flushcacheLinux：
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/ | 适合华为生态用户 |
切换命令：
pnpm config set registry https://registry.npmmirror.com验证是否生效：
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 优先）：
precedence ::ffff:0:0/96 100然后重启网络：
# Linux（Systemd）
sudo systemctl restart NetworkManager
# macOS
sudo killall -HUP mDNSResponder方法 5：彻底禁用 IPv6（终极方案）
适用场景：网络环境完全不支持 IPv6，且其他方法无效。
Windows
以管理员身份运行 CMD：
netsh interface ipv6 set global state=disabled- 重启电脑生效。
Linux
编辑 /etc/sysctl.conf，添加：
net.ipv6.conf.all.disable_ipv6 = 1
net.ipv6.conf.default.disable_ipv6 = 1执行生效：
sudo sysctl -pmacOS
networksetup -setv6off Wi-Fi # 替换 Wi-Fi 为你的网络接口名三、验证解决方案是否生效
3.1 检查连接日志
pnpm install --loglevel debug | grep -i "connect"正常输出应显示 IPv4 地址（如 101.89.19.12:443）。
3.2 测试网络连通性
# 测试 IPv4 连接
curl -v https://registry.npmmirror.com/node-opcua
# 测试端口是否开放
telnet 101.89.19.12 4433.3 使用 tcpdump 抓包分析（高级）
# Linux/macOS
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：
netsh interface ipv6 set global state=enabledLinux：
sed -i 's/net.ipv6.conf.all.disable_ipv6 = 1/#net.ipv6.conf.all.disable_ipv6 = 1/' /etc/sysctl.conf 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 导致的安装失败问题！ 🚀
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。