強(qiáng)制 pnpm 使用 IPv4 而不是 IPv6 的終極解決方案指南

一、問題背景與影響

1.1 為什么會(huì)出現(xiàn) IPv6 問題？

隨著 IPv6 的普及，許多域名（如 mirrors.cloud.tencent.com）會(huì)同時(shí)返回 IPv4（如 101.89.19.12） 和 IPv6（如 240e:95e:4001:1:38::11） 地址。當(dāng)你的網(wǎng)絡(luò)環(huán)境 不支持 IPv6 或 IPv6 連接不穩(wěn)定 時(shí)，pnpm 默認(rèn)優(yōu)先嘗試 IPv6 連接會(huì)導(dǎo)致以下問題：

• 安裝超時(shí)：pnpm install 卡在 Fetch Metadata 或 Downloading 階段。
• 錯(cuò)誤提示：如 connect ETIMEDOUT、getaddrinfo ENOTFOUND 等。
• 日志分析：通過 pnpm install --loglevel debug 可看到連接嘗試的是 IPv6 地址。

1.2 如何驗(yàn)證 IPv6 問題？

運(yùn)行以下命令測試：

# 測試 IPv6 連接（可能超時(shí)）
ping mirrors.cloud.tencent.com

# 強(qiáng)制使用 IPv4（應(yīng)正常響應(yīng)）
ping -4 mirrors.cloud.tencent.com

# 查詢域名的 DNS 解析結(jié)果
nslookup mirrors.cloud.tencent.com

輸出示例：

非權(quán)威應(yīng)答:
名稱:    mirrors.cloud.tencent.com
Addresses:  240e:95e:4001:1:38::11  # IPv6（可能不可用）
             101.89.19.12           # IPv4（可用）

二、解決方案詳解

方法 1：通過 NODE_OPTIONS 強(qiáng)制 Node.js 優(yōu)先 IPv4（推薦）

原理：pnpm 基于 Node.js，可通過環(huán)境變量調(diào)整 DNS 解析順序。
適用場景：臨時(shí)測試或快速修復(fù)，無需修改系統(tǒng)配置。

操作步驟：

# Linux/macOS（終端臨時(shí)生效）
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：通過系統(tǒng)屬性 → 環(huán)境變量添加 NODE_OPTIONS。

方法 2：修改 Hosts 文件固定 IPv4 地址

原理：繞過 DNS 解析，直接綁定域名到 IPv4。
適用場景：長期穩(wěn)定使用，避免 DNS 返回 IPv6。

操作步驟：

1. 查詢鏡像的 IPv4 地址：

   nslookup mirrors.cloud.tencent.com
   

   記錄輸出的 IPv4 地址（如 101.89.19.12）。

2. 編輯 Hosts 文件：

   • Windows：
     1. 以管理員身份打開記事本，編輯 C:\Windows\System32\drivers\etc\hosts。
     2. 添加一行：

        101.89.19.12 mirrors.cloud.tencent.com
        

   • Linux/macOS：

     sudo nano /etc/hosts
     

     添加相同內(nèi)容后保存。

3. 刷新 DNS 緩存：

   • Windows：

     ipconfig /flushdns
     

   • macOS：

     sudo dscacheutil -flushcache
     

   • Linux：

     sudo systemd-resolve --flush-caches
     

方法 3：切換到純 IPv4 的鏡像源

原理：使用國內(nèi)鏡像源（如淘寶、華為云），默認(rèn)優(yōu)先 IPv4。
適用場景：國內(nèi)開發(fā)者，兼顧速度和穩(wěn)定性。

常用鏡像源列表：

切換命令：

pnpm config set registry https://registry.npmmirror.com

驗(yàn)證是否生效：

pnpm config get registry

方法 4：調(diào)整系統(tǒng) DNS 解析優(yōu)先級

Windows 系統(tǒng)

1. 禁用 IPv6 DNS 解析：

   • 打開 控制面板 > 網(wǎng)絡(luò)和 Internet > 網(wǎng)絡(luò)和共享中心。
   • 點(diǎn)擊當(dāng)前網(wǎng)絡(luò) → 屬性 → 取消勾選 Internet 協(xié)議版本 6 (TCP/IPv6)。
   • 或保留 IPv6 但調(diào)整 DNS 順序：
     • 雙擊 IPv4 → 高級 → DNS 選項(xiàng)卡 → 將 IPv4 DNS 服務(wù)器移到頂部。

2. 使用 IPv4 專用 DNS：

   • 推薦 DNS：
     • 8.8.4.4（Google Public DNS IPv4）
     • 114.114.114.114（國內(nèi) 114 DNS）

Linux/macOS 系統(tǒng)

編輯 /etc/gai.conf，取消注釋以下行（強(qiáng)制 IPv4 優(yōu)先）：

precedence ::ffff:0:0/96  100

然后重啟網(wǎng)絡(luò)：

# Linux（Systemd）
sudo systemctl restart NetworkManager

# macOS
sudo killall -HUP mDNSResponder

方法 5：徹底禁用 IPv6（終極方案）

適用場景：網(wǎng)絡(luò)環(huán)境完全不支持 IPv6，且其他方法無效。

Windows

1. 以管理員身份運(yùn)行 CMD：

   netsh interface ipv6 set global state=disabled
   

2. 重啟電腦生效。

Linux

編輯 /etc/sysctl.conf，添加：

net.ipv6.conf.all.disable_ipv6 = 1
net.ipv6.conf.default.disable_ipv6 = 1

執(zhí)行生效：

sudo sysctl -p

macOS

networksetup -setv6off Wi-Fi  # 替換 Wi-Fi 為你的網(wǎng)絡(luò)接口名

三、驗(yàn)證解決方案是否生效

3.1 檢查連接日志

pnpm install --loglevel debug | grep -i "connect"

正常輸出應(yīng)顯示 IPv4 地址（如 101.89.19.12:443）。

3.2 測試網(wǎng)絡(luò)連通性

# 測試 IPv4 連接
curl -v https://registry.npmmirror.com/node-opcua

# 測試端口是否開放
telnet 101.89.19.12 443

3.3 使用 tcpdump 抓包分析（高級）

# Linux/macOS
sudo tcpdump -i any host 101.89.19.12 and port 443 -nn

觀察是否有 IPv6 流量（以 :: 開頭的地址）。

四、常見問題解答

Q1：為什么修改 Hosts 后仍然無效？

• 可能原因：
  1. Hosts 文件權(quán)限不足（需管理員權(quán)限編輯）。
  2. 系統(tǒng) DNS 緩存未刷新（執(zhí)行 ipconfig /flushdns 或重啟網(wǎng)絡(luò)）。
  3. 鏡像源更換了 IPv4 地址（需重新查詢 nslookup）。

Q2：禁用 IPv6 會(huì)影響其他服務(wù)嗎？

• 影響范圍：
  • 僅影響依賴 IPv6 的服務(wù)（如某些企業(yè)內(nèi)部系統(tǒng)）。
  • 現(xiàn)代網(wǎng)站（如 Google、GitHub）均支持 IPv4，可正常訪問。

Q3：如何恢復(fù) IPv6？

• Windows：

  netsh interface ipv6 set global state=enabled
  

• Linux：

  sed -i 's/net.ipv6.conf.all.disable_ipv6 = 1/#net.ipv6.conf.all.disable_ipv6 = 1/' /etc/sysctl.conf
  sudo sysctl -p
  

五、總結(jié)與推薦

推薦流程：

1. 嘗試 NODE_OPTIONS="--dns-result-order=ipv4first" pnpm install。
2. 若無效，切換到淘寶鏡像 pnpm config set registry https://registry.npmmirror.com。
3. 仍有問題時(shí)，修改 Hosts 文件或禁用 IPv6。

通過以上方法，你可以徹底解決 pnpm 因 IPv6 導(dǎo)致的安裝失敗問題！ ??