WSL——Windows Subsystem for Linux流程一览

一、WSL 是什么（核心概念、为什么有用）

说明：本文假定用 Windows 10（需满足最低 build 要求）或 Windows 11。

WSL（Windows Subsystem for Linux） 是 Windows 的一个功能，允许在 Windows 上直接运行完整的 Linux 用户态环境（bash、常见命令行工具、脚本、开发工具等），无需传统的虚拟机或双系统。它让开发者可以同时使用 Windows 工具与 Linux 工具链，提高效率。(Microsoft Learn)
主要用途 / 典型场景
- 在 Windows 上运行 Linux 命令行工具（ssh、git、make、apt 等）。
- 本地开发（Web、后端、嵌入式工具链、Python / Node / Rust / Go 等）。
- 使用 Linux-only 工具与脚本进行自动化、CI 本地化测试。
- 运行 Docker（在 WSL2 上通过 Docker Desktop 获得更好兼容性）。
- 在 VS Code 中无缝使用 Remote - WSL 扩展做开发。

二、WSL1 vs WSL2：关键差异

WSL1：基于"系统调用转换层"（translation layer），性能对某些 I/O 场景较好（与 Windows 文件系统交互密集时），但不完全兼容所有 Linux 系统调用。
WSL2 ：基于轻量级虚拟机、包含真正的 Linux 内核，提供完整系统调用兼容性 （因此能运行 Docker、更多 Linux 软件），通常对大多数 Linux 工作负载更兼容。(Microsoft Learn)

推荐：绝大多数用户选择 WSL2，除非有特殊原因需要 WSL1（极少数与 Windows 文件系统极端交互的场景）。

三、系统要求（简要）

Windows 11：原生支持最新 WSL。
Windows 10：需要 1903/1909/2004 及更高 （不同功能对 build 有最低要求），若要使用 WSL2，需满足 Build 要求（如 19041+ 等，官方文档有详细说明）。(Microsoft Learn)

检查当前 Windows 版本：

powershell 复制代码

winver

四、最简单的一条安装命令（Windows 11 / 支持的 Windows 10）

在 以管理员身份打开的 PowerShell（或 Windows Terminal）中执行：

powershell 复制代码

wsl --install

这条命令会启用所需功能、下载并安装（默认）Ubuntu，并把 WSL 设置为 WSL2（若系统兼容）。这是官方推荐的最简单方式。(Microsoft Learn)

五、手动 / 离线 / 高级安装（当 `wsl --install` 失败或网络受限）

常见场景：不能访问 Microsoft CDN、需要自定义发行版或安装在非系统磁盘等。

A. 启用必需的 Windows 功能（手动步骤，推荐逐条执行）

以管理员 PowerShell 执行：

powershell 复制代码

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

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

完成后重启电脑。若要启用 Hyper-V（某些场景需要）：

powershell 复制代码

dism.exe /online /enable-feature /featurename:Microsoft-Hyper-V-All /all /norestart

（重启后生效）(Microsoft Learn)

B. 手动下载安装包（当 `--web-download` 失败）

微软提供离线 MSIX/MSIXBUNDLE 下载入口（aka.ms/wslstore），可以手动下载并安装：

在浏览器打开： https://aka.ms/wslstore 下载 WSL.msixbundle（或相应 distro 的 Appx/MSIX）。
在管理员 PowerShell 执行：
powershell 复制代码
```
Add-AppxPackage .\WSL.msixbundle
```
然后选择安装某个发行版或运行：
powershell 复制代码
```
wsl --install -d Ubuntu
```

这条流程在无法访问 Microsoft CDN 时非常稳妥。(Microsoft Learn)

C. 安装特定发行版（Microsoft Store / 手动）

Microsoft Store：搜索并安装 Ubuntu / Debian / Kali / openSUSE 等（最简单）。
无 Store：从官方手动下载安装包（MSIX/Appx），或使用 wsl --import 将导出的 tar 导入到自定义位置。

六、常用 WSL 管理命令（实用集合）

powershell 复制代码

# 显示 WSL 版本与信息
wsl --version
wsl --list --verbose          # 列出已安装的 distro 与 WSL1/WSL2 状态
wsl -l -v

# 设置默认 WSL 版本（1 或 2）
wsl --set-default-version 2

# 将某个 distro 转换为 WSL2
wsl --set-version <DistroName> 2

# 安装指定 distro（如果已下载 msix 或启用了 store）
wsl --install -d Ubuntu

# 进入某个 distro 的 shell（从 Windows Shell）
wsl -d Ubuntu

# 关闭所有 WSL 实例（用于重置/释放资源）
wsl --shutdown

# 导出 / 导入（备份/迁移）distro
wsl --export <DistroName> filename.tar
wsl --import <NewName> <InstallLocation> filename.tar --version 2

# 卸载 / 注销某个 distro（数据会丢失）
wsl --unregister <DistroName>

七、常见问题与排查步骤（按症状分类）

1) `wsl --install --web-download` 一直下载不了

常见原因 ：网络被代理/防火墙拦截、网络屏蔽 Microsoft CDN、DNS 或 hosts 文件被改写。
快速修复：

首选：按上面"手动下载安装包"的方法，去 https://aka.ms/wslstore 下载并用 Add-AppxPackage 安装（100% 成功的离线方式）。(Microsoft Learn)

检查系统代理：

powershell 复制代码

netsh winhttp show proxy
netsh winhttp reset proxy  # 若需清除

2) `wsl --install` 报 `Invalid command line option` 或功能缺失

检查 Windows 版本： winver，确认是否满足最低 build 要求（WSL2 在 Windows 10 上有最低 build 限制）。若不满足需先升级 Windows 更新。(Microsoft Learn)

3) 转换或启动某个 distro 很慢 / 容器相关报错（Docker）

确保使用的是 WSL2 （wsl -l -v），Docker Desktop 推荐使用 WSL2 后端。WSL1 无法运行 Docker 的多数功能。(Microsoft Learn)

4) 出现"Virtualization not enabled in firmware" 或相关错误

在 Windows 上运行 systeminfo，查看 "Hyper-V Requirements" 里的 "Virtualization Enabled In Firmware" 是否为 Yes。若为 No，需要进入 BIOS/UEFI 打开虚拟化支持（Intel VT-x / AMD SVM）。

5) 权限 / 文件系统慢

访问 Windows 主机文件系统（/mnt/c）时，某些操作会比原生 Linux 慢。尽量把代码放在 WSL 的 Linux 文件系统（/home/youruser）下进行编译和 I/O 密集型操作。
想把整个 distro 移到其它磁盘，可使用 wsl --export 和 wsl --import。

6) 需要 GPU / CUDA（机器学习）

新版 WSL 和驱动已经支持 GPU 加速（需安装正确的 GPU 驱动并使用支持 WSL GPU 的发行版与 Windows 版本），具体以 GPU 型号和驱动为准（查 NVIDIA / AMD 对 WSL 的支持文档）。

八、进阶：与 Docker、VS Code、Windows 集成

Docker Desktop ：在 Windows 上安装并配置为使用 WSL2 backend，可以直接在 WSL 的 Linux 环境里使用 docker 命令（无需在 Windows 上做额外 VM）。
VS Code Remote - WSL：在 Windows 上安装 VS Code，并启用 Remote - WSL 扩展后，可以在 VS Code 中直接打开 WSL 文件系统，调试、终端、插件都在 WSL 环境中运行，体验等同于在 Linux 上开发。
图形界面（GUI）应用 ：最新 WSL 版本支持 GUI 应用（WSLg），可直接运行 Linux GUI 应用（取决于 Windows 版本与 WSL 版本）。官方文档有说明。(Microsoft Learn)

九、备份、迁移、恢复建议

备份：使用 wsl --export <Distro> file.tar 定期导出。
迁移：在新机器上 wsl --import 将导出文件导入到指定目录并指定版本（1 或 2）。
恢复：如果某个 distro 损坏，先 wsl --unregister 再 wsl --import 恢复。

十、常用排查命令清单（可以直接复制运行）

以管理员 PowerShell 运行下面命令做一次全面检查（按顺序）：

powershell 复制代码

# 查看 Windows 版本
winver

# 查看 WSL 版本
wsl --version

# 列出已安装 distro 及版本（WSL1/2）
wsl --list --verbose

# 检查 Hyper-V / 虚拟化支持
systeminfo | findstr /C:"Hyper-V Requirements"

# 如果需要启用 WSL 与虚拟化（运行后重启）
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 清除 winhttp 代理（若有代理导致下载失败）
netsh winhttp show proxy
netsh winhttp reset proxy

# 关闭所有 WSL 实例（用于重置）
wsl --shutdown

参考（官方文档）

Windows Subsystem for Linux --- 概述与文档（Microsoft）。(Microsoft Learn)
How to install WSL（官方安装指南与命令）。(Microsoft Learn)
Compare WSL versions（WSL1 vs WSL2 对比）。(Microsoft Learn)
Manual install / offline install steps（MSIX / kernel update / manual）。(Microsoft Learn)

WSL——Windows Subsystem for Linux流程一览

一、WSL 是什么（核心概念、为什么有用）

二、WSL1 vs WSL2：关键差异

三、系统要求（简要）

四、最简单的一条安装命令（Windows 11 / 支持的 Windows 10）

五、手动 / 离线 / 高级安装（当 wsl --install 失败或网络受限）

A. 启用必需的 Windows 功能（手动步骤，推荐逐条执行）

B. 手动下载安装包（当 --web-download 失败）

C. 安装特定发行版（Microsoft Store / 手动）

六、常用 WSL 管理命令（实用集合）

七、常见问题与排查步骤（按症状分类）

1) wsl --install --web-download 一直下载不了

2) wsl --install 报 Invalid command line option 或功能缺失

3) 转换或启动某个 distro 很慢 / 容器相关报错（Docker）

4) 出现"Virtualization not enabled in firmware" 或相关错误

5) 权限 / 文件系统慢

6) 需要 GPU / CUDA（机器学习）

八、进阶：与 Docker、VS Code、Windows 集成

九、备份、迁移、恢复建议

十、常用排查命令清单（可以直接复制运行）

参考（官方文档）

五、手动 / 离线 / 高级安装（当 `wsl --install` 失败或网络受限）

B. 手动下载安装包（当 `--web-download` 失败）

1) `wsl --install --web-download` 一直下载不了

2) `wsl --install` 报 `Invalid command line option` 或功能缺失