WSL 完全指南：安装配置、日常使用、网络与文件互通、性能调优与排障

一、WSL 是什么#

WSL1 vs WSL2#

结论：2024 年了，无脑选 WSL2。

WSL 的适用场景#

二、安装#

1.1 前置条件#

1.2 一键安装（Win10 2004+ / Win11）#

# 管理员 PowerShell
wsl --install

# 这条命令自动完成：
# 1. 启用 WSL 和虚拟机平台功能
# 2. 下载 WSL2 内核
# 3. 设置 WSL2 为默认版本
# 4. 安装默认发行版（Ubuntu）

安装完重启，然后 Ubuntu 会自动弹窗让你设置用户名和密码。

1.3 手动安装（旧版 Windows 或需要控制选择）#

# 1. 启用 WSL 功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 2. 启用虚拟机平台
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 3. 重启电脑
shutdown /r /t 0

# 4. 下载 WSL2 内核更新包
# https://aka.ms/wsl2kernel

# 5. 设置默认版本为 WSL2
wsl --set-default-version 2

# 6. 从 Microsoft Store 安装发行版
# 或者命令行：
wsl --install -d Ubuntu-24.04
wsl --install -d Debian
wsl --install -d openSUSE-Tumbleweed

1.4 可用发行版列表#

# 列出在线可用发行版
wsl --list --online

# 常见选择：
# Ubuntu-24.04    → 最主流，包最多
# Ubuntu-22.04    → LTS 保守
# Debian          → 轻量稳定
# openSUSE-Tumbleweed → 滚动更新
# Kali-Linux      → 安全测试
# OracleLinux_8_5 → RHEL 兼容

三、发行版管理#

2.1 核心命令#

# 列出已安装的发行版
wsl -l -v
# 输出示例：
#   NAME            STATE           VERSION
#   Ubuntu-24.04    Running         2
#   Debian          Stopped          2
# * Ubuntu-22.04    Running         2    ← 默认

# 启动默认发行版
wsl

# 启动指定发行版
wsl -d Ubuntu-24.04

# 以指定用户启动
wsl -d Ubuntu-24.04 -u root

# 在 WSL 中执行命令（不进入交互 shell）
wsl -d Ubuntu-24.04 -- apt update
wsl -d Ubuntu-24.04 -- cat /etc/os-release

# 指定工作目录启动
wsl -d Ubuntu-24.04 --cd /home/user/project

# 关闭指定发行版
wsl -t Ubuntu-24.04

# 关闭所有
wsl --shutdown

# 设置默认发行版
wsl --set-default Ubuntu-24.04

# 设置某发行版使用 WSL2
wsl --set-version Ubuntu-24.04 2

# 从 WSL1 升级到 WSL2
wsl --set-version Debian 2

2.2 导出 / 导入 / 迁移#

# 导出为 tar（备份或迁移）
wsl --export Ubuntu-24.04 D:\backups\ubuntu-24.04.tar

# 导入到新位置（迁移到 D 盘）
wsl --import Ubuntu-24.04-New D:\WSL\Ubuntu-24.04 D:\backups\ubuntu-24.04.tar

# 删除某个发行版
wsl --unregister Ubuntu-24.04

迁移到 D 盘实操（C 盘空间不够时常用）：

# 1. 关闭
wsl --shutdown

# 2. 导出到 D 盘
wsl --export Ubuntu-24.04 D:\wsl-backup\ubuntu.tar

# 3. 注销原来的
wsl --unregister Ubuntu-24.04

# 4. 导入到 D 盘新位置
wsl --import Ubuntu-24.04 D:\WSL\Ubuntu-24.04 D:\wsl-backup\ubuntu.tar

# 5. 设置默认用户（导入后默认是 root）
ubuntu2404.exe config --default-user youruser
# 或在 /etc/wsl.conf 里配

四、配置文件详解#

WSL 有两个配置文件，作用范围不同：

3.1 /etc/wsl.conf（WSL 内部配置，每个发行版独立）#

# /etc/wsl.conf

[boot]
# 启用 systemd（WSL 0.67.2+，需要 Win11 或更新版 WSL）
systemd=true

# 自动挂载 Windows C 盘
[automount]
enabled=true
# 挂载点（默认 /mnt/c）
root=/mnt/
# 挂载选项
options="metadata,umask=22,fmask=11"
# 自动挂载固定驱动器（C/D/E...）
mountFsTab=true

# 域名解析
[network]
# 生成 /etc/resolv.conf 从 Windows DNS
generateResolvConf=true
# 不想用 Windows DNS 就设 false，然后自己写 /etc/resolv.conf

# 默认用户（导入后改默认用户用这个）
[user]
default=youruser

# 互操作（Windows ↔ Linux 命令互通）
[interop]
enabled=true
# 允许从 Windows 调用 Linux 命令
appendWindowsPath=true

改完后必须 wsl --shutdown 再重新启动才生效。

3.2 .wslconfig（全局配置，影响所有发行版）#

放在 Windows 用户目录：C:\Users\你的用户名\.wslconfig

# C:\Users\Robin\.wslconfig

[wsl2]
# 内存上限（默认是宿主 50%）
memory=8GB

# 处理器数（默认等于宿主逻辑核心数）
processors=4

# 交换空间大小（swap，默认与 memory 等大）
# swap=2GB

# 虚拟磁盘路径（迁移 vhdx 位置）
# vhdPath=D:\\WSL\\ext4.vhdx

# 网络模式：NAT（默认）或 Mirrored（Win11 22H2+）
# networkingMode=mirrored

# 自动释放内存（Win11+）
# autoMemoryReclaim=gradual

# 内核命令行
# kernelCommandLine = vsyscall=epoll

# 自定义内核（编译场景）
# kernel=C:\\path\\to\\custom-kernel

# 防火墙集成
# firewall=true

# DNS 隧道
# dnsTunneling=true

# 自动代理
# autoProxy=true

改完后同样需要 wsl --shutdown 生效。

五、systemd 支持#

4.1 启用 systemd#

WSL 0.67.2+ 支持原生 systemd，不用再装第三方 hack。

# 编辑 WSL 内部配置
sudo tee /etc/wsl.conf << 'EOF'
[boot]
systemd=true
EOF

# 重启 WSL
# 在 Windows PowerShell 执行：
wsl --shutdown
wsl

4.2 验证#

# systemd 在跑
systemctl --version

# PID 1 是 systemd
ps -p 1 -o comm=
# 输出: systemd

# 测试服务管理
sudo systemctl status ssh
sudo systemctl enable --now ssh
sudo systemctl restart docker

4.3 为什么需要 systemd#

如果你装的东西报错 systemctl: command not found，说明 systemd 没开。

六、文件系统互通#

5.1 Windows → WSL：访问 Windows 文件#

# Windows 的 C:\Users\Robin\Projects 在 WSL 里是：
cd /mnt/c/Users/Robin/Projects
ls

# D 盘 → /mnt/d
cd /mnt/d/WSL

# 所有 Windows 盘符都在 /mnt/ 下
ls /mnt/
# c  d  e

5.2 WSL → Windows：访问 Linux 文件#

# 方法 1：Windows 资源管理器地址栏输入
\\wsl$\Ubuntu-24.04\home\youruser

# 方法 2：Win11 新路径
\\wsl.localhost\Ubuntu-24.04\home\youruser

# 方法 3：WSL 内用 explorer.exe
explorer.exe .

5.3 性能差异（重要！）#

黄金法则：Linux 项目放 Linux 文件系统（~/），不要放在 /mnt/c/。git clone / npm install / make 在 /mnt/c/ 下慢到怀疑人生。

5.4 行尾符问题#

Windows 用 \r\n（CRLF），Linux 用 \n（LF）。在 /mnt/c/ 下 git clone 会遇到：

# 方法 1：配置 git 自动转换
git config --global core.autocrlf input
# input = 提交时转成 LF，签出时不加 CRLF

# 方法 2：项目根目录加 .gitattributes
echo "* text=auto eol=lf" > .gitattributes

# 方法 3：把项目放在 ~/（Linux 文件系统）就不会触发

七、网络互通#

6.1 默认 NAT 模式#

flowchart TB
  WIN["Windows 宿主（172.20.10.2）"]
  WSL["WSL2 VM（172.20.10.3）<br/>独立 IP，和宿主不同段<br/>访问外网走 NAT 转换"]
  UB["Ubuntu"]
  EXT["其他网络<br/>Windows 访问 WSL 端口自动转发"]
  WIN --> WSL
  WSL --> UB
  WIN --> EXT

• WSL 有独立 IP（和宿主不同段）
• WSL 访问外网 → 通过 NAT 转换
• Windows 访问 WSL 端口 → 自动端口转发

6.2 Mirrored 模式（Win11 22H2+）#

# .wslconfig
[wsl2]
networkingMode=mirrored

flowchart TB
  WIN2["Windows 宿主（192.168.1.100）"]
  WSL2["WSL2（192.168.1.100）<br/>和宿主同 IP！<br/>局域网其他机器可直连 WSL 端口<br/>不需要端口转发"]
  UB2["Ubuntu"]
  WIN2 --> WSL2
  WSL2 --> UB2

• WSL 和宿主共享 IP
• 局域网其他机器可以直接访问 WSL 端口
• 不需要端口转发
• 推荐 Win11 用户开启

6.3 端口访问场景#

# WSL 里起了个 web 服务
python3 -m http.server 8080

# 场景 1：Windows 浏览器访问 WSL 的 8080
# → http://localhost:8080 （NAT 模式自动转发）

# 场景 2：局域网其他机器访问 WSL 的 8080
# NAT 模式：需要在 Windows 上做端口转发
# Mirrored 模式：直接 http://windows-ip:8080

# NAT 模式端口转发（PowerShell 管理员）：
# 先取 WSL 的 IP（hostname -I 可能返回多个或带尾空格，取第一个并 Trim）
$wsl_ip = (wsl hostname -I).Trim().Split()[0]
netsh interface portproxy add v4tov4 listenport=8080 listenaddress=0.0.0.0 connectport=8080 connectaddress=$wsl_ip

# 删除转发规则
netsh interface portproxy delete v4tov4 listenport=8080 listenaddress=0.0.0.0

6.4 DNS 问题#

WSL 默认从 Windows 生成 /etc/resolv.conf，有时 DNS 不对导致 apt update 失败。

# 方法 1：关闭自动生成，手动写 DNS
# /etc/wsl.conf:
[network]
generateResolvConf=false

# 然后手动写
sudo rm /etc/resolv.conf
sudo tee /etc/resolv.conf << 'EOF'
nameserver 223.5.5.5
nameserver 8.8.8.8
EOF

# 关键：加 chattr immutable 防止被覆盖
sudo chattr +i /etc/resolv.conf

# 方法 2：Mirrored 模式 + dnsTunneling
# .wslconfig:
[wsl2]
networkingMode=mirrored
dnsTunneling=true

6.5 代理配置#

如果 Windows 上有代理（如 Clash），WSL 需要配置才能用：

# NAT 模式：代理指向 Windows 的 IP
# 获取宿主 IP（NAT 模式下是网关地址）
WIN_IP=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')

# 临时设置
export http_proxy="http://${WIN_IP}:7890"
export https_proxy="http://${WIN_IP}:7890"
export no_proxy="localhost,127.0.0.1"

# 写入 ~/.bashrc 永久生效
echo "export WIN_IP=\$(cat /etc/resolv.conf | grep nameserver | awk '{print \$2}')" >> ~/.bashrc
echo 'export http_proxy="http://${WIN_IP}:7890"' >> ~/.bashrc
echo 'export https_proxy="http://${WIN_IP}:7890"' >> ~/.bashrc
echo 'export no_proxy="localhost,127.0.0.1"' >> ~/.bashrc

# Mirrored 模式下直接用 127.0.0.1
# export http_proxy="http://127.0.0.1:7890"

八、开发环境搭建#

7.1 Docker#

# 方法 A：Docker Desktop（推荐新手）
# 安装 Docker Desktop for Windows → 设置里勾选 WSL2 后端
# 勾选要集成的发行版（Settings → Resources → WSL Integration）
# WSL 里直接 docker ps 就能用

# 方法 B：原生 Docker Engine（不装 Docker Desktop）
sudo apt update
sudo apt install docker.io -y
sudo usermod -aG docker $USER

# 启用 systemd 后 docker 服务自动管理
sudo systemctl enable --now docker

# 测试
docker run hello-world

7.2 Node.js（nvm）#

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 重启 shell 后
nvm install 22
nvm install 20
nvm use 22
node -v

# 项目建议放 ~/ 下，不要放 /mnt/c/
cd ~/projects/my-app
npm install

7.3 Python（pyenv / uv）#

# 方法 A：pyenv
curl https://pyenv.run | bash
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

pyenv install 3.12.6
pyenv global 3.12.6

# 方法 B：uv（更快，推荐 2024+）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12
uv venv
uv pip install -r requirements.txt

7.4 Go#

# 官方方式
wget https://go.dev/dl/go1.23.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.23.0.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin:~/go/bin' >> ~/.bashrc

go version

7.5 Rust#

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

rustc --version
cargo new hello && cd hello && cargo run

九、VS Code Remote-WSL#

8.1 安装与使用#

1. VS Code 安装扩展：WSL（旧名 Remote-WSL）
2. 在 WSL 里进入项目目录：

cd ~/projects/my-app
code .

3. VS Code 会自动以 WSL 环境打开，所有终端、扩展、调试器都在 Linux 侧运行

8.2 为什么不能直接用 Windows VS Code 编辑 Linux 文件#

8.3 常用快捷键#

# 在当前 WSL 目录打开 VS Code
code .

# 指定发行版打开
code --remote wsl+Ubuntu-24.04 /home/user/project

# 从 VS Code 终端回到 WSL shell
# Ctrl+` 打开终端，默认就是 WSL bash

十、GUI 应用（WSLg）#

Win11 内置 WSLg，可以直接跑 Linux GUI 程序。

# 安装一个 GUI 程序
sudo apt install gedit -y
gedit  # 直接弹出窗口

# 运行 Firefox
sudo apt install firefox -y
firefox

# 运行 Wireshark
sudo apt install wireshark -y
sudo wireshark

# GUI 程序的显示不需要配 DISPLAY 环境变量
# WSLg 自动处理了 X11 转发

WSLg 的窗口和 Windows 窗口混在一起，可以 Alt+Tab 切换，剪贴板互通。

十一、性能调优#

10.1 两个配置文件的分工#

10.2 内存优化#

WSL2 默认占宿主 50% 内存，且不主动释放。大内存机器问题不大，8G 机器会撑满。

# .wslconfig
[wsl2]
memory=4GB
swap=1GB

# Win11 22H2+ 自动回收内存
autoMemoryReclaim=gradual

10.3 磁盘优化#

# WSL2 的虚拟磁盘是 vhdx 文件，只会增不会自动缩
# 路径默认在：
# C:\Users\你\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu*\LocalState\ext4.vhdx

# 定期压缩（回收已删除文件的空间）
# PowerShell 管理员：
wsl --shutdown
# 找到你的 vhdx 路径
diskpart
# 在 diskpart 里：
select vdisk file="C:\Users\Robin\AppData\Local\Packages\...\ext4.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit

10.4 文件系统性能#

# /etc/wsl.conf - 关闭不需要的元数据可以加速 /mnt/c
[automount]
options="noatime,umask=22"

# 检查当前挂载选项
mount | grep mnt

10.5 网络优化#

# .wslconfig
[wsl2]
# Mirrored 模式更简单（Win11）
networkingMode=mirrored

# DNS 隧道（解决 DNS 被代理干扰）
dnsTunneling=true

# 自动继承 Windows 代理设置
autoProxy=true

十二、备份与迁移#

11.1 完整导出导入#

# 导出（含所有文件 + 配置）
wsl --shutdown
wsl --export Ubuntu-24.04 D:\backup\ubuntu-full.tar

# 导入到新机器
wsl --import Ubuntu-24.04 D:\WSL\Ubuntu-24.04 D:\backup\ubuntu-full.tar

11.2 只备份用户数据#

# 在 WSL 里打包 home 目录
tar czf /mnt/d/backup/home-$(date +%Y%m%d).tar.gz \
  --exclude='.cache' \
  --exclude='node_modules' \
  --exclude='.venv' \
  --exclude='__pycache__' \
  -C /home user/

11.3 快照（Win11 22H2+）#

# 创建快照
wsl --manage Ubuntu-24.04 --set-snapshot

# 恢复
wsl --manage Ubuntu-24.04 --revert-snapshot

十三、常用命令速查#

十四、常见排障#

排障 1：WSL2 启动报错 0x8007019e#

Error: WSL 2 requires an update to its kernel component

原因：WSL2 内核没安装。

# 方法 1：自动更新
wsl --update

# 方法 2：手动下载
# https://aka.ms/wsl2kernel
# 双击安装后重启

排障 2：apt update 超时 / DNS 解析失败#

# 检查 DNS
cat /etc/resolv.conf
# 如果 nameserver 是 172.x.x.x 但 ping 不通 → DNS 被代理或 VPN 干扰

# 修复：关闭自动 DNS，手动写
sudo tee /etc/wsl.conf << 'EOF'
[network]
generateResolvConf=false
EOF

sudo rm /etc/resolv.conf
sudo tee /etc/resolv.conf << 'EOF'
nameserver 223.5.5.5
nameserver 8.8.8.8
EOF

sudo chattr +i /etc/resolv.conf

# 在 PowerShell 重启
wsl --shutdown
wsl

排障 3：/mnt/c 挂载消失#

# 检查 wsl.conf
cat /etc/wsl.conf
# 确保 [automount] enabled=true

# 手动挂载
sudo mkdir -p /mnt/c
sudo mount -t drvfs C: /mnt/c

# 重启 WSL
wsl --shutdown && wsl

排障 4：systemctl: command not found#

# 检查 WSL 版本
wsl --version
# 需要 0.67.2+，旧版不支持 systemd

# 更新 WSL
wsl --update

# 确认 /etc/wsl.conf 有 systemd=true
cat /etc/wsl.conf

# 重启
wsl --shutdown && wsl

# 验证
ps -p 1 -o comm=
# 输出应该是 systemd

排障 5：Docker 服务起不来#

# 确认 systemd 开了
systemctl status docker

# 如果报 Failed to start
sudo systemctl status docker --no-pager -l
# 常见原因：
# 1. systemd 没开 → 按 4 修
# 2. iptables 权限 → sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
# 3. 磁盘满了 → df -h

# 终极大法
sudo systemctl restart docker
# 不行就
wsl --shutdown && wsl

排障 6：文件权限变成 777#

# /mnt/c 下的文件在 WSL 里看着全是 777
# 这是 drvfs 的默认行为

# 在 wsl.conf 加 metadata 挂载选项可以支持 chmod
[automount]
options="metadata,umask=22,fmask=11"

# 但注意：加了 metadata 后 /mnt/c 性能会再慢一截
# 如果不在 Windows 文件上跑 Linux 权限检查，不加也行

排障 7：VS Code Remote-WSL 连不上#

# 确认 WSL 扩展装了
# VS Code → Extensions → 搜 "WSL" → 安装

# 在 WSL 里手动启动
code .

# 如果报 "WSL daemon not found"
# 在 VS Code 里 Ctrl+Shift+P → "WSL: Restart WSL Server"

# 检查 WSL 版本是否太旧
wsl --update

排障 8：端口被占用#

# WSL 里起了 8080 但 Windows 报 "端口被占用"
# 可能是上次的 WSL 进程没清干净

# 查看 Windows 端口占用
# PowerShell:
netstat -ano | findstr 8080

# 杀掉占用进程
taskkill /PID <PID> /F

# 或直接重启 WSL
wsl --shutdown && wsl

排障 9：磁盘越来越大但里面没多少东西#

# WSL2 的 vhdx 只增不缩
# 定期压缩：

# PowerShell 管理员：
wsl --shutdown

# 方法 1：diskpart（通用）
diskpart
select vdisk file="C:\Users\你\AppData\Local\Packages\...\ext4.vhdx"
attach vdisk readonly
compact vdisk
detach vdisk
exit

# 方法 2：Win11 新命令（如果支持）
wsl --manage Ubuntu-24.04 --compact

排障 10：Vmmem 内存占用过高#

# 任务管理器里 Vmmem 占了 5-8 GB

# .wslconfig 限制内存
[wsl2]
memory=4GB
autoMemoryReclaim=gradual

# 然后
wsl --shutdown

排障 11：GUI 程序打不开（WSLg）#

# 检查 WSLg 是否启用
echo $DISPLAY
# 应该输出 :0 或类似

# 如果为空，检查 .wslconfig 没有禁用 GUI
# 确保 WSL 更新到最新
wsl --update

# Win10 不支持 WSLg，需要 Win11
# 或用 VcXsrv 做外部 X Server

排障 12：多个发行版时间不同步#

# WSL2 的时钟可能和 Windows 不同步（挂起恢复后常见）

# 手动同步
sudo hwclock -s

# 或从 NTP 同步
sudo apt install ntpdate -y
sudo ntpdate ntp.aliyun.com

# 永久修复：启用 systemd 后
sudo systemctl enable --now systemd-timesyncd

十五、最佳实践总结#

14.1 10 条黄金法则#

1. 项目放 ~/ 不放 /mnt/c/ — 性能差 3-5 倍
2. 用 WSL2 不用 WSL1 — Docker/systemd 都要它
3. 开 systemd — /etc/wsl.conf 里 systemd=true
4. 配 .wslconfig 限内存 — 不然 Vmmem 吃满
5. Win11 开 mirrored 网络 — 省去端口转发
6. DNS 手动配 — 避免 VPN/代理干扰
7. 定期压缩 vhdx — 磁盘不会无限增长
8. 用 VS Code Remote-WSL — 别用 Windows VS Code 直接编辑 Linux 文件
9. 行尾符统一 LF — git config core.autocrlf input
10. 快照备份 — wsl --export 定期做

14.2 推荐配置模板#

C:\Users\你\.wslconfig：

[wsl2]
memory=8GB
processors=4
swap=2GB
networkingMode=mirrored
autoMemoryReclaim=gradual
dnsTunneling=true
autoProxy=true

/etc/wsl.conf：

[boot]
systemd=true

[automount]
enabled=true
options="metadata,umask=22"

[network]
generateResolvConf=true

[user]
default=youruser

[interop]
enabled=true
appendWindowsPath=true