Windows 10/11 安装 WSL 2 完整指南：从报错排查到开发环境搭建

装了又卸、卸了又装WSL 我在 Windows 10 和 Windows 11 上来来回回折腾了不少遍。说句实话我最开始对微软搞的这套子系统是持怀疑态度的——一个跑在 Windows 里的“假 Linux”能有多正经但等我真正用 WSL 2 跑起编译、开发、Docker 容器之后才意识到这货确实能打。尤其是你不想为了一个grep命令或者apt包管理就重启进双系统的时候WSL 的“Zero 重启切环境”能力实在让人回不去。这篇文章我打算把 Windows 10 和 Windows 11 安装 WSL 的完整过程、版本选型、常见报错和装完之后的必做配置一次讲透。内容不搞花架子全部按我实际敲过的命令和踩过的坑来写适合刚接触 WSL 的人照着操作也适合已经装上但频繁出问题的人对照排查。1. 我为什么从双系统转向WSL三个真实场景1.1 场景一编译Linux工具链时的内存压力我原来用双系统Windows 10 和 Ubuntu 各自占了两个分区。每次需要编译 C/C 项目或者跑 Linux 下的 Python 依赖就得重启进 Ubuntu。听着不算麻烦但实际用起来非常恼火——你打开 20 个浏览器标签页、几个 IDE 窗口突然发现要进 Linux就得全部关掉重启等 Grub再等 Ubuntu 开机。一次两次能忍天天这样就绷不住了。后来我试着在 Windows 里开 VMware 虚拟机跑 Ubuntu但虚拟机的内存开销摆在那里。我的笔记本只有 16G 内存Windows 10 空载就要吃 4G 左右虚拟机再分配 4G开发工具再占一点内存就开始告急。而 WSL 2 的虚拟机是轻量化的它跟 Windows 共享内核调度和内存管理启动一个 Ubuntu 发行版的进程开销远比完整虚拟机低。实测下来同时开 WSL 里的 Docker、VS Code Remote 和浏览器内存占用也就比纯 Windows 多 1-2G 的样子。1.2 场景二文件在不同系统之间来回倒腾另外一个让我转向 WSL 的原因是文件交换。双系统下的 Windows 和 Linux 分区格式不同NTFS 和 ext4 互认麻烦。你想从 Windows 拷贝一个压缩包到 Ubuntu要么通过 U 盘要么开 samba 共享要么搞个共享 NTFS 分区怎么弄都很绕。WSL 把文件互通的问题直接解决了。你可以在 Windows 的 Explorer 地址栏输入\\wsl$直接看到 WSL 里的 Linux 文件系统像访问本地文件夹一样拷贝东西。反过来WSL 里也能通过/mnt/c/访问 Windows 的 C 盘。虽然跨文件系统的读写性能有损耗这个后面细讲但绝大多数场景下这种“文件透明互访”的体验已经足够顺滑了。1.3 场景三团队协作中的环境一致性我们团队后端同学统一用 Linux提交的代码里有不少 shell 脚本、Makefile还有依赖apt安装的编译库。以前我在 Windows 上只能装个 Git Bash 凑合跑结果经常遇到“我这个脚本在 Windows 上不行”的情况。有些脚本用到了 Linux 特有的/proc信息、inotify、netstat -lntp的输出格式Git Bash 根本模拟不了。有了 WSL 2 之后我直接在 Windows 上跑同一个 Ubuntu 版本把团队脚本原样拉下来就能跑环境一致性有了质的提升。这个价值比单纯免去重启更值钱——它让“我在 Windows 上写代码行为却跟在 Linux 服务器上一样”这件过去很别扭的事变得顺理成章。2. WSL 1与WSL 2的本质差异文件性能与内核的取舍2.1 架构层级与系统调用翻译WSL 1 和 WSL 2 虽然都叫“Windows Subsystem for Linux”但实现原理完全不同。WSL 1 是一个系统调用翻译层把 Linux 的系统调用翻译成 Windows NT 内核能理解的调用不包含真正的 Linux 内核。好处是启动快、内存占用小坏处是兼容性不够——很多内核模块、Docker 容器这种依赖完整内核能力的场景会出问题。WSL 2 则跑在一个轻量级虚拟机里里面是一个真正的 Linux 内核。微软把内核源码放在了开源仓库里基于主线 Linux 分支做定制专门为 WSL 2 编译。这个虚拟机由 Windows 自带的管理组件调度开机时按需启动内存分配是动态的不是传统虚拟机那种固定分配所以用起来感觉很轻但它骨子里就是一台小虚拟机。你可以用wsl -l -v查看当前发行版的 WSL 版本wsl -l -v输出类似NAME STATE VERSION * Ubuntu Running 2看到 VERSION 是 2说明运行在 WSL 2 模式下。2.2 文件系统跨越带来的性能差异这是装完 WSL 之后最容易被坑的地方一定要搞清楚。WSL 2 内部使用 ext4 文件系统挂在它自己的虚拟机磁盘里磁盘文件是 Windows 下的ext4.vhdx。当你在 WSL 里访问/mnt/c/下的 Windows 文件时数据要从虚拟机里往外跨文件系统拷贝再走 9P 协议传输性能损耗非常大。我实测过在 WSL 2 里编译放在/mnt/c/下的代码耗时比放在 Linux 原生目录如~/project慢 3 到 5 倍。所以一个基本原则代码和依赖放在 WSL 内部文件系统不要把项目放到/mnt/c/下用 WSL 编译。我犯过这个错——一开始图方便把项目放在 D 盘结果 WSL 里跑npm install慢得离谱后来把项目挪到 WSL 的 home 目录下再通过\\wsl$路径在 VS Code 里打开速度立刻正常了。场景WSL 1WSL 2跨文件系统访问/mnt/c快慢9P 协议损耗内部 ext4 文件系统无直接跑 NTFS快Docker 容器不支持完整 Docker支持 Docker Desktop内核模块/系统调用兼容性有限完整 Linux 内核内存开销低较高但动态回收2.3 版本选择建议与转换命令我给你的建议很简单主力用 WSL 2但项目文件必须放在 Linux 侧。如果只是偶尔跑几条 Linux 命令又不想多占内存WSL 1 也可以不过你迟早会碰到 Docker、inotifywait、内网穿透工具这类只有 WSL 2 才能支持的东西。版本切换命令也不难# 查看所有发行版 wsl -l -v # 将指定发行版切换为 WSL 2 wsl --set-version Ubuntu 2 # 设置默认版本 wsl --set-default-version 2 # 将指定发行版切换回 WSL 1 wsl --set-version Ubuntu 1切换的时候系统会提示你在下载内核组件耐心等一会儿就行。如果报错基本就是内核安装或虚拟机平台功能没就绪这个在第 4 章排查。3. Windows 10 与 Windows 11 的差异及安装流程3.1 安装前的软硬件检查清单不管你是 Windows 10 还是 Windows 11安装之前先做几个检查免得装到一半才发现电脑根本不满足条件。系统版本Windows 10 需要 2004 版本内部版本号 19041以上。Windows 11 全系都支持。CPU 虚拟化需要在 BIOS/UEFI 中开启 Intel VT-x 或 AMD SVM。内存最低 4G但我建议 8G 起步因为 WSL 2 常驻内存大概占用 800M-1.5G汉中低于这个数会明显卡。存储Ubuntu 默认安装在系统盘建议 C 盘留出至少 10G 空间。你后面装 Docker 镜像、编译器缓存10G 还不一定够。怎么查看 Windows 版本和内部版本号快捷键Win R输入winver回车就会弹出系统信息窗口。如果你看到“版本 20H2 内部版本 19042”那就放心装如果还停留在 1809 甚至更老我建议先更新 Windows 再装 WSL不然很多新功能用不了。检查 CPU 虚拟化是否开启可以用任务管理器——Ctrl Shift Esc切到“性能”页签选中“CPU”右下角会有“虚拟化已启用”字样。如果显示“已禁用”进 BIOS 找 Intel Virtualization Technology 或 SVM Mode 打开。3.2 Windows 11 与新版 Win10一条命令装完如果你用的是 Windows 11或者 Windows 10 已经升级到较新版本最省事的方式就是直接用管理员身份打开 PowerShell 或 Windows Terminal执行wsl --install这条命令会一次性做几件事启用 WSL 功能、启用虚拟机平台、下载并安装 WSL 2 内核、默认安装 Ubuntu 发行版。装完之后重启电脑它会让你设置一个 Linux 用户名和密码这就完成了。对于 Windows 10 2004 的用户我建议先执行wsl --install -d Ubuntu-22.04这样可以直接指定你想要的发行版。我一开始默认装的是 Ubuntu后来因为项目里用到一些只有新版本才有的工具链又装了 22.04。新版安装还有一个细节wsl --install --no-download参数可以在不联网的情况下用它已在本地缓存好的包这个在你网络环境差的时候很有用。3.3 老版本 Win10 手动安装路径与回退方案如果wsl --install在你机器上报错或者你的 Windows 10 版本太老就走手动路线。步骤一以管理员身份打开 PowerShell执行下面两条命令启用功能组件dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart执行完重启电脑。步骤二去微软官网下载 WSL 2 内核更新包文件名类似wsl_update_x64.msi双击安装。步骤三下载你想要的 Linux 发行版。最简单的方式是打开 Microsoft Store搜索 Ubuntu、Debian、Kali 等关键字点安装。如果你想用命令行方式安装而避免商店的问题也可以在 PowerShell 里执行wsl --install -d Debian步骤四确认版本模式。wsl -l -v如果还是 VERSION 1就执行wsl --set-version Ubuntu 2微软商店的“应用安装程序”有时候会抽风导致发行版下载失败如果你遇到下载卡住或者报 0x80070005 权限错误我的经验是直接访问商店里对应发行版的页面通过网页版安装也可以然后使用命令行替代商店应用。4. 安装与启动阶段的高频报错错误代码排查链路4.1 “WSL needs updating”与内核更新卡顿这是网上提问最多的问题之一。你运行wsl命令的时候系统弹出一段话WSL needs updating. Your version of Windows Subsystem for Linux is too old然后让你wsl --update。原因很简单你的 WSL 组件还是老版本需要把内核更新到系统要求的版本。但很多同学的wsl --update会卡在下载阶段——进度条不动等半天没反应。我的排查思路是分两步走第一步确认网络通畅。wsl --update需要去微软的服务器拉包如果你所在网络环境访问微软 CDN 不稳定确实容易卡。这一步可以换个网络试试比如手机热点。第二步如果网络换了好几个还是卡着不动就直接去微软官方 GitHub 仓库下载 WSL 安装包离线安装。该仓库发布页里有wsl.x.x.x.x.x64.msi这类安装包文件下载好之后双击安装然后重启终端再运行wsl --update或重新打开 WSL 发行版问题基本解决。提示wsl --update更新的是 WSL 整体组件而发行版里的apt upgrade更新的是 Ubuntu 系统的软件包两者别混淆。4.2 错误代码 0x80070003 与 error_file_not_found这个报错我遇到过一次简直让人抓狂。启动 Ubuntu 的时候弹窗首次启动请等待... WslRegisterDistribution failed with error: 0x80070003 Error: 0x80070003 Error code: WSL/Service/CreateInstance/CreateVm/HCS/ERROR_FILE_NOT_FOUNDERROR_FILE_NOT_FOUND表面意思很直白——找不到虚拟化相关的文件或组件。在网上查了一圈之后发现出现这个错误通常有两种原因一种原因是“虚拟机平台”可选功能没有完整启用。你虽然在功能列表里勾了 WSL但没有勾“虚拟机平台”。解决办法是回到 3.3 节的两条 DISM 命令确保VirtualMachinePlatform也启用。如果已经显示启用可以尝试禁用再重新启用然后重启。另一种原因是和第三方虚拟化软件冲突。如果你装过 VMware、VirtualBox、Hyper-V 并且改动过 Windows 的启动配置可以用管理员 PowerShell 执行bcdedit /set hypervisorlaunchtype auto然后重启电脑再启动 WSL。看到这里你可能担心 Windows 的 Hyper-V 和 VMware 会冲突这个问题的确存在但 WSL 2 用的也是微软 Hyper-V 架构如果你的 VMware 不想终版共存需要在两者之间做取舍。4.3 BIOS 虚拟化未开启检查方法与我走过的弯路还有一种情况是 CPU 虚拟化根本没开现象往往是安装完 WSL 之后启动发行版系统提示Please enable the Virtual Machine Platform Windows feature and ensure virtualization is enabled in the BIOS。我第一次遇到这个提示时有点慌因为任务管理器里明明显示“虚拟化已启用”。后来仔细查了一下才发现这是两码事——任务管理器里看到的是 CPU 虚拟化指令已启用但 Windows 功能中的“虚拟机平台”还有可能是关闭状态。两个条件缺一不可。正确的检查路径是控制面板 → 程序 → 启用或关闭 Windows 功能 → 找到“虚拟机平台”确保这个勾被选中。如果这里没勾上任务管理器显示虚拟化已启用也白搭。如果你确认 BIOS 和系统功能都打开了但 WSL 仍然报虚拟化错误可以打开 PowerShell 输入systeminfo拉到输出靠后的位置看“Hyper-V 要求”部分如果四项都显示“是”说明虚拟化基础完好。如果出现“固件中已启用虚拟化: 否”说明 BIOS 设置有问题重启进 BIOS找“Intel Virtualization Technology”、“VT-x”或“SVM Mode”改成 Enabled保存重启。4.4 磁盘空间异常ext4.vhdx 膨胀与压缩方法这是很多人装完 WSL 用了一阵子之后才遇到的问题——明明已经在 Linux 里删了好几个大文件但 Windows 的 C 盘空间没有释放反而越来越小。原因在于 WSL 2 的虚拟磁盘文件ext4.vhdx用得比较“大方”。你在里面删除文件ext4 文件系统确实释放了空间但虚拟磁盘文件不会自动收缩它认为自己还有可能继续写所以保留着曾经膨胀到的大小。解决方法是手动压缩虚拟磁盘。首先确定 WSL 发行版已经停止运行然后执行wsl --shutdown接着打开 PowerShell进入 Ubuntu 或其它发行版对应的 vhdx 所在目录一般路径是C:\Users\你的用户名\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu...\LocalState\ext4.vhdx如果路径找不到可以打开资源管理器在地址栏输入%LOCALAPPDATA%\Packages搜索ext4.vhdx文件。然后以管理员身份打开命令提示符执行diskpart select vdisk fileC:\Users\你的用户名\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu...\LocalState\ext4.vhdx compact vdisk detach vdisk exit压缩完再启动 WSL你会发现 C 盘空间回来了。我自己的ext4.vhdx曾经膨胀到 40G压缩之后变回 18G效果立竿见影。唯一要说一下的是压缩过程中不要强制关机或者中断命令否则虚拟磁盘文件可能损坏别问我怎么知道的……5. 装完Ubuntu后的第一轮配置换源、终端与文件互通5.1 apt换源为什么必须做以及怎么换Ubuntu 官方源在国外国内网络环境下apt update慢到怀疑人生。我在刚装好 WSL 那会儿就踩过这个坑——执行apt update等了将近十分钟进度条缓缓爬最后还超时失败了好几次。所以换源这件事属于装完系统之后的刚需。首选方案是换成国内开源镜像源比如清华 TUNA 或者阿里云镜像。以清华源为例先把系统自带的源文件备份再覆盖sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo sed -i s//.*archive.ubuntu.com//mirrors.tuna.tsinghua.edu.cng /etc/apt/sources.list sudo apt update如果你用的是 Ubuntu 22.04 或者 24.04新版 Ubuntu 的源文件可能已经改成了以.sources后缀命名的格式位于/etc/apt/sources.list.d/ubuntu.sources这时的替换命令会略有不同。你只需要把文件后面URIs:开头的 URL 改成镜像地址即可。换源之后apt update的速度会从几分钟降到几秒。之后再装build-essential、git、python3-pip这些基础包就顺滑多了。建议同时把vim、curl、wget、unzip、net-tools这些日常工具装一遍后面会经常用到。5.2 Windows Terminal 与字体设置接近 macOS 的中文显示效果系统装好之后如果你还是用系统自带的老式控制台窗口跑 WSL体验会比较一般因为我实测 PowerShell 里嵌入 WSL 的显示效果远不如 Windows Terminal 舒服。推荐直接用 Windows Terminal微软商店搜索“Windows Terminal”安装即可。它对我这类长期在 macOS 和 Windows 之间切换的人非常友好——标签页、多面板、自定义主题配色全部支持。字体方面如果想追求接近 macOS 的显示体验我建议在终端里给中英文混排环境配一个比较圆润的等宽字体比如“JetBrains Mono”或者“Cascadia Code”。这两款字体在 Windows Terminal 的设置里直接指定即可。你可以在 WSL 里执行cat /etc/shells来查看当前可用的 shell然后按喜好安装zsh和oh-my-zshsudo apt install zsh -y chsh -s /usr/bin/zsh重新打开终端后就会进入 zsh再配合插件敲命令的舒适度会明显提升。热词里搜“wsl ubuntu写代码最推荐的字体接近macos的体验”我猜就是有人和我有类似的诉求——想要终端既保留 Linux 的利落感又别让人一看就觉得是平行世界的 Windows 古早界面Windows Terminal 搭配合适的等宽字体确实能解决这个体验问题。5.3 文件互通机制\wsl$ 与 /mnt/WSL 和 Windows 文件互通是很多人装它的原因之一这块简单但容易误解我多写几句。在 Windows 资源管理器地址栏直接输入\\wsl$回车后就能看到所有已安装的发行版目录比如\\wsl$\Ubuntu-22.04\home\你的用户名。你可以把这里拖一个快捷方式到桌面以后就当普通文件夹使用。我经常是把 Windows 下载目录里的压缩包直接复制到这个“网络路径”里然后回到 WSL 解压。反过来在 WSL 里访问 Windows 磁盘的方式是/mnt/c/、/mnt/d/cd /mnt/c/Users/你的用户名/Downloads不过我要再强调一遍跨文件系统访问的读写性能损耗明显。日常拷贝几个文件没问题但如果你在/mnt/c/目录下直接跑npm install或yarn install你会感受到明显的卡顿。正确的姿势是代码放 Linux 侧~/project需要访问 Windows 文件时再通过/mnt/c/拷贝到~/project里处理。还有一个小技巧在 WSL 里执行explorer.exe .会直接打开 Windows 的资源管理器并定位到当前 WSL 目录等同于帮你手动输入对应的\\wsl$\...路径。如果你想在 WSL 里用 Windows 的记事本打开某个文本文件执行notepad.exe 文件名也行WSL 会自动做路径转换这也简化了跨系统打开文件的流程。6. 把WSL用成开发主力的联动物件VS Code、Docker与CUDA6.1 VS Code Remote-WSL在Windows里写Linux代码的正确姿势在 VSCode 里使用 WSL这句话在热词里出现过可见很多人都在搜。实际上只要你安装了 VS Code 的“WSL”扩展扩展名 Remote-WSL然后在 WSL 终端里进入项目目录执行code .VS Code 就会自动切到“WSL”模式的远程开发窗口。这个模式不是简单的远程控制而是 VS Code Server 直接跑在 WSL 内部你在 Windows 侧看到的只是界面本质上是编辑器和终端共享同一个 Linux 环境所以 Node、Python、Go 这些命令都直接来自 WSL而不是 Windows。这里面的好处是你不再需要为 Windows 单独配一套环境。比如你的项目需要 Python 3.10 并且依赖 Linux 的某个动态库你只需要在 WSL 里安装好VS Code 的终端和调试器就自动用上了这套环境不会出现“Windows 下能跑、WSL 下报错”这种闹心问题。如果你是老版本 VS Code需要在扩展面板搜索“WSL”并手动安装。新版本 VS Code 输入code .时如果检测到 WSL 环境会提示你安装推荐扩展按提示走就好。6.2 Docker Desktop 与 WSL 2 后端替代传统虚拟机的容器方案Docker 在 Windows 上的安装方法我推荐直接装 Docker Desktop它现在底层就是基于 WSL 2 后端运行的。安装 Docker Desktop 后在设置里选择“Use WSL 2 based engine”并勾选“Enable integration with my default WSL distro”。这样你的 WSL 里就能直接运行docker命令不需要在 WSL 内部单独安装 Docker Engine。与直接在 Windows 上跑 Hyper-V 虚拟机相比WSL 2 后端的优势是启动速度快资源占用可控。启动 Docker Daemon 通常几秒钟就完事跑个 Nginx 或者 MySQL 容器跟本地进程差不多的感觉。我前阵子帮同事排查一个 Node 服务问题就是用 WSL 里的 Docker 起了一个相同镜像几分钟就复现了问题。另外提一句很多人搜“redis windows”其实 Redis 官方明确不推荐在 Windows 原生环境下运行除非用 Memurai 这类第三方移植版本。我的做法就是在 WSL 2 里用 Docker 跑一个redis:7容器或者直接apt install redis-server装到 WSL 里既稳定又省心。6.3 CUDA直通与Linux工具链人工智能场景的另一种打开方式最后聊一个稍微进阶一点的话题在 WSL 里跑 CUDA 和 GPU 相关工具。如果你有 NVIDIA 显卡并且安装了支持 WSL 的 NVIDIA 驱动那么 WSL 2 可以直通 GPU 进行计算。装 CUDA 的步骤大致是先在 Windows 侧安装对应版本的 NVIDIA 显卡驱动然后在 WSL 里安装 CUDA Toolkit 的 Linux 版不需要在 Windows 里装整套 CUDA。WSL 里安装 CUDA 的方式wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt update sudo apt install cuda -y装好后用nvidia-smi验证看到熟悉的显卡信息表说明 GPU 直通已经生效。我的切身体会是有了这套能力之后“在 WSL 里调 GPU”已经不是噱头而是正常运行的方式。无论是 PyTorch 训练小模型还是跑binwalk这类需要大量 CPU 和文件操作的安全分析工具WSL 2 都能扛住。很多安全研究工具天然是 Linux 生态比如固件分析里的binwalk现在不用再为了跑它重启到 Ubuntu直接在 WSL 里执行即可前提是把依赖补齐说的就是python3、mtd-utils、sasquatch这类组件。写在最后给新手的三个建议说了这么多最后给你直接可用的建议。第一代码放 WSL 内部不要贪图方便放/mnt/c这是 WSL 性能好坏的分水岭。第二换源、装 Windows Terminal、配远程扩展这三件事能在十分钟内让 WSL 变得顺手值得装完之后马上做。第三遇到报错先看 Windows 系统版本和虚拟化状态至少一半的 WSL 启动问题都出在这两个前提上。WSL 这个东西只要你把第一遍的安装和配置扛过去后面的开发体验会非常顺滑你会再也不想来回想“没有 WSL 的日子是怎么过来的”。