最近又有好几个同事在群里问Windows 机器上想跑 Linux 环境到底怎么装项目里有台 Windows 电脑要跑 Linux 下的脚本、装 Docker、用 VSCode 连上去写代码最省事的方案就是 WSL也就是适用于 Linux 的 Windows 子系统。我自己从 WSL1 一路用到 WSL2中间踩了不少坑这篇就把从零安装、常见报错、装完必做的优化一次说清楚打算在 Windows 上用 Linux 的朋友可以照着抄作业刚入门的也能当成一份避坑手册。1. WSL 是什么为什么 Windows 用户需要一个 Linux 子系统1.1 从双系统到虚拟机再到“系统里套系统”在没有 WSL 之前想在 Windows 上使用 Linux 环境一般只有三条路装双系统开机时选择进入 Windows 还是 Linux缺点是切换系统必须重启来回折腾很伤效率。装虚拟机比如 VMware 或 VirtualBox优点是隔离完整缺点是资源占用高、启动慢而且图形界面和文件共享都绕。找一台单独的 Linux 服务器远程连过去用适合团队协作但不适合本地快速验证。WSL 的出现改变了这个局面。微软在 Windows 里直接提供了一层 Linux 兼容运行环境你不需要额外装虚拟机软件也不需要重启系统打开终端输一条命令就能进入一个完整的 Ubuntu 或 Debian 环境。它本质上是一个运行时不是一个完整桌面系统但对于绝大多数开发者来说我们要的本来就是那个“能跑命令、能装软件、能执行脚本”的 Linux 环境而不是那个需要维护的桌面。1.2 WSL1 和 WSL2到底选哪个WSL 有两个大版本我建议新用户直接使用 WSL2但如果遇到某些历史遗留的问题理解两者区别仍然很重要。对比项WSL1WSL2架构系统调用翻译层轻量级虚拟机Linux 内核没有完整内核有完整 Linux 内核磁盘 I/O 性能跨文件系统表现一般Linux 文件系统内性能更好系统调用兼容性部分软件无法运行几乎完全兼容Docker 支持不支持原生支持GPU 加速不支持支持 CUDA内存占用低略高可配置上限我最早用 WSL1 的时候最明显的痛点是 node_modules 安装偶尔会报奇怪错误后来换成 WSL2所有问题基本消失。如果你只是简单跑几个 Linux 命令WSL1 也能凑合但只要涉及 Docker、数据库、CUDA、内核模块这类场景一定选 WSL2。现代 Windows 上默认就是 WSL2除非你手动指定否则不用过分纠结。1.3 什么场景下值得装 WSL不是所有人都需要 WSL但下面这几类人装了基本不亏学习 Linux 命令的新手拿 WSL 当练习场不会把电脑搞坏。本地开发使用 Linux 工具链的工程师比如跑 Python 脚本、Node 服务、Go 项目。需要在 Windows 上使用 Docker 的团队Docker Desktop 的后端就是 WSL2。做数据处理或 AI 相关工作的同学WSL2 支持 GPU 直通可以跑 CUDA。需要频繁操作 Linux 命令但不想维护虚拟机的运维同学。如果你的目标是深度使用 Linux 桌面、长期跑图形界面那我建议还是用实体机或虚拟机更合适。WSL 的定位是“子系统和开发环境”不是“替代 Linux 桌面”。2. 安装前检查Windows 版本、虚拟化这些必须确认2.1 你的 Windows 版本到底够不够WSL2 对 Windows 版本有硬性要求最简单的判断标准是Windows 10 版本 2004内部版本 19041及以上或者 Windows 11 任意版本。怎么查看按下 Win R输入 winver在弹出的窗口里可以看到系统版本和内部版本号。如果你的系统低于这个版本也不是完全没法装但过程会复杂很多需要手动启用“适用于 Linux 的 Windows 子系统”和“虚拟机平台”两个 Windows 功能还要下载内核更新包。所以如果你手里是一台很旧的 Windows 10建议先把系统更新推到 2004 以上再动手省得走弯路。2.2 CPU 虚拟化到底开没开WSL2 是基于轻量虚拟机的所以必须依赖 CPU 的虚拟化功能。检查方法很简单按 Ctrl Shift Esc 打开任务管理器切换到“性能”选项卡点击 CPU看右下角“虚拟化”这一项如果是“已启用”那就没问题。如果是“已禁用”需要进 BIOS 开启。不同品牌 BIOS 界面不一样但核心入口都差不多开机按 Del 或 F2 进入 BIOS找到 Advanced / CPU Configuration / Virtualization 之类的选项把 Intel VT-x 或 AMD SVM 打开保存重启。这一步是很多新手第一次装 WSL2 报错 0x80370102 的直接原因遇到这个错先回来检查虚拟化。2.3 安装前容易被忽略的几个小细节正式安装前我还建议你做三件事能省掉后续很多麻烦确保磁盘空间充足至少留出 10GB 给 Linux 发行版装完开发工具链之后空间消耗会很快。所有涉及安装的命令都建议用管理员身份的 PowerShell 或 CMD 执行否则容易遇到权限不足的报错。确认 Windows 已经打了最新更新尤其是补丁版本比较老的机器WSL 经常在系统更新后才有更好的兼容性。另外提醒一点如果你电脑上已经装了 VMware、VirtualBox 或 Hyper-V它们和 WSL2 在功能上会有一些交叉。WSL2 默认会在需要时开启“虚拟机平台”功能某些情况下可能和其他虚拟化软件争夺同类资源如果遇到冲突优先考虑把实在用不上的第三方虚拟机软件卸载。3. 一行命令装好 WSL标准安装流程全解析3.1 最省事的安装方式wsl --install如果你的 Windows 版本满足要求安装 WSL 真的只需要一条命令。右键开始菜单选择“终端(管理员)”或“Windows PowerShell(管理员)”输入wsl --install这条命令会自动做几件事启用需要的 Windows 功能、下载并安装 WSL2 内核、安装默认的 Ubuntu 发行版。执行过程中会提示你重启电脑重启后继续完成初始化和用户配置。整个过程基本不需要手动操作是当前官方推荐的方式。如果你想安装指定的发行版而不是默认的 Ubuntu可以先看有哪些选择wsl --list --online输出会显示 Debian、Ubuntu、Kali Linux 等多个发行版。确定好名字后执行wsl --install -d Ubuntu-22.04这里有个小经验如果你的目的是普通开发和日常使用Ubuntu 22.04 LTS 是最稳妥的选择安全更新时间长社区资料多遇到问题搜索答案容易。3.2 首次启动创建用户不是创建管理员重启电脑后第一次打开 WSL 终端系统会提示你为 Linux 环境创建一个用户名和密码。这里的用户名可以和 Windows 用户名不同我建议用一个简短的全小写英文名别带特殊字符否则后面很多工具链配置容易出问题。注意一个细节这个用户会被自动加入 sudo 组但普通操作不需要加 sudo只有安装软件、修改系统文件时才需要。创建完用户后先执行一次sudo apt update这个命令会拉取软件包索引第一次可能会有点慢尤其是在网络环境不理想的时候。如果特别慢可以先看 5.1 节的换源操作换完源再执行 apt update。3.3 日常进出 WSL 的方式WSL 装好以后你会发现自己和这个 Linux 环境打交道的方式比想象中简单直接在 Windows Terminal 或 PowerShell 里输入 wsl回车就进入默认 Linux 发行版。输入 exit 退出回到 Windows 环境。同时装了多个发行版时用 wsl -d Ubuntu-22.04 指定进入哪个系统。用 wsl --shutdown 彻底关闭 WSL 虚拟机一般在磁盘清理或配置生效时需要。还有一个高频操作在 WSL 里直接输入 explorer.exe .会把当前 Linux 目录在 Windows 文件资源管理器中打开方便传输文件。3.4 装完之后先别急着用先更新 WSL 本体很多人装完 WSL 只盯着 Linux 发行版更新忽略了 WSL 本身也是可以升级的组件。执行一下wsl --update这个命令会把 WSL 运行时更新到最新版。我遇到过有人一直用旧版 WSL 跑 Docker时不时出现莫名奇妙的网络问题后来更新了 WSL 本体就恢复正常了。所以在开始折腾各种环境之前把这一步当成标准流程。4. WSL 安装慢、报错、版本太旧常见问题排查实录4.1 wsl --install 卡住不动或下载太慢这个是我看到最多的抱怨执行 wsl --install 之后一两个小时内没有反应或者显示下载进度但速度很慢。原因通常是安装过程需要从远程服务器拉取内核和发行版包一旦网络连接不稳定整个流程就会变得像卡住了一样。我的建议是先等 10 到 15 分钟如果进度条完全没有变化按 Ctrl C 中断然后重新执行 wsl --install有时候重试几次能完成。如果反复失败就不要硬等了走离线安装路线详见 4.3 节。另外把 Windows 的地区设置改成“全球”或非中国地区有时候也能让商店服务和文件下载更顺畅这个方法在部分网络环境下实测有效。注意这里说的“顺畅”是指软件源连接成功率不涉及任何第三方工具正规软件源本身在国内是可以直连的。4.2 一直提示 WSL 版本太旧怎么办如果你启动 WSL 时看到类似 “your version of windows subsystem for linux (wsl) is too old. run the command wsl --update” 的提示说明本地的 WSL 运行时版本太老微软已经不再通过系统更新去分发新版本而是改成了独立包方式。解决办法很简单执行wsl --update如果这个命令也报错或者提示没有该命令说明你的 WSL 运行时实在太老可以手动去微软官方 GitHub 仓库下载最新的 WSL 安装包MSI 格式下载后双击安装再重新打开终端。这是官方提供的更新路径不需要第三方工具。装完 MSI 后建议重启电脑然后再次执行 wsl --version 确认版本号已经变化。4.3 离线安装 WSL 和 Ubuntu网络差也能搞定如果 wsl --install 反复失败离线安装是我目前最推荐的二号方案尤其在网络条件差的环境下比反复重试靠谱得多。第一步是更新 WSL 本体去微软官方 GitHub 仓库找到 “Windows Subsystem for Linux” 的 Release 页面下载最新的 .msi 安装包双击安装即可。第二步是安装 Linux 发行版。进入微软商店的 Ubuntu 页面找到 Ubuntu 22.04.3 LTS 这个版本通过浏览器打开商店链接后会有一个“获取”按钮点击后有时会弹出让你安装“应用安装程序”的提示顺着完成即可。如果你在商店里也下载不动就找一台网络状况好的电脑把 Ubuntu 的 .appx 或 .msixbundle 离线包拷贝过来然后在 PowerShell 里执行Add-AppxPackage -Path 下载的离线包路径安装完成后开始菜单里会出现 Ubuntu 图标点击运行就会进入初始化流程创建用户后就能正常使用。这个方法不依赖商店下载速度是离线折腾 WSL 最常用的一条路。4.4 常见 WSL 错误码速查表这些年帮人排查 WSL 问题遇到最多的就是下面几个报错我整理成一张表方便你对照处理错误码常见含义处理思路0x80370102CPU 虚拟化未开启或虚拟机平台未启用进 BIOS 打开虚拟化并在 Windows 功能里启用“虚拟机平台”0x8007019eWSL 内核缺失或版本过旧执行 wsl --update或者手动安装官方内核更新包0x80070003系统找不到指定路径检查 Windows 版本是否满足确认安装位置没有异常0x80070005权限不足用管理员身份的 PowerShell 重新执行安装命令0x80070020资源冲突可能与其他虚拟化软件冲突关闭 VMware/VirtualBox 等服务重启后再试WSL 服务无法启动Windows 服务里相关项被禁用以管理员身份运行 services.msc找到 LxssManager 等服务并设置为自动启动遇到错误码先别急着搜贴吧或找人问按表里的思路排查一遍成功率已经很高了。4.5 安装完发现没有 WSL2 模式有些人装完后运行 wsl -l -v发现版本还是 WSL1或者一直没有升级到 WSL2。可以在 PowerShell 里手动指定wsl --set-version Ubuntu-22.04 2如果提示需要启用“虚拟机平台”功能先去 Windows 功能里勾选然后重启再重新执行转换命令。转换过程可能需要几分钟耐心等它走完。你也可以直接把默认版本设定为 WSL2这样以后安装新发行版都默认使用 WSL2wsl --set-default-version 25. 装完 WSL 先别急着写代码这五项配置更关键5.1 更换软件源apt 下载不再慢到怀疑人生装完 WSL 第一件事我强烈建议先换软件源也就是把 apt 默认连接的软件仓库地址换成国内开源镜像站。默认的官方源在部分网络环境下速度不稳定而镜像站的下载速度通常能翻好几倍。先备份原来的源文件sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak然后编辑源文件Ubuntu 22.04 可以参考下面的内容sudo nano /etc/apt/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-security main restricted universe multiverse如果你用的是阿里云镜像把域名 mirrors.tuna.tsinghua.edu.cn 换成 mirrors.aliyun.com 即可。不同 Ubuntu 版本的代号不一样22.04 是 jammy20.04 是 focal别写错。替换完后执行sudo apt update看到下载速度明显提升就说明生效了。5.2 在 VSCode 里直接写 WSL 代码很多人在 Windows 上装 VSCode然后在 WSL 里打开项目最顺畅的方式是安装 Remote - WSL 插件。这个插件安装后你在 WSL 终端里进入一个项目目录输入code .VSCode 会自动以“WSL 模式”打开这个目录。此时 VSCode 的终端、调试器、任务运行器都会在 Linux 环境里执行但界面还是你熟悉的 Windows 软件文件树、代码补全、git 面板都正常使用。一个小经验给 WSL 里的项目配置 VSCode 扩展时部分扩展需要在 WSL 侧安装。第一次使用 code . 时VSCode 会在右下角弹出提示让你在 WSL 中安装推荐扩展选择“在 WSL 中安装”即可。Python、Remote - SSH、Docker 这类扩展都有 WSL 版本别装错到本地 Windows 侧。5.3 终端和字体把体验调到接近 macOS 的水平WSL 默认的终端窗口比较朴素让人没有那么强的码字欲望。我目前的方案是Windows Terminal Cascadia Code 字体 自定义配色。Windows Terminal 在微软商店可以直接安装安装后把它设为默认终端这样打开 WSL 时界面就统一了。字体方面Cascadia Code 是微软官方开源等宽字体自带连字显示效果清晰JetBrains Mono 也是很好的选择两者都能在各自官网免费下载。配置方法是在 Windows Terminal 的设置里把字体名称修改为 Cascadia Code 或 JetBrains Mono字号习惯用 12 或 14。如果你想要更舒服的 Linux 命令行体验可以给 WSL 里的默认 shell 换成 zsh配合 oh-my-zsh 常用插件提示符会好看很多但这个属于进阶优化不是必须装完能用顺手再折腾也不迟。5.4 WSL 里跑 Docker 和 CUDADocker 在 Windows 上通常用 Docker Desktop而 Docker Desktop 的 Linux 容器后端就是 WSL2。安装完 WSL 后再去官网下载 Docker Desktop安装时勾选 “Use WSL 2 based engine”Docker 就会在 WSL2 虚拟机里运行。至于 CUDAWSL2 支持 GPU 直通你不需要在 WSL 里装传统 Linux 显卡驱动只需要在 Windows 侧安装 NVIDIA 驱动程序然后进入 WSL 安装对应版本的 CUDA Toolkit for WSL就可以正常调用 GPU。注意这里一定要选 WSL 版本的 CUDA Toolkit不要选原生 Linux 版本否则会出现版本不匹配的问题。我实测跑过轻量模型推理和 PyTorch 训练在 WSL2 里的 GPU 性能和原生 Linux 几乎没差别日常开发完全够用。5.5 文件互访机制别把跨盘符读写当默认路径WSL 和 Windows 之间可以互相访问文件但性能差异很大Windows 访问 WSL 文件在文件资源管理器地址栏输入 \wsl.localhost\Ubuntu-22.04\home\用户名。WSL 访问 Windows 文件Linux 路径下挂载在 /mnt/c、/mnt/d 等位置。表面看起来很方便但跨文件系统读写非常慢。如果你把一个 npm 项目放在 Windows 的 D 盘然后在 WSL 里通过 /mnt/d 去运行 npm install安装速度会慢到让人崩溃因为文件系统转换消耗太大。正确做法是所有需要被 Linux 工具处理的代码、依赖和缓存都放在 WSL 的 Linux 文件系统内也就是 /home/用户名 下面然后用 Windows 侧的资源管理器通过 \wsl.localhost 去访问。这个习惯越早养成后面踩的坑越少。6. 高频踩坑行为来自真实使用记录6.1 解压中文文件乱码从 Windows 下载的 zip 压缩包拿到 WSL 里解压经常出现文件名乱码原因是压缩包内文件名编码是 GBK而 Linux 默认按 UTF-8 解码。解决办法是安装 unar 或用 7z 处理sudo apt install unar unar 中文文件.zip如果你用的 unzip可以尝试指定编码unzip -O GBK 中文文件.zip注意 unzip 的 -O 参数需要较新版本才支持老版本会提示无效选项这时直接装 unar 更省事。6.2 DNS 配置总被重置WSL2 的网络配置默认由系统自动生成每次重启 WSL 后/etc/resolv.conf 都会被覆盖成默认内容。如果你手动修改过 DNS 配置比如换成公共 DNS 地址重启后会发现又变回去了。想要永久生效需要修改 /etc/wsl.conf[network] generateResolvConf false然后重启 WSLwsl --shutdown重新进入后手动编辑 /etc/resolv.conf写入你需要的 DNS 配置。这样系统就不会再覆盖你的设置了。6.3 VHDX 磁盘文件越来越大WSL2 的虚拟磁盘文件 ext4.vhdx 存放所有 Linux 文件它会自动扩容但不会自动缩水。删了大量文件后vhdx 文件体积可能还是十几 GB。这时可以手动收缩在 Windows 终端里执行wsl --shutdown diskpart在 diskpart 里选择磁盘文件select vdisk fileC:\Users\你的用户名\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu22.04LTS_xxx\LocalState\ext4.vhdx attach vdisk readonly compact vdisk detach vdisk exit操作完成后 vhdx 文件会明显变小。这里的路径不一定固定搜索包名里的 LocalState 目录就能找到对应文件。要注意的是执行 compact 前务必确保 WSL 完全关闭否则文件被占用会失败。6.4 默认用户跑到了 root想切回来我自己有过一次手滑操作把 WSL 默认用户改成了 root后面每次打开终端都是 root很不安全。想改回普通用户有两个办法方法一打开 CMD进入对应发行版的可执行文件目录执行ubuntu2204 config --default-user 你的用户名方法二在 /etc/wsl.conf 里追加[user] default你的用户名然后执行 wsl --shutdown 重启 WSL 生效。注意 wsl.conf 只对 WSL2 生效WSL1 不识别这个配置。6.5 端口访问与宿主机互通WSL2 里的服务默认和 Windows 共享 localhost。也就是说你在 WSL 里执行 python app.py 启动了一个 8000 端口的服务Windows 浏览器里直接访问 localhost:8000 就能打开非常方便。但如果你想从局域网内其他设备访问这个服务那就需要额外设置端口转发和防火墙规则了因为 WSL2 的 IP 地址是虚拟网络分配的不是固定的。这个场景我实际用得不多真要对外提供服务我还是建议把服务部署到正式 Linux 服务器或容器环境WSL 更适合当本地开发调试环境。6.6 Windows 创建的脚本到 WSL 里报错如果你用记事本或 VSCode 在 Windows 下写了一个 .sh 脚本然后拷到 WSL 里执行可能会遇到 -bash: xxx.sh: /bin/bash^M: bad interpreter 这类报错原因就是文件换行符是 Windows 的 CRLFLinux 不认识。处理方式很简单sed -i s/\r$// 脚本名.sh执行后再运行脚本就正常了。永久解法是在 VSCode 里把“文件 - 首选项 - 设置”中的 files.eol 设置为 \n这样新文件默认就是 LF 换行。6.7 所有发行版共用一个“默认发行版”的坑如果你装了好几个 WSL 发行版并且直接用 wsl 命令进入进入的是默认发行版而不是你脑子里想的那个。查看默认发行版可以执行wsl -l -v带有“默认”标记的就是当前 wsl 命令会进入的系统。想修改默认发行版wsl --set-default Debian这样以后直接敲 wsl 就进入 Debian。如果只是临时进入某个系统指定 -d 参数即可不用频繁修改默认设置。把 WSL 从零装到顺手的完整流程基本就是这样。我个人在实际使用中最深的体会是WSL 的坑大多不是某个复杂配置而是文件系统路径、编码和网络这几个基础问题上把 5.1 到 5.5 这些基础配置一次做到位后续开发会顺畅很多。最后再分享一个小技巧把 apt、git、Node、Python 常用工具的安装命令写成一个 install.sh 脚本放在自己的配置仓库里哪天重装系统或换了新电脑WSL 装好后直接跑一遍脚本整个开发环境就回来了省去一个个手动配置的时间。