适用场景
这套方案适合已经在 Windows 上用 WSL2 做开发、跑 Linux 工具链、Docker、Python/CUDA 推理或训练的人。典型问题是：项目放在 /mnt/c 下编译慢，npm install、pip install、git status 卡顿，Docker 构建耗时，网络转发和内存回收不如预期。升级到 WSL3 的目标不是追新，而是用同一台 Windows 机器获得更接近原生 Linux 的 I/O、网络和进程启动体验。公开讨论中，WSL3 在部分场景相对 WSL2 有 5%–60% 的提升区间，具体取决于硬件、文件位置和负载类型；CPU 密集任务可能差异较小，I/O 和网络相关任务更容易看到变化。
> 说明：WSL3 的发布状态、版本参数、配置节名和预览通道以微软官方文档与 wsl --help 当前输出为准。如果当前系统还没有提供 WSL3，先按本文把 WSL 升级到官方最新版，等对应渠道可用后再切换；不要手动改不认识的文件或强行替换内核。
环境与前置条件
- 操作系统：Windows 10 64 位较新版本或 Windows 11，建议保持系统更新。具体支持矩阵以官方文档为准。
- 虚拟化：BIOS/UEFI 中开启 Intel VT-x 或 AMD-V；Windows 功能启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”。
- 权限：安装和启用功能需要管理员 PowerShell。
- 内存：普通开发建议 16GB 起步；跑容器、编译大型项目建议 32GB；跑本地 AI 模型按模型大小准备 32GB、64GB 或更多。
- 显存：NVIDIA GPU 用户需要 Windows 侧安装官方驱动，WSL 内通常不要安装 Linux 显示驱动。CUDA、PyTorch 等版本组合以官方文档为准。
- 磁盘：建议 NVMe/SSD。WSL 发行版本身预留 20GB 以上；AI 模型、数据集、Docker 镜像另算。把 WSL 的虚拟磁盘放在剩余空间充足的分区。
- 备份：升级前导出已有发行版，避免转换失败后无法回退。
分步骤部署
第 1 步：确认 Windows、虚拟化和现有 WSL 状态
在 Windows 搜索“启用或关闭 Windows 功能”，确认已勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”。也可以用管理员 PowerShell：
```powershell
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
```
在任务管理器“性能”页查看 CPU 虚拟化是否已启用。若显示已禁用，重启进 BIOS/UEFI 开启 Virtualization、VT-x、AMD-V 或 SVM。
查看现有发行版：
```powershell
wsl --list --verbose
wsl --status
```
成功标志：能看到发行版名称、状态和当前 WSL 版本。若命令不存在，先执行 wsl --install，再重启。
第 2 步：备份现有发行版
先建备份目录，再导出。把 <发行版名称> 换成 wsl --list --verbose 里的名字：
```powershell
New-Item -ItemType Directory -Force D:\wsl-backup
wsl --export <发行版名称> D:\wsl-backup\<发行版名称>-backup.tar
```
成功标志：D:\wsl-backup 下出现 .tar 文件，大小与发行版数据量相符。备份文件不要放在 C 盘空间紧张的位置。
第 3 步：更新 WSL 组件
管理员 PowerShell 执行：
```powershell
wsl --update
wsl --shutdown
wsl --version
```
若 WSL3 通过预览通道提供，按官方说明加入对应通道后更新；命令以官方页面为准。成功标志：wsl --version 能输出 WSL 版本、内核版本、WSLg 版本等信息，不再提示内核过旧。
第 4 步：设置默认版本并转换现有发行版
先看帮助，确认当前版本支持的版本参数：
```powershell
wsl --help
```
如果帮助中显示 WSL3 对应参数为 3，则执行：
```powershell
wsl --set-default-version 3
wsl --shutdown
wsl --set-version <发行版名称> 3
```
如果官方参数不是 3，把上面命令中的 3 换成官方给出的值。转换过程可能持续几分钟，不要中断。成功标志：命令返回转换完成或类似提示，再次执行 wsl --list --verbose，发行版 VERSION 列显示为 3。
若转换失败，优先检查 wsl --update 是否成功、Windows 是否重启过、发行版是否在支持列表。也可以用“导出再导入”的方式创建 WSL3 发行版：
```powershell
wsl --import <新发行版名称> D:\wsl\<新发行版名称> D:\wsl-backup\<发行版名称>-backup.tar --version 3
```
第 5 步：安装新发行版（可选）
列出可安装发行版：
```powershell
wsl --list --online
```
安装时替换为实际名称：
```powershell
wsl --install -d <发行版名称>
```
首次启动会要求创建 Linux 用户名和密码。成功标志：进入 Linux shell，能执行 uname -a。
第 6 步：配置 /etc/wsl.conf
在 Linux 内编辑：
```bash
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
[user]
default=<你的Linux用户名>
[automount]
enabled=true
options="metadata,umask=22,fmask=11"
[interop]
appendWindowsPath=false
EOF
```
systemd=true 让依赖 systemd 的服务可用；appendWindowsPath=false 能减少 PATH 扫描，提升 shell 启动和命令查找速度，但之后调用 Windows 程序需要写全路径。若需要直接调用 code、explorer.exe，可把该项改为 true 或删除。保存后：
```powershell
wsl --shutdown
wsl -d <发行版名称>
```
第 7 步：配置 .wslconfig
在 Windows 用户目录创建或编辑 C:\Users\<Windows用户名>\.wslconfig。节名以官方文档为准；若 WSL3 使用 [wsl3]，就写对应节，若仍兼容 [wsl2]，键名通常相同：
```ini
[wsl3]
memory=8GB
processors=4
swap=4GB
pageReporting=true
localhostForwarding=true
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true
sparseVhd=true
```
含义：限制 WSL 占用内存、CPU 核数；swap 控制交换空间；networkingMode=mirrored 可改善网络兼容性；dnsTunneling 缓解 DNS 问题；sparseVhd 让虚拟磁盘按需增长。AI 训练需要大内存时，把 memory 调高，但给 Windows 留出余量。修改后必须：
```powershell
wsl --shutdown
```
第 8 步：Linux 内核与文件系统调优
创建 sysctl 配置：
```bash
sudo tee /etc/sysctl.d/99-wsl.conf >/dev/null <<'EOF'
vm.swappiness=10
vm.max_map_count=262144
fs.inotify.max_user_watches=524288
fs.file-max=1048576
EOF
sudo sysctl --system
```
项目文件尽量放在 Linux 文件系统，例如 /home/$USER/projects，不要长期放在 /mnt/c/Users/...。跨文件系统访问适合临时取文件，不适合大规模编译、训练和容器构建。定期回收虚拟磁盘：
```bash
sudo fstrim -av
```
第 9 步：GPU 与容器配置（可选）
Windows 侧安装官方 GPU 驱动后，在 WSL 内验证：
```bash
nvidia-smi
```
成功标志：能看到 GPU 型号、驱动版本和显存信息。CUDA Toolkit、PyTorch、TensorFlow 的安装按官方说明选择匹配组合。Docker 用户可在 Docker Desktop 中启用 WSL 后端，或在 WSL 内按官方文档安装 Docker Engine。容器数据放 Linux 文件系统，通常比挂载 Windows 目录更顺。
第 10 步：跑性能基准，对比 WSL2 与 WSL3
先安装工具：
```bash
sudo apt update
sudo apt install -y sysbench fio iperf3
```
CPU：
```bash
sysbench cpu --threads=$(nproc) run
```
内存：
```bash
sysbench memory --memory-block-size=1M --memory-total-size=10G run
```
顺序写：
```bash
cd /home/$USER
dd if=/dev/zero of=./dd-test bs=1M count=4096 oflag=direct status=progress
sync
```
顺序读：
```bash
dd if=./dd-test of=/dev/null bs=1M iflag=direct status=progress
```
随机写：
```bash
fio --name=randwrite --ioengine=libaio --rw=randwrite --bs=4k --numjobs=4 --size=1G --runtime=60 --time_based --group_reporting
```
网络：
```bash
iperf3 -c <服务器地址>
```
构建类负载可以用同一份项目分别测：
```bash
time npm ci
time make -j$(nproc)
```
对比方法：同一台机器、同一电源模式、关闭后台大任务，WSL2 和 WSL3 各跑至少 3 次，取中位数。公开讨论中 5%–60% 的提升区间常出现在 I/O、网络、启动等场景；不要用一次跑分下结论。
验证部署是否成功
依次执行：
```powershell
wsl --version
wsl --list --verbose
wsl -d <发行版名称> -- uname -a
wsl -d <发行版名称> -- systemctl is-system-running
```
预期结果：
wsl --version输出 WSL、内核等版本信息。wsl --list --verbose中目标发行版 STATE 为 Running 或 Stopped，VERSION 为 3。uname -a输出 Linux 内核和架构信息。systemctl is-system-running输出running或degraded，说明 systemd 已接管。
GPU 和性能验证：
```bash
nvidia-smi
sysbench cpu --threads=$(nproc) run
dd if=/dev/zero of=./dd-test bs=1M count=1024 oflag=direct status=progress
rm ./dd-test
```
能正常输出 GPU 信息、CPU 事件数和磁盘吞吐，说明基础环境可用。把升级前后的同一组结果记录到表格，比单看某个数字更有意义。
常见报错与解决
WSL 2 requires an update to its kernel component.→ WSL 内核组件过旧或未安装 →wsl --update，然后wsl --shutdown，必要时重启 Windows。Please enable the Virtual Machine Platform Windows feature and ensure virtualization is enabled in the BIOS.→ 虚拟机平台未启用或 BIOS 虚拟化关闭 → 管理员执行dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart，进入 BIOS 开启 VT-x/AMD-V，重启。WslRegisterDistribution failed with error: 0x80370102→ 虚拟化未开启或被其他虚拟化软件占用 → 任务管理器确认虚拟化已启用；BIOS 开启虚拟化；执行bcdedit /set hypervisorlaunchtype auto；重启。The term 'wsl' is not recognized as the name of a cmdlet...→ WSL 未安装或 PATH 异常 → 管理员执行wsl --install；若仍不行，用第 1 步的两条dism.exe命令启用功能后重启。There is no distribution with the supplied name.→ 发行版名称拼写错误或未安装 →wsl --list --verbose查看名称；wsl --list --online查看可安装项；wsl --install -d <发行版名称>。The operation could not be started because a required feature is not installed.→ Windows 功能未启用 → 启用Microsoft-Windows-Subsystem-Linux和VirtualMachinePlatform，重启后再执行 WSL 命令。.wslconfig配置不生效 → 文件位置、文件名或节名不对 → 放到C:\Users\<Windows用户名>\.wslconfig；确认节名与官方文档一致；执行wsl --shutdown后重新进入。- WSL 虚拟磁盘占用持续变大 → 删除文件后 vhdx 未自动收缩 →
wsl --shutdown；Linux 内执行sudo fstrim -av；Windows 侧可用diskpart的compact vdisk，或按官方说明使用wsl --manage <发行版名称> --set-sparse true。 nvidia-smi: command not found→ Windows 驱动未装或 WSL 内误装 Linux 显示驱动 → Windows 侧安装官方 GPU 驱动；WSL 内不要安装 Linux 显示驱动；重启后执行nvidia-smi。
后续维护
备份：定期导出发行版，命令：
```powershell
wsl --export <发行版名称> D:\wsl-backup\<发行版名称>-backup.tar
```
恢复或迁移到新机器：
```powershell
wsl --import <新发行版名称> D:\wsl\<新发行版名称> D:\wsl-backup\<发行版名称>-backup.tar --version 3
```
升级：Windows 侧定期执行 wsl --update；Linux 内定期执行 sudo apt update && sudo apt upgrade。WSL3 的预览通道、内核更新和版本参数以官方文档为准。
日志与监控：用 wsl --status 看整体状态；Linux 内用 dmesg、journalctl -xe、/var/log 排查问题；性能监控用 htop、iotop、iostat -x 1、free -h、df -h；GPU 用 nvidia-smi dmon 或 nvtop。
清理：定期执行 sudo fstrim -av；Docker 用 docker system prune；Conda 用 conda clean -a；删除不再使用的数据集和模型缓存。把 .wslconfig、/etc/wsl.conf、/etc/sysctl.d/99-wsl.conf 放进 dotfiles 或笔记，换机后可快速复现。每次升级 WSL 后，用同一组基准命令做回归对比，确认吞吐、延迟和内存占用没有异常。