fnzhang/tool-skills
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
tool-skills/wsl2-ubuntu/SKILL.md

12 KiB
Raw Blame History

name description
install-wsl2-ubuntu 在 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 步：预检

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 启用两个功能（管理员）

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 镜像）

# 查最新 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）

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

# 导入（导入是文件解压，但 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 步：验证

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 工具 + 依赖

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

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

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）

# 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）

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 视情况修）

$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 侧）代码目录大小写敏感

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 等平台。

回退 / 卸载

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 几万小文件要几小时，已避坑）