一份完整的 WSL2 配置记录我每次换新笔记本都要拿着这套流程跑一遍。现在微信上动不动就有同事问“WSL2 到底怎么装”“为什么我装完一堆报错”与其一次一次截图讲不如把完整的过程、参数和踩过的坑都写下来。这篇文章不讲花架子就从打开 Windows 的“虚拟机平台”开关开始一步步走到 Node.js、Python、Docker、GPU 都能正常干活为止。适合刚接触 WSL2 的新手也适合已经装上但总是出幺蛾子想系统排查一遍的老手。1. 为什么最后选 WSL2先把环境定位搞清楚1.1 WSL2 到底是“模拟器”还是“虚拟机”WSL2 的全称是 Windows Subsystem for Linux 2它和第一代 WSL1 最大的区别就是从一个“API 翻译层”变成了一个“轻量级虚拟机”。WSL1 的做法是把 Linux 的系统调用翻译成 Windows 的系统调用好处是启动快、文件访问直接走 Windows 磁盘但坏处是兼容性不够很多底层调用、Docker、内核模块根本玩不了。WSL2 直接改用真正的 Linux 内核跑在一个轻量虚拟机里虽然文件访问跨系统时会慢一点但兼容性几乎和原生 Linux 一模一样。打个比方WSL1 像是一个翻译员帮你把 Linux 的“语言”翻译成 Windows 的“语言”翻译员水平再高也有词不达意的时候WSL2 更像是在 Windows 里划出一块小房间把一整套真正的 Linux 塞进去窗户就是那个“跨系统文件共享”和“端口转发”。现在绝大多数开发工具、深度学习环境、Docker 容器都是围绕原生 Linux 设计的所以 WSL2 才是正路。这套环境的定位我实际用下来是“日常开发主力 一次性项目试验场”。不用装双系统不用单独配一台 Linux 服务器打开终端就能切到 Ubuntu写完代码可以直接跑坏了重建也方便。尤其是做 Node.js、Python、Go 这类服务端开发或者用 Docker 跑中间件WSL2 的体验已经非常接近“原生 Linux 开发机”了。1.2 WSL1 和 WSL2 的实操差异很多老教程还在讲 WSL1 的用法如果你是从旧文档复制命令很容易踩坑。我列一个自己体会最深的功能差异表对比项WSL1WSL2Linux 内核没有真实内核系统调用翻译完整真实内核运行在轻量虚拟机文件读写性能跨系统访问极快跨系统访问偏慢Linux 内部读写快systemd 支持不原生支持新版默认支持可跑服务Docker基本没法用非常顺滑内核模块、GPU 算力不支持支持 CUDA、IO 等启动速度极快较快秒级启动这里最需要记住的一句是在 WSL2 里操作 Linux 内部的文件大部分场景下都很快但如果你在 /mnt/c 下面跑 node_modules、Python 虚拟环境速度会明显下降。所以后续配环境时项目文件尽量放在 Linux 的文件系统里比如 ~/code 目录。1.3 什么场景不适合 WSL2WSL2 不是万能的。做嵌入式开发需要连 USB 设备、做内核驱动调试、跑大型数据库集群、追求极致 IO 性能时原生 Linux 或者云服务器仍然是更好的选择。还有一个典型场景是“公司要求所有开发环境统一”那得看规范是否支持 WSL2 或者用 Docker 镜像兜底。我自己的结论是WSL2 适合个人开发、学习、试验不适合生产部署、不适合对硬件设备有直接操作需求的场景。把这层定位搞清楚后面配置时就不容易“贪多嚼不烂”。2. 从零开始安装 WSL2分步实操记录2.1 安装前的准备别跳过虚拟化检查先说一个最常见的安装失败原因BIOS / UEFI 中没有开启虚拟化。WSL2 依赖 Windows 的“虚拟机平台”功能如果 CPU 虚拟化被禁用后面的安装会报各种稀奇古怪的错误比如0x80370102或者“请启用虚拟机平台 Windows 功能”。检查方式很简单打开“任务管理器”切换到“性能”选项卡选中“CPU”看右下角“虚拟化”状态必须是“已启用”。如果显示“已禁用”就需要重启电脑进 BIOS/UEFI找到类似Intel Virtualization Technology、SVM ModeAMD CPU的选项打开后保存退出。这一步不做后面代码敲再多也白搭。2.2 用一条命令进入安装流程Windows 10 2004 及以上、Windows 11 系统现在都推荐用命令行安装。以管理员身份打开 PowerShell 或 Windows Terminal执行wsl --install这条命令会自动完成这些事情启用“适用于 Linux 的 Windows 子系统”功能启用“虚拟机平台”功能下载并安装最新 WSL2 内核将 WSL2 设为默认版本安装默认的 Ubuntu 发行版。如果网络状况不好或者你的系统比较旧可能需要手工指定发行版wsl --install -d Ubuntu-22.04也可以在 Microsoft Store 里搜索 Ubuntu 安装但直接从命令行安装有一个好处默认走的是系统组件更新通道版本相对干净不会被 Store 的旧包拖累。我试过 Store 版和命令行版命令行版后续wsl --update管理起来更方便。2.3 老系统或者“WSL1 转 WSL2”失败怎么办如果你本来就是 WSL1想改造成 WSL2但执行了wsl --set-version Ubuntu-22.04 2之后报错或者是 Windows Server 2022 上遇到 WSL1 改不成 WSL2多半是下面几个原因虚拟机平台功能没有启用WSL2 内核没有更新当前系统版本太老需要先安装 Windows 更新。强烈建议按顺序执行一遍dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart然后重启再执行wsl --update wsl --set-default-version 2 wsl --set-version Ubuntu-22.04 2最后用下面命令确认版本wsl --list --verbose输出里VERSION那列应该是2。只要看到1就说明转换没成功继续排查虚拟化和内核问题。2.4 安装后的首次启动与用户创建装完 Ubuntu 之后首次启动会要求你创建一个 Linux 用户名和密码。这里有个容易踩的坑用户名不必和 Windows 用户名一致但密码不要设太复杂到忘记因为 sudo 经常要用。创建完之后建议马上执行一次系统更新sudo apt update sudo apt upgrade -y这一步会花几分钟但能把系统拉到比较新的状态。我建议别跳过很多 WSL2 后续的诡异问题其实都是因为基础包太旧导致的。3. 初始化配置镜像源、Shell、文件互通3.1 换掉默认 apt 源的完整方法国内网络环境下Ubuntu 默认源访问速度不稳定apt update经常卡住。换镜像源是配置环境的第一件正事。Ubuntu 20.04 和 22.04 的源配置路径不同先确认系统版本cat /etc/os-release如果是 Ubuntu 22.04编辑/etc/apt/sources.list。老版本只需要改动开头的archive.ubuntu.com为镜像站地址。以清华源为例替换后的文件头部内容大致是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 cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo vim /etc/apt/sources.list改完再执行sudo apt update这一步做完你会发现下载速度明显上来了。国内常见的镜像源有清华、阿里云、中科大选一个稳定的即可。不建议同时混用多个源容易遇到依赖版本不一致的问题。3.2 基础工具包与 Shell 体验我会在配置任何语言环境之前先把基础工具装齐sudo apt install -y build-essential git curl wget unzip zip vimbuild-essential里包含了 gcc、g、make 这些编译工具后面装很多 Python 包、Node.js 原生模块时都用得到。提前装好能少踩一半编译报错的坑。Shell 方面如果你喜欢 zsh可以装zsh和oh-my-zsh但这不是必需项。我个人的体会是WSL2 里最重要不是炫酷的终端主题而是快速的启动响应和稳定的路径转换。bash 完全够用装了图形美化反而占用额外的配置时间。Windows Terminal 的配色默认就挺耐看把默认终端设置为 Windows Terminal 后打开 WSL 的体验已经很舒服了。3.3 Windows 和 WSL2 之间怎么互访文件WSL2 和 Windows 的文件互通有两个方向在 Windows 资源管理器地址栏输入\\wsl$\Ubuntu-22.04\home\你的用户名就能直接看到 Linux 里的文件在 WSL2 里访问 Windows 盘符路径是/mnt/c/Users/你的Windows用户名/...。如果需要在当前目录用 Windows 资源管理器打开可以直接执行explorer.exe .或者用wslpath做路径转换wslpath C:\Users\admin\Desktop输出是/mnt/c/Users/admin/Desktop。反过来如果要在 Linux 下用 Windows 程序处理文件也可以直接调用notepad.exe、code等命令。有个细节必须强调跨文件系统操作会慢特别是大量小文件的读写。比如把 Windows 目录里的 node_modules 拷贝到 Linux 里最好先把压缩包传过去再解压而不是直接在/mnt/c目录下面跑npm install。这是 WSL2 使用中最容易被忽视的性能杀手。3.4 网络和代理配置记录WSL2 的网络默认是 NAT 模式系统会分配一个内部 IP。查看 IP 用hostname -IWindows 主机则可以通过/etc/resolv.conf里的 nameserver 找到。不过现在新版 WSL2 默认开启了 localhost 转发你在 Windows 浏览器里访问http://localhost:8080通常可以直接打通 WSL2 里监听的 8080 端口。这个特性叫localhostForwarding如果遇到访问不了的情况可以检查/etc/wsl.conf里的配置或者稍后在.wslconfig中统一设置。开发时经常需要设置 HTTP 代理。在 WSL2 里配置HTTP_PROXY、HTTPS_PROXY环境变量时不能用 localhost要写 Windows 主机的实际 IP因为 localhost 在 WSL2 里指向的是 Linux 自己。简便做法是每次启动时用ip route show | grep default获取网关 IP 作为代理地址。不过代理问题因网络环境而异具体参数我不展开记住“localhost 不等于主机”这条原理就能少走弯路。4. 开发环境配置实录Node.js、Python、Docker、GPU4.1 Node.js 环境用 nvm 而不是直接 apt 安装很多教程会直接sudo apt install nodejs但这样装出来的 Node 版本往往偏旧而且后续升级麻烦。我强烈建议用 nvm 来管理理由很简单你可以随时切换 Node 版本不用把系统搞乱。安装 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后新开终端或执行source ~/.bashrc然后nvm install 18.20.4 nvm alias default 18.20.4 node -v npm -v第一次执行npm install时建议把 npm 源切到国内镜像速度提升非常明显npm config set registry https://registry.npmmirror.com我实际上遇到过一个问题在 WSL2 里跑npm install时如果项目放在/mnt/c下文件监听和编译速度会很慢。放到~/code下之后整个体验顺滑很多。如果你用的是 VS Code直接打开 WSL 窗口VS Code Server 会自动装到 Linux 环境里调试 Node 项目几乎零配置。4.2 Python 环境Conda 方案最省心Python 环境配置是另一个高频需求。我的原则是别直接用 apt 装 Python也别手动往系统 Python 里 pip 包。做数据分析和深度学习时用 Miniconda / Anaconda 管理环境最省心。先下载安装脚本wget https://repo.anaconda.com/archive/Anaconda3-2024.06-1-Linux-x86_64.sh bash Anaconda3-2024.06-1-Linux-x86_64.sh安装完成后执行source ~/.bashrc conda create -n py310 python3.10 conda activate py310Conda 环境默认源在国外可以按需替换为清华 conda 镜像。pip 源也可以单独配置pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple一个常见疑问是“WSL2 里能不能装 PyTorch”。答案是可以而且 GPU 版也能跑前提是 Windows 侧显卡驱动装好。这个我在后面 GPU 小节详细说。4.3 Docker 远程开发方案两种路线怎么选Docker 是 WSL2 的一大核心亮点。很多人来问“docker 安装前要安装 WSL2 吗”如果用的是 Docker Desktop for Windows答案是“会帮你装但安装前强烈建议确保虚拟化开启”。Docker Desktop 在 Windows 上默认用 WSL2 后端所以 WSL2 和 Docker Desktop 是协同关系。路线一安装 Docker Desktop for Windows然后在设置里把“Use the WSL 2 based engine”打开再在 Resources - WSL Integration 里勾选你要用的发行版。这样你在 WSL2 的终端里直接敲docker ps就能用无需在 Linux 里单独装 Docker。这是最省事、兼容性最好的路线。路线二不装 Docker Desktop直接在 WSL2 里安装 Docker Engine适合不想开启桌面软件、希望环境更纯粹的场景。安装命令curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh sudo usermod -aG docker $USER新版本 Ubuntu 默认开 systemdDocker 服务可以这样启动sudo systemctl enable docker sudo systemctl start docker如果你是跑远程开发环境还想用 VS Code 的 Dev Containers那建议直接走 Docker Desktop 路线因为插件会自动管理容器链接体验很统一。我自己在本地跑中间件时经常这样组合Windows 上装 Docker DesktopWSL2 里写代码容器起在 WSL2 后端里端口直接通过 localhost 转发访问。4.4 GPU 与 CUDAWSL2 里能不能用显卡关于 WSL2 和 GPU网上问得最多的一句话是“WSL2 英伟达驱动生效吗”。答案先说清楚生效只要你 Windows 侧安装了支持 WSL 的 NVIDIA 驱动。这个驱动不是装在 Linux 里的而是装在 Windows 里WSL2 启动时会自动把 GPU 能力穿透给 Linux 侧。所以你要做的第一件事是在 Windows 里更新显卡驱动到较新版本然后进 WSL2 执行nvidia-smi如果能看到显卡信息和驱动版本说明 GPU 已经被 WSL2 认到了。接下来如果需要 CUDA 编程或深度学习框架可以在 WSL2 内安装 CUDA Toolkitwget 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-toolkit不过对大多数用户来说直接用 PyTorch 的预编译包就够了它会自动拉起 CUDA runtimeconda activate py310 pip install torch torchvision然后验证import torch print(torch.cuda.is_available())如果输出 True说明 CUDA 环境已经通了。实际经验告诉我最常导致torch.cuda.is_available()返回 False 的不是 WSL2 配置问题而是 Windows 驱动太旧或者安装的是 CPU 版本的 PyTorch 包。排查顺序就是先nvidia-smi再检查 PyTorch 包来源。5. 常见问题与排查技巧5.1 虚拟化和 WSL1 转 WSL2 的报错排查现象可能原因解决办法安装时报0x80370102BIOS 虚拟化未开启进 BIOS 打开 Intel VT-x / AMD SVMWslRegisterDistribution failed with error: 0x8007019eWSL2 内核未安装执行wsl --updatewsl --set-version从 1 转 2 失败虚拟机平台未启用补开VirtualMachinePlatform功能并重启系统提示“请启用适用于 Linux 的 Windows 子系统”未启用 WSL 功能执行dism.exe命令启用两个功能还有一个小技巧重置网络状态有时能解决 WSL 起不来的问题wsl --shutdown netsh winsock reset重启后再试。5.2 localhost 访问不通与端口冲突WSL2 默认的 localhost 转发一般很稳但如果你自己改了.wslconfig里的localhostForwardingfalse或者防火墙规则异常就会访问不了。先用下面命令检查监听状态ss -tlnp | grep 8080确认服务监听在0.0.0.0或*上再回到 Windows 浏览器测试。如果还是不行可以临时在 Windows 侧执行netsh interface portproxy add v4tov4 listenport8080 listenaddress127.0.0.1 connectport8080 connectaddressWSL2 IP不过这只是临时方案最根本的解决办法还是检查是否误关了端口转发或者 Windows 防火墙拦了端口。WSL2 的网络模式有时也会因为升级而变化动手改配置前先记录当前 IP 和监听端口。5.3 磁盘空间与 VHDX 文件瘦身用久了会发现 WSL2 的虚拟磁盘文件ext4.vhdx越来越占空间。原因很简单你删了文件但虚拟磁盘不会自动收缩。这跟物理磁盘不一样删除只是把块标记为空磁盘文件本身并不缩小。解决办法完全关闭 WSL2然后用 diskpart 压缩 VHDX。wsl --shutdown diskpart进入 diskpart 后执行select vdisk fileC:\Users\你的用户名\AppData\Local\Packages\CanonicalGroupLimited...\LocalState\ext4.vhdx attach vdisk readonly compact vdisk detach vdisk exit路径里的具体目录取决于发行版安装来源建议先用资源管理器搜索ext4.vhdx确定实际位置。执行完 diskpart 压缩再看文件大小通常能瘦不少。如果想彻底迁移发行版到其他磁盘用wsl --export Ubuntu-22.04 D:\wsl-backup.tar wsl --unregister Ubuntu-22.04 wsl --import Ubuntu-22.04 D:\wsl\Ubuntu D:\wsl-backup.tar --version 2这里有个坑wsl --import之后默认用户会变成 root需要手动指定原用户名。建议在导出之前先写好/etc/wsl.conf[user] default你的用户名然后wsl --shutdown重启一次。这样迁移后默认用户依旧是原来的。5.4 内存和 CPU 限制WSL2 默认会使用 Windows 可用内存的一定比例如果机器配置不高或者运行多个发行版会感觉内存被吃紧。可以通过在用户目录下创建.wslconfig来限制资源文件位置在C:\Users\你的用户名\.wslconfig内容示例[wsl2] memory8GB processors4 swap4GB localhostForwardingtrue改完之后执行wsl --shutdown重启 WSL2 才生效。注意这里设置的是 WSL2 虚拟机的总资源如果你同时跑多个发行版它们共享这份资源。我见过不少人在这里踩坑设置了过小的内存Docker 里跑几个容器直接 OOM。建议至少给 WSL2 4GB 内存起步跑深度学习或者多容器时 8GB 以上。5.5 发行版卸载重装与离线导入如果发行版内部被搞乱了最简单的恢复方式就是重装wsl --unregister Ubuntu-22.04注意这个命令会删除该发行版的所有 Linux 内部文件无法恢复。执行前如果里面有重要代码先备份。对于无法通过正常商店渠道安装的发行版比如特定版本或者离线环境可以先在一台能上网的机器上执行wsl --export 发行版名 backup.tar再把 tar 文件拷贝到目标机器执行 import。国内如果遇到下载 Ubuntu 失败也可以从镜像站获取 rootfs tar 包。整个过程和普通 tar 导入一样只是路径和发行版名要对应好。6. 最后分享一个用得上的小经验这套 WSL2 配置方案我前后换过三台电脑从 Windows 10 到 Windows 11从 Intel 到 AMD基本流程都一样。个人最深的体会是WSL2 强大的地方不是“模拟一个 Linux”而是让你在不用切换系统的情况下把 Linux 开发环境的体验和 Windows 的日常使用揉在一起。编译器、包管理器、容器这些重型工具跑在 Linux 侧而 Office、浏览器、输入法这些日常工具留在 Windows 侧。还有一个经常被忽略的小技巧如果觉得每次进 WSL2 还要想“这个项目放哪个目录”可以在~/.bashrc里加一条友好的路径切换函数。比如我习惯做一件事echo alias cccd ~/code ~/.bashrc source ~/.bashrc看起来简单但实际开发里避免项目文件不小心被放到/mnt/c下面能减少大量莫名其妙的性能问题。WSL2 的坑大部分不是功能缺失而是 Windows 和 Linux 两边文件系统交互时造成的性能损耗把工作目录固定好问题就少了一半。配置过程中如果遇到报错不要急着删了重装。优先看wsl --status和wsl --list --verbose这两条命令输出的信息比什么日志都直观。再不行就去查 Windows 事件日志里 WSL 相关条目多数问题都能锁定到虚拟化、驱动或网络三个方向上。希望这份记录能帮你少走点弯路。