启用及配置WSL

在使用 WSL Dashboard 之前，您的 Windows 系统必须正确启用并配置好 WSL 2 环境。本文档分为以下三大部分：

1. 启用与配置 WSL：完成 WSL 2 的基础安装与配置。
2. 命令可用不等于安装成功：说明 wsl 命令可执行并不代表可以成功安装 Linux。
3. 安装失败排查：配置完成后安装仍失败时的检查与修复方法。

1. 启用与配置 WSL

本章节将指导您完成必要的基础设置。完成本章后，请阅读 第 2 章 了解命令可用与安装成功之间的区别；若安装仍出现问题，请参考 第 3 章。

1.1 检查系统要求

WSL 2 对 Windows 版本有最低要求。请按下 Win + R，输入 winver 检查您的版本：

• Windows 10: 版本 1903 或更高，且内部版本 (Build) 需为 18362 或更高。
• Windows 11: 所有版本均支持。

IMPORTANT

如果您的版本过低，请先通过"Windows 更新"升级您的系统。

1.2 开启硬件虚拟化

WSL 2 基于虚拟化技术运行，因此必须在主板 BIOS/UEFI 中启用 虚拟化技术 (Virtualization Technology)。

• 检查方法: 打开"任务管理器" -> "性能"选项卡 -> "CPU"。
• 查看状态: 确认右下角的"虚拟化"状态显示为 "已启用"。
• 开启方式: 若未启用，您需要重启电脑进入 BIOS/UEFI 设置，找到类似 Intel VT-x 或 AMD-V 的选项并将其设为 Enabled。

1.3 启用 Windows 相关功能

您需要开启 Windows 的"适用于 Linux 的 Windows 子系统"和"虚拟机平台"功能。

方法 A：通过图形界面 (推荐)

1. 按下 Win + S，搜索并打开 "启用或关闭 Windows 功能"。
2. 勾选以下两项：
   • 适用于 Linux 的 Windows 子系统 (Windows Subsystem for Linux)
   • 虚拟机平台 (Virtual Machine Platform)
3. 点击"确定"，并在提示时重启电脑。

方法 B：通过命令行 (管理员权限)

以管理员身份运行 PowerShell 并执行以下命令：

# 启用 WSL
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

执行完毕后，请手动重启电脑。

1.4 安装/更新 WSL 内核

现代版本的 Windows 可以通过 Microsoft Store 获取 WSL 更新。

• 下载地址: Microsoft Store - Windows Subsystem for Linux
• 手动下载: 如果无法使用商店，可以从 WSL GitHub Releases 下载最新的 .msixbundle 或 .msi 安装包进行离线安装。

1.5 设置 WSL 2 为默认版本

为了确保新安装的发行版默认使用 WSL 2，请在终端执行：

wsl --set-default-version 2

1.6 常见问题

• 错误 0x80370102: 通常是因为 BIOS 中未开启虚拟化，或者 Hyper-V 存在冲突。
• WSL 1 与 WSL 2 切换: 您可以使用 wsl --set-version <分发版名称> 2 将现有的 WSL 1 实例升级到 WSL 2。

2. 命令可用不等于安装成功

wsl --version、wsl -l -v 等命令能够正常执行，并不意味着已经具备安装 Linux 的条件。两者处于不同阶段，不能画等号。

命令可用，只说明：

• ✅ Windows 中 WSL 组件已经启用/安装好了
• ✅ wsl.exe 命令行工具是可用的
• ✅ 系统能识别 WSL 相关命令

但成功安装 Linux 发行版，还需要满足额外条件。 常见会卡住的地方有：

1. 虚拟化被关闭：BIOS/UEFI 中未开启 VT-x / AMD-V，WSL 2 无法启动，或安装发行版时报告虚拟化错误（检查方法见 1.2 开启硬件虚拟化）。
2. Windows 版本/内部版本过低：WSL 2 对内核和版本有要求，家庭版、过老的企业镜像可能功能不全（检查方法见 1.1 检查系统要求）。
3. 尚未实际安装 Linux 发行版：wsl -l -v 仅列出已安装的发行版，什么都没装时列表就是空的，不代表可以直接运行 Ubuntu。
4. 网络 / Microsoft Store 问题：wsl --install -d <发行版> 需要从商店或网络拉取镜像，公司网络、代理、防火墙都可能阻断。
5. 权限不足：安装发行版或修改 WSL 设置需要管理员权限。

TIP

简单来说：WSL 命令能用 ≠ Linux 已就绪，只是拿到了"入场券"，还没有真正安装系统。

3. 安装失败排查

按照 第 1 章 完成配置（或您认为自己已完成配置）后，若执行 wsl --install 仍然失败，请按以下顺序检查。

3.1 先做"一键检测"

以管理员身份运行 PowerShell，依次执行：

wsl --install --no-distribution
wsl --set-default-version 2

• ✅ 如果这两条命令都能顺利执行，说明 WSL 可选组件已启用，虚拟化条件基本满足。
• ❌ 如果失败，会直接提示缺少什么（如虚拟机平台、Hyper-V、BIOS 虚拟化等）。

再执行 systeminfo，在输出中确认出现 Virtualization Enabled In Firmware: Yes。若以上均无报错，基本可以放心执行 wsl --install 安装发行版。

NOTE

没有任何命令能 100% 保证 wsl --install 一定成功，但上述检测可以确认安装条件是否已满足。

3.2 手动检测清单

如果"一键检测"仍无法定位问题，可逐项检查：

1. 检测 BIOS/固件虚拟化是否开启：管理员 PowerShell 执行 systeminfo，输出中必须看到 Virtualization Enabled In Firmware: Yes。
2. 检测 Windows 功能是否已开启：

   Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
   Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

   两条命令的状态均应为 Enabled。
3. 检测 WSL 是否可用：执行 wsl --version 应有正常输出；若提示命令不存在，说明 WSL 组件未安装，请回到 第 1 章。
4. 检测能否使用 WSL 2（内核 & 虚拟机平台）：执行 wsl --set-default-version 2 应成功返回。常见失败原因：未启用虚拟机平台，或 BIOS 中未开启 VT-x / AMD-V。

3.3 常见失败原因速查

情况	说明	处理方式
BIOS 未开启虚拟化	必定失败	重启进入 BIOS 开启 VT-x / AMD-V（见 1.2）
Windows 10 低于 19041	不支持 wsl --install	升级系统（见 1.1）
企业环境禁用 Hyper-V / 虚拟化	可能失败	联系系统管理员
旧版家庭版系统	需手动安装	按 1.4 手动安装 WSL 内核

3.4 错误 0xc03a0014：找不到虚拟磁盘支持提供程序

错误信息为 Cannot find a virtual disk support provider for the specified file。这不是 Linux 发行版本身的问题，而是 Windows 的 VHD/VHDX 虚拟磁盘栈没有正常工作，WSL 2 在注册发行版、创建/挂载 ext4.vhdx 时失败。

先做最小验证：以管理员身份运行 PowerShell，执行 New-VHD 测试（例如 New-VHD -Path C:\test.vhdx -SizeBytes 1GB）。如果这条命令也报告同样的错误，问题 100% 在 Windows 端，与发行版无关。

按以下顺序排查修复：

1. Virtual Disk 服务未运行：打开 services.msc，找到 Virtual Disk 服务，将启动类型设为"自动"并启动它。

2. WSL / 虚拟机平台功能未启用（或未生效）：重新执行 1.3 启用 Windows 相关功能 中的命令，然后必须重启。Windows 家庭版没有完整的 Hyper-V，但 WSL 2 只需要虚拟机平台，并非 Hyper-V 管理界面。

3. 虚拟磁盘驱动/设备缺失：打开设备管理器，检查"系统设备 / 存储控制器"中是否存在：

   • Microsoft Virtual Disk Provider
   • Microsoft Virtual Drive Enumerator
   • Microsoft VHD Loopback Controller

   缺少时可通过 hdwwiz.exe 手动添加（存储控制器 → Microsoft → Microsoft VHD 环回控制器），并确认 FsDepends 服务未被禁用。

4. 导入的镜像不符合 WSL 要求：使用 wsl --import --vhd 时，VHDX 必须是 ext4 文件系统，不能是 LUKS 加密盘、普通 raw.img、Live ISO 或 NTFS/FAT 格式化后的空盘。.img / .qcow2 / .iso 不能直接 wsl --import --vhd。

5. 路径/权限/文件系统问题：目标目录必须在 NTFS 磁盘上（FAT32/exFAT 不行）；路径避免中文、空格和特殊符号；不要从网络盘、OneDrive、压缩文件夹导入；务必使用真正的管理员 PowerShell（而非普通终端）。

6. 系统组件损坏：依次运行 DISM 与 SFC 修复系统组件，然后重新尝试：

   DISM.exe /Online /Cleanup-Image /RestoreHealth
   sfc /scannow

TIP

第三方虚拟机（VirtualBox、VMware）或安全软件的沙箱/加固功能（如 360、火绒）可能干扰虚拟磁盘操作，排查时可以暂时关闭再试。