WSL 全攻略：从原理安装到 Docker/CUDA/PyTorch 开发环境配置

你在 Windows 上写代码，却总被一件事卡住——项目要在 Linux 环境里跑，服务器是 Linux，CI 是 Linux，连同事的电脑也是 Linux。装个双系统来回重启太折腾，开个虚拟机又臃肿到影响日常办公。WSL 就是解决这个尴尬的东西：Windows Subsystem for Linux，微软官方做的 Linux 子系统，直接在 Windows 里跑一个原生 Linux 环境，不用装虚拟机、不用换系统，命令行一开就能用。这篇攻略写给三类人：刚听说 WSL 的入门新手、装了 WSL 但网络和路径搞不定的半桶水、想在 WSL 里折腾 Docker、CUDA、PyTorch 和各类 Linux 工具链的开发者。全文按「原理 → 安装 → 配置 → 场景 → 排错」的顺序展开，尽量让你看完就能动手，少走弯路。

1. WSL 到底是什么：先花三分钟搞清楚版本和原理

1.1 WSL 1 和 WSL 2 的核心区别

网上关于 WSL 的教程很多，但不少人装完也不知道自己用的是哪个版本。WSL 有两条技术路线，差别非常大，安装之前一定要弄清楚。

WSL 1 本质是一个系统调用翻译层。它把 Linux 程序发出的系统调用，比如读写文件、创建进程、操作网络套接字，在运行时就地翻译成 Windows 的系统调用。好处是进程直接跑在 Windows 内核之上，启动快，跨文件系统的读写性能特别好；坏处是兼容性不完整，Linux 内核的一些底层机制，比如内核模块、iptables、dmesg，它没法支持。如果你只是想跑几个 Linux 命令行工具，WSL 1 够用，但指望它跑 Docker 或者需要内核特性的软件，就会碰壁。

WSL 2 则完全不同，它是一个轻量虚拟机。微软把 Hyper-V 虚拟化平台和真正的 Linux 内核封装起来，每个发行版跑在一个独立的虚拟磁盘（ext4 格式）里。说是虚拟机，但启动速度和系统开销比传统虚拟机小得多，而且和 Windows 的集成度也高。代价是跨文件系统读写变慢了，从 Windows 盘访问 WSL 里的文件，或者反过来，性能有明显损耗。

我把两者的差异整理成一张表，方便你对照：

1.2 为什么现在建议直接用 WSL 2

结论放在前面：新装环境，一律用 WSL 2，除非你的电脑有特殊限制（比如老旧 CPU 不支持虚拟化，或者公司电脑禁用了 Hyper-V）。原因很简单：WSL 2 才支持 Docker Desktop、CUDA 加速、GPU 推理这些现代开发刚需。你如果是为了跑 PyTorch 训练模型或者做固件分析，拿 WSL 1 基本寸步难行。

另外一个容易被忽略的点是版本更新机制。早年间 WSL 是 Windows 组件，跟着系统更新走，版本老旧的问题很常见。现在 WSL 已经拆成独立组件，可以在管理员 PowerShell 里用wsl --update手动更新，微软的迭代速度明显加快，很多新特性都是优先落在新版 WSL 里的。网上有人讨论「WSL 3.0」这个说法，其实不用太纠结版本号，你只要关注两件事：一是wsl --version能看到当前 WSL 版本，二是保持更新到最新。像 NAT 模式与镜像模式切换、systemd 支持这些功能，都依赖较新的 WSL 版本，版本太旧会出现各种「理论上应该能用但就是不行」的诡异问题。

2. 从零安装 WSL：不同场景下的四套完整方案

2.1 最快路径：wsl --install 一条命令

如果你的 Windows 是 Windows 10 2004（build 19041）以上，或者 Windows 11，安装 WSL 其实只有一步：

打开 PowerShell 或 Windows Terminal，以管理员身份运行，然后敲：

wsl --install

这条命令会自动开启「适用于 Linux 的 Windows 子系统」和「虚拟机平台」两个 Windows 功能，下载并安装 WSL 内核，默认安装 Ubuntu 发行版。整个过程无需手动勾选功能、无需单独下载内核，这是目前最标准的安装姿势。

如果你想指定发行版，比如 Ubuntu 24.04，可以写成：

wsl --install -d Ubuntu-24.04

查看所有可用的发行版列表，用wsl --list --online。装完后系统一般会提示重启，重启完首次启动 Ubuntu，会让你设置一个用户名和密码。这里有个新手容易慌的点：输入密码时终端不显示任何字符，这不是键盘坏了，是 Linux 的安全策略，照常输入然后回车就行。

需要注意，wsl --install看起来简单，但它背后其实做了三件事：启用 Windows 功能、安装内核、安装发行版。如果其中任何一步因为系统版本或者网络环境失败，命令就会报错。最常见的报错之一就是「无法与服务器建立连接」，这通常不是 WSL 本身的问题，而是镜像服务器不可达，后面的离线安装章节会讲替代方案。

2.2 把发行版装到 D 盘：路径迁移三步走

WSL 默认安装在 C 盘，虚拟磁盘文件是ext4.vhdx，随着你安装软件、拉取镜像、构建项目，这个文件会越来越大。C 盘吃紧的 Windows 用户，十个里有八个都会问「能不能把 WSL 装到 D 盘」。答案是能，而且不需要重新装系统，用三个命令就能完成迁移。

操作之前，先确保 WSL 里的数据已经备份。然后执行：

wsl --shutdown wsl --export Ubuntu D:\wsl-backup\ubuntu.tar wsl --unregister Ubuntu wsl --import Ubuntu D:\WSL\Ubuntu D:\wsl-backup\ubuntu.tar

解释一下每步在干嘛：wsl --export把当前整个发行版打包成一个 tar 文件；wsl --unregister删除原有发行版（注意，它会连同 C 盘里的虚拟磁盘一起删掉，所以备份一定要先做）；wsl --import再从 tar 文件还原到指定目录，第二个参数是新的安装位置，第三个参数是备份文件路径。

这里有一个很容易踩的坑：用wsl --import还原的发行版，默认登录用户是 root，而不是你原来的普通用户，而且新创建的 WSL 快捷方式也长得和商店版不一样。解决方法是手动创建一个/etc/wsl.conf文件：

[user] default=你的用户名

保存后执行wsl --shutdown再进 WSL，用户名就恢复正常了。这个方法同样适用于把 WSL 从一台电脑迁到另一台电脑，算是 WSL 迁移的万能钥匙。

2.3 网络环境受限的替代方案：离线安装发行版

在实际场景里，网络环境不理想导致 WSL 安装失败的情况太常见了。现象就是wsl --install -d Ubuntu-24.04卡在下载阶段，或者提示「无法与服务器建立连接」。遇到这种情况，别硬等，直接切换到离线安装。

离线安装的思路是绕过在线分发服务器，从官方渠道手动获取发行版安装包。Windows 上 WSL 发行版本质上是一个.appx（或.msixbundle）格式的应用包，你从官方发布渠道下载到本地后，用 PowerShell 执行：

Add-AppxPackage .\Ubuntu_2204.1.7.0_x64.appx

安装包添加完成后，开始菜单里会出现 Ubuntu 图标，点击运行即可完成首次初始化，设置用户名密码。这个方法对 Windows Server 2022 这类需要离线部署 WSL 容器的场景同样适用：先把 WSL 内核安装包和发行版 appx 一起拷到目标机器上，依次安装，就能在不联网的情况下把 WSL 环境搭起来。

离线安装时注意发行版之间的相互依赖，比如 Ubuntu 的 appx 包名里有 CPU 架构标识，x64 机器别下 ARM64 版本。装完如果启动报错，先确认系统里是否已经装过 WSL 内核，内核缺失的话，发行版启动会直接失败。

2.4 老系统提示“wsl 不是可识别命令”的处理姿势

很多人在 PowerShell 里敲wsl得到这样一句：

wsl: 术语 "wsl" 不会被识别为 cmdlet、函数、脚本文件或可执行程序的名称。

看到这句话先别慌，它只说明两件事：要么你的 Windows 版本太老，根本没有 wsl.exe 这个命令文件；要么 WSL 功能没启用。Windows 10 1903 以前的系统，wsl --install并不存在，需要在「控制面板 → 程序和功能 → 启用或关闭 Windows 功能」里手动勾选「适用于 Linux 的 Windows 子系统」，重启后再去微软官方下载中心获取 WSL 内核安装包和发行版安装包。Windows 10 1903/1909 的用户，可以勾选功能后直接去商店下载发行版，但体验远不如 2004 以上版本。

我的建议很简单：如果系统版本还停留在 Win10 1909 或更早，先更新 Windows 系统。WSL 2 对 Windows 版本的依赖很强，老系统勉强化解出来的环境，后续跑 Docker 或者新版内核功能大概率还要折腾一遍，不如一步到位。

3. 装完先别急着用：网络、内存、磁盘这三个配置必须落地

3.1 网络模式怎么选：NAT 还是镜像模式

WSL 2 默认的网络模式是 NAT。简单说，WSL 里的 Linux 有自己独立的虚拟网卡和 IP 地址，和 Windows 主机的网络不在一个网段，外界访问不到。好处是隔离性好；坏处是你想在 Windows 上访问 WSL 里启动的服务，或者反过来，偶尔会遇到端口不通、IP 对不上这类问题。

其实 WSL 2 做了 localhost 转发，大部分场景是自动的：你在 WSL 里跑一个 Jupyter Notebook 监听 8888 端口，Windows 浏览器直接访问localhost:8888就能打开。但也有限制，比如监听地址绑定了特定 IP、或者需要 IPv6 多播、或者你有多个网卡接口的情况，NAT 转发就会出岔子。

新版 WSL 提供了镜像模式（mirrored）。在用户目录下创建.wslconfig文件，写入：

[wsl2] networkingMode=mirrored

保存后wsl --shutdown，重启 WSL，网络接口就会镜像 Windows 主机的网络，WSL 和 Windows 共享同一套 IP、同一个网段，localhost 自然互通。什么时候用镜像？我自己的经验是：如果你需要在 WSL 里监听 0.0.0.0 并且希望局域网设备直接访问这个端口，或者你日常用 IPv6，镜像模式省心很多；否则默认的 NAT 模式足够，毕竟改动越少，出问题的面越小。

3.2 WSL 里连不上网？先按这个顺序排查

「WSL 内不能联网」是我看到的高频问题，大概率发生在刚安装完成、还没配置任何网络的情况下。常见症状是ping 8.8.8.8通但ping www.baidu.com不通，或者全都超时。

第一步先查 DNS。在 WSL 里执行：

cat /etc/resolv.conf

正常情况下里面有一个nameserver指向虚拟网关地址。如果这个文件是空的，或者指向了奇怪的地址，DNS 解析就会失败，表现就是「能 ping 通 IP 但打不开域名」。解决方法比较粗暴但有效：在 WSL 里编辑/etc/wsl.conf，加入：

[network] generateResolvConf = false

然后手动写/etc/resolv.conf：

sudo sh -c 'echo "nameserver 223.5.5.5" > /etc/resolv.conf'

223.5.5.5 是阿里公共 DNS，国内访问稳定，实测下来效果不错。改完wsl --shutdown再进来，DNS 就不会被 WSL 自动覆盖了。

第二步查 Windows 防火墙和安全软件。WSL 的虚拟网卡流量有时会被防火墙拦掉，尤其某些安全软件会注入网络过滤驱动，导致 WSL 的流量异常。排查时可以临时退出安全软件，或者把 WSL 相关进程加入白名单后重试。有些网络过滤工具还需要在系统层面进行 Winsock 目录重置，这个操作影响面比较大，建议作为最后手段，并且提前备份好网络配置。

最后再说一个几乎万能的办法：wsl --shutdown然后重启 WSL。WSL 2 的虚拟交换机偶尔进入异常状态，重启一下大部分网络问题都能自愈。

3.3 .wslconfig 限制内存和 CPU，避免宿主卡顿

WSL 2 默认会占用宿主机 50% 的内存（或者 8GB，取较小值），如果你只有 16GB 内存，Windows 上还开着浏览器、IDE、微信，再有一个 WSL 里的 Docker daemon 吃内存，系统很快会卡成幻灯片。限制 WSL 资源用量，是每个入门玩家应该学会的第一份配置文件。

在 Windows 用户目录下创建.wslconfig文件（注意文件名开头有个点），内容示例：

[wsl2] memory=6GB processors=4 swap=8GB localhostForwarding=true

参数含义很直白：memory是 WSL 最大可用内存，processors是最大可用 CPU 核数，swap是交换分区大小，localhostForwarding控制 localhost 端口的转发开关。修改完必须wsl --shutdown再重启 WSL 才生效。

我遇到过有人把 memory 设成 12GB 想要「尽兴」，结果 Windows 自己先卡死了。记住一个原则：WSL 不是这台电脑上唯一的应用，Windows 本身、IDE、浏览器都要内存，给 WSL 留个 6GB 左右基本够日常开发了，真跑大训练任务再去调高。

3.4 无活动时 WSL 会不会空转：内存回收与 wsl --shutdown

很多人问：“我开着 WSL 什么程序都不跑，宿主机内存怎么还是被占着？” 这要分两种情况。WSL 2 会在最后一个 Linux 进程退出后自动关闭虚拟机，并回收内存，所以你什么都不跑、关掉所有窗口之后，它一般会自己安静下来。但如果你在 WSL 里启动了常驻进程——数据库、Docker daemon、Redis、开发服务器——这些进程不退，WSL 虚拟机就不会自动关闭，内存自然一直被占用。

想让它立刻安静下来，最简单的命令：

wsl --shutdown

这会强制关掉所有正在运行的 WSL 发行版和虚拟机，释放全部资源。下次需要时再敲wsl进入，又会重新启动。我习惯在睡前或者长时间离开电脑时敲一下这个命令，比让 WSL 在后台默默吃资源放心得多。注意它影响的是所有发行版，不只是当前这个，所以养成「该关就关」的习惯很重要。

4. 把 WSL 真正用起来：开发环境的四个高频场景

4.1 VS Code 无缝接入：Remote - WSL 的正确玩法

装好 WSL 后第一个值得配置的开发工具就是 VS Code。微软做了官方扩展 Remote - WSL，装上之后，你在 WSL 里进入任何目录执行：

code .

VS Code 会自动检测到这是 WSL 环境，在 Windows 窗口里打开编辑器，但左下角会显示一个「WSL: Ubuntu」的标识，说明正在连接远程环境。整个过程像远程开发一样：你的终端是 Linux、解释器是 Linux、调试器也是 Linux，但 UI 还是你熟悉的 Windows 编辑器。

这里有个文件存放的重要建议：项目代码尽量放在 WSL 的 Linux 文件系统里，比如/home/用户名/projects，不要放在/mnt/c/...下。原因是 WSL 2 访问 Windows 盘（跨文件系统）性能很慢，编译、安装依赖、跑测试都会有明显延迟。如果你把项目放在/mnt/c然后抱怨 WSL 慢，那九成是这个原因。真实的 Windows 文件在哪里看？在资源管理器地址栏输入\\wsl$\Ubuntu就能直接浏览整个 WSL 文件系统，文件互拷很方便，但日常读写还是各归各的好。

4.2 Docker Desktop + WSL 2：容器环境的打通与问题

Docker 桌面版在 Windows 上有两种后端：Hyper-V 后端和 WSL 2 后端。现在主推的就是 WSL 2 后端，因为集成度更高、启动更快、资源占用更少。安装 Docker Desktop 后在 Settings 里勾选 Use WSL 2 based engine，然后到 Resources → WSL Integration 里勾选你要集成的发行版，比如 Ubuntu。

设置完成后，你在 WSL 里直接敲docker命令就能连上 Docker daemon，和 Windows 上共享一套镜像和容器。这种「Windows 装 Docker Desktop，WSL 里用 docker 命令」的模式，是我见过的本地容器开发最舒服的组合。镜像默认存在 Windows 侧，WSL 里不用单独装 docker 引擎，也省掉了 Linux 上配置 docker daemon 的繁琐步骤。

在实际使用中有一个高频坑：Docker Desktop 更新之后，WSL 突然跑不起来了，或者 Docker 启动提示 WSL 版本过旧。这个问题后面 5.3 节专门讲，这里先记一个原则：Docker Desktop 的版本要求和 WSL 内核版本强绑定，两者更新不同步就出问题，优先把 WSL 更新到最新版。

4.3 WSL 里装 CUDA 和 PyTorch：深度学习本地调试

WSL 2 支持 GPU 加速，而且是原生支持 NVIDIA CUDA。这对做深度学习的人来说是个巨大福利：不用装双系统，就能在 Windows 的 WSL 里跑 PyTorch、跑 CUDA 程序。具体怎么做？

先说一个最常见的误解：在 WSL 里不需要安装 NVIDIA 显卡驱动，也不需要安装 Linux 版的 CUDA driver。WSL 通过特殊的用户态库，把 Linux 的 CUDA 调用转发给 Windows 的驱动程序。所以你只需要做两件事：Windows 侧安装最新版 NVIDIA 显卡驱动，然后 WSL 里安装 CUDA 工具链。

第一步验证硬件是否可用，在 WSL 里执行：

nvidia-smi

如果输出显示显卡型号和驱动版本，说明 WSL 的 GPU 转发已经就绪。接下来安装 PyTorch。最简单的方式是直接用 pip 安装预编译包，比如 CUDA 12.1 版本：

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

安装完成后做个快速验证：

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

输出True和显卡型号，就说明 CUDA 环境全部打通。至于 CUDA toolkit，很多场景其实不需要全量安装，PyTorch 自带 CUDA 运行时，你只要依赖 PyTorch 提供的包即可。只有当你需要编译原生的 CUDA 扩展或者使用 nvcc 编译器时，才需要额外安装 CUDA Toolkit。

4.4 Linux 工具链的体验：binwalk 等硬件与固件分析工具

WSL 对我来说最爽的价值，是你随手就能用到 Linux 生态里那些专业工具。举一个例子：binwalk，一个嵌入式固件分析和文件提取工具，在固件逆向、路由器分析、摄像头固件解包等领域几乎是标配。在 Windows 下想跑 binwalk，要么装虚拟机，要么用臃肿的模拟环境；但在 WSL 里，一行命令：

sudo apt update && sudo apt install binwalk

装完就能直接用。比如拿到一个固件文件router.bin，用binwalk -e router.bin就能自动扫描并提取其中嵌入的文件系统。整个过程跟在真实 Linux 服务器上的操作完全一致。

这种「WSL 即 Linux 跳板」的思路可以延伸到很多场景：嵌入式开发、系统性逆向、自动化脚本、数据处理，甚至你想在 WSL 里研究一些 JavaScript 引擎（比如 Hermes）的实现源码，配环境都比在 Windows 里顺畅得多。用过一次之后你就会发现，WSL 最大的价值不是替代谁，而是把整个 Linux 工具链完整地搬到了 Windows 旁边。

5. 高频问题排查速查：新手的典型坑，一次讲完

5.1 启动与安装类报错排查表

以下是我在实际操作中被问过最多的几个报错，整理成速查表。先看现象，再对号入座。

这里面我特别想强调虚拟化的问题。很多人的电脑其实支持虚拟化，但 BIOS 里默认关闭了；也有人的系统开了「内核隔离」导致 WSL 2 无法启动。排查顺序建议是：先用任务管理器「性能」标签确认虚拟化是否启用，再检查 Windows 功能里「虚拟机平台」是否打开，最后才去改 BIOS。不要一上来就乱调 BIOS，大部分情况下是 Windows 层面的设置问题。

5.2 apt 源不可用：Ubuntu 镜像源替换实操

「WSL 里 apt update 失败」「无法获取」「无法与服务器建立连接」——这些问题的本质，绝大多数是默认的 Ubuntu 官方源在你当前的网络环境下不可达。解决办法不是重装系统，而是把 apt 源替换成国内镜像源。

先备份原配置，Ubuntu 24.04 之后用的是新的 deb822 格式，配置文件在/etc/apt/sources.list.d/ubuntu.sources；更老的版本则直接修改/etc/apt/sources.list。以 Ubuntu 24.04 为例：

sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak sudo sed -i 's@//.*archive.ubuntu.com@//mirrors.aliyun.com@g' /etc/apt/sources.list.d/ubuntu.sources sudo apt update

我把源替换成阿里云镜像，国内连通性很好。如果你习惯清华源，把mirrors.aliyun.com换成mirrors.tuna.tsinghua.edu.cn即可。替换之后apt update速度会有肉眼可见的提升，后续apt install也不容易再卡住。这个操作是每个 WSL 用户都要过的一道坎，早晚都要做，建议直接养成成文习惯。

5.3 Docker 更新后 WSL 跑不起来，怎么办

Docker Desktop 更新之后 WSL 突然不能用了，这个问题的触发点是：Docker Desktop 新版本对 WSL 内核版本提出了更高要求，而你系统里的 WSL 还停留在旧版。表现可能是 Docker Desktop 弹窗提示 WSL 版本过旧，也可能是 WSL 发行版启动失败。

处理顺序按下面来，基本能覆盖九成情况：

# 1. 以管理员身份打开 PowerShell，更新 WSL wsl --update # 2. 彻底关闭 WSL，释放所有被占用的资源 wsl --shutdown # 3. 重启 Docker Desktop

如果更新完 WSL 仍有问题，检查一下你有没有在.wslconfig里自定义过内核路径：

[wsl2] kernel=C:\path\to\custom\kernel

如果指定了自定义内核，Docker Desktop 新版本可能对新内核有额外要求，稳妥做法是暂时注释掉这行，让 WSL 使用微软官方提供的默认内核。这个坑我见过不止一次，Docker 更新不是问题本身，问题是你用了和默认环境差异太大的配置。

5.4 磁盘膨胀与空间管理：vhdx 压缩

WSL 2 的虚拟磁盘文件ext4.vhdx有个特点：自动增长，但不会自动收缩。你在 WSL 里安装卸载大量软件、拉取 Docker 镜像、编译项目，C 盘上这个文件会越来越大，即使你在 WSL 里把数据删了，文件占用的空间也不会还回来。这就是「C 盘空间神秘消失」的元凶。

压缩 vhdx 的操作可以做成一条标准流程。先备份重要数据，然后：

wsl --shutdown

打开管理员 PowerShell，用 diskpart 工具压缩虚拟磁盘：

diskpart # 进入 diskpart 后执行： select vdisk file="C:\Users\你的用户名\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu*\LocalState\ext4.vhdx" attach vdisk readonly compact vdisk detach vdisk exit

注意 vhdx 的实际路径可能因发行版而异，你可以在资源管理器里搜ext4.vhdx找到准确位置。执行完压缩后，C 盘释放出来的空间通常非常可观，我压缩过一次，释放了接近 20GB。养成定期检查 C 盘空间的习惯，WSL 使用时间长了，这一步早晚用得上。

写到最后，分享一个我个人的体会：WSL 入门最大的门槛不是命令，而是观念转换。很多人习惯用 Windows 的思维方式去套 Linux，遇到问题先想着「装个工具解决」，而不是先想想「这个工具在 Linux 生态里的原生姿势是什么」。WSL 给了一个很低的试错门槛——你随时可以wsl --shutdown关掉一切，随时可以导出备份、删除重来。我建议你装好之后不要急着追求花哨的多发行版配置，先把 Ubuntu 一个环境用熟，把wsl --export、.wslconfig、wsl --shutdown这几个命令变成肌肉记忆，后面无论换电脑、换磁盘、折腾 Docker 还是 CUDA，你都有一整套兜底方案。踩过几次坑之后你会发现，WSL 最值钱的地方，是把 Linux 从「另一个系统」变成了 Windows 桌面上随时可以打开的一个窗口。