---
name: install-wsl2-ubuntu
description: "在 Windows 11 上启用 WSL2 并安装 Ubuntu 22.04（国内网络实测可行路径）。当用户说装 WSL/WSL2、装 Ubuntu、开 WSL、初始化 Linux 子系统，或遇到 wsl 报 0x80370102/0x800701bc/HCS_E_SERVICE_NOT_AVAILABLE/wsl --install 只提示不安装 时使用。关键：系统 wsl.exe 是 stub(其 --install 不工作)、winget msstore 与 Microsoft CDN 下载极慢，正确路径是 DISM 启用功能 + GitHub MSI(ghfast 镜像)装运行时 + 清华镜像下 rootfs + wsl --import，且一切运行操作都需先重启+开 BIOS VT-x。"
---

# 启用 WSL2 并安装 Ubuntu 22.04（国内网络实测路径）

## ⚠️ 关键经验（2026-07-24 实战踩坑，必读）

1. **系统自带 `C:\Windows\System32\wsl.exe` 是 stub**：WSL 平台未真正安装时，`wsl --install` / `wsl --install -d Ubuntu-22.04` **退出码 0 但不安装**，只返回"未安装适用于 Linux 的 Windows 子系统"提示。即便功能已 Enabled 仍是 stub。**别指望 `wsl --install`。**
2. **`winget install Microsoft.WSL` 走 msstore 源会卡死**：在国内卡在 "Starting package install" 超过 12 分钟无进展。winget 不可用于装 WSL。
3. **Microsoft CDN 下 Ubuntu appx 极慢**：`https://aka.ms/wslubuntu2204`（→ wslstorestorage.blob.core.windows.net，Ubuntu2204-221101.AppxBundle，1.04GB）只有 **~17KB/s，要 17 小时**，不可行。
4. **✅ 验证可行的三段式路径**（本 skill 的主体）：
   - DISM 启用两个 Windows 功能
   - 从 **GitHub `microsoft/WSL` releases 下 x64 MSI**，用 **`ghfast.top` 镜像**加速，`msiexec` 装真实 WSL 运行时（替换 stub）
   - 从 **清华镜像下 Ubuntu rootfs**（比 appx 小、快），`wsl --import` 注册
5. **所有 WSL2 运行操作（`--import`、启动）都要求**：① 已**重启** Windows（让 VirtualMachinePlatform / HCS 驱动加载，否则 `HCS_E_SERVICE_NOT_AVAILABLE`）② **BIOS 开了 VT-x**（否则 `0x80370102`）。这两条缺一不可，且只能用户手动。
6. **编码**：`wsl.exe`/`dism`/`msiexec` 输出多为 **UTF-16LE**，在 Git Bash 是乱码；`iconv -f UTF-16LE -t UTF-8 | tr -d '\0'` 解码，不行改 `-f GBK`。所有原生 exe 调用加 `MSYS_NO_PATHCONV=1`，防止 `/online` `/i` `/import` 这类参数被 MSYS 路径转换破坏。

## 第 0 步：预检

```bash
powershell.exe -NoProfile -Command "'build ' + (Get-ItemProperty 'HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion').CurrentBuild"   # 需 ≥ 19041
powershell.exe -NoProfile -Command "Get-CimInstance Win32_Processor | Select-Object Name,VirtualizationFirmwareEnabled,VMMonitorModeExtensions | Format-List"  # VMMonitorModeExtensions=True=CPU支持; VirtualizationFirmwareEnabled=False=BIOS没开VT-x
powershell.exe -NoProfile -Command "Get-WindowsOptionalFeature -Online | Where-Object { \$_.FeatureName -match 'Linux|VirtualMachinePlatform' } | Select FeatureName,State"
powershell.exe -NoProfile -Command "'{0:N1} GB free' -f ((Get-PSDrive C).Free/1GB)"
```

判断：`VirtualizationFirmwareEnabled=False` → 必须进 BIOS 开 VT-x，否则装完跑不起来。

## 第 1 步：DISM 启用两个功能（管理员）

```bash
MSYS_NO_PATHCONV=1 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
MSYS_NO_PATHCONV=1 dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
# 验证 State 变 Enabled（dism 退出码可能误报如 194，以 Get-WindowsOptionalFeature 的 State 为准）
powershell.exe -NoProfile -Command "Get-WindowsOptionalFeature -Online | Where-Object { \$_.FeatureName -match 'Linux|VirtualMachinePlatform' } | Select FeatureName,State"
```

## 第 2 步：装 WSL 运行时（GitHub MSI + ghfast 镜像）

```bash
# 查最新 release 的 tag 和 x64 MSI 文件名
powershell.exe -NoProfile -Command "\$r=Invoke-RestMethod 'https://api.github.com/repos/microsoft/WSL/releases/latest' -Headers @{'User-Agent'='PowerShell'}; \$r.tag_name; \$r.assets | Where-Object {\$_.name -match 'x64.msi'} | Select name,browser_download_url"
# 用 ghfast.top 镜像下载 x64 MSI（直连 GitHub 也行但可能慢；curl -k 跳过 Git Bash 的 CA bundle 问题）
curl -k -L --fail -o /c/Users/admin/wsl.msi 'https://ghfast.top/https://github.com/microsoft/WSL/releases/download/<tag>/wsl.<ver>.x64.msi'
# 静默安装
MSYS_NO_PATHCONV=1 msiexec.exe /i 'C:\Users\admin\wsl.msi' /quiet /norestart /L*v 'C:\Users\admin\wsl-msi.log'
# 验证：wsl --version 显示真实版本(如 2.7.10.0)，不再是 stub 提示
MSYS_NO_PATHCONV=1 wsl.exe --version 2>&1 | iconv -f UTF-16LE -t UTF-8 | tr -d '\0'
```

> ghfast.top 备选：`gh-proxy.com`、`mirror.ghproxy.com`。PowerShell `Invoke-WebRequest` 下载大文件会先缓冲到内存（看不到进度且慢），**优先用 curl**。

## 第 3 步：下 Ubuntu rootfs（清华镜像，325MB，~5MB/s）

```bash
curl -k -L --fail -o /c/Users/admin/ubuntu-rootfs.tar.gz \
  'https://mirrors.tuna.tsinghua.edu.cn/ubuntu-cloud-images/wsl/jammy/current/ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz'
# 验证大小约 325MB (341130963 bytes)
```

> 文件名以 `cloud-images.ubuntu.com/wsl/jammy/current/` 目录实际为准（曾为 `ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz`）。rootfs 比 appx(1GB) 小得多且走国内镜像，是装发行版的首选。

## 第 4 步：进 BIOS 开启 VT-x（用户手动，WSL2 运行前提）

**本机为联想 ThinkPad，开机时按 `F1` 进入 BIOS**（其他品牌多为 `F2` 或 `DEL`）→ `Config`（或 `Configuration`/`Security`）→ **`Intel Virtualization Technology`**（VT-x/Vanderpool）→ `Enabled` → `F10` 保存退出。

## 第 5 步：重启 Windows

让 VirtualMachinePlatform / HCS 驱动加载。**不重启则 `wsl --import` 报 `HCS_E_SERVICE_NOT_AVAILABLE`**。

## 第 6 步：重启后注册并配置 Ubuntu-22.04

```bash
# 导入（导入是文件解压，但 WSL2 仍需 HCS+VT-x 就绪）
mkdir -p "/c/Users/admin/WSL/Ubuntu-22.04"
MSYS_NO_PATHCONV=1 wsl.exe --import Ubuntu-22.04 'C:\Users\admin\WSL\Ubuntu-22.04' 'C:\Users\admin\ubuntu-rootfs.tar.gz' --version 2
# rootfs 导入默认是 root 用户；创建普通用户并设为默认
wsl -d Ubuntu-22.04 -u root -- bash -c "adduser <用户名> && usermod -aG sudo <用户名>"
# 设默认登录用户：写 /etc/wsl.conf
wsl -d Ubuntu-22.04 -u root -- bash -c "printf '[user]\ndefault=<用户名>\n' >> /etc/wsl.conf"
wsl.exe --shutdown
```

## 第 7 步：验证

```bash
wsl.exe -l -v            # 期望 Ubuntu-22.04，VERSION 2
wsl -d Ubuntu-22.04      # 以普通用户进入
```

## 常见报错对照

| 报错 | 含义 | 处理 |
|---|---|---|
| `HCS_E_SERVICE_NOT_AVAILABLE` | HCS/VMPlatform 驱动未运行 | 功能没重启生效 → 重启；仍不行查 VT-x |
| `0x80370102` | 虚拟机监视器未运行 | BIOS 没开 VT-x → 进 BIOS 开启 → 重启 |
| `0x800701bc` | WSL2 内核未装/旧 | `wsl --update` 或重装 MSI |
| `wsl --install` 只提示不安装 | stub，未装 Store 版 WSL | 走第 1+2 步（DISM + MSI），勿用 `wsl --install` |
| winget 卡在 "Starting package install" | msstore 国内不可达 | 改用 GitHub MSI（第 2 步） |
| appx 下载 ~17KB/s | Microsoft CDN 限速 | 改用 rootfs + 清华镜像（第 3 步） |

## NDK 编译环境部署（iflytek，参考 wsl-linux环境安装.pdf）

WSL Ubuntu 装好后，按 iflytek 内部文档部署 Android NDK r16b 交叉编译环境（用于编译 Linux_x86_64_PC / Android_arm_64 等平台）。

**两个前置坑**：① Windows 版 NDK（`D:\Android\android-ndk-r16b`，prebuilt/windows-x86_64）在 WSL Linux 里**不能用**，必须单独装 Linux 版；② NDK r16b 较老（2017），在 Ubuntu 22.04 有 `libncurses.so.5` 缺失的坑。

### 1. 装 build 工具 + 依赖

```bash
sudo apt install -y cmake ninja-build g++ make zip dos2unix unzip libldap2-dev openjdk-8-jdk-headless
```

### 2. sh 改 bash（仓库脚本用大量 bash 语法，默认 dash 会报错）

```bash
echo "dash dash/sh boolean false" | sudo debconf-set-selections
sudo DEBIAN_FRONTEND=noninteractive dpkg-reconfigure dash
ls -l /bin/sh          # 期望 -> /bin/bash
```

### 3. 下载 + 解压 NDK r16b Linux 版（~813MB，dl.google.com 国内 ~5MB/s）

```bash
# zip 是单文件，下载到 D 盘不慢
cd /mnt/d/Android
curl -L -o android-ndk-r16b-linux-x86_64.zip https://dl.google.com/android/repository/android-ndk-r16b-linux-x86_64.zip
# **必须解压到 WSL 原生家目录(ext4)**：实测 ~/ 解压 67 秒；解压到 /mnt/d(D盘/9P)几万小文件要几小时
unzip -q /mnt/d/Android/android-ndk-r16b-linux-x86_64.zip -d ~/android-ndk-r16b-linux-x86_64
# 结果: ~/android-ndk-r16b-linux-x86_64/android-ndk-r16b (约 1.8 万文件)
```

> Linux 版 NDK 只在 WSL 用，放 ~/ 即可，无需共享给 Windows。大 zip 解压后归档到 `D:\fnzhang\Package\`。

### 4. 环境变量（~/.bashrc）

```bash
cat >> ~/.bashrc << 'EOF'

# NDK r16b (iflytek 交叉编译)
export NDK_ROOT=$HOME/android-ndk-r16b-linux-x86_64/android-ndk-r16b
export PATH=$PATH:$NDK_ROOT
EOF
source ~/.bashrc
```

### 5. 验证 clang（libncurses.so.5 视情况修）

```bash
$NDK_ROOT/toolchains/llvm/prebuilt/linux-x86_64/bin/clang --version
# 实测本环境(已装 libldap2-dev 等) clang 5.0 正常，未触发 libncurses.so.5 缺失。
# 若报 "error while loading shared libraries: libncurses.so.5"(Ubuntu 22.04 只有 ncurses6)，软链顶替:
#   sudo ln -sf /usr/lib/x86_64-linux-gnu/libncurses.so.6 /usr/lib/x86_64-linux-gnu/libncurses.so.5
#   sudo ln -sf /usr/lib/x86_64-linux-gnu/libtinfo.so.6   /usr/lib/x86_64-linux-gnu/libtinfo.so.5
# aarch64 工具链(编译 Android_arm_64): $NDK_ROOT/toolchains/aarch64-linux-android-4.9/
```

### 6.（Windows 侧）代码目录大小写敏感

```powershell
fsutil file setCaseSensitiveInfo D:\code enable
```

### 备注

- **adb 用 Windows 的**（设备在 Windows 侧）：`~/.bashrc` 加 `alias adb='adb.exe'`，PATH 加 Windows platform-tools。
- 验证通过后即可拉 `ZNQC_VA3.5/issmain` 的 `feature/build_linux_x86_pc_2` 分支，编译 Linux_x86_64_PC & Android_arm_64 等平台。

## 回退 / 卸载

```bash
wsl.exe --unregister Ubuntu-22.04                                   # 卸发行版(删数据)
MSYS_NO_PATHCONV=1 msiexec.exe /x 'D:\fnzhang\Package\wsl.msi' /quiet    # 卸 WSL 运行时
powershell.exe -NoProfile -Command "Disable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux,VirtualMachinePlatform -NoRestart"  # 关功能(再重启)
```

## 实施记录

- **2026-07-24 本机首装**（Win11 build 26200 / i5-10210U / BIOS VT-x 当时 False）：
  - DISM 启用两功能 → Enabled ✓
  - winget msstore 卡死 → 弃用；改 GitHub MSI(2.7.10) 经 ghfast.top 镜像 50s 下完 246MB，msiexec 装好，`wsl --version`=2.7.10.0 ✓
  - aka.ms Ubuntu appx 1.04GB 仅 17KB/s → 弃用；改清华镜像下 rootfs 325MB/~5MB/s ✓
  - `wsl --import` 首次因未重启+VT-x 报 `HCS_E_SERVICE_NOT_AVAILABLE`
  - 本机为**联想 ThinkPad，开机按 `F1` 进 BIOS**；用户已开 VT-x(Intel Virtualization Technology) 并重启
  - ✅ import 成功 → **Ubuntu-22.04.5 LTS / VERSION 2 / 内核 6.18.33.2 / systemd running**
  - 已配置：默认用户 `fnzhang` + 免密 sudo + 清华 apt 源(3MB/s)
  - 安装产物均归档至 `D:\fnzhang\Package\`：`ubuntu-rootfs.tar.gz`(325M) / `wsl.msi`(246M) / `wsl-setup.sh`(配置脚本) / `android-ndk-r16b-linux-x86_64.zip`(813M)
  - **NDK 编译环境（参考 wsl-linux环境安装.pdf）**：apt 装 cmake/ninja/g++/dos2unix/libldap2-dev 等 + sh→bash + NDK r16b Linux 解压到 `~/android-ndk-r16b-linux-x86_64/` + `NDK_ROOT` + clang 5.0 验证通过、aarch64 工具链在；实测 ~/ 解压 67s（解压到 /mnt/d 几万小文件要几小时，已避坑）