WSL 安装与配置

WSL（Windows Subsystem for Linux）让你在 Windows 上原生运行 Linux 环境。

这页只记录安装、配置、文件互通和开发配套。

推荐使用方式

对大多数开发者来说，比较稳的一套组合是：

• Windows 负责桌面、浏览器、图形工具
• WSL 负责终端、Node.js / Python / Git / Linux 工具链
• VS Code 通过 Remote - WSL 直接连进去开发
• Docker Desktop 负责引擎，WSL 里直接用 docker

这样既保留 Windows 桌面体验，又尽量避免跨文件系统性能损耗。

安装

# 一键安装（默认 Ubuntu）
wsl --install

# 指定发行版
wsl --install -d Ubuntu-24.04

# 查看可用发行版
wsl --list --online

重启后设置用户名和密码。

常用命令

wsl --list --verbose          # 查看已安装的发行版
wsl --set-default Ubuntu      # 设置默认发行版
wsl --shutdown                # 关闭所有实例
wsl --terminate Ubuntu        # 关闭指定实例
wsl --update                  # 更新 WSL
wsl --version                 # 查看版本
wsl --export Ubuntu backup.tar    # 导出
wsl --import MyUbuntu C:\WSL backup.tar  # 导入

配置文件

.wslconfig（全局）

%USERPROFILE%\.wslconfig：

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

wsl.conf（每个发行版）

/etc/wsl.conf：

[automount]
enabled = true
root = /mnt/
options = "metadata,umask=22,fmask=11"

[network]
generateResolvConf = true

[boot]
systemd = true

[interop]
enabled = true
appendWindowsPath = true

修改后需要 wsl --shutdown 重启生效。

文件互通

# WSL 访问 Windows 文件
ls /mnt/c/Users/

# Windows 访问 WSL 文件
# 资源管理器地址栏输入：
\\wsl$\Ubuntu\home\user\

建议将项目放在 WSL 文件系统内（~/projects），跨文件系统操作性能较差。

开发环境

# 更新系统
sudo apt update && sudo apt upgrade -y

# 常用工具
sudo apt install -y build-essential git curl wget unzip

# Node.js（通过 nvm）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install --lts

# Docker（使用 Docker Desktop 的 WSL 集成）
# Docker Desktop → Settings → Resources → WSL Integration

Docker + WSL 2 的推荐工作流

这是 Windows 上体验最好的 Docker 开发方式之一：

• Docker Desktop 安装在 Windows，负责图形界面、后台引擎与更新
• 项目代码放在 WSL 的 Linux 文件系统，避免跨文件系统带来的性能损耗
• 终端命令在 WSL 中执行，包括 docker、docker compose、pnpm、npm、uv 等
• 编辑器使用 VS Code Remote - WSL，尽量不要直接在 C: 盘大型仓库里反复 bind mount

建议的验证方式：

docker version
docker context ls
docker compose version
pwd

如果 docker 在 WSL 中不可用，优先检查 Docker Desktop 的 Use the WSL 2 based engine 和 WSL Integration 是否已为当前发行版开启。

如需进一步配置容器与 MCP，可搭配阅读 Docker Desktop 安装与使用 和 MCP 模型上下文协议。

VS Code 集成

# 在 WSL 中打开项目
code .

VS Code 会自动安装 Remote - WSL 扩展，实现无缝开发。

网络

# WSL 中访问 Windows 服务
# 使用 Windows 主机 IP
cat /etc/resolv.conf | grep nameserver

# Windows 中访问 WSL 服务
# 直接用 localhost（需要 localhostForwarding=true）

推荐配置顺序

建议按下面顺序完成：

1. 先安装 WSL 和发行版
2. 打开 systemd
3. 更新系统并安装基础命令行工具
4. 配好 Git、Node.js / Python、包管理器
5. 再接 VS Code 和 Docker 工作流

一开始不要急着装满所有工具，先把终端与文件系统体验调顺最重要。

常见问题

DNS 解析失败

# 临时修复
sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
sudo chattr +i /etc/resolv.conf

磁盘空间回收

WSL 的虚拟磁盘不会自动缩小：

# 关闭 WSL
wsl --shutdown

# 压缩虚拟磁盘
diskpart
select vdisk file="C:\Users\<user>\AppData\Local\Packages\...\ext4.vhdx"
compact vdisk

文件系统很慢

最常见的原因是项目放在 C:\，再从 WSL 中操作。更推荐把活跃项目直接放进 WSL 的 Linux 文件系统中，例如 ~/projects/app。

Docker 在 WSL 中不可用

优先检查：

• Docker Desktop 是否已启动
• 是否开启了 Use the WSL 2 based engine
• 当前发行版是否在 WSL Integration 列表中启用

时间久了不知道哪套环境在生效

Windows 和 WSL 是两套独立环境。建议尽量明确：

• Git 配置放哪边
• Node.js / Python 用哪边的版本管理器
• SSH 密钥是否只保留一份主用来源

延伸阅读

• Windows 重装部署清单
• Windows 重装部署清单（详情）
• 本地开发环境搭建
• Docker Desktop 安装与使用
• VS Code 配置指南

参考链接

• WSL 文档 — 微软官方
• WSL GitHub — 问题反馈