Windows 11 + WSL2 开发环境搭建全教程：国内镜像、VS Code、Docker 与代理排障（2026）

本文最后核对于 2026 年 8 月 6 日，适用于 Windows 11；Windows 10 新版本也能参考，但镜像网络、自动代理等部分能力可能不可用。

文中的外链图片优先采用 Microsoft Learn、VS Code 官方静态资源，避免使用在中国大陆访问波动较大的 GitHub Raw 图床。

很多开发者在 Windows 上装完一堆编译器、Python、Node.js、Docker 和命令行工具后，最终会得到一套“能跑但很难维护”的环境：PATH 相互污染、同一依赖装了两份、Windows 与 Linux 行尾冲突、Docker 占满内存，代理一开一关后 apt 和 Git 又全部失效。

WSL2 更适合承担一个明确角色：Windows 负责桌面、编辑器与日常软件，Linux 负责代码、依赖、容器和构建。

这篇文章将从零搭建一套可长期使用的开发环境，最终得到：

• Windows 11 + WSL2 + Ubuntu；
• 国内访问更稳定的 Ubuntu 软件源；
• 可运行 systemd 的完整 Linux 用户空间；
• VS Code 运行在 Windows、工具链运行在 WSL；
• Git、Python、Docker Compose 等基础工具；
• 可控的代理继承、DNS、内存和磁盘占用；
• 可导出、可恢复的 WSL 备份。

刚装完新电脑的读者，可以先参考本站的《新电脑必装软件（程序员向）》，安装 Windows Terminal、VS Code、GitHub Desktop 等常用桌面软件，再回到本文配置 Linux 开发环境。

一、WSL2 适合什么，不适合什么

WSL2 使用真实 Linux 内核，适合以下工作：

• Go、Python、Node.js、Rust、C/C++ 等开发；
• Docker、Compose、数据库和消息队列；
• Linux Shell、构建脚本、CI 环境复现；
• AI 工具、命令行 Agent 和服务端项目；
• 需要 Linux 依赖但仍希望使用 Windows 桌面的场景。

它不是所有虚拟化需求的替代品。需要严格隔离、完整模拟多台主机、测试自定义内核或复杂网络拓扑时，Hyper-V、VMware、PVE 或真实 Linux 服务器仍然更合适。

二、安装并更新 WSL

以管理员身份打开 PowerShell，先查看 WSL 当前状态：

wsl --status
wsl --version
wsl --list --online

没有安装 WSL 时，执行：

wsl --install

该命令会启用 WSL 与虚拟机平台、安装 Linux 内核、将 WSL2 设为默认版本，并安装默认 Ubuntu。希望指定发行版时，先以 wsl --list --online 显示的名称为准，例如：

wsl --install -d Ubuntu-24.04

安装完成后重启 Windows，首次启动 Ubuntu 时需要创建 Linux 用户名和密码。输入密码时终端不会显示星号，这是 Linux 的正常行为，并不是键盘失效。

再次打开 PowerShell，检查发行版是否运行在 WSL2：

wsl -l -v

如果 VERSION 显示为 1，可执行：

wsl --set-default-version 2
wsl --set-version Ubuntu-24.04 2

其中 Ubuntu-24.04 必须替换为 wsl -l -v 显示的真实名称。

如果安装过程长期停在 0.0%，可以尝试：

wsl --install --web-download -d Ubuntu-24.04

--web-download 会绕过 Microsoft Store 下载路径，但在不同网络环境下未必比商店更快，应将它作为备用方案而不是必选项。

三、初始化 Ubuntu，并切换国内软件源

进入 Ubuntu 后，先查看系统版本和架构：

cat /etc/os-release
uname -m

Ubuntu 24.04 起主要使用 DEB822 格式的软件源文件：

/etc/apt/sources.list.d/ubuntu.sources

较早版本通常使用：

/etc/apt/sources.list

下面的命令会自动检测这两个文件，先备份，再把 Ubuntu 主仓库替换为清华大学 TUNA 镜像。它不会替换安全更新源，以减少镜像同步延迟对安全更新时效的影响。

for f in /etc/apt/sources.list /etc/apt/sources.list.d/ubuntu.sources; do
  [ -f "$f" ] || continue
  sudo cp -a "$f" "$f.bak.$(date +%Y%m%d%H%M%S)"
  sudo sed -i -E \
    's#https?://([a-z]{2}\.)?archive\.ubuntu\.com/ubuntu#https://mirrors.tuna.tsinghua.edu.cn/ubuntu#g' \
    "$f"
done

检查替换结果：

grep -RniE 'archive\.ubuntu\.com|mirrors\.tuna\.tsinghua\.edu\.cn|security\.ubuntu\.com' \
  /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null

然后更新系统并安装基础工具：

sudo apt clean
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y \
  build-essential git curl wget rsync unzip zip jq \
  ca-certificates gnupg lsb-release software-properties-common

ARM64 设备不能直接使用普通 Ubuntu x86 镜像仓库，应使用对应的 ubuntu-ports 镜像。替换前务必以 uname -m 的结果为准。

四、确认 systemd 是否工作

当前版本的 Ubuntu 通常已经默认启用 systemd，先检查 PID 1：

ps -p 1 -o comm=

输出为 systemd 就无需修改。若输出不是 systemd，创建配置：

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

回到 PowerShell 完整关闭 WSL：

wsl --shutdown

重新打开 Ubuntu 后验证：

systemctl is-system-running
systemctl list-unit-files --type=service | head

状态显示 running 或 degraded 通常都说明 systemd 已经启动；degraded 代表至少有一个服务启动失败，可用 systemctl --failed 继续检查。

五、项目必须放在 Linux 文件系统中

这是 WSL 开发体验最关键、也最容易被忽略的一条规则：

使用 Linux 工具构建的项目，尽量放在 WSL 的 ext4 文件系统中，而不是 /mnt/c、/mnt/d 等 Windows 挂载目录。

推荐目录：

mkdir -p ~/Projects
cd ~/Projects

不推荐：

/mnt/c/Users/你的用户名/Desktop/project

跨 Windows 与 Linux 文件系统的大量小文件访问会明显拖慢 npm install、Go 编译、Git 状态扫描和 Docker bind mount。项目放在 ~/Projects 后，仍可从 Windows 资源管理器访问：

explorer.exe .

也可以在资源管理器地址栏输入：

\\wsl$\Ubuntu-24.04\home\你的用户名\Projects

六、用 VS Code 连接 WSL

VS Code 应安装在 Windows，而语言运行时、编译器和依赖安装在 WSL。在 Windows 版 VS Code 中安装 Microsoft 发布的 WSL 扩展。

进入一个 WSL 项目目录：

mkdir -p ~/Projects/hello-wsl
cd ~/Projects/hello-wsl
printf 'print("Hello from WSL")\n' > hello.py
code .

首次执行 code . 时，VS Code 会在 WSL 内安装与桌面客户端匹配的 VS Code Server：

连接成功后，左下角会显示 WSL: Ubuntu：

需要注意，VS Code 扩展分为两类：

• 界面主题、账号同步等扩展安装在 Windows 本地；
• Python、Go、Rust、C/C++ 等语言扩展通常需要安装到 WSL 环境中。

准备在这套环境里使用 Codex，可以继续阅读本站的《OpenAI Codex 安装与使用全指南：命令行、GUI 与提示词技巧》。将仓库放在 ~/Projects 后再运行 Codex，通常比直接操作 /mnt/c 下的仓库更稳定。

七、配置 Git，避免行尾混乱

在 WSL 内单独配置 Git：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
git config --global init.defaultBranch main
git config --global core.autocrlf input
git config --global fetch.prune true

检查配置来源：

git config --global --list --show-origin

core.autocrlf=input 会在提交时把 CRLF 转为 LF，但不会在检出时强制把 LF 变成 CRLF，更适合 Linux 构建环境。团队项目仍应通过 .gitattributes 明确规定文本与脚本的行尾，而不是只依赖个人全局配置。

八、代理与 DNS：先决定“继承”还是“不继承”

很多 WSL 网络问题并不是网络本身断了，而是 Windows 代理、Shell 环境变量、Git、npm 和 apt 各自保留了一套旧代理。

Windows 11 可以通过用户目录下的 %UserProfile%\.wslconfig 控制 WSL2 全局行为。希望 WSL 默认直连国内镜像、不自动继承 Windows HTTP 代理时，可以使用：

[wsl2]
networkingMode=mirrored
dnsTunneling=true
autoProxy=false
firewall=true

[experimental]
autoMemoryReclaim=gradual
sparseVhd=true

修改后执行：

wsl --shutdown

说明：

• networkingMode=mirrored 使用镜像网络模式，适用于 Windows 11 22H2 及以上；
• dnsTunneling=true 让 WSL 的 DNS 请求通过 Windows 转发；
• autoProxy=false 禁止 WSL 自动复制 Windows 的 HTTP 代理；
• autoMemoryReclaim=gradual 会逐步回收 Linux 页缓存；
• sparseVhd=true 仍属于实验性设置，谨慎用户可以不写。

镜像网络在多数 VPN、IPv6 与 localhost 场景下更方便，但不是所有网络环境都更稳定。出现异常时，先删除 networkingMode=mirrored，让 WSL 回到默认 NAT 模式，再执行 wsl --shutdown 对比测试。

清理 WSL 中残留的代理

先查看当前环境：

env | grep -i proxy || true

清除当前 Shell 会话中的代理：

unset http_proxy https_proxy all_proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

清理 Git 全局代理：

git config --global --unset-all http.proxy || true
git config --global --unset-all https.proxy || true

使用 npm 时再执行：

npm config delete proxy
npm config delete https-proxy

如果关闭终端后代理又出现，搜索持久化配置：

grep -RniE 'http_proxy|https_proxy|all_proxy|proxy=' \
  ~/.bashrc ~/.profile ~/.zshrc /etc/environment /etc/apt/apt.conf.d \
  2>/dev/null

删除对应文件中的旧配置，而不是每次只执行 unset。

希望 WSL 跟随 Clash Verge Rev 时，可以把 autoProxy 改为 true，也可以手动设置代理地址。完整的 Clash 安装、TUN 与系统代理说明见本站《Clash Verge Rev + Clash Meta for Android 全平台安装配置攻略》。

完成后用国内站点验证直连：

curl -I --connect-timeout 10 https://mirrors.tuna.tsinghua.edu.cn
curl -I --connect-timeout 10 https://www.baidu.com

不要一遇到 DNS 问题就永久锁死 /etc/resolv.conf。启用 DNS 隧道后，WSL 会自动维护解析配置，手工覆盖反而可能在切换 Wi-Fi、校园网、VPN 后制造新的故障。

九、限制 WSL 的内存和 CPU

WSL2 默认最多可使用 Windows 总内存的一部分，并按需动态分配。一般不必限制；只有在 VmmemWSL 长期挤占桌面软件资源时，才建议调整 .wslconfig。

例如一台 32GB 内存、逻辑核心较多的开发机，可以在 [wsl2] 下增加：

memory=12GB
processors=8
swap=4GB

修改后重启 WSL：

wsl --shutdown

在 Linux 内检查：

free -h
nproc

限制过小会导致 Docker 构建、Rust 编译、Java 构建和本地模型推理异常。不要照抄数值，应根据主机内存和项目规模调整。

十、在 WSL 中使用 Docker Desktop

推荐做法是：

1. 在 Windows 安装 Docker Desktop；
2. 在 Docker Desktop 中使用 WSL 2 Engine；
3. 打开 Settings → Resources → WSL Integration；
4. 勾选实际使用的 Ubuntu 发行版；
5. 在 WSL 项目目录中运行 Docker CLI。

如果选择 Docker Desktop，就不要再在同一个 WSL 发行版里并行安装一套独立 Docker Engine，否则可能出现 CLI 指向错误 daemon、端口冲突和权限混乱。

验证集成，不需要先拉取镜像：

docker version
docker info
docker compose version

中国大陆访问 Docker Hub 可能不稳定。镜像加速地址经常变化，不建议教程长期硬编码来源不明的第三方地址。更稳妥的做法是使用自己云厂商账号提供的可信镜像加速服务，并在 Docker Desktop 的 Docker Engine 配置中填写当时有效的地址。

Docker 官方也建议把项目代码放在 Linux 发行版文件系统中，再通过 Windows 上的 VS Code 编辑，这与本文前面的目录规则一致。

十一、准备 Python 基础环境

Ubuntu 自带的 Python 应尽量保留给系统组件使用，项目应创建虚拟环境：

sudo apt install -y python3 python3-pip python3-venv pipx
pipx ensurepath

mkdir -p ~/Projects/python-demo
cd ~/Projects/python-demo
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

退出虚拟环境：

deactivate

需要完整 Conda 数据科学环境时，可参考本站的《Anaconda安装配置全教程（小白向）》。在 WSL 中安装 Conda 时，应下载 Linux 版本，而不是复用 Windows 版安装目录。

十二、备份与迁移 WSL

WSL 环境配置完成后，建议立即做一次基线备份。先在 PowerShell 中查看真实发行版名称：

wsl -l -v

完整关闭并导出：

wsl --shutdown
New-Item -ItemType Directory D:\WSL-Backup -Force
wsl --export Ubuntu-24.04 D:\WSL-Backup\Ubuntu-24.04-2026-08-06.tar

恢复为一个新的发行版：

New-Item -ItemType Directory D:\WSL\Ubuntu-Dev -Force
wsl --import Ubuntu-Dev D:\WSL\Ubuntu-Dev D:\WSL-Backup\Ubuntu-24.04-2026-08-06.tar --version 2

导入的发行版可能默认以 root 登录，可以在该发行版的 /etc/wsl.conf 中指定默认用户：

[user]
default=你的Linux用户名

然后执行：

wsl --shutdown

wsl --unregister <发行版名称> 会永久删除该发行版的文件、配置和软件。没有确认备份可用之前，不要执行。

十三、常见故障速查

1. code . 提示命令不存在

确认 VS Code 安装在 Windows，并在安装时加入 PATH；关闭所有 WSL 终端后重新打开。仍然失败时，在 VS Code 命令面板执行 WSL: Connect to WSL。

2. apt update 很慢或超时

检查软件源是否确实替换成功：

grep -RniE 'URIs:|^deb ' /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null

再检查代理与 DNS：

env | grep -i proxy || true
getent hosts mirrors.tuna.tsinghua.edu.cn

3. 项目编译和 Git 状态扫描很慢

先运行：

pwd

如果路径以 /mnt/c 或 /mnt/d 开头，把仓库迁移到 ~/Projects。

4. 修改 .wslconfig 后没有生效

必须完整关闭 WSL 虚拟机：

wsl --shutdown

只关闭 Ubuntu 窗口并不等于关闭 WSL2。

5. 忘记 Linux 密码

在 PowerShell 中以 root 启动指定发行版：

wsl -d Ubuntu-24.04 -u root

然后重置：

passwd 你的用户名

6. Docker 在 Windows 能用，WSL 里提示找不到命令

确认发行版运行在 WSL2，并在 Docker Desktop 的 Resources → WSL Integration 中启用了该发行版，然后重启 Docker Desktop 与 WSL。

7. WSL 长时间占用大量内存

先执行：

wsl --shutdown

再考虑启用 autoMemoryReclaim 或设置合理的 memory 上限。不要把频繁强制关闭当作唯一解决方案。

十四、最终检查清单

在 PowerShell 中：

wsl --version
wsl --status
wsl -l -v

在 WSL 中：

printf 'Distro: '; . /etc/os-release && echo "$PRETTY_NAME"
printf 'Kernel: '; uname -r
printf 'PID 1: '; ps -p 1 -o comm=
printf 'Git: '; git --version
printf 'Curl: '; curl --version | head -n 1
printf 'Project dir: '; realpath ~/Projects
printf 'Proxy variables:\n'; env | grep -i proxy || true

使用 Docker Desktop 时再检查：

docker version
docker compose version

至此，Windows 负责图形界面和编辑器，WSL 负责 Linux 工具链，Docker 负责可重复的服务环境，三者边界清晰。后续无论安装 Codex、搭建 Go/Python 项目，还是运行数据库和消息队列，都可以在这套基础上继续扩展。

相关阅读

• 新电脑必装软件（程序员向）
• OpenAI Codex 安装与使用全指南：命令行、GUI 与提示词技巧
• Clash Verge Rev + Clash Meta for Android 全平台安装配置攻略
• Anaconda安装配置全教程（小白向）

参考资料

• Microsoft Learn：安装 WSL
• Microsoft Learn：设置 WSL 开发环境
• Microsoft Learn：WSL 高级配置
• Microsoft Learn：在 WSL 中使用 systemd
• VS Code：Remote development in WSL
• Docker Docs：Docker Desktop WSL 2 backend
• 清华大学 TUNA：Ubuntu 软件仓库镜像帮助