WSL 虚拟机创建与管理笔记

适用 Windows 10/11 + WSL 2.x，聚焦"创建虚拟机"的完整流程、日常管理、迁移、故障排查。

📌 这是个独立专题——聚焦 WSL 虚拟机的创建、迁移、日常管理与故障排查，不展开具体发行版的应用层配置。

---

目录

• 一、WSL 的本质
  • 1.1 怎么找可安装的发行版
• 二、3 种创建方式
• 三、命名与路径规则
• 四、WSL 启用 systemd
  • 4.1 启用方法（3 步）
  • 4.2 验证 + 排错
  • 4.3 注意事项
  • 4.4 反向操作（关掉 systemd）
• 五、WSL 启用 systemd 后的标准配置
  • 5.1 /etc/wsl.conf 配置参考
  • 5.2 ~/.wslconfig 配置参考
  • 5.3 常见问题
• 六、日常管理命令速查
• 七、备份与恢复
  • 7.1 备份整个 WSL
  • 7.2 恢复 WSL
  • 7.3 备份单个目录
  • 7.4 备份整个 vhdx 文件
• 八、故障排查
  • 8.1 启动报错
  • 8.2 systemd 启不动
  • 8.3 WSL 占内存大
  • 8.4 vhdx 越用越大
  • 8.5 WSL 不能访问网络
  • 8.6 完整重置 WSL（保底）
• 九、决策树
• 十、各发行版 rootfs 镜像获取方式
• 附录 A：常用命令速查表
• 附录 B：路径速查
• 附录 C：常见错误与踩坑
  • C.1 主机名改了重启后丢失
  • C.2 wsl --import 后默认 root，没普通用户
  • C.3 改了主机名后 sudo 报 "unable to resolve host"
  • C.4 .wslconfig 改了不生效
  • C.5 docker save 导出的 tar 不能 wsl --import
  • C.6 systemd 启用了但 WSL 启动变慢
  • C.7 装完发现装到 C 盘了，想挪到 E 盘

---

一、WSL 的本质

WSL2 是轻量级 Hyper-V 虚拟机（vmcompute.exe + vmwp.exe）——用户主要与一个虚拟磁盘文件（ext4.vhdx）交互，挂载到 /，由 WSL Runtime 管理。

Windows 11
└── WSL Service (Win32)
    └── WSL VM (Hyper-V)
        ├── ext4.vhdx  ← 你的"Ubuntu"实际是这个文件
        │   └── / (根目录)
        └── WSL Init Shim  ← PID 1 进程

关键认识：

• "WSL 虚拟机" = 一个 .vhdx 文件 + WSL 注册表项
• "创建 WSL" = 创建 .vhdx + 在 WSL 注册
• "删除 WSL" = 注销（删注册项，可选删 vhdx）
• 默认 PID 1 是 init（WSSL 实现的 init），不是 systemd——所以默认所有 systemd 工具不能用（systemctl、hostnamectl、timedatectl 等）。启用 systemd 后 PID 1 才会变成 systemd（见 四、WSL 启用 systemd）。

---

1.1 怎么找可安装的发行版

在"创建 WSL"之前，先要知道有哪些发行版可装。3 种方法：

方法 1：wsl --list --online（最快）

# 看 WSL 官方仓库的所有可装发行版
wsl --list --online
# 简写
wsl -l -o

预期输出（持续更新）：

NAME                   FRIENDLY NAME
Ubuntu                 Ubuntu
Ubuntu-22.04           Ubuntu 22.04 LTS
Ubuntu-24.04           Ubuntu 24.04 LTS
Ubuntu-20.04           Ubuntu 20.04 LTS
openSUSE-Tumbleweed    openSUSE Tumbleweed
Debian                 Debian GNU/Linux
kali-linux             Kali Linux Rolling
Arch                   Arch Linux
Alpine                 Alpine Linux

只取 ID 列表：

wsl -l -o | Select-Object -ExpandProperty NAME

方法 2：winget 搜

# 列出所有 Linux 发行版
winget search "linux" --source msstore

# 精确搜 Ubuntu
winget search "Ubuntu" --source msstore

方法 3：Microsoft Store（图形）

# 命令行打开 Store 搜 Linux
start ms-windows-store://pdp/?ProductId=9P9TQC7NFM8H

# 或直接搜 Ubuntu
start ms-windows-store://pdp/?ProductId=9N0TNB7V0V3J

⚠️ Store 打不开 / 内容为空时：

• 检查网络（国内连 Store 经常慢/失败）
• 检查是否登录 Microsoft 账号
• 换用下面的 winget 方案（最稳）

装指定发行版：

⚠️ 关键提醒：下面 wsl --install -d <Distro> 不带 --location 时默认装到 C 盘（%LOCALAPPDATA%\Packages\...）。C 盘空间紧张或想统一管理 WSL 在其他盘时，必须加 --location。

强烈建议第一次安装就指定自定义名字 + 路径，避免后期迁移。

# ✅ 推荐：装到自定义位置（管理员 PowerShell）
# 先创建目标目录
New-Item -ItemType Directory -Path "E:\WSL\Ubuntu-24.04" -Force

# 再装（--name 自定义名字，--location 指定 vhdx 目录）
wsl --install -d Ubuntu-24.04 --name Ubuntu-24.04 --location "E:\WSL\Ubuntu-24.04"

# ⚠️ 简化写法（不带 --name 和 --location）：默认名字 + 默认 C 盘
# 仅在测试 / 临时使用 / C 盘空间充裕时才用
wsl --install -d Ubuntu-24.04

# 用 winget 装（默认也是装到 C 盘）
winget install --id Canonical.Ubuntu.2404 -e

# 装默认（不指定 -d 时装列表第一个）
wsl --install

💡 wsl --install 完整语法（需 WSL ≥ 1.0）：

wsl --install [选项] [发行版]
  -d, --distribution <Distro>       指定发行版（默认装列表第一个）
  --name <Name>                     自定义发行版名字
  --location <Path>                 安装到指定目录（目录需先创建）
  --no-distribution                 仅装 WSL 内核，不装发行版

查看所有参数：wsl --install --help

💡 提示：wsl --list --online 显示的是微软官方仓库——不包含你已经从 Docker 拉、或者用 wsl --import 自己 import 的镜像。

如果上面 3 种方法都打不开 / 找不到想要的发行版，用下面 4 种备用方案：

# 方案 1：用 winget 直接装（**最推荐**，绕开 Store UI）
winget install --id Canonical.Ubuntu.2404 -e

# 方案 2：wsl 自带安装命令
wsl --install                 # 装默认（列表第一个）
wsl --install -d Ubuntu-24.04  # 装指定

# 方案 3：从微软文档找（浏览器访问）
# https://aka.ms/wslstorepage
# 列出所有可用发行版的稳定入口

# 方案 4：用 wsl --export 从已有 Store 版导出，再 wsl --import 装成新名字
#    （不能直接用 docker save 的 tar——Docker 镜像是分层结构，WSL 不接受）
wsl --export Ubuntu-24.04 D:\wsl\ubuntu-24.04-rootfs.tar
wsl --import Ubuntu-Custom D:\wsl\Ubuntu-Custom D:\wsl\ubuntu-24.04-rootfs.tar

---

二、3 种创建方式

📋 安装前必读：路径规划

核心原则：装之前先想好 vhdx 放哪个盘。WSL 发行版占空间不小（Ubuntu 24.04 默认占 5-10 GB，跑一段时间后可达 30-50 GB），强烈建议放在非 C 盘。

两种自定义路径的姿势：

方式	关键参数	适合场景
wsl --install --location	wsl --install -d Ubuntu-24.04 --name xxx --location "E:\WSL\xxx"	全新装（最推荐，1 步到位）
wsl --import	wsl --import <Name> <InstallPath> <TarFile>	有现成 rootfs tar 时

默认位置（不加 --location）：%LOCALAPPDATA%\Packages\...（C 盘）

方式 1：wsl --install 装（推荐 99% 场景）

方式 1A：自定义名字 + 路径（最推荐）

# 1. 创建目标目录
New-Item -ItemType Directory -Path "E:\WSL\Ubuntu-24.04" -Force

# 2. 装到指定位置（需要管理员 PowerShell + WSL ≥ 1.0）
wsl --install -d Ubuntu-24.04 --name Ubuntu-24.04 --location "E:\WSL\Ubuntu-24.04"

优点：

• ✅ 开箱即用，直接装到想要的位置
• ✅ 自定义名字（项目命名友好，如 Ubuntu-RestCloud-ETL）
• ✅ 微软持续维护、自动更新
• ✅ 能启用 systemd
• ✅ 启动后自动设置用户名密码
• ✅ 镜像复用：装过的发行版镜像会缓存，再装不重新下载

装完：

• 开始菜单或 wsl -d <Name> 启动
• 第一次启动会让你设置用户名和密码
• vhdx 在你指定的 E:\WSL\Ubuntu-24.04\ext4.vhdx

方式 1B：Microsoft Store 装（默认装到 C 盘，不推荐）

仅在不想用命令行、或 Store 是唯一可用渠道时用此方式。

操作：

# 方法 A：命令行打开 Store
start ms-windows-store://pdp/?ProductId=9N0TNB7V0V3J

# 方法 B：用 winget 装
winget install --id Canonical.Ubuntu.2404 -e

装完：

• 开始菜单搜 "Ubuntu 24.04"
• 第一次启动会让你设置用户名和密码
• vhdx 路径：%LOCALAPPDATA%\Packages\CanonicalGroupLimited.Ubuntu24.04LTS_<随机串>\LocalState\ext4.vhdx（C 盘）
• 装完后想挪到其他盘：参考 七、备份与恢复 中的 wsl --export + wsl --unregister + wsl --import 三步迁移

验证（1A / 1B 通用）：

# WSL 内
ps -p 1 -o comm=
# 预期：systemd  ← 关键

方式 2：wsl import 手动装

优点：

• ✅ 自定义发行版名字
• ✅ 自定义 vhdx 路径
• ✅ 适合"重命名"场景

缺点：

• ❌ 默认登录 root（没 ubuntu 用户，需要手动创建）
• ⚠️ systemd 启用方法与 Store 版完全一样（见 四、WSL 启用 systemd）

rootfs 来源（wsl --import 只接受 Linux 根文件系统的扁平 tar 包——Docker 镜像那种分层结构不行）：

来源	说明
A. 从 Microsoft Store 装的发行版 vhdx 导出	wsl --export <名字> out.tar（最稳，格式完美）
B. 第三方/官方 WSL 发行版 rootfs	Ubuntu Cloud Image、archlinux 官方 WSL 镜像、Red Hat 官方 RHEL WSL 镜像等——装法与 A 完全相同，区别仅在镜像获取（见 十、各发行版 rootfs 镜像获取方式）
❌ Docker 镜像	docker save 导出的 tar 不能直接 import——Docker 镜像是分层结构，WSL 需要的是 rootfs 扁平 tar

操作（以"从 Microsoft Store 装的 Ubuntu 导出再 import"为例）：

# 1. 创建目录
New-Item -ItemType Directory -Path D:\wsl\Ubuntu-24.04 -Force

# 2. 从已有 Store 版导出 rootfs（前提：Store 版 Ubuntu-24.04 已装）
wsl --export Ubuntu-24.04 D:\wsl\ubuntu-24.04-rootfs.tar

# 3. 注册到自定义名字和路径
wsl --import Ubuntu-Custom D:\wsl\Ubuntu-24.04 D:\wsl\ubuntu-24.04-rootfs.tar

# 4. 启动（默认 root）
wsl -d Ubuntu-Custom

操作（用第三方 rootfs，例：Ubuntu Cloud Image）：

# 1. 下载 cloud image 的 rootfs
#    例：https://cloud-images.ubuntu.com/minimal/releases/noble/release/ubuntu-24.04-minimal-cloudimg-amd64-root.tar.xz
Invoke-WebRequest -Uri "https://.../ubuntu-24.04-minimal-cloudimg-amd64-root.tar.xz" -OutFile D:\wsl\ubuntu-rootfs.tar.xz

# 2. 解压（wsl --import 接受 .tar 或未压缩的流）
#    如果是 .tar.xz，先解压成 .tar：
#    Windows 10 1803+ 自带 tar：tar -xJf ubuntu-rootfs.tar.xz -C D:\wsl\extracted

# 3. 注册
wsl --import Ubuntu-Custom D:\wsl\Ubuntu-24.04 D:\wsl\ubuntu-rootfs.tar

# 4. 启动
wsl -d Ubuntu-Custom

⚠️ import 后建议做的事（默认 root 登录时）：

# 默认登录 root，需要：
# 1. 创建普通用户
useradd -m -s /bin/bash ubuntu
passwd ubuntu

# 2. 配 sudo 权限
echo "ubuntu ALL=(ALL) ALL" > /etc/sudoers.d/ubuntu
chmod 440 /etc/sudoers.d/ubuntu

# 3. 设为默认登录用户（在 wsl.conf 加）
#    [user]
#    default = ubuntu

# 4. 启用 systemd（与 Store 版方法一致，详见下文章节）

启用 systemd 的具体操作见 四、WSL 启用 systemd。

💡 非 Ubuntu 系发行版的包管理器差异：

发行版	包管理器	常用命令
Ubuntu / Debian	apt	sudo apt update && sudo apt install -y <pkg>
RHEL / Fedora	dnf	sudo dnf install -y <pkg>
openSUSE	zypper	sudo zypper install <pkg>
Arch	pacman	sudo pacman -S <pkg>

systemd、/etc/wsl.conf 配置、用户管理命令跨发行版通用——只有装包工具不同。

方式 3：从 wsl --export 备份恢复（实用技巧）

如果之前 wsl --export 过当前发行版，可以从备份恢复（适用于换机器或重装）：

# 1. 注销原发行版（备份前先关掉）
wsl --shutdown
wsl --unregister Ubuntu-24.04

# 2. 从 tar 恢复（装回原名字最稳）
wsl --import Ubuntu-24.04 D:\wsl\Ubuntu-24.04 D:\wsl-backup\ubuntu-24.04.tar

# 3. 启动
wsl -d Ubuntu-24.04

⚠️ 关于"装成新名字"：

• wsl --import 接受任意新名字，技术上可以装成 MyUbuntu 这种
• 但强烈建议装回原名字——wsl --export 导出的 tar 保留原发行版的内部 ID、机器 ID、SSH 主机密钥等，装成新名字会导致：
  • 主机密钥不一致（/etc/ssh/ssh_host_* 重新生成）
  • systemd 内部 ID 冲突
  • 一些依赖 machine-id 的服务异常
• 最佳实践：用原名字 import，导入路径可以是新路径（wsl --import 的第二个参数）

---

三、命名与路径规则

WSL 发行版名字规则

来源	名字示例	改名能力	建议
Microsoft Store	Ubuntu、Ubuntu-24.04	❌ 不能直接改	想要别的名字只能注销后用 wsl --import 装成新名字
wsl --import	你注册时起的任意名字	✅ 能改（注销 + 用新名字重新 import）	任意名字都行
wsl --export 恢复	备份时的原名字	✅ 能改	名字可随意改——改名只影响 Windows 注册表里的 DistributionName，vhdx 内 /etc/ssh/ssh_host_*、/etc/machine-id 不会重新生成；但需检查是否有硬编码旧名的脚本或工具链（见下方"改名/迁移后 Windows 侧缓存清理"）

vhdx 路径规则

来源	路径	改路径能力	建议
Microsoft Store	%LOCALAPPDATA%\Packages\CanonicalGroupLimited.Ubuntu24.04LTS_<随机串>\LocalState\ext4.vhdx	❌ 不能直接改	想挪盘的两种方法：① wsl --export → --unregister → --import 三步迁移（见 附录 C.7，通用可靠）；② WSL 2.0.0+ 可直接用 wsl --manage <Distro> --move <NewPath> 一步迁移，无需 export/import（目标目录需为空，目标盘需为 NTFS——FAT32/exFAT 因不支持稀疏文件会失败）
wsl --import	你指定的（wsl --import 的第二个参数）	✅ 能改（注销 + 用新路径重新 import）	任意路径都行，建议直接放在非 C 盘
wsl --export 恢复	任意（wsl --import 的第二个参数）	✅ 能改	路径随意；名字是否装回原名由上表"改名建议"决定

改名/迁移后 Windows 侧缓存清理

改名或迁移 vhdx 路径后，vhdx 内部文件完全不变（包括 SSH 主机密钥、machine-id、hostname 等）。但 Windows 侧一些组件可能仍引用旧名字，需要手动检查：

引用场景	检查/修复方式
\\wsl$\旧名字 UNC 路径	文件资源管理器、脚本里的这类路径全部失效，需改为新名字或用 wsl -d 新名字 挂载
wsl -d 旧名字 命令	脚本、批处理、VS Code wsl-remote 配置里的命令全部失效
Windows Terminal Profile	设置 → 配置文件，把引用旧名字的命令行（如 "wsl.exe -d Ubuntu-24.04"）改为新名字，或直接删除旧 profile
VS Code Remote-WSL 连接历史	VS Code → 文件 → 打开最近的文件 → 找到 vscode-remote://wsl+旧名字/... 记录移除（或 Ctrl+Shift+P → File: Clear Recently Opened）；终端配置检查 settings.json 里的 terminal.integrated.profiles.windows 或 remote.WSL.defaultDistro
第三方工具配置	Docker Desktop、JetBrains Gateway、Termius 等工具里指定了 WSL 名字的地方都要同步修改

💡 通用做法：改名/迁移完成后，执行 wsl -l -v 看一眼当前名字，再按下面分场景排查硬编码引用：

# Windows 侧（PowerShell）：脚本/配置/批处理通常在 Documents、scripts 等目录
Select-String -Path "$env:USERPROFILE\Documents","$env:USERPROFILE\scripts" -Pattern "旧名字" -Recurse

# WSL 内部：.bashrc、.zshrc、/etc、/usr/local/bin 等
grep -r "旧名字" ~/.bashrc ~/.zshrc /etc/ /usr/local/bin/ 2>/dev/null

关键命令

# 看所有 WSL
wsl -l -v

# 启动
wsl -d <名字>

# 注销（删注册表项，不删 vhdx）
wsl --unregister <名字>

---

四、WSL 启用 systemd

核心结论：任何 WSL2 发行版都能启用 systemd——与镜像来源无关。前提是 WSL ≥ 0.67.6 + /etc/wsl.conf 配置正确。

4.1 启用方法（3 步）

第 1 步：编辑 /etc/wsl.conf

# 备份
sudo cp /etc/wsl.conf /etc/wsl.conf.bak.$(date +%Y%m%d%H%M%S) 2>/dev/null

# 看现有段（避免覆盖）
cat /etc/wsl.conf

# 安全追加 [boot] systemd=true
if grep -q "^\[boot\]" /etc/wsl.conf; then
  sudo sed -i '/^\[boot\]/a systemd=true' /etc/wsl.conf
else
  echo "" | sudo tee -a /etc/wsl.conf > /dev/null
  echo "[boot]" | sudo tee -a /etc/wsl.conf > /dev/null
  echo "systemd=true" | sudo tee -a /etc/wsl.conf > /dev/null
fi

# ⚠️ 强烈建议同时加 [network] 段，否则主机名重启会丢
if ! grep -q "^\[network\]" /etc/wsl.conf; then
  echo "" | sudo tee -a /etc/wsl.conf > /dev/null
  echo "[network]" | sudo tee -a /etc/wsl.conf > /dev/null
  echo "generateHosts = false" | sudo tee -a /etc/wsl.conf > /dev/null
  echo "hostname = dev-workspace" | sudo tee -a /etc/wsl.conf > /dev/null
fi

# 验证
cat /etc/wsl.conf

第 2 步：Windows PowerShell 重启 WSL

wsl --shutdown

第 3 步：重开 WSL，验证

ps -p 1 -o comm=
# 应该输出：systemd

4.2 验证 + 排错

如果 PID 1 仍是 init：

# 1. 确认 wsl.conf 写对了
cat /etc/wsl.conf
# 应该看到 [boot] systemd=true

# 2. 确认 WSL 版本
#    Windows PowerShell: wsl --version
#    至少 0.67.6

# 3. 再次重启
#    wsl --shutdown

4.3 注意事项

• ✅ 启用 systemd 后，[boot] command = ... 会被忽略——服务用 systemctl enable 管理
• ✅ 启用 systemd 后，所有 systemd 工具都能用：systemctl、hostnamectl、timedatectl、journalctl、localectl、loginctl
• ⚠️ 某些 Docker pull 镜像可能仍启不动——与镜像源有关

4.4 反向操作（关掉 systemd）

# 安全方式：sed 改 systemd=true 为 false（其他段保留）
if grep -q "^systemd=true" /etc/wsl.conf; then
  sudo sed -i 's/^systemd=true/systemd=false/' /etc/wsl.conf
fi

# 验证
grep "systemd" /etc/wsl.conf
# 应该输出：systemd=false

# Windows PowerShell: wsl --shutdown

---

五、WSL 启用 systemd 后的标准配置

启用 systemd 后，回归"真机 Linux"方案——下面是一次性配置脚本：

# 1. 装常用包
sudo apt update
sudo apt install -y ufw openssh-server fail2ban vim htop curl wget git

# 2. ufw 防火墙
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

# 3. SSH
sudo systemctl enable --now ssh

# 4. fail2ban
sudo systemctl enable --now fail2ban

# 5. 时区
sudo timedatectl set-timezone Asia/Shanghai

# 6. 主机名
sudo hostnamectl set-hostname dev-workspace

# 7. 验证
date
hostname
sudo systemctl status ssh
sudo fail2ban-client status sshd

5.1 /etc/wsl.conf 配置参考

最小化配置（能用 systemd 就够）：

[user]
default = ubuntu

[boot]
systemd=true

推荐配置（含主机名持久化，日常开发建议加上）：

[user]
default = ubuntu

[boot]
systemd=true

[network]
# 禁用 WSL 自动覆盖 /etc/hosts
# 适用场景：改主机名后希望不被覆盖、/etc/hosts 自定义条目不被清空
generateHosts = false
# 显式指定 WSL 主机名
# 适用场景：不想用 Windows 计算机名当 Linux 主机名
hostname = dev-workspace

📋 各段作用：

• [user] default = ubuntu —— 默认登录用户（避免 root 登录）
• [boot] systemd=true —— 启用 systemd（所有 systemd 工具可用）
• [network] generateHosts = false —— 阻止 WSL 覆盖 /etc/hosts（按需）
• [network] hostname = xxx —— 阻止 WSL 用 Windows 计算机名覆盖 Linux 主机名（按需）

📋 [network] 段什么时候需要：

• 不在乎主机名 = Windows 计算机名 → 不需要
• 改过主机名想持久 → 加 hostname = xxx
• 自定义了 /etc/hosts 又总被覆盖 → 加 generateHosts = false

⚠️ 启用 systemd 后，[boot] command = ... 会被忽略——服务管理用 systemctl enable。

🔗 主机名详细配置（包括 /etc/hosts 同步、sudo 解析陷阱等）见 WSL 主机名设置。

5.2 ~/.wslconfig 配置参考

[wsl2]
memory=8GB
swap=2GB

📋 内存配置建议：

物理内存	推荐 memory	推荐 swap
8 GB	4 GB	2 GB
16 GB	8~12 GB	2~4 GB
32 GB	16~24 GB	2~4 GB
64 GB+	32 GB	2~4 GB

不要超过 Windows 物理内存的 80%。

5.3 常见问题

Q1：启用 systemd 后，原来的 service 命令还能用吗？

✅ 能。service 是 SysVinit 兼容命令，所有 WSL 都支持。但推荐用 systemctl（更标准）。

Q2：启用 systemd 后，WSL 启动变慢吗？

会慢几秒（systemd 启动要时间）。如果不在意——完全可接受。

Q3：能在 WSL 里用 systemd-nspawn 跑嵌套容器吗？

✅ 能（这是 systemd 的功能）。但多数情况用不上。

---

六、日常管理命令速查

查看

# 列出所有 WSL（详细：版本、状态、默认）
wsl -l -v

# 看 WSL 客户端版本
wsl --version

# 看 WSL 全局状态
wsl --status

# 查 vhdx 路径（在注册表里）
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss" /s

启动 / 停止

# 启动指定发行版
wsl -d <名字>

# 启动默认发行版
wsl

# 关闭所有 WSL 实例
wsl --shutdown

# 终止指定发行版
wsl -t <名字>

更新

# 升级 WSL 客户端
wsl --update

# 更新后重启
wsl --shutdown

配置（.wslconfig，Windows 侧）

文件位置：C:\Users\<你>\.wslconfig

[wsl2]
memory=8GB              # 内存限制
swap=2GB                # 交换区
processors=4            # CPU 核心数
localhostForwarding=true

UTF-8 无 BOM 写入（避免 WSL 解析失败）：

# 手动编辑（推荐）：用记事本/VSCode 另存为 UTF-8 无 BOM

# 或 PowerShell 脚本写入（注意：换行符用 [Environment]::NewLine，更安全）
$content = "[wsl2]" + [Environment]::NewLine +
           "memory=8GB" + [Environment]::NewLine +
           "swap=2GB" + [Environment]::NewLine +
           "processors=4" + [Environment]::NewLine +
           "localhostForwarding=true" + [Environment]::NewLine
[System.IO.File]::WriteAllText("$env:USERPROFILE\.wslconfig", $content, [System.Text.UTF8Encoding]::new($false))

# 验证无 BOM
$bytes = [System.IO.File]::ReadAllBytes("$env:USERPROFILE\.wslconfig")
if ($bytes.Length -ge 3 -and $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF) {
    Write-Warning "⚠️ 文件有 BOM，WSL 可能解析失败"
} else {
    Write-Host "✅ 无 BOM，配置正常"
}

发行版内配置（/etc/wsl.conf）

启用 systemd 后的推荐配置：

[user]
default = ubuntu                # 默认登录用户

[boot]
systemd=true                    # 启用 systemd（用 systemctl / hostnamectl 等工具的前提）

[network]
generateHosts = false           # 关闭自动生成 hosts（改了主机名/自定义 hosts 时建议加）
generateResolvConf = true       # DNS 走 Windows
hostname = dev-workspace        # 显式指定 WSL 主机名（希望主机名不被 Windows 计算机名覆盖时加）

⚠️ 启用 systemd 后 [boot] command = ... 会被忽略——服务用 systemctl enable 管理。

🔗 完整配置说明（含 WSL 主机名设置的踩坑与修复）见 四、WSL 启用 systemd 和 5.1 /etc/wsl.conf 配置参考。

网络配置进阶（.wslconfig 镜像模式）

使用 networkingMode=mirrored 镜像网络模式时，WSL 与 Windows 共享同一网络栈，WSL 服务在局域网里有独立 IP。此时 Windows 通过 WSL 的 IP（如 192.168.0.101）访问 WSL 内服务时，需要额外开启 hostAddressLoopback：

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

[experimental]
hostAddressLoopback=true

⚠️ hostAddressLoopback 是实验性功能，必须放在 [experimental] 段下，不能放在 [wsl2] 下。放错位置会导致 WSL 启动报错 wsl2.hostAddressLoopback 中的键"13"未知 并忽略该配置。

生效：wsl --shutdown 后重启 WSL。

验证：

# Windows PowerShell
Test-NetConnection -ComputerName <WSL_IP> -Port <PORT>
# 期望输出：TcpTestSucceeded : True

⚠️ 镜像网络下常见误区：即使配了 hostAddressLoopback=true，Windows 防火墙仍可能拦截入站连接。需在 Windows Defender 防火墙 → 高级设置 → 入站规则里放行对应端口（按应用/TCP 端口放行均可）。

---

七、备份与恢复

7.1 备份整个 WSL

# 导出为 tar
wsl --export <名字> D:\backup\my-wsl-20260611.tar

# 验证
Get-Item D:\backup\my-wsl-20260611.tar | Select-Object Length

7.2 恢复 WSL

# 从 tar 注册（自定义名字）
wsl --import <新名字> D:\wsl\new D:\backup\my-wsl-20260611.tar

7.3 备份单个目录

# WSL 内
sudo tar -czf /mnt/d/backup-home.tar.gz /home/ubuntu

7.4 备份整个 vhdx 文件

# 关闭 WSL 后复制 vhdx
wsl --shutdown
Copy-Item D:\wsl\Ubuntu-24.04\ext4.vhdx D:\backup\ext4-20260611.vhdx

---

八、故障排查

8.1 启动报错

A virtual disk support provider for the specified file was not found

vhdx 路径错误或文件被删。检查：

Get-Item D:\wsl\Ubuntu-24.04\ext4.vhdx

键 "X" 未知

.wslconfig 或 wsl.conf 格式错。检查：

• BOM 字符（用 WriteAllText + UTF-8 无 BOM 写 .wslconfig）
• 键名拼写错误（如 networkingMode 写成 networkingmode）
• 段名/键名不支持：.wslconfig 只支持 [wsl2] 段（见 Microsoft 官方文档）；wsl.conf 各段支持的键名见 wsl.conf 参考

8.2 systemd 启不动

症状：

ps -p 1 -o comm=
# 输出 init（不是 systemd）

根因：/etc/wsl.conf 没配 [boot] systemd=true，或配置后没 wsl --shutdown 重启。

解法：

# 1. 确认配置
cat /etc/wsl.conf
# 确认里面有 [boot] systemd=true 这一行

# 2. Windows PowerShell 重启
wsl --shutdown

# 3. 重开 WSL 验证
ps -p 1 -o comm=
# 应输出 systemd

详见 四、WSL 启用 systemd。

⚠️ 极少见情况：某些精简镜像（如 docker pull ubuntu:24.04 导出的 rootfs）确实可能启不动 systemd，原因是镜像里 systemd 二进制/库不完整。解决方案：换用 Microsoft Store 版，或用 wsl --export <已有 Store 版> 导出的 rootfs。

8.3 WSL 占内存大

.wslconfig 设 memory 限制（见上文）。

8.4 vhdx 越用越大

WSL2 的 vhdx 是稀疏文件——你在 WSL 里 rm 大文件，vhdx 不会自动缩小。手动回收：

wsl --shutdown
diskpart
# 进入 diskpart 后：
select vdisk file="D:\wsl\Ubuntu-24.04\ext4.vhdx"
compact vdisk
exit

8.5 WSL 不能访问网络

# 看网络
ip addr show eth0

# 看 DNS
cat /etc/resolv.conf

# 看默认路由
ip route show default

# 测试连通（ping、curl 都行）
ping -c 3 baidu.com
curl -v http://baidu.com

如果用了镜像模式（networkingMode=mirrored），回到上文 网络配置进阶（.wslconfig 镜像模式） 检查 hostAddressLoopback 是否放在了 [experimental] 段下。

8.6 完整重置 WSL（保底）

# 1. 注销所有发行版
wsl --unregister Ubuntu-RestCloud-ETL
wsl --unregister Ubuntu-24.04

# 2. 重置 WSL 服务
wsl --shutdown
wsl --update

# 3. 重装 Microsoft Store 版
winget install --id Canonical.Ubuntu.2404 -e

# 4. 启动 + 重新设置
wsl -d Ubuntu-24.04

---

九、决策树

我想创建一个 WSL Ubuntu
│
├── 第一步：确定安装路径 ⚠️ 不要跳过
│   │
│   ├── C 盘空间充足（> 100 GB 剩余）+ 临时测试
│   │   └── 可用 wsl --install -d Ubuntu-24.04（默认装 C 盘）
│   │
│   └── 想装到非 C 盘（**99% 场景推荐**）
│       │
│       └── ✅ wsl --install -d Ubuntu-24.04 --name xxx --location "E:\WSL\xxx"
│           （管理员 PowerShell + WSL ≥ 1.0，最推荐）
│
├── 第二步：选择具体方式
│   │
│   ├── 全新装 + 自定义路径 → wsl --install --location（**方式 1A**）
│   ├── 全新装 + 默认路径   → Microsoft Store（**方式 1B**，不推荐）
│   ├── 有现成 rootfs tar   → wsl --import（**方式 2**）
│   └── 从已有备份恢复      → wsl --export/--import（**方式 3**）
│
└── 第三步：装完后启用 systemd
    │
    └── 配置 /etc/wsl.conf + wsl --shutdown
        详见 [四、WSL 启用 systemd](#四wsl-启用-systemd)
        ⚠️ 改了主机名后要加 [network] hostname = xxx，否则重启会丢

---

十、各发行版 rootfs 镜像获取方式

用途：当 方式 2 的"来源 B"需要下载第三方/官方 WSL rootfs 时，本节列出常见发行版的下载入口、镜像文件名约定、账号门槛。

统一安装命令（下载后都一样）：

# 通用模板
wsl --import <Name> "E:\WSL\<Name>" "D:\Downloads\<rootfs>.tar" --version 2
wsl -d <Name>

格式要求：rootfs 必须是扁平 tar 包（.tar 或已解压的 .tar.xz），不能是 Docker 镜像那种分层结构。

10.1 Ubuntu / Debian 系

发行版	下载入口	镜像格式	账号门槛
Ubuntu Cloud Image	https://cloud-images.ubuntu.com/	*-root.tar.xz（例：ubuntu-24.04-minimal-cloudimg-amd64-root.tar.xz）	无（公开下载）
Debian Cloud Image	https://cloud.debian.org/images/cloud/	debian-*-genericcloud-amd64.tar.xz	无

💡 提示：Cloud Image 是为云环境优化的精简版，不带桌面、无 snap，但文件小、启动快，适合作为 WSL rootfs。导入前需先手动解压 .tar.xz 成 .tar（Windows 10 1803+ 自带 tar -xJf 可解压）。

10.2 Red Hat 系

发行版	下载入口	镜像格式	账号门槛
RHEL（红帽企业 Linux）	https://developers.redhat.com/（搜 "WSL"）	rhel-<版本>-x86_64-wsl.tar.gz（例：rhel-8-x86_64-wsl.tar.gz）	需免费 Red Hat Developer 账号
Fedora	https://github.com/fedora-cloud/docker-brew-fedora/ 或 WSL 社区镜像	通常为 *.tar.xz	无（公开）

⚠️ RHEL 特殊性：

• 微软 Store 里没有 RHEL 官方包，必须从 Red Hat 开发者门户下载
• 账号注册免费，但首次下载必须登录
• 装包用 dnf（不是 apt），详见前文"非 Ubuntu 系发行版的包管理器差异"表

10.3 Arch / openSUSE / Alpine 系

发行版	下载入口	镜像格式	账号门槛
Arch Linux	https://gitlab.archlinux.org/archlinux/archlinux-wsl（官方 WSL 仓库）	通常为 *.tar.gz	无
openSUSE	https://download.opensuse.org/（找 WSL 镜像）	通常为 *.tar.xz	无
Alpine	https://alpinelinux.org/downloads/	通常为 alpine-minirootfs-*-x86_64.tar.gz（非 WSL 专用，但可 import）	无

💡 Alpine 说明：Alpine 没有官方 WSL 镜像，但官方提供的 minirootfs 是扁平 rootfs，可直接 wsl --import。装包用 apk。

10.4 Kali / 其他

发行版	下载入口	镜像格式	账号门槛
Kali Linux	Microsoft Store（推荐）或 https://www.kali.org/get-kali/#kali-virtual-machines	Store 版直接 wsl --install -d kali-linux	无

💡 建议：能在 wsl --list --online 找到的发行版（Ubuntu、Debian、Kali、openSUSE、Arch、Alpine 等），优先用 wsl --install——无需下载 rootfs、微软维护、自动更新。仅当找不到想要的发行版（典型如 RHEL）时才走"下载 rootfs → wsl --import"这条路。

10.5 验证 rootfs 合法性的快速方法

如果不确定下载下来的 tar 能不能直接 wsl --import，可以先不实际导入，快速排查：

# 看 tar 顶层是否就是 Linux 根目录（应该是 bin/ boot/ etc/ home/ ...）
tar -tf D:\Downloads\ubuntu-rootfs.tar | Select-Object -First 20

# 如果输出是 "layer/layer1.json" 这种分层结构，那是 Docker 镜像，不能 import

---

附录 A：常用命令速查表

操作	命令
列出 WSL	wsl -l -v
启动 WSL	wsl -d <名字>
关闭所有 WSL	wsl --shutdown
注销 WSL	wsl --unregister <名字>
导入 WSL	wsl --import <DistroName> <InstallLocation> <FileName> [--vhd]
导出 WSL	wsl --export <名字> <tar路径>
升级 WSL	wsl --update
看 WSL 版本	wsl --version
装 Store 版	winget install --id Canonical.Ubuntu.2404 -e
装指定发行版（默认路径）	wsl --install -d Ubuntu-24.04
装指定发行版 + 自定义路径	wsl --install -d Ubuntu-24.04 --name <Name> --location "<Path>"

附录 B：路径速查

用途	路径
用户配置	C:\Users\<你>\.wslconfig
Store 版 vhdx	%LOCALAPPDATA%\Packages\CanonicalGroupLimited.Ubuntu24.04LTS_<随机串>\LocalState\ext4.vhdx
import 版 vhdx	你指定的（任意位置）
备份目录（推荐）	D:\wsl-data\
WSL 内 /mnt/c	Windows C 盘
WSL 内 /mnt/d	Windows D 盘

---

附录 C：常见错误与踩坑

遇到坑时优先翻这里。

C.1 主机名改了重启后丢失

症状：hostnamectl set-hostname xxx 改了，重启后又变回 Windows 计算机名。

原因：/etc/wsl.conf 缺少 [network] 段的 hostname = xxx 配置。

修复：

# 追加 [network] 段
sudo tee -a /etc/wsl.conf > /dev/null << 'EOF'

[network]
generateHosts = false
hostname = dev-workspace
EOF

# Windows PowerShell 重启
wsl --shutdown

C.2 wsl --import 后默认 root，没普通用户

症状：导入 rootfs 后直接进 root，提示符是 root@xxx。

修复：

# 创建用户、设密码、加 sudo
useradd -m -s /bin/bash ubuntu
passwd ubuntu
echo "ubuntu ALL=(ALL) ALL" > /etc/sudoers.d/ubuntu
chmod 440 /etc/sudoers.d/ubuntu

C.3 改了主机名后 sudo 报 "unable to resolve host"

症状：

sudo whoami
# sudo: unable to resolve host dev-workspace: Temporary failure in name resolution
# root

原因：hostnamectl 不自动同步 /etc/hosts，WSL 也没有 hook。

修复：

echo "127.0.1.1 $(hostname)" | sudo tee -a /etc/hosts
sudo whoami  # 应无警告

C.4 .wslconfig 改了不生效

症状：改了内存、CPU 限制，WSL 仍然用旧的。

修复：

wsl --shutdown
# 重新打开 WSL

C.5 docker save 导出的 tar 不能 wsl --import

症状：

wsl --import Ubuntu D:\wsl\Ubuntu D:\wsl\ubuntu.tar
# Error: 0x8004031d ... The data is not in the correct format

原因：Docker 镜像是分层（OCI 格式）结构，wsl --import 需要的是扁平 rootfs tar。

修复：

• 用 wsl --export <已有 Store 版> out.tar 导出（最稳）
• 或从 Ubuntu Cloud Image 下载 *-root.tar.xz（已是正确格式）

C.6 systemd 启用了但 WSL 启动变慢

说明：这是正常现象。systemd 启动要加载服务管理器，比原生的 init 多几秒。可接受——换来的 systemctl 等标准工具链非常值得。

如果实在不能忍：

# .wslconfig 里调小 VM idle timeout（空闲时更快释放）
vmIdleTimeout=15000

C.7 装完发现装到 C 盘了，想挪到 E 盘

症状：wsl --install -d Ubuntu-24.04 没加 --location，装完后 vhdx 落在 C:\Users\<你>\AppData\Local\...。

解决：wsl --export + --unregister + --import 三步迁移。

# 1. 关闭 WSL
wsl --shutdown

# 2. 导出当前系统到备份目录（带日期）
$date = Get-Date -Format "yyyy-MM-dd"
wsl --export Ubuntu-24.04 "E:\WSL-Backup\ubuntu-24.04-$date.tar"

# 3. 注销 C 盘实例（删除 C 盘 vhdx）
wsl --unregister Ubuntu-24.04

# 4. 创建新位置目录
New-Item -ItemType Directory -Path "E:\WSL\Ubuntu-24.04" -Force

# 5. 导入到 E 盘
wsl --import Ubuntu-24.04 "E:\WSL\Ubuntu-24.04" "E:\WSL-Backup\ubuntu-24.04-$date.tar"

# 6. 重新设置默认用户（导入后默认是 root）
Ubuntu-24.04 config --default-user <你的用户名>

# 7. 验证位置
Get-ChildItem "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss" | Get-ItemProperty | Select-Object DistributionName, BasePath
# 应该看到 BasePath 是 E:\WSL\Ubuntu-24.04

💡 防患于未然：下次装新 WSL，直接用：

wsl --install -d Ubuntu-24.04 --name <Name> --location "E:\WSL\<Name>"