☰
Windows 11 搭建 WSL2 Ubuntu 22.04 开发环境完整指南
2026/9/30 3:28:09 网站建设 项目流程

Windows 11 上搭 Linux 开发环境这件事,我前后折腾了不少方案,最终长期留用的就是 WSL2 + Ubuntu 22.04 LTS 这套组合。写这篇东西的起因,是最近又有好几个朋友来问我在 Windows 上怎么做 Linux 开发、跑 PyTorch、用一些只能在 Linux 下运行的嵌入式工具链,聊到最后发现卡点都出在 WSL 环境本身没搭顺。所以干脆把自己从零开始配置 WSL 的完整过程、踩过的坑、以及最终沉淀下来的方案整理成一篇文章。无论你是刚接触 WSL 的新手,还是已经装了但用得别扭的老手,这篇应该都能给你省下不少时间。

先说结论:Windows 11 自带的新版 WSL2 已经不是什么“能用”的水平,而是“日常开发完全够用”的水平。启动秒级、支持 GPU 直通、能用 VS Code 无缝开发、还能直接访问 Windows 文件系统,对绝大多数开发场景来说,真没必要再单独维护一台虚拟机或者折腾双系统了。下面我会把整套环境的安装、磁盘规划、软件源配置、GPU 加速、PyTorch 深度学习环境搭建,还有一堆高频报错的排查过程,从头到尾讲清楚。

1. 方案选型底层逻辑:为什么 WSL2 而不是虚拟机或双系统

1.1 三种方案的真实体验对比

在正式开装之前,值得先花点时间聊清楚“为什么是 WSL2”。我周围很多人一开始都倾向于装 VMware 虚拟机或者直接搞双系统,但实际用下来,WSL2 在开发场景下的综合体验远好于前两者,关键在于它解决了一个核心矛盾:开发时既需要用 Linux 的工具链和生态,又不想放弃 Windows 的日常办公和娱乐环境。

虚拟机的问题在于“重”。VMware 或 VirtualBox 跑一个 Ubuntu 桌面版,光内存就要吃掉 4GB 以上,启动要等一两分钟,磁盘 IO 经过虚拟化层折腾之后明显变慢,而且和 Windows 共享文件总要经过共享文件夹那一套配置,网络也经常要单独调。双系统的问题在于“切换成本高”。每次想跑个 Linux 命令都得重启一次,切过去之后 Windows 的文件和工具又用不了,对写代码的人来说这个打断感是非常伤的。

WSL2 的设计就聪明在这里。它底层是一个真正的 Linux 内核,跑在微软的 Hyper-V 虚拟化平台上,但通过轻量级的运行时管理和与 Windows 的文件系统互操作,让使用体验几乎接近原生终端。启动只需要几秒钟,没有图形界面需要渲染,内存是动态分配的,用多少占多少。更重要的是 WSL2 支持完整的 Linux 内核系统调用,像 Docker、systemd、FUSE 这类依赖内核特性的东西都能原生跑起来,这也正是它比 WSL1 强出几个档次的根本原因。

1.2 版本选择的底层逻辑:为什么是 Ubuntu 22.04 LTS

确定了用 WSL2 之后,下一个问题就是选哪个发行版。在微软商店里你能看到 Ubuntu、Debian、Kali、openSUSE 等各种选项,但我每次给别人推荐都只说 Ubuntu,具体版本固定在 22.04 LTS。

选 Ubuntu 的理由很现实:软件生态最全,遇到问题搜到解决方案的概率最高。PyTorch、TensorFlow、ROS、CUDA Toolkit 这些重量级开发工具,官方文档里最优先支持的就是 Ubuntu,很多二进制包和 PPA 源都是按 Ubuntu 版本维护的。对开发者来说,生态即效率,冷门发行版遇到依赖缺失时需要你自己从源码编译,而 Ubuntu 通常一个 apt install 就完事了。

版本固定在 22.04 而不是追求最新,是因为 LTS 版本的稳定性收益在开发场景下是实打实的。22.04 有五年维护周期,到 2027 年都有官方安全更新。很多深度学习相关库的官方支持也是按 LTS 版本对齐的,你拿个 24.04 虽然系统本身没问题,但个别老项目的预编译依赖可能只提供到 22.04 的版本,反而要多折腾。我的建议非常明确:没有特殊理由就选 22.04 LTS,省心。

方案对比启动速度资源占用GPU 加速支持Win/Linux 文件互操作使用成本
WSL2秒级动态分配,占用低原生支持 NVIDIA GPU通过 \\wsl$ 直接访问低
虚拟机分钟级固定分配,占用高需要显卡直通,配置复杂需要共享文件夹配置中
双系统需要重启切换独立系统,资源独占原生完整分区互读,写操作有风险高

2. WSL2 完整安装流程与磁盘空间规划

2.1 一条命令装完 WSL2:wsl --install 背后发生了什么

Windows 11 上安装 WSL 已经比 Windows 10 时代简单太多了。在 Windows 10 上你需要手动去“启用或关闭 Windows 功能”里勾选两个选项,再下载内核安装包,再手动装发行版,中间每一步都有可能出岔子。Windows 11 之后微软把整个流程整合成了一条命令,但很多人并不知道这条命令到底帮你做了什么,以至于出了问题也不知道从哪里排查。

打开 PowerShell(注意一定要以管理员身份运行),执行:

wsl --install

这条命令会依次完成以下几件事:启用“适用于 Linux 的 Windows 子系统”功能、启用“虚拟机平台”功能、下载并安装 WSL2 内核、将 WSL 默认版本设置为 2、最后从微软商店下载并安装默认的 Ubuntu 发行版。执行完之后系统会提示你重启,重启后 Ubuntu 会自动完成初始化,让你设置用户名和密码。

如果你想指定安装 Ubuntu 22.04 而不是商店默认的最新版,可以这样:

wsl --install -d Ubuntu-22.04

如果只想装 WSL 本体、稍后再决定装哪个发行版,则用:

wsl --install --no-distribution

装完以后建议先用wsl --version确认 WSL 版本,再决定要不要手动更新内核。新版 WSL 是独立安装的,不随 Windows 更新走,所以有时候会提示 WSL needs updating,这时候直接在 PowerShell 里跑wsl --update就好。

这里有个很多人容易忽略的点:执行wsl --install之所以要求管理员权限,是因为它要启用 Windows 功能并写入系统级配置。如果你在普通权限的终端里跑,会直接报错或者卡在权限提示上。另外,Windows 11 的版本不要太老,最好保持在 22H2 以上,新版 WSL 的一些功能(比如 systemd 支持、镜像网络模式)在老版本上体验会差很多。

2.2 把 WSL 装到 D 盘,避免 C 盘空间被吃干净

WSL 的根文件系统本质是一个 ext4 格式的虚拟磁盘文件(VHDX),默认放在 C 盘用户目录下。这个文件会随着你安装的软件和依赖越来越多而膨胀,深度学习环境动辄二三十个 GB 的显存依赖和 CUDA 工具链,很容易把 C 盘塞爆。所以我的建议是:从一开始就规划好磁盘位置,直接把 WSL 装到其他盘。

有两种做法。第一种是在全新安装时就指定位置。如果你的 WSL 版本比较新(0.64 以上,Windows 11 23H2 之后的系统一般自带),可以直接用--location参数:

wsl --install -d Ubuntu-22.04 --location D:\WSL\Ubuntu2204

第二种是已经装好了,现在需要迁移。标准流程是导出、注销、再导入:

# 1. 先关闭所有 WSL 实例 wsl --shutdown # 2. 导出当前系统为 tar 文件 wsl --export Ubuntu-22.04 D:\backup\ubuntu.tar # 3. 注销原来的发行版(这一步会删除原系统数据!) wsl --unregister Ubuntu-22.04 # 4. 从 tar 文件导入到 D 盘,并指定 WSL 2 版本 wsl --import Ubuntu-22.04 D:\WSL\Ubuntu2204 D:\backup\ubuntu.tar --version 2

导入完成之后你会发现一个细节:默认登录用户变成了 root,因为你导入的是 tar 归档,它不保留发行版与 Windows 用户的映射关系。需要手动指定默认用户:

ubuntu2204.exe config --default-user 你的用户名

注意:执行wsl --unregister前一定要先确认已经导出成功。这个操作是彻底的,一旦执行,原发行版里的所有文件都会消失,没有回收站可以翻。

迁移之后 VHDX 文件就位于 D 盘了,C 盘空间即时释放。另外还要提醒一句:WSL 的磁盘性能非常依赖底层物理介质,如果你把它放在机械硬盘上,apt 安装和读取大文件时会明显变慢。有条件的话尽量放在 SSD 上,这个体验差距是实打实的。

2.3 初始化 Ubuntu 的第一件事:换源、更新、装基础工具

装完 Ubuntu 进入终端之后,第一件事不是急着装 Python 或者 PyTorch,而是把软件源换成国内镜像并做完系统更新。这一步很多人忽略,结果后面装什么包都慢得要命,还以为是 WSL 的问题。

Ubuntu 默认的 apt 源指向的是官方服务器,在国内网络环境下延迟高、速度不稳定。换源的操作本身不复杂,修改 /etc/apt/sources.list 文件(Ubuntu 22.04 用这个文件;如果你用的是 24.04,源文件路径变成了 /etc/apt/sources.list.d/ubuntu.sources,格式也不同,需要注意区分)。

以清华源为例,22.04 的 sources.list 内容大致是:

deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-security main restricted universe multiverse

修改完之后执行:

sudo apt update sudo apt upgrade -y

更新完系统之后,我建议顺手把一套基础工具链装上,后面做开发会经常用到,与其到时候想起来再装,不如一开始就备齐:

sudo apt install -y build-essential git curl wget htop net-tools unzip zip

build-essential里包含 gcc、g++、make 这套编译工具链,很多 Python 原生扩展在安装时需要现场编译,少了它你会看到一堆 error: command 'gcc' failed 之类的报错。git、curl、wget 就不用多说了,htop 用来监控系统状态,net-tools 提供 ifconfig 等命令。

3. 开发环境三板斧:VS Code、GPU 加速与 PyTorch

3.1 VS Code 连接 WSL:把 Windows 变成真正的开发工作站

WSL 本身只是个终端环境,写代码总不能一直用 vim。我的方案是 VS Code + Remote - WSL 扩展,这套组合用起来之后基本是无缝的:Windows 上装 VS Code,WSL 里不需要装 IDE,扩展会自动处理连接。

操作非常简单。在 Windows 侧装好 VS Code 后,在扩展市场搜索并安装 “WSL”(扩展全名是 Remote - WSL)。然后在 WSL 终端里进入你的项目目录,直接执行:

code .

VS Code 会自动启动,并以 WSL 客户端模式连接到这个发行版。你看到左下角绿条显示 “WSL: Ubuntu-22.04” 就说明连接成功了。这时候你打开的文件、终端、调试器,全部运行在 Linux 环境里,Windows 侧的 VS Code 窗口只是一个前端。

这里有一个小细节值得注意:扩展要装在 WSL 侧。比如你想用 Python 扩展,在连接 WSL 的状态下到扩展面板搜索安装,才会安装到 WSL 环境里。如果你在 Windows 侧直接装了 Python 扩展,WSL 里可能用不了,因为扩展的运行时是跟着远端环境走的。

VS Code 连接 WSL 之后,\\wsl$\Ubuntu-22.04\home\你的用户名\也能在 Windows 资源管理器里直接访问,需要拖文件进去的时候很方便,但这种文件互操作有一个性能陷阱:如果你在 WSL 里跑程序,项目文件放在 Windows 文件系统(比如 /mnt/c/ 下面)会比放在 Linux 原生文件系统慢不少,尤其是涉及频繁小文件读写的时候。我的建议是代码项目都放在 Linux 侧的 home 目录里,需要交换文件时再用资源管理器或者复制命令,性能体验会好很多。

3.2 WSL2 用上 NVIDIA GPU:CUDA 环境配置与验证

WSL2 对 GPU 的支持是它比 WSL1 强非常多的地方。借助 WSLg 和 GPU 虚拟化,Linux 侧可以直接调用 Windows 的 NVIDIA 显卡做 CUDA 计算,这就意味着你可以用 WSL2 跑 PyTorch 训练,而不需要单独装双系统。

GPU 直通有一个反直觉的点:NVIDIA 驱动只需要在 Windows 侧安装,WSL 里不需要也不能再装 Linux 版驱动。你在 WSL 里跑nvidia-smi时看到的驱动版本,实际上就是 Windows 侧那个驱动在 WSL 里的映射。很多人不懂这个,看到 WSL 里没有驱动就跑去装,结果把环境搞坏。

具体配置分三步。第一步,确认 Windows 侧驱动版本足够新,最好到 NVIDIA 官网下载最新 Game Ready 驱动或 Studio 驱动,老驱动对 WSL2 的支持可能不完整。第二步,在 WSL 里安装 CUDA Toolkit。

CUDA Toolkit 的安装建议用 NVIDIA 官方提供的 deb 源,这样能跟随 apt 管理升级。在 WSL 里执行:

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 -y cuda-toolkit-12-1

安装完成后需要配置环境变量,把 CUDA 的 bin 和 lib64 目录加进 PATH 和 LD_LIBRARY_PATH。在 ~/.bashrc 末尾追加:

export PATH=/usr/local/cuda/bin:$PATH export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

然后source ~/.bashrc让配置生效。最后在终端里跑nvidia-smi,如果能看到显卡型号、驱动版本和显存信息,就说明 WSL2 的 GPU 直通成功了。

如果 nvidia-smi 提示 command not found,先不要急着重装 CUDA Toolkit。先检查 Windows 侧驱动是否正常,再检查 /usr/local/cuda/bin 是否存在,最后确认环境变量有没有生效。装 CUDA Toolkit 是一个重量级操作,没必要因为路径问题反复重来。

3.3 从零搭建 PyTorch 环境:Conda 隔离与 GPU 验证

GPU 通起来之后,深度学习环境就顺理成章了。我的习惯是先用 Miniconda 做 Python 环境隔离,再在 conda 环境里用 pip 装 PyTorch。为什么不用系统自带的 Python?因为深度学习项目对 Python 版本和包版本非常敏感,环境隔离能避免“这个项目要 Python 3.8,那个项目要 3.10”的冲突。

安装 Miniconda:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh

安装过程全部按默认来即可。装完激活 conda 后,创建一个干净的 Python 环境:

conda create -n py310 python=3.10 -y conda activate py310

然后安装 GPU 版 PyTorch。最新的安装命令以 PyTorch 官网为准,给定的安装命令里要包含对应 CUDA 版本的 index-url。例如 CUDA 12.1 对应的是:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

装完立刻验证 GPU 是否真的可用:

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"

如果看到True和你的显卡型号,说明 PyTorch 已经能用 GPU 跑张量运算了。我建议再跑一个简单的矩阵运算确认显存分配正常:

python -c "import torch; x = torch.rand(1000, 1000).cuda(); print(x.sum().item())"

这一步能跑通,整个深度学习环境就算真正落地了。之后装其他依赖包的时候,记住先conda activate py310再操作,避免装错环境。

4. 高频坑位实录与排查手册

4.1 wsl --install 卡住、太慢,先别急着重装系统

“wsl install 太慢了怎么解决”是我在搜索后台里看到频率很高的一个词。这个问题的本质通常是 Windows 在下载 WSL 内核或发行版镜像时网络不顺畅,但实际原因可能有好几种,需要按顺序排查。

第一步,确认 Windows 更新服务是否正常。WSL 安装过程依赖 Windows Update 核心服务来下载部分组件,你可以用管理员 PowerShell 执行Get-Service wuauserv查看状态,如果服务被禁用或者异常,先把服务设置成自动并启动。

第二步,检查 WSL 本体版本。有些机器上wsl --install会卡在“正在下载 WSL”阶段,这时候可以跳过命令自带下载,直接到微软官网下载 WSL 的 msi 安装包手动安装,然后重启终端,再单独安装发行版。具体方法是先装好 WSL 本体,再执行:

wsl --install -d Ubuntu-22.04

第三步,换一个时间段再试。微软商店和下载服务器的带宽在高峰时段确实会有波动,我在夜间安装时的成功率比白天高不少。如果你每次卡的位置都一样,也可以考虑用wsl --install --web-download让 WSL 使用在线安装源而不是商店通道,有时候这个参数能绕过商店的问题。

还有一种很隐蔽的情况:机器上装过 WSL1,残留的配置导致新版安装时状态异常。这时候先wsl --update把内核升到最新,再wsl --shutdown清掉所有实例,重新执行安装命令。如果提示 “WSL needs updating”,说明 WSL 主程序太旧,先更新它再继续后面操作。

4.2 错误代码 wsl/installdistro/service/registerdistro/createvm/hcs/error_file_n 的完整排查思路

这个错误码很长,长到很多朋友直接蒙圈。拆开来看,它其实是在告诉你一个流程断点:安装发行版时,WSL 尝试在 HCS(Host Compute Service)里创建一个虚拟机,结果失败了。error_file_n通常意味着 HCS 在查找或创建某个关键文件时出了问题。定位到 HCS 虚拟机创建环节之后,排查方向就清晰了。

我整理了一个按优先级排序的排查清单:

  1. 确认虚拟化是否在 BIOS 中开启。Windows 11 的 WSL2 依赖 CPU 的虚拟化指令。在任务管理器“性能”标签页找到“虚拟化”,如果显示“已禁用”,需要重启进 BIOS 开启 Intel VT-x 或 AMD-V。

  2. 确认虚拟机平台功能已启用。在“启用或关闭 Windows 功能”里找到“虚拟机平台”和“适用于 Linux 的 Windows 子系统”,确保两个都勾选。如果已经勾选,可以取消后重启再重新勾选,强制系统重建相关组件。

  3. 检查 Hypervisor 是否被第三软件禁用。某些安全软件或旧版本的虚拟机软件会关闭 Windows 的 Hyper-V 引导项。以管理员身份运行命令提示符,执行:

bcdedit /set hypervisorlaunchtype auto

然后重启。这个操作会强制系统在引导时启动 Hyper-V 管理程序,WSL2 的运行依赖它。

  1. 查看 Windows 事件日志。在“事件查看器”里定位到“应用程序”日志,查找来源为 HCS 或者 vmcompute 的错误条目。日志里通常会有更具体的错误码,比如具体是哪个文件找不到,能进一步定位问题。

  2. 重置 WSL 运行时。最后的手段是重置整个 WSL 运行时状态:

wsl --shutdown net stop vmcompute net start vmcompute

如果以上五步都试过仍然报同样错误,可以考虑把问题提交到微软的反馈中心,附带事件日志截图。但就我的经验来看,绝大多数人卡在前面三步,尤其是 bcdedit 和 BIOS 虚拟化这两项,解决之后错误就消失了。

4.3 Ubuntu 侧常见问题速查:中文输入法、忘记密码、环境变量与编译工具

WSL 环境搭好之后,日常使用还会碰到一批“不是 WSL 的问题,但是 WSL 用户肯定会问”的 Ubuntu 系统问题。我把高频的几个整理成了一张速查表,并附上我实测有效的处理方案。

问题常见原因推荐处理方案
中文输入法无法使用缺少输入法框架和引擎安装 fcitx5 和 fcitx5-chinese-addons,配置环境变量 GTK_IM_MODULE、QT_IM_MODULE、XMODIFIERS 为 fcitx
忘记 Ubuntu 登录密码长期没用或临时想不起来PowerShell 执行wsl -u root -d Ubuntu-22.04 passwd 用户名,直接重设
环境变量配错导致 command not found/etc/environment 或 ~/.bashrc 中 PATH 被误改用绝对路径 /usr/bin/sudo 修复文件内容,保证 PATH 包含 /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
apt install gcc 失败软件源状态不一致或依赖损坏先 sudo apt update,再 sudo apt --fix-broken install,最后重新安装
在 WSL 中运行 binwalk 报错缺少 Python 依赖或未安装完整sudo apt install binwalk,并确认 python3 环境正常

中文输入法的问题值得展开多说一句。WSL2 配合 WSLg 其实可以跑图形界面应用,fcitx5 装好之后需要在 ~/.bashrc 里追加三行环境变量:

export GTK_IM_MODULE=fcitx export QT_IM_MODULE=fcitx export XMODIFIERS=@im=fcitx

然后重启 WSL,调出输入法的快捷键是 Ctrl+Space。如果你是经常在 WSL 里写中文文档的人,这套配置值得提前弄好,不然每次切到 Windows 输入法再切回来非常打断思路。

环境变量 bug 这个问题我遇到过不止一次。有人往 /etc/environment 里写 PATH 时把原本的基础路径覆盖了,结果所有基础的sudo、ls命令都找不到了。修复思路其实很简单:先用绝对路径/usr/bin/sudo调用编辑器,把配置文件改回来,然后重开终端。写环境变量有一个原则:永远是在已有 PATH 的基础上追加而不是覆盖,这是避免这类问题的根本方法。

gcc 安装失败的问题,在刚换完软件源的时候尤其容易出现。原因是换源后本地的 apt 索引和新的源不同步,依赖关系对不上。先sudo apt update刷新索引,再用--fix-broken install修补依赖,基本就解决了。这里有一个小经验:尽量不要在换源之后立刻执行大范围的 apt upgrade,先把索引稳定下来再说,否则容易看到一堆依赖错误。

我个人在实际使用中还有一个习惯:在 WSL 的 /etc/wsl.conf 里开启 systemd 支持。这样 Docker、SSH 这类依赖 systemd 的服务能原生跑起来,不用额外装 supervisor 之类的东西绕路。配置很简单,在 /etc/wsl.conf 的 [boot] 段下加一行systemd=true,然后重启 WSL。很多进阶玩法都是从这一步开始的。

最后再分享一个小技巧:当你觉得 WSL 用久了变慢、磁盘占用异常大的时候,执行wsl --shutdown之后运行optimize-vhd工具压缩 VHDX 文件,或者干脆用wsl --manage <发行版> --set-sparse true启用稀疏虚拟磁盘,能让磁盘文件自动瘦身。Windows 11 上 WSL 的成熟度已经很高,只要地基打好了,后续装 Docker、跑 ROS、刷固件,都能顺风顺水。

需要专业的网站建设服务?

联系我们获取免费的网站建设咨询和方案报价,让我们帮助您实现业务目标

立即咨询