WSL 3.0.3 安装排障实录：从 MSI 损坏到网络崩溃

一次装 WSL，踩了六个坑、绕了五条弯路。真正的原因只有一个，但前面五个”疑似凶手”每一个都看起来很像。

本文记录完整的排查链路、每个阶段的判断依据，以及最后那条一击致命的命令。

Note

如果你只是想装 WSL 还没开始，先看安装教程。这篇是装不上 / 网络不通时的救命文档。

一、环境与目标#

项目	值
系统	Windows 11 Build 26200（25H2）
CPU	13th Gen Intel Core i7-13700H
内存	16 GB
网卡	Intel Wi-Fi 6 AX201（无线连接）
目标	WSL 3.0.3 + Ubuntu 24.04 LTS
初始状态	已装 Store 版 `WindowsSubsystemForLinux 2.5.9.0`，未装任何发行版

先做体检，确认硬件层面没问题：

1
(Get-ComputerInfo).HyperVisorPresent                      # True
2
Get-Service AppXSVC                                        # Running
3
Get-AppxPackage MicrosoftCorporationII.WindowsSubsystemForLinux

虚拟化开着、AppX 部署服务正常、WSL 内核包已存在 —— 只差一个发行版。看起来是顺手的事。

二、坑 1：`Wsl/CallMsi/REGDB_E_CLASSNOTREG`#

现象#

1
wsl --install
2
wsl: WSL 安装似乎已损坏 (错误代码： Wsl/CallMsi/Install/REGDB_E_CLASSNOTREG)。
3
按任意键修复 WSL，或 CTRL-C 取消。
4
此提示将在 60 秒后超时。
5
正在更新适用于 Linux 的 Windows 子系统: 3.0.3。

REGDB_E_CLASSNOTREG 即 COM 类未注册，发生在 Store 版 WSL 从 2.5.9 升级到 3.0.3 的 MSI 环节。

Warning

别按任意键。 它的自动修复基本不会成功，只会让你多等 60 秒。直接 CTRL-C 取消。

排查#

AppXSVC（AppX Deployment Service）状态正常，msiserver 是 Manual 按需启动也属正常。所以问题不在服务，而在这条升级链路本身。

解决：绕过 Store，用独立 MSI 安装#

微软在 GitHub Release 上提供完整的离线安装包 —— microsoft/WSL/releases。最新版是 wsl.3.0.3.0.x64.msi（约 351 MB）。

Note

国内直连 GitHub Release 经常中断（curl: (56) schannel: server closed abruptly）。用浏览器或下载工具通常更稳，下载完校验一下大小，351 MB 才完整。

管理员 PowerShell 里执行这套组合拳：

1
# 1. 停掉 WSL 进程
2
Get-Process wsl, wslservice -ErrorAction SilentlyContinue | Stop-Process -Force
3

4
# 2. 卸载损坏的 Store 包（此时未装任何发行版，删它零风险）
5
Get-AppxPackage MicrosoftCorporationII.WindowsSubsystemForLinux | Remove-AppxPackage
6

7
# 3. 清掉失效的 wsl.exe 别名
8
Remove-Item 'HKCU:\Software\Microsoft\Windows\CurrentVersion\App Paths\wsl.exe' -Recurse -Force
9

10
# 4. 用本地 MSI 安装（/passive 显示进度条，/norestart 不自动重启）
11
msiexec /i "C:\Users\w\Downloads\wsl.3.0.3.0.x64.msi" /passive /norestart
12

13
# 5. 确保两个 Windows 功能开着
14
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
15
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

msiexec 返回 0 或 3010 都算成功（3010 表示需要重启）。

三、坑 2：`localhost` 代理未镜像#

重启后装发行版，这次很顺利：

1
wsl --install -d Ubuntu-24.04
2
已成功安装分发。可以通过"wsl.exe -d Ubuntu-24.04"启动它
3
wsl: 检测到 localhost 代理配置，但未镜像到 WSL。NAT 模式下的 WSL 不支持 localhost 代理。

创建了 UNIX 用户后进入系统。但那行警告埋下伏笔 —— 本机 Windows 开着系统代理 127.0.0.1:7897，而默认的 NAT 模式里 WSL 是独立 IP，够不到 Windows 的 127.0.0.1。

第一反应：切镜像模式#

镜像模式（mirrored）让 WSL 直接共用 Windows 的网络栈，127.0.0.1 就是 Windows 的 127.0.0.1：

1
[wsl2]
2
networkingMode=mirrored
3
autoProxy=true

然后就是长达一个小时的噩梦开始。

四、坑 3：`0x8007054f`，WSL 直接退化成无网卡#

1
wsl ~
2
wsl: 出现了内部错误。
3
错误代码： CreateInstance/CreateVm/ConfigureNetworking/0x8007054f
4
wsl: 无法配置网络 (networkingMode Mirrored)，回退到 networkingMode None。

Caution

注意最后那句：回退到 networkingMode None —— 这不是降级，是这台虚拟机连网卡都没有了。后面所有的”网络不通”都源于此。

误判一：以为是 VMware 的锅#

本机装了 VMware，有两张虚拟网卡 VMnet1 / VMnet8：

1
Get-NetAdapter | Where-Object { $_.InterfaceDescription -match 'TUN|TAP|VMware|Hyper-V' }

VMware 的虚拟交换机确实会跟 Hyper-V 抢网络配置，是 mirrored 失败的常见原因。先禁用网卡试：

1
Get-NetAdapter -Name "VMware Network Adapter VMnet1","VMware Network Adapter VMnet8" | Disable-NetAdapter -Confirm:$false

仍然报 0x8007054f。

再把 VMware 整个卸载、重启：

1
Get-Service | Where-Object { $_.Name -match 'VMnet|VMWARE|VMAuthd' }   # 空，确认清干净
2
Get-NetAdapter -IncludeHidden                                           # VMnet 已消失

还是报 0x8007054f。

Important

到这里可以确认：VMware 是无辜的。但它背了最久的锅，因为它”看起来最像”。

五、坑 4：NAT 模式下的 IPv6 陷阱#

先回退到 NAT 保命：

1
[wsl2]
2
networkingMode=nat
3
dnsTunneling=true

网络起来了：

1
$ ip -4 addr show eth0 | grep inet
2
inet 172.30.7.40/20 brd 172.30.15.255 scope global eth0
3
$ cat /etc/resolv.conf | grep nameserver
4
nameserver 10.255.255.254          # dnsTunneling 的隧道地址，正常

换清华源后 apt update，索引文件全部下载成功，但 deb 包集体失败：

1
Get:1 https://mirrors.tuna.tsinghua.edu.cn/ubuntu noble InRelease [256 kB]   ← 成功
2
Err:1 ... libgssapi-krb5-2_1.20.1-6ubuntu2.10_amd64.deb
3
  Cannot initiate the connection to mirrors.tuna.tsinghua.edu.cn:443 (2402:f000:1:400::2).
4
  - connect (101: Network is unreachable)

关键线索是那个 IPv6 地址 2402:f000:1:400::2。清华源有 AAAA 记录，apt 优先走 IPv6，而 WSL 的 NAT 网络没有 IPv6 路由 → 直接不可达。

强制 IPv4 即可：

1
echo 'Acquire::ForceIPv4 "true";' | sudo tee /etc/apt/apt.conf.d/99force-ipv4

同理，curl 在 WSL 里没输出也是这个原因，加 -4 验证：

1
curl -4 -sI https://mirrors.tuna.tsinghua.edu.cn --max-time 10 | head -1

六、坑 5：IPv6 修好了还是连不上#

加了 ForceIPv4 之后，错误里的 IPv6 地址确实消失了，但换成了：

1
E: Failed to fetch ... libcurl3t64-gnutls_8.5.0-2ubuntu10.16_amd64.deb
2
  Unable to connect to mirrors.tuna.tsinghua.edu.cn:https:

判断依据#

这一段值得单独说：

dists/ 下的 InRelease（126 ~ 256 KB）全部成功
pool/ 下的 deb 包（几百 KB ~ 几十 MB）大量失败
报错是 Unable to connect（连接建立失败），不是传输中断

如果是 MTU 问题，小文件一样会挂；所以不是 MTU。结合”索引通、包不通”，更像是连接层被掐 —— 后来证实这其实是网络栈损坏的连带症状，而不是源的问题。

又排除了一个：代理软件#

把梯子整个关掉重跑，apt update 照样失败。代理软件无辜。

Note

顺带一个易忽略的点：只退出梯子软件、但 Windows 的”系统代理”开关还开着（ProxyEnable=1 指向 127.0.0.1:7897），会让 Windows 处于半断网状态，WSL 的 dnsTunneling 也会跟着遭殃。关梯子要连开关一起关。

七、阶段性突破：重置 Windows 网络栈#

查 0x8007054f 时确认了两件事：

该错误由 Hyper-V 虚拟交换机与主机物理网卡驱动初始化冲突 触发
社区验证有效的解法是重置 Windows 网络栈

有个低成本试法：先断网（关 Wi-Fi / 拔网线）→ wsl --shutdown → 启动 WSL → 再连网。断网状态下没有物理网卡可绑定，交换机能干净建起来。

但更彻底、一步到位的是这个（管理员 PowerShell，需重启）：

1
wsl --shutdown
2
net stop hns
3
net start hns
4
netsh winsock reset
5
netsh int ip reset
6
shutdown /r /t 0

重启后再进 WSL —— 报错消失了。

1
$ hostname -I
2
192.168.1.112 fd8e:133f:b5f7:0:bd12:a5a:7ee2:e51d ...   # 与 Windows 同网段 + IPv6 都回来了
3
$ sudo apt update
4
Fetched 3227 kB in 1s (4548 kB/s)                        # 一次成功

镜像模式正常，代理自动同步，IPv6 可用，apt 跑满速。

当时以为故事到此结束。并没有 —— 第二天它又崩了，而且崩得一模一样。

八、反转：真凶其实是代理软件#

复现规律是用户自己发现的：

使用途中如果开了代理再关掉，就会弹窗提示重启 WSL，重启之后还是报 0x8007054f。

这条线索一下子把前面所有矛盾都解释了 —— 那天 winsock reset 之后之所以成功，是因为那次启动代理还没打开。

证据#

查进程确认本机跑的是 Clash Verge：

1
Get-Process | Where-Object { $_.ProcessName -match 'clash|mihomo|verge|sing|v2ray' }

1
 3532 clash-verge         D:\Program Files\Clash Verge\clash-verge.exe
2
27320 verge-mihomo        D:\Program Files\Clash Verge\verge-mihomo.exe

再看网卡，WSL 的那张 vEthernet (WSL (Hyper-V firewall)) 不见了，多出来一对陌生组件：

1
Get-NetAdapter -IncludeHidden | Where-Object { $_.InterfaceDescription -match 'Hyper-V|WSL' }

1
Name                     InterfaceDescription                       Status
2
----                     --------------------                       ------
3
vEthernet (FSE HostVnic) Hyper-V Virtual Ethernet Container Adapter Up
4
vSwitch (FSE Switch)     Hyper-V Virtual Switch Extension Adapter   Up

代理软件运行时会改 Windows 代理状态、并往 Hyper-V 网络栈里插入自己的组件。 而镜像模式的网络初始化恰恰依赖这份状态 —— 开关一次，状态就不一致了，下次 WSL 起不来。

Warning

结论：只要 Windows 上装了本地代理客户端，镜像模式就不稳定。 这不是配置问题，是架构冲突。查资料时其实早就看到这句话（“只要你在 Windows 开了本地代理，WSL Mirrored 网络就极易报这个错”），当时没当回事。

最终架构：NAT + 自动探测代理#

既然会频繁开关梯子，那就彻底不用镜像模式。NAT 不读 Windows 代理状态，开关梯子对它毫无影响。

代价是 NAT 下 127.0.0.1 够不到 Windows 的代理，得绕一下：

Clash Verge 里打开「允许局域网连接 / Allow LAN」，让它监听 0.0.0.0:7897 而不只是 127.0.0.1
WSL 里放一段自动探测脚本，梯子开着才走代理，关了自动降级：

1
cat >> ~/.bashrc <<'EOF'
2

3
# ---- WSL proxy (auto-detect) ----
4
wsl_proxy() {
5
    GW=$(ip route show default 2>/dev/null | awk '{print $3}')
6
    if [ -n "$GW" ] && timeout 1 bash -c "</dev/tcp/$GW/7897" 2>/dev/null; then
7
        export http_proxy="http://$GW:7897"
8
        export https_proxy="http://$GW:7897"
9
        export no_proxy="localhost,127.0.0.1,192.168.*,10.*,172.16.*,172.17.*,172.18.*,\
10
172.19.*,172.20.*,172.21.*,172.22.*,172.23.*,172.24.*,172.25.*,172.26.*,172.27.*,\
11
172.28.*,172.29.*,172.30.*,172.31.*,mirrors.aliyun.com,mirrors.tuna.tsinghua.edu.cn"
12
        echo "[proxy] on -> $GW:7897"
13
    else
14
        unset http_proxy https_proxy no_proxy
15
        echo "[proxy] off (梯子没开，国内源直连)"
16
    fi
17
}
18
wsl_proxy
19
EOF
20

21
source ~/.bashrc

脚本用 /dev/tcp 探测网关的 7897 是否可达：开着就 export，关着就 unset。这样就不会出现”关了梯子导致 WSL 半瘫”的情况 —— 国内源本来也不需要代理。

Tip

不想开 Allow LAN 的话，Windows 侧改用端口转发也行（管理员 PowerShell）：

1
netsh interface portproxy add v4tov4 listenaddress=<WSL网关IP> listenport=7897 connectaddress=127.0.0.1 connectport=7897

只监听网关地址，比 0.0.0.0 安全，代价是 WSL 网段变了要重配。

九、最终配置#

C:\Users\<你>\.wslconfig：

1
[wsl2]
2

3
# --- 为什么不用 mirrored ---
4
# 镜像模式初始化网络时依赖 Windows 代理状态，本机跑 Clash Verge，
5
# 每次开关梯子都会让下一次 WSL 启动报 0x8007054f 并回退 None。
6
# 结论：有本地代理客户端时，镜像模式不可用。
7
networkingMode=nat
8

9
# 必须关：NAT 模式下读取 Windows 代理只会每启动一次的无效警告
10
autoProxy=false
11

12
# 通过 Windows 解析 DNS，而不是走 NAT 网关
13
dnsTunneling=true
14

15
# 资源限制（i7-13700H / 16GB），按需调整
16
# 不设的话 WSL 会吃掉约一半内存和全部核心
17
memory=8GB
18
processors=8
19
swap=4GB
20

21
[experimental]
22

23
# 空闲时把缓存内存还给 Windows
24
autoMemoryReclaim=gradual
25

26
# 阻止 ext4.vhdx 只增不减
27
sparseVhd=true

apt 源（/etc/apt/sources.list.d/ubuntu.sources）：

1
Types: deb
2
URIs: https://mirrors.aliyun.com/ubuntu
3
Suites: noble noble-updates noble-backports noble-security
4
Components: main restricted universe multiverse
5
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

梯子开着时验证（注意这里是网关 IP 而不是 127.0.0.1，NAT 下 WSL 是独立 IP）：

1
$ ip route show default | awk '{print $3}'
2
172.30.0.1
3

4
$ env | grep -i proxy
5
http_proxy=http://172.30.0.1:7897
6
https_proxy=http://172.30.0.1:7897
7
no_proxy=localhost,127.0.0.1,192.168.*,10.*,...,mirrors.aliyun.com   # 内网自动绕过
8

9
$ curl -sI https://github.com --max-time 10 | head -1
10
HTTP/1.1 200 Connection established

梯子关掉后重开一个终端：

1
[proxy] off (梯子没开，国内源直连)
2
$ curl -sI https://mirrors.aliyun.com --max-time 10 | head -1
3
HTTP/2 200                            # 国内源照常能通，只是 GitHub 不通而已

十、速查表：错误码 → 处置#

错误	含义	处置
`Wsl/CallMsi/REGDB_E_CLASSNOTREG`	Store 版升级时 MSI 注册失败	下载独立 MSI 手动装；先卸 Appx 包
`CreateInstance/CreateVm/ConfigureNetworking/0x8007054f`	本机是代理客户端所致；其他机器多为网络栈损坏	装了 Clash 类软件就直接切 NAT；否则 `netsh winsock reset`
`回退到 networkingMode None`	虚拟机无网卡，一切网络问题的根源	见上
`connect (101: Network is unreachable)` + IPv6 地址	NAT 下无 IPv6 路由	`Acquire::ForceIPv4 "true"`
`Temporary failure resolving 'xxx'`	DNS 不通	多为上层问题的表象，别只改 DNS
`检测到 localhost 代理配置，但未镜像`	NAT 下用不了 Windows 代理	无害。要代理就开 Allow LAN + 网关 IP，或 portproxy 转发

Tip

推荐排查顺序（能省两小时）：

装了本地代理客户端（Clash / v2ray 类）就别用 mirrored，直接改 NAT
netsh winsock reset + netsh int ip reset + 重启
net stop hns / net start hns
再怀疑 VMware / VPN / 杀毒软件的 NDIS 驱动
最后才去换源、调 apt 参数

十一、复盘#

怀疑对象	处置	结论
WSL 安装包损坏	独立 MSI 重装	✅ 确实是问题，已解决
IPv6 路由缺失	`ForceIPv4`	⚠️ 只是表象
清华源 / 并发连接	换阿里云源	⚠️ 只是表象
VMware 虚拟网卡	禁用 → 卸载 → 重启	❌ 全部无效
Windows 网络栈损坏	`winsock reset`	⚠️ 暂时有效，第二天复发
本地代理客户端（Clash Verge）	切 NAT + 自动探测代理	✅ 真凶

四条教训：

表象会骗人。 IPv6、镜像源、并发数 —— 每一个都能自圆其说，但都不是根因。真正有效的判断方式是看哪些成功、哪些失败：索引能下、包不能下，这个组合指向底层网络栈而非应用层配置。
“修好了”不等于”修对了”。 winsock reset 之后一切正常，我当场下了结论。区别在哪？那次启动代理还没开。一个修复恰好绕开了真正的触发条件，看起来就像是修好了 —— 这种假成功最危险。
复现规律比日志值钱。 最后破案靠的是用户一句话：“开关代理之后就会崩”。这条规律直接指向了因果关系，比任何错误码都准确。所以排查时要多问一句：什么情况下会出现？什么情况下不会？
分清楚命令在哪边跑。 全程最大的低级失误是把 curl ... | head -1、env | grep 之类的 Linux 命令粘进了 PowerShell。head、env、grep 在 Windows 上不存在 —— 给命令时务必标注「Windows 端」还是「WSL 端」。

附：一键修复脚本#

fix-wsl.ps1（管理员运行），处理坑 1 的 MSI 损坏：

1
Set-ExecutionPolicy -Scope Process Bypass -Force
2
& ".\fix-wsl.ps1" -MsiPath "C:\Users\w\Downloads\wsl.3.0.3.0.x64.msi"

脚本依次执行：停进程 → 卸载损坏 Appx → 清 wsl.exe 别名 → 本地 MSI 安装 → 启用 Windows 功能 → 提示重启。

环境：Windows 11 Build 26200 / WSL 3.0.3 / Ubuntu 24.04 LTS

还没装上？看安装教程从零开始。

音乐

音乐

一、环境与目标#

二、坑 1：`Wsl/CallMsi/REGDB_E_CLASSNOTREG`#

现象#

排查#

解决：绕过 Store，用独立 MSI 安装#

三、坑 2：`localhost` 代理未镜像#

第一反应：切镜像模式#

四、坑 3：`0x8007054f`，WSL 直接退化成无网卡#

误判一：以为是 VMware 的锅#

五、坑 4：NAT 模式下的 IPv6 陷阱#

六、坑 5：IPv6 修好了还是连不上#

判断依据#

又排除了一个：代理软件#

七、阶段性突破：重置 Windows 网络栈#

八、反转：真凶其实是代理软件#

证据#

最终架构：NAT + 自动探测代理#

九、最终配置#

十、速查表：错误码 → 处置#

十一、复盘#

附：一键修复脚本#

支持与分享

音乐

WSL 3.0.3 安装排障实录：从 MSI 损坏到网络崩溃

一、环境与目标#

二、坑 1：Wsl/CallMsi/REGDB_E_CLASSNOTREG#

现象#

排查#

解决：绕过 Store，用独立 MSI 安装#

三、坑 2：localhost 代理未镜像#

第一反应：切镜像模式#

四、坑 3：0x8007054f，WSL 直接退化成无网卡#

误判一：以为是 VMware 的锅#

五、坑 4：NAT 模式下的 IPv6 陷阱#

六、坑 5：IPv6 修好了还是连不上#

判断依据#

又排除了一个：代理软件#

七、阶段性突破：重置 Windows 网络栈#

八、反转：真凶其实是代理软件#

证据#

最终架构：NAT + 自动探测代理#

九、最终配置#

十、速查表：错误码 → 处置#

十一、复盘#

附：一键修复脚本#

支持与分享

二、坑 1：`Wsl/CallMsi/REGDB_E_CLASSNOTREG`#

三、坑 2：`localhost` 代理未镜像#

四、坑 3：`0x8007054f`，WSL 直接退化成无网卡#