Windows Docker Desktop 安装失败，提示“WSL2 未启用”怎么办？

Question

Windows Docker Desktop 安装失败并提示“WSL2 未启用”，是常见于 Win10/Win11 系统的典型问题。根本原因在于：Docker Desktop（v2.3.0.0+）默认依赖 WSL2 后端运行 Linux 容器，而系统未启用 WSL2 或未安装内核更新。常见诱因包括：① Windows 版本过低（需 Win10 2004+/Build 19041+ 或 Win11）；② BIOS 中虚拟化（VT-x/AMD-V）未开启；③ “Windows Subsystem for Linux” 和 “Virtual Machine Platform” 两个可选功能未启用；④ 未下载并安装官方 WSL2 Linux 内核更新包（wsl_update_x64.msi）；⑤ 已安装旧版 WSL1 但未升级至 WSL2。解决需依次执行：以管理员身份运行 PowerShell，启用功能、重启、安装内核、设置默认版本为 WSL2（`wsl --set-default-version 2`），最后重试 Docker Desktop 安装。跳过任一环节均可能导致提示持续出现。

Answer 1

一、现象层：Docker Desktop 安装失败的直观表现

在 Windows 10（Build < 19041）或未正确配置的 Win11 系统上，双击 Docker Desktop Installer.exe 后弹出红色警告框：“WSL2 is not enabled”，安装进程强制中止。该提示并非 Docker 自定义校验逻辑，而是其启动时调用 wsl --status 和 wsl -l -v 的底层 API 返回非零退出码后的用户友好反馈。

二、依赖链层：Docker Desktop v2.3.0+ 与 WSL2 的强耦合机制

• Docker Desktop 不再通过 Hyper-V 虚拟机（如旧版 MobyLinuxVM）运行 LinuxKit 内核，而是将容器引擎（containerd）、镜像存储、网络栈等全部托管于 WSL2 发行版（如 Ubuntu-22.04）的轻量级虚拟化环境中；
• WSL2 本质是基于 Hyper-V 架构的轻量级 VM（但无需启用完整 Hyper-V 角色），其内核由微软独立维护并热更新；
• 因此，Docker Desktop 安装程序在预检阶段会严格验证：wsl --list --verbose 是否返回 WSL2 发行版、wsl --status 是否显示“Running”、以及 wsl --version 是否 ≥ 2。

三、系统基础层：五大关键诱因的深度归因分析

序号	诱因类别	技术本质	验证命令	典型错误输出
①	Windows 版本不兼容	WSL2 需 NT Kernel 10.0.19041+（20H1），低于此版本仅支持 WSL1	winver 或 [System.Environment]::OSVersion.Version	18363（1909）→ 不支持 WSL2
②	硬件虚拟化禁用	BIOS/UEFI 中 VT-x（Intel）或 SVM（AMD）关闭 → WSL2 VM 无法创建	systeminfo | findstr "Hyper-V Requirements"	"Virtualization Enabled In Firmware: No"
③	系统功能未启用	两个 Windows 可选组件缺一不可： • Windows Subsystem for Linux • Virtual Machine Platform	dism /online /get-features | findstr "Wsl|VirtualMachinePlatform"	状态为 "Disabled"
④	内核未更新	即使启用了 WSL2 功能，若未安装 wsl_update_x64.msi，则内核仍为 WSL1 兼容模式	wsl --update --web-download	"No valid WSL2 kernel found"
⑤	WSL 版本混用残留	已安装 Ubuntu via Microsoft Store（默认 WSL1），但未执行 wsl --set-version Ubuntu 2 升级	wsl -l -v	NAME: Ubuntu VERSION: 1

四、工程实践层：标准化修复流程（含幂等性保障）

1. 以管理员身份打开 PowerShell，执行：
   dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
2. 执行：
   dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
3. 下载并静默安装最新内核：
   Invoke-WebRequest -Uri https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi -OutFile wsl_update.msi; msiexec.exe /i wsl_update.msi /quiet
4. 重启系统（必须！否则 WSL2 驱动未加载）
5. 重启后设置默认版本：
   wsl --set-default-version 2
6. 导入发行版（推荐 Ubuntu-22.04）：
   wsl --install -d Ubuntu-22.04
7. 验证 WSL2 运行时状态：
   wsl -l -v && wsl --status → 应见 VERSION 2 且 STATE: Running
8. 最后，重新运行 Docker Desktop 安装程序（建议使用 --no-ce-ipfs 参数跳过旧版组件冲突）

五、进阶诊断层：自动化检测与根因定位脚本

# PowerShell 根因诊断脚本（保存为 diagnose-wsl2.ps1）
function Test-WSL2Readiness {
  Write-Host "[1] Checking Windows Build..." -ForegroundColor Green
  $build = [System.Environment]::OSVersion.Version.Build
  if ($build -lt 19041) { throw "❌ Windows build $build < 19041 — WSL2 unsupported" }

  Write-Host "[2] Checking Virtualization..." -ForegroundColor Green
  $vmInfo = systeminfo | Select-String "Virtualization"
  if ($vmInfo -notmatch "Yes") { throw "❌ Hardware virtualization disabled in BIOS" }

  Write-Host "[3] Checking WSL Features..." -ForegroundColor Green
  $wslFeat = dism /online /get-featureinfo /featurename:Microsoft-Windows-Subsystem-Linux | Select-String "State"
  $vmFeat = dism /online /get-featureinfo /featurename:VirtualMachinePlatform | Select-String "State"
  if ($wslFeat -notmatch "Enabled" -or $vmFeat -notmatch "Enabled") { 
    throw "❌ WSL or VMP feature not enabled" 
  }

  Write-Host "[4] Checking WSL2 Kernel & Default Version..." -ForegroundColor Green
  $ver = wsl --version 2>&1
  if ($ver -notmatch "2\..*") { throw "❌ WSL2 kernel not installed or default version not set" }
  
  Write-Host "✅ All checks passed. Proceed with Docker Desktop install." -ForegroundColor Cyan
}
Test-WSL2Readiness

六、架构演进层：WSL2 与 Docker Desktop 的协同设计哲学

微软与 Docker 共同推动的“Windows-native container experience”范式转移，本质上是将传统 Linux 容器运行时（runc + containerd）无缝嵌入 Windows 内核抽象层之上。WSL2 提供了：
• 用户态隔离（无需 root 权限即可运行 systemd）
• 9P 文件系统直通（性能逼近原生 Linux）
• AF_UNIX socket 互通（Docker CLI 可直接连接 WSL2 中的 dockerd）
• 内核模块热加载能力（支持 cgroups v2、overlayfs 等关键特性）
这使得 Docker Desktop 不再是“Windows 上跑 Linux 虚拟机”，而是“Windows 原生容器平台”的一部分。

七、避坑指南层：高频反模式与企业级部署建议

• 反模式 #1：仅启用 WSL 功能但跳过 VirtualMachinePlatform → 导致 wsl --set-version 失败且无明确报错；
• 反模式 #2：使用 wsl --update 但网络受限 → 推荐强制 --web-download 并指定国内镜像源（需修改 hosts 或代理）；
• 企业建议：通过 Intune 或 SCCM 部署时，应将 wsl_update_x64.msi 作为先决条件包，并在 GPO 中启用“Turn on Virtualization Based Security”策略；
• CI/CD 场景：GitHub Actions Windows Runner 默认禁用 WSL2，需显式添加 steps: 中的 run: wsl --install --no-distribution 步骤。

八、可视化验证层：WSL2-Docker 启动依赖流程图

graph TD
  A[用户双击 Docker Desktop Installer] --> B{预检阶段}
  B --> C[检查 Windows Build ≥ 19041]
  B --> D[检查 BIOS VT-x/SVM 已开启]
  B --> E[检查 WSL & VMP 功能已启用]
  B --> F[检查 wsl --version == 2]
  B --> G[检查 wsl --list -v 中存在 VERSION 2 发行版]
  C -->|Fail| H["弹出 'WSL2 is not enabled'"]
  D -->|Fail| H
  E -->|Fail| H
  F -->|Fail| H
  G -->|Fail| H
  C & D & E & F & G -->|All Pass| I[启动 dockerd-in-wsl2]
  I --> J[Docker Desktop GUI 连接成功]