From 42f6886b8883f5bd0cbacdb8ff7ebb675499a137 Mon Sep 17 00:00:00 2001 From: fnzhang Date: Fri, 24 Jul 2026 17:49:36 +0800 Subject: [PATCH] feat: add install-wsl2-ubuntu skill (wsl2-ubuntu/SKILL.md) --- README.md | 2 + wsl2-ubuntu/SKILL.md | 192 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 wsl2-ubuntu/SKILL.md diff --git a/README.md b/README.md index 6046306..e022f3c 100644 --- a/README.md +++ b/README.md @@ -5,3 +5,5 @@ ## 技能 - [install-my-git-bash](my-git-bash/SKILL.md) — 在 Windows Git Bash 上安装 xnng/my-git-bash 终端美化与工具集（mintty 主题 / git 提示符 / tmux / tree / Powerline 字体 / alias），按用户偏好安全增量安装。 + +- [install-wsl2-ubuntu](wsl2-ubuntu/SKILL.md) — 在 Windows 11 上启用 WSL2 并安装 Ubuntu 22.04（国内网络实测路径：DISM 启用功能 + GitHub MSI 经 ghfast 镜像装运行时 + 清华镜像下 rootfs + wsl --import；附 NDK r16b 交叉编译环境）。 diff --git a/wsl2-ubuntu/SKILL.md b/wsl2-ubuntu/SKILL.md new file mode 100644 index 0000000..b0375f9 --- /dev/null +++ b/wsl2-ubuntu/SKILL.md @@ -0,0 +1,192 @@ +--- +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//wsl..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 几万小文件要几小时，已避坑） + +