绵羊料理1. 升级前的准备工作
1.1 WSL1 与 WSL2 到底差在哪里
第一次接触 WSL 的读者，十有八九都被同一个词卡住过：WSL2。很多人装了 Windows 自带的 Linux 子系统功能，用了一段时间觉得“够用”，直到某天想跑 Docker、想用 PyCharm 连远程解释器、想跑 CUDA，才发现 WSL1 根本干不了这些活。其实 WSL2 不是 WSL1 的“小改款”，而是一次底层架构的替换。
WSL1 的原理是在 Windows 内核里实现了一层 Linux 系统调用翻译，把 Linux 程序发出的系统调用翻译成 Windows API。好处是启动快、文件互相访问方便，坏处也很明显——不是所有调用都能翻译，Docker、systemd、GPU 直通这类依赖 Linux 内核特性的功能基本用不了。WSL2 则完全不同，它跑在真正的轻量虚拟机上，使用完整的 Linux 内核，兼容性接近原生 Linux。代价是首次启动稍慢、跨文件系统访问性能下降，但绝大多数场景下这些代价都是值得的。
用一句话总结：如果你只是想在 Windows 里敲几条 Linux 命令，WSL1 够用；如果你想在 Windows 上做正经开发，现在就升级到 WSL2，别犹豫。这也正是我在团队里带新人时最常说的一句话。
1.2 确认你的 Windows 版本是否支持
升级前先别急着敲命令，先确认系统版本。WSL2 依赖 Windows 10 版本 1903 以上（x64 系统）或 1909 以上（ARM64 系统），Windows 11 全系都支持。查版本的方法很简单，按下 Win + R，输入 winver 回车，会弹出一个窗口显示系统版本号。
如果你的系统是 Windows 10 且版本号低于 1903，建议先升级 Windows 再继续。不要试图在老旧系统上强行装 WSL2，我在实际工作中遇到过不少 Win10 1809 的机器，折腾半天最后只能放弃，浪费的时间远超系统升级的时间。另外需要记住，WSL2 默认基于虚拟机平台（Virtual Machine Platform），所以 Windows 的 Hyper-V 虚拟机监控程序组件也需要可用，如果你之前手动禁用了 Hyper-V，后面会单独提到怎么处理。
提示：Windows 家庭版也能用 WSL2，不是只有专业版才行。这个误解蛮常见的，别担心。
1.3 检查 BIOS 虚拟化是否开启
有一个“坑”几乎每个新手都会踩一次：命令全部按教程敲完了，最后启动发行版时报错 0x80370102，提示虚拟化未启用。这个错误的原因很简单——BIOS 里的虚拟化开关没打开。
开机时进入 BIOS（不同主板按键不同，通常是 Delete 或 F2），找到 Intel Virtualization Technology（Intel 平台）或 SVM Mode（AMD 平台），设为 Enabled。保存重启后再继续。这里有个小技巧：可以先在 Windows 的任务管理器里看一眼性能标签页，右下角会显示“虚拟化：已启用”或“虚拟化：已禁用”，先确认状态，能省去进 BIOS 的折腾。
如果你确定 BIOS 已经开启了虚拟化，但仍然报 0x80370102，那大概率是 Windows 的可选功能没有完整启用，后面的章节我会给出完整排查方案。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 正式操作：从检查到升级的完整流程
2.1 先把当前 WSL 状态摸清楚
在动手之前，先打开 PowerShell（普通用户权限即可），输入 wsl --status 查看当前 WSL 的版本状态。如果提示“默认版本：2”，说明你已经是 WSL2，整个流程可以跳过。如果提示“默认版本：1”，就需要继续。如果你连 wsl --status 都提示“无法将‘wsl’项识别为 cmdlet”，说明你的系统里根本没有安装 WSL 命令，稍后我会专门说这种情况。
另外一个常用的查询命令是 wsl -l -v，它会列出所有已安装的发行版以及每个发行版当前的 WSL 版本。这个命令在升级之后还会用到，用来验证升级结果。
注意：如果你以前用
lxrun /install或者直接启用“适用于 Linux 的 Windows 子系统”功能来安装 WSL1 发行版，系统里可能没有新版的wsl.exe命令，需要先通过 Microsoft Store 安装“Windows 子系统用于 Linux”应用，或者用官方离线包更新 wsl.exe。
2.2 启用必要的 Windows 功能
传统升级路径有两条，先说最稳妥的一条。以管理员身份打开 PowerShell，逐条执行以下命令：
powershell复制dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
第一条命令启用 WSL（Linux 子系统）功能，第二条命令启用虚拟机平台。执行完后重启系统，这是关键一步，不要跳过重启。如果你在重启之前继续执行后面的操作，大概率会在 wsl --set-default-version 2 那一步碰到“WSL 2 需要更新其内核组件”的报错。
如果你使用 Windows 11 并且已经通过 Microsoft Store 安装了新版 WSL 应用，那么这两条可选功能命令多数情况下系统已经自带了，但仍然建议执行一遍，确保功能状态是完整的。判断功能是否启用的方法：执行前先运行 Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform（需要管理员权限），如果 State 显示 Enabled 就不用再开了。
2.3 设置 WSL 2 为默认版本
重启完成后，再次打开 PowerShell（普通权限即可），执行：
powershell复制wsl --set-default-version 2
如果一切正常，系统会提示“有关与 WSL 2 主要区别的信息，请访问...”。如果没有弹出任何提示就直接回到命令行，也正常，说明设置已经生效。可以用 wsl --status 验证“默认版本”是否变成了 2。
这一步常见的报错有两个：一是提示需要更新内核，二是直接报错 403 或“WSL 2 需要更新其内核组件”。前者的解决方法是下载并安装内核更新包，后者通常是新版 WSL 分发机制的问题，后面的章节我会展开讲。
2.4 把已有的 WSL1 发行版转换到 WSL2
如果你已经有一个安装好的发行版（比如 Ubuntu 20.04），并且想把它的版本从 1 升到 2，执行：
powershell复制wsl --set-version <发行版名称> 2
把 <发行版名称> 换成你实际的发行版名，可以用 wsl -l -v 查看准确名称。系统会开始转换，这个过程持续几分钟到几十分钟不等，取决于你发行版里已有的文件数量。转换期间不要关闭终端窗口，也不要强制关机。转换完成后，重新运行 wsl -l -v，VERSION 列会从 1 变成 2。
这里要提醒一句：如果只想转换某一个发行版，上面命令中的版本参数必须写准；如果需要一次性把默认版本设为 2，那么之后新建的发行版都会默认使用 WSL2，但已经存在的发行版不会自动转换，必须手动逐个执行一次。
2.5 从零安装并直升 WSL2
对于还没有安装任何发行版的读者，最省事的方式是直接用一条命令搞定：
powershell复制wsl --install -d Ubuntu-24.04
这条命令会自动完成三件事：安装 WSL 核心组件、启用虚拟机平台功能、下载并注册 Ubuntu 24.04 发行版。第一次执行时如果提示需要重启，照做就行。重启后再次执行同样的命令，或者直接搜索“Ubuntu”应用，系统会引导你设置 Linux 用户名和密码。
如果你不想用 Ubuntu 24.04，也可以把 -d 后面的参数换成其他发行版，常见的有 Ubuntu-22.04、Debian、Kali-Linux。查看完整支持列表用 wsl --list --online。如果是 Windows 10 系统，部分新发行版可能不受支持，选择列表里能查到的即可。
安装完成后，用 wsl -l -v 查看版本，正常情况下 VERSION 列显示的就是 2。如果你运行的 Windows 版本太老，或者用的旧版 WSL 内核，新安装的发行版可能会落在版本 1，此时再用 wsl --set-version Ubuntu-24.04 2 手动转。
3. 下载太慢与 403 报错的解决方案
3.1 为什么会碰到“已禁止(403)”
相信不少人在执行 wsl --install 时看到过这样的输出：
text复制无法从 https://github.com/microsoft/WSL/releases 下载...
已禁止(403)。
看着挺吓人，其实原因不复杂：新版 WSL 在安装或更新时需要从微软的发布服务器拉取安装包和内核组件，部分地区访问这些地址会出现间歇性 403 或者超时。这和你的系统本身没关系，换一台机器一样可能碰到。
最直接的绕开办法是给 wsl --install 或 wsl --update 加上一个参数：
powershell复制wsl --update --web-download
wsl --install -d Ubuntu-24.04 --web-download
--web-download 的作用是让 WSL 从 GitHub Releases 直接下载最新版，而不是走 Windows Update 内容分发通道。很多场景下这个参数能解决 403 和更新失败的问题。如果用了之后还是下载慢，那问题就出在网络链路上，继续往下看。
3.2 离线安装内核包
另一种绕开网络限制的方法，是手动下载内核更新包。在浏览器中打开微软官方 WSL 内核更新页，找到 wsl_update_x64.msi，下载后双击安装。安装完成后重新打开终端，执行 wsl --version，看到版本号就说明内核组件已经就绪。
安装这个 .msi 之后，之前困扰你的“WSL 2 需要更新其内核组件”的报错通常会消失。如果你的系统提示“无法安装此程序包”，那可能是因为你手动开启过“Windows 虚拟机监控程序平台”，两种虚拟化组件冲突了，需要先在“启用或关闭 Windows 功能”里取消勾选“虚拟机监控程序平台”，重启后再装内核包。
提示：新版本 WSL 已经作为独立商店应用分发，如果用旧版 .msi 装完后提示“WSL 正在更新”，建议打开 Microsoft Store 搜索“Windows Subsystem for Linux”安装最新版，或者用
wsl --update把组件升级到商店版，避免新旧组件版本不一致导致的隐藏问题。
3.3 通过镜像 rootfs 导入发行版
如果 wsl --install 在下载发行版环节死活卡住，还有一个百试百灵的办法：直接用 rootfs 导入。原理很简单，不经过商店分发，而是手动下载一个 Ubuntu 的 rootfs 压缩包，然后用 wsl --import 命令导入。
以 Ubuntu 为例，从 Ubuntu 官方云镜像站找到 WSL 专用的 rootfs 地址，下载 .tar.gz 文件后，按下面的格式导入：
powershell复制wsl --import Ubuntu-24.04 D:\WSL\Ubuntu-24.04 C:\Users\你的用户名\Downloads\ubuntu-jammy-wsl-amd64-wsl.rootfs.tar.gz
第一个参数是发行版名称，第二个参数是发行版在你 Windows 系统里的安装目录，第三个参数是 tar 包路径。导入完成后，用 wsl -l -v 就能看到新导入的发行版。首次进入时你可能发现默认是 root 用户，这时候可以执行：
bash复制adduser 你的用户名
创建普通用户，再用 usermod -aG sudo 你的用户名 把它加入 sudo 组。
这个方法还有一个衍生用途：你可以把装好环境的发行版整体打包成 tar，再在另一台电脑上快速恢复，省去重新安装配置的时间。我自己的开发环境迁移就是用这个方式完成的，实测比重新安装快很多，也避免了商店下载不稳定的问题。
3.4 设置默认登录用户，绕过初始化卡顿
经常有人导入完发行版后发现“create a default unix account”这一步卡了很久，其实这个提示是在系统初始化阶段要求你创建一个 Unix 账户。用 wsl --import 导入的发行版默认用 root 登录，不经过这个交互，但如果你是正常安装发行版遇到了这个提示卡住，多数原因是控制台输入法或编码问题。
解决方法是先退出发行版，然后在 PowerShell 里执行：
powershell复制ubuntu2404 config --default-user root
发行版名称不同，命令前缀会不一样，Ubuntu 24.04 对应 ubuntu2404。执行后再进入发行版，以 root 身份手动创建用户，补全初始化步骤。这样做的好处是绕开交互式初始化脚本，直接接管系统控制，后面再一步步配置用户环境。
4. 常见报错与排查技巧
4.1 “无法将‘wsl’项识别为 cmdlet”
这个报错是字面意思：你的系统里没有 wsl.exe。原因一般有三个：一是系统版本太旧，Windows 10 1809 之前的版本没有内置 wsl 命令；二是只启用了传统“适用于 Linux 的 Windows 子系统”功能，但没有安装商店版 WSL 应用；三是 PATH 环境变量被精简过，wsl.exe 所在目录不在搜索路径里。
排查方法：先运行 C:\Windows\System32\wsl.exe --version，如果这个完整路径能输出版本信息，说明命令存在，只是 PATH 问题，手动把 %SystemRoot%\System32 加回 PATH 即可。如果完整路径提示找不到文件，那就需要前面说的离线安装或商店安装来补齐组件。这里我特别建议优先考虑商店版，因为后续更新维护省心很多。
4.2 wsl --update 报 403 或更新失败
遇到这个报错，执行：
powershell复制wsl --update --web-download
这一步的原理是切换下载通道。如果仍然失败，手动下载 msixbundle 或 msi 安装包，离线安装。注意新版 WSL 有两种分发格式，Store 版用 MSIX，独立版用 MSI。下载前先 wsl --version 看一下当前是哪种版本，然后下载对应的更新包。
装完后再验证一次版本号，确保更新生效。不要只装完包不检查，我就见过有人装完 MSI 后忘记关旧终端，重新打开终端才看到版本变化，于是误以为更新失败。
4.3 0x80370102 虚拟化未启用
最常见的原因就是 BIOS 虚拟化开关没开，或者 Windows 功能“虚拟机平台”没启用。处理顺序是：先在任务管理器确认虚拟化状态，再检查可选功能状态，最后再动 BIOS。
如果你确认 BIOS 虚拟化和功能都开了，还是报这个错，还有一个冷门原因：系统里的“内核隔离”或“内存完整性”设置阻止了虚拟化堆栈运行。尝试在“Windows 安全中心 -> 设备安全性 -> 内核隔离”里暂时关闭“内存完整性”，重启后再试。我在一台 Win11 机器上遇到过这个问题，关闭内存完整性后 WSL2 立刻能用了。
4.4 error_file_not_found 与 VHD 挂载失败
wsl 命令报出的 wsl/service/createinstance/createvm/hcs/error_file_not_found 以及 wsl/service/createinstance/mountdisk/hcs/error_file_not_found，本质都是 WSL 发行版的虚拟磁盘（通常是 ext4.vhdx）加载失败。触发原因五花八门：Windows 更新后虚拟化组件状态异常、发行版 VHD 文件损坏、杀毒软件锁定了文件。
第一步先执行 wsl --shutdown，彻底关闭 WSL 进程；第二步执行 wsl --unregister <发行版名>，把异常发行版注销。注意这一步会删除发行版内的所有数据，如果里面有重要文件，先备份。如果你不想删除，可以手动找到发行版的安装目录，把 ext4.vhdx 改名后重新进入系统，让 WSL 重建磁盘文件。这个方法看起来粗暴，但经常是唯一快捷出路。
4.5 WSL 配置不完整：an error occurred while running a wsl command
这个报错信息挺模糊，经常伴随着“please check your WSL config”的提示。遇到时先看细节，如果是在 Docker Desktop 启动时报的，那说明 Windows 里的 WSL 版本过旧，先执行 wsl --update --web-download 升级。如果升级后仍然报错，删除 %UserProfile%\.wslconfig 里所有自定义配置，再试试，因为某些老配置项在新版 WSL 里已经被移除了。
还有一种情况是 wsl --install 执行到一半杀毒软件拦截了组件注册。关掉杀毒软件的“文件夹保护”或“勒索病毒防护”后再执行安装，完成后可以重新开启。这个原因不太起眼，但实际排查时确实遇到过几次。
4.6 卸载残留导致 fresh install 失败
step 'wsl create' failed: fresh wsl install did not register expected distro 这种报错多见于多版本 WSL 混装或卸载不干净的机器。出现的原因是新旧 WSL 包互相覆盖，发行版注册信息错乱。
彻底卸载的流程建议如下：先 wsl --shutdown，然后用 wsl --unregister <发行版名> 注销所有发行版；接着在“设置 -> 应用 -> 已安装的应用”里找到“Windows 子系统用于 Linux”并卸载；之后在“启用或关闭 Windows 功能”里取消勾选“适用于 Linux 的 Windows 子系统”和“虚拟机平台”，重启；再手动删除 %LocalAppData%\Packages 下残留的 MicrosoftCorporationII.WindowsSubsystemForLinux* 文件夹；最后重新按前面的完整流程安装。整个过程看着繁琐，但能解决绝大多数卸载不干净的问题。
5. 升级后的验证与日常实战
5.1 用三个命令确认升级成功
升级完成后别急着开开心心去装环境，先做一次验证。打开 PowerShell，依次运行：
powershell复制wsl --version
wsl -l -v
wsl --status
第一条确认 WSL 组件工具链版本，第二条确认每个发行版的版本是 1 还是 2，第三条看默认版本设置。只要 wsl -l -v 输出里 VERSION 列全为 2，说明你的升级彻底完成了。如果只显示版本列但你的发行版依然为 1，回到 2.4 节手动转换一次。
我在实际工作中还习惯用 wsl -d Ubuntu-24.04 uname -r 直接看内核版本。如果输出的是以 microsoft-standard-WSL2 结尾的内核版本号，那就更稳了——这是 WSL2 标志性的内核版本后缀。
5.2 给你的 WSL2 分配合理的内存和 CPU
WSL2 默认情况下会使用大约一半的系统内存，如果你只是跑跑命令行、写写代码，这个默认值问题不大。但要跑 Docker、多个 WSL 发行版、或者同时开几个重量级 IDE，建议手动限制资源。
在 Windows 用户目录下（一般是 C:\Users\你的用户名\），新建或编辑 .wslconfig 文件，写入：
ini复制[wsl2]
memory=6GB
processors=4
swap=2GB
localhostForwarding=true
保存后运行 wsl --shutdown，再重新进入发行版，配置才会生效。这里的 memory 是 WSL2 虚拟机最高可用内存，processors 是可用 CPU 逻辑核心数，swap 是需要时自动扩容的交换空间。如果机器本身配置不高，比如 16GB 内存的笔记本，建议 memory 设置为 4GB 到 6GB，留足内存给 Windows 本体和浏览器，这样整体体验反而更流畅。
5.3 在 VSCode 和 PyCharm 中使用 WSL2
很多新手升级到 WSL2 后，下一步就是纠结开发工具怎么接。VSCode 最简单，先安装微软官方的 Remote Development 扩展包，然后在 WSL 终端里进入你的项目目录，输入：
bash复制code .
VSCode 会自动启动并连接到这个 WSL 发行版，你可以直接用 Windows 的图形界面编辑文件，但实际编译和运行全部发生在 WSL2 里。这个模式下文件 IO、Python 环境、git 命令、Docker CLI 的体验都跟原生 Linux 基本一致。
PyCharm 稍微绕一点：在 Windows 版 PyCharm 里进入“Settings -> Project -> Python Interpreter -> Add Interpreter -> WSL”，指定你安装的那个发行版，自己选好解释器路径。PyCharm 会自动使用 WSL2 里的 Python 环境，调试、终端、运行配置全部走 WSL2。如果列表里没有 WSL，确认 PyCharm 版本是专业版，社区版不支持 WSL 远程解释器。
5.4 让 Docker Desktop 跑在 WSL2 后端
Docker Desktop 是目前在 Windows 上使用 Docker 最主流的方案，而它从 2020 年起默认推荐使用 WSL2 后端。安装 Docker Desktop 时，勾选“Use WSL 2 based engine”，安装完成后在“Settings -> General”里确认这一项是开启的，再到“Resources -> WSL Integration”里选择需要启用 Docker 的发行版。
启动后，在 Ubuntu 终端里运行 docker version，如果能看到 Server 版本信息，说明 Docker 已经正常接入。很多人在这个环节会遇到“WSL needs updating your version of Windows subsystem for Linux”的提示，原因就是 WSL 内核版本太旧，把 wsl --update --web-download 执行一遍，再重启 Docker Desktop 即可。
5.5 从命令行小工具到 GPU 加速
WSL2 给日常开发带来的最大改变，就是很多 Linux 生态里的工具可以直接用了。比如固件分析用的 binwalk，装一个系统包管理器就能跑；命令行 AI 辅助工具 codex，直接在 WSL2 里安装，运行速度比在 Windows 原生环境稳定得多。
如果你的机器有 NVIDIA 显卡，WSL2 还支持 GPU 加速和 CUDA。在 WSL2 里安装 CUDA Toolkit 的 Linux 版本，Windows 端不用装任何额外驱动（显卡驱动是通用的），就能跑 PyTorch、TensorFlow 的 GPU 训练。这项能力对很多做深度学习的同学来说，是把 Windows 当作主力办公系统又不牺牲开发体验的关键。
注意：GPU 加速先用
nvidia-smi验证驱动是否正常，再装 CUDA 库。如果 nvidia-smi 显示不了，先更新 Windows 显卡驱动到较新版本，再重启 WSL。
5.6 用 wsl.conf 调整启动行为
最后分享一个更容易忽略的配置：WSL2 发行版内部的 /etc/wsl.conf 文件。比如你可以配置默认用户、允许 systemd、设置自动挂载选项：
ini复制[boot]
systemd=true
[user]
default=你的用户名
[automount]
enabled=true
options="metadata,umask=22,fmask=11"
改完以后还是老规矩，wsl --shutdown 再重新进入。systemd 支持从 Windows 11 和较新的 WSL 版本开始默认开启，如果你需要跑 systemctl 管理的服务，这一行一定要打开。
我个人在实际使用中的最大体会是：WSL2 升级这件事本身并不复杂，真正花时间的其实是对底层机制的理解和杂七杂八的报错排查。把这篇文章里的每个排查路径都过一遍，你会发现自己不仅能升级，还能解决一堆配套问题。最后再分享一个小技巧：装好 WSL2 之后，第一时间用 wsl --export 导出一份干净的发行版备份，以后环境搞坏了直接 wsl --import 还原，比重新安装省心太多了。