============================================================

双平台兼容 frontmatter：SkillHub（腾讯 skillhub.cn）+ WorkBuddy

SkillHub 必填：slug / displayName / version / summary / license

WorkBuddy 必填：name / description / visibility

============================================================

slug: wsl2-offline-install-user-d70812d0
name: wsl2-offline-install

SkillHub 用 displayName（对外展示标题），WorkBuddy 用 display_name

displayName: WSL2 离线安装
display_name: "WSL2 离线安装"
display_name_en: "WSL2 Offline Installer"

version: 1.1.0
agent_created: true
visibility: "public"
license: MIT

SkillHub 简介（一句话展示在搜索结果里）

summary: 在 Windows 上离线安装 WSL2 + Ubuntu（22.04/24.04 双版本），覆盖默认安装失败的全部兜底路径，兼容 WSL 3.0

WorkBuddy 用 description（三段：何时用、做了什么、价值）

description: 在 Windows（特别是 Win11 24H2）上离线安装 WSL2 + Ubuntu（22.04/24.04）的完整工作流，兼容 WSL 3.0。当默认 wsl --install 失败（DNS 污染、Microsoft Store 不可用、raw.githubusercontent.com 解析失败、用户没有 Microsoft 账户等）时使用本 skill。覆盖身份诊断、绝对路径版启用命令、离线 rootfs 下载、wsl --import、非 root 用户配置、sudo NOPASSWD、BitLocker 应对、PATHEXT/PATH 损坏修复。

description_zh: "在 Windows（特别是 Win11 24H2）上离线安装 WSL2 + Ubuntu 22.04。当默认 wsl --install 失败（DNS 污染、Microsoft Store 不可用、企业网络受限、没有 Microsoft 账户等）时启用。覆盖身份诊断、绝对路径命令、离线 rootfs 导入、非 root 用户配置、sudo NOPASSWD 配置、BitLocker 应对、PATHEXT/PATH 损坏修复。"

description_en: "Offline installation workflow for WSL2 + Ubuntu 22.04 on Windows 11 24H2. Use when default wsl --install fails (DNS poisoning, Microsoft Store unavailable, no Microsoft account, BitLocker lockout, corrupted PATHEXT/PATH). Covers admin diagnostics, absolute-path commands, offline rootfs import via wsl --import, non-root user setup, and sudo NOPASSWD configuration."

SkillHub 长描述（详情页正文，可选）

long_description: |
这是一条面向"已经在 WSL 安装上折腾了很久、走投无路"的工程师的离线兜底工作流。

默认 wsl --install 在中国大陆网络环境下经常失败：raw.githubusercontent.com
被 DNS 污染、Microsoft Store 不可访问、企业网关拦截、企业机没有 Microsoft
账户……本 skill 把所有这些失败场景里"还能走通"的最稳路径抽出来：

1. 用管理员 cmd + 绝对路径命令（绕过 PATHEXT 坏掉、PATH 缺省等环境问题）
2. 从 cloud-images.ubuntu.com 直接下 rootfs（绕过微软 CDN）
3. wsl --import 直接导入（绕过 Microsoft Store / Winget 通道）
4. 进入 Linux 后建非 root 用户、装 sudo、配 NOPASSWD、配默认登录用户

一气呵成，不会再走"装好了 → 重启 → 微软账户卡死"的死循环。

metadata:
categories: [development-tools, productivity-tools, operating-system]
author: "@user_d70812d0"
handle: "user_d70812d0" # SkillHub 用户 handle，发布 slug 前缀
display_handle: "@user_d70812d0"
homepage: ""
repository: ""
tested_on:
- "Windows 11 24H2 (Build 26200, Xiaomi Book Pro 14)"
- "Windows 11 23H2 (Build 22631, validated via repo records)"
prerequisites:
- "当前用户必须在本地 Administrators 组"
- "联网下载 ~340-360MB Ubuntu rootfs"
- "管理员 cmd（注意：不是 PowerShell / .cmd 文件右键菜单）"
failure_modes_addressed:
- "WININET_E_NAME_NOT_RESOLVED (raw.githubusercontent.com DNS 污染)"
- "0x800f0922 / ERROR_ACCESS_DENIED (dism 启用功能被拒)"
- "BitLocker 恢复密钥拦截 WinRE"
- "PATHEXT 只剩 .CPL"
- "管理员 cmd 窗口 POST 换行丢失"
keywords: [wsl, wsl2, ubuntu, windows, offline, dism, rootfs, 离线安装, 内网, dns污染, bitlocker]

Windows WSL2 离线安装工作流

何时用这条 skill

满足任一条件时优先用本 skill 而不是默认 wsl --install：

1. wsl --install -d Ubuntu-22.04 报 WININET_E_NAME_NOT_RESOLVED（raw.githubusercontent.com 解析失败，国内 DNS 常见）
2. Microsoft Store 无法访问（企业网络、机器没有 Microsoft 账户）
3. dism enable-feature 被拒（用户不是真管理员 / UAC 关闭 / BitLocker 卡住）
4. 用户机器 PATHEXT 被改坏 / PATH 不完整，命令报"不是内部或外部命令"
5. 任何"已经卡了很久、走投无路"的 WSL 安装场景

WSL 3.0 时代兼容性说明（2026-10 更新）

微软已发布 WSL 3.0（WSLC Linux 容器 GA、wslc.exe/container.exe、内核升至 6.18 LTS）。与本 skill 的关系：

• 本 skill 的离线路径在 WSL 3.0 下依然有效，完全向后兼容——dism 启用功能 + wsl --import 导入发行版的核心流程没有变化
• wsl --update 更新的是 WSL 系统组件版本，不影响已导入的发行版，也不改变导入方式
• WSLC 容器（wslc）是独立的新能力，与本 skill 的离线安装无关；离线装好后想用容器再 wsl --update 升级即可
• 内核 6.18 随 WSL 更新自动跟进，无需在安装阶段关心内核版本

三段式流程

A. 诊断（必须先做，避免后面绕路）
B. 启用 WSL2 功能 + 离线 rootfs 导入
C. 配置非 root 用户 + sudo NOPASSWD

A. 诊断（管理员 cmd，单条粘，别一次粘多行）

whoami /groups | findstr "S-1-16-12288"

• 看到 Mandatory Label\High Mandatory Level 一行 → 真管理员，跳到 B
• 没看到 → 当前用户不是管理员，停——按下面"管理员失效"应急处理

echo %PATHEXT%

• 必须是 .COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC
• 不是（比如只剩 .CPL）→ 修复：[Environment]::SetEnvironmentVariable("PATHEXT", ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC", "User")（必须新开窗口才生效）

where dism & where wsl & where curl

• 三个都返回绝对路径 → 环境正常
• 哪个缺 → 用 C:\Windows\System32\<name>.exe 绝对路径顶替

网络探测（验证能不能下 rootfs）：

curl -sI https://cloud-images.ubuntu.com/wsl/jammy/current/ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz | findstr "HTTP"

• 返回 HTTP/1.1 200 OK → 直下这条路可走
• 返回 000 / 超时 → 走镜像源（见 B-2 备选）

B. 启用 + 离线导入

B-1. 启用 WSL2 功能（单行，避免换行丢失）

C:\Windows\System32\dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all

C:\Windows\System32\dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all

中间可能提示"需要重启"——真重启一次（不要靠 /norestart，那个标志会抑制重启对话框导致用户找不到"同意重启"入口）。

B-2. 下载 Ubuntu rootfs（先选版本，再用单行 + & 串联）

版本选择（链接均 2026-10 实测有效）：

选 22.04（cloud-images 直下，国内网络 1-5 分钟）：

mkdir C:\WSL 2>nul & curl -L -o C:\WSL\ubuntu-22.04.tar.gz https://cloud-images.ubuntu.com/wsl/jammy/current/ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz

选 22.04 备选（直连不通时，清华镜像）：

mkdir C:\WSL 2>nul & curl -L -o C:\WSL\ubuntu-22.04.tar.gz https://mirrors.tuna.tsinghua.edu.cn/ubuntu-cloud-images/wsl/jammy/current/ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz

选 24.04（cloud-images 直下，注意国内镜像站未同步此结构，无备选源）：

mkdir C:\WSL 2>nul & curl -L -o C:\WSL\ubuntu-24.04.tar.gz https://cloud-images.ubuntu.com/wsl/releases/24.04/current/ubuntu-noble-wsl-amd64-wsl.rootfs.tar.gz

文件名历史坑：早期 22.04 叫 jammy-server-cloudimg-amd64-wsl.rootfs.tar.gz，现名是 ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz；24.04 的目录结构与 22.04 不同（在 releases/24.04/current/ 下而非 noble/current/，noble/current/ 下只有 manifest 没有 rootfs）。如果下到 ~286 字节的 404 页面，先 del 再换文件名/目录重试。

验证下载完整：

dir C:\WSL\ubuntu-22.04.tar.gz

• 22.04 大小应在 330–350 MB 区间；24.04 应在 345–370 MB 区间

B-3. 导入 + 首次启动（单行）

22.04：

wsl --import Ubuntu-22.04 C:\WSL\Ubuntu22 C:\WSL\ubuntu-22.04.tar.gz & wsl -d Ubuntu-22.04

24.04（发行版名和目录对应改）：

wsl --import Ubuntu-24.04 C:\WSL\Ubuntu24 C:\WSL\ubuntu-24.04.tar.gz & wsl -d Ubuntu-24.04

预期：先看到 操作成功完成，提示符自动切到 root@...#（默认 root 登录）。

C. 配置非 root 用户（Linux 终端里逐条粘）

C-1. 建用户

useradd -m -s /bin/bash court

（court 改成你想要的用户名，下同）

C-2. 设密码（交互式，两次盲打）

passwd court

• 输入密码时屏幕不显示任何字符（连星号都没有），这是 Linux 设计，不是键盘坏了
• 两次必须完全一致，否则报 Sorry, passwords do not match，重跑即可
• 建议：避开 Windows 密码，纯字母+数字

C-3. 装 sudo + 配置 NOPASSWD + 默认用户 + 退出（一气呵成）

apt update -qq && apt install -y sudo && echo 'court ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/court && chmod 0440 /etc/sudoers.d/court && printf '[user]\ndefault=court\n' > /etc/wsl.conf && exit

预期：
- apt install -y sudo 跑 30-90 秒（网络慢的话更久）
- echo / chmod / printf 瞬间完成
- exit 退出 Ubuntu，自动回 Windows cmd

C-4. 验证默认用户生效

wsl --shutdown & wsl -d Ubuntu-22.04

预期提示符变成 court@...$（结尾 $ = 普通用户，# = root）。如果还是 root@...#，说明 /etc/wsl.conf 没写对，重复 C-3。

C-5. 验证 sudo 可用

sudo apt update -qq

无密码提示直接执行 → NOPASSWD 生效。

D. 换国内 apt 源（装完必做，不然所有 apt install 都极慢或失败）

为什么必须做

Ubuntu 22.04 默认 sources.list 指向 http://archive.ubuntu.com/ubuntu/（美国/欧洲节点），国内直连：
- 30KB/s ~ 200KB/s（要装 node/python/git 全天打底）
- 偶发 DNS 污染完全连不上
- 频繁断流 apt update 超时

在 Ubuntu 上做 Python/Node/AI 任何开发前，先换源。

一键换源脚本（推荐）

仓库自带 change-apt-source.sh（阿里云镜像，幂等可重跑）：

bash /mnt/d/Users/2026-09-04-12-31-52/wsl2-offline-install-v1.0.0/change-apt-source.sh

脚本会自动：
1. 备份 /etc/apt/sources.list → sources.list.bak.YYYYMMDD_HHMMSS
2. 把 archive.ubuntu.com / security.ubuntu.com 全部替换为 mirrors.aliyun.com
3. 跑 apt update && apt upgrade -y

> ⚠️ 注意：脚本只处理传统格式的 /etc/apt/sources.list（22.04 适用）。24.04 用 deb822 格式（/etc/apt/sources.list.d/ubuntu.sources），请用上面"手工换源"的 24.04 命令。

手工换源（不想跑脚本）

22.04（传统 sources.list 格式）：

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
sudo sed -i 's|http://archive.ubuntu.com|http://mirrors.aliyun.com|g; s|http://security.ubuntu.com|http://mirrors.aliyun.com|g' /etc/apt/sources.list
sudo apt update && sudo apt upgrade -y

24.04（⚠️ 改用 deb822 格式，源文件在 /etc/apt/sources.list.d/ubuntu.sources，对 /etc/apt/sources.list 跑 sed 无效）：

sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak
sudo sed -i 's|http://archive.ubuntu.com|http://mirrors.aliyun.com|g; s|http://security.ubuntu.com|http://mirrors.aliyun.com|g' /etc/apt/sources.list.d/ubuntu.sources
sudo apt update && sudo apt upgrade -y

清华源（备选）：把 mirrors.aliyun.com 换成 mirrors.tuna.tsinghua.edu.cn。

验证换源生效

apt policy python3 2>/dev/null | head -3
# 应显示 Candidate from mirrors.aliyun.com/ubuntu

或直接看更新后下载速度：

time sudo apt install -y python3-pip    # 应 < 30 秒

还原成默认源

sudo cp /etc/apt/sources.list.bak.* /etc/apt/sources.list
sudo apt update

应急：管理员身份失效怎么办

症状

• whoami /groups | findstr "S-1-16-12288" 无输出
• net session >nul 2>&1 && echo ADMIN_YES || echo ADMIN_NO 报 ADMIN_NO
• dism / Enable-WindowsOptionalFeature 直接拒绝

第一步：先排除"命令粘贴换行丢失"假阳性

一次粘多行命令到 cmd 时换行可能丢失，导致 findstr 找不到输出。每条命令单独粘一行重试。

第二步：查真实身份

让用户手动开管理员 cmd，粘：

whoami /groups | findstr "S-1-16-12288"

单独一行粘。如果还没看到 → 真的不是管理员。

第三步：找管理员

• 让用户右键 cmd.exe（命令提示符程序本身，不是 .cmd 文件） → "以管理员身份运行" → UAC 弹窗点"是"
• .cmd 文件的右键菜单默认没有"以管理员身份运行"——必须右键 cmd.exe 程序

第四步：Administrator 不可用时

如果当前用户确实不在 Administrators 组，且 WinRE 因 BitLocker 进不去：
- 用 PowerShell 跑 Enable-LocalUser -Name Administrator 会拒绝访问（普通用户改不了）
- 最后兜底：制作一个 Win10/11 安装 U 盘，从 U 盘启动进"修复计算机 → 命令提示符"（SYSTEM 身份，不需要 BitLocker 密钥）→ net user Administrator /active:yes → net user Administrator <密码>

防换行丢失的硬规则（最重要）

给用户的 cmd 命令必须：
1. 每条单独一行粘贴——一次粘多行换行符会丢，命令拼接成诡异路径
2. 需要串行多条时用 & 串联成单行：cmd1 & cmd2 & cmd3
3. 路径中有空格的用双引号包："C:\Program Files\..."
4. 绝对路径优先：C:\Windows\System32\dism.exe 比 dism 稳

速查：今日踩过的全部坑（避免重蹈）

完成标志

• Windows cmd 跑 wsl -d Ubuntu-22.04 → 提示符 court@...$
• 跑 sudo apt update -qq 无密码提示
• 跑 whoami 在 WSL 里返回 court（不是 root）
• 跑 apt policy python3 | head -3 显示 mirrors.aliyun.com/ubuntu（换源已完成）

引用方式

在 WorkBuddy / Claude / Cursor 中直接使用

把本 SKILL.md 丢到本地 skills 目录（WorkBuddy：~/.workbuddy/skills/wsl2-offline-install/），下次遇到 WSL 安装问题时把这一段发给 AI 助手即可：

请按 wsl2-offline-install skill 工作流帮我在 Windows 上装 WSL2 + Ubuntu 22.04。
路径：C:\WSL\ubuntu-22.04.tar.gz 已下载完毕。

作为 SkillHub skill 安装

参见仓库根目录 PUBLISH.md。

反馈与支持（用过本 skill 觉得好用 / 不好用都告诉我）

哪里反馈

反馈什么最有价值

最有用的反馈不是"好用/不好用"，而是：
1. 你在哪一步卡住了？（对应 SKILL.md 的 A/B/C/D 哪一段）
2. 报错原文是什么？（尤其是 Win10 / 11 24H2 / 企业网络环境下的特殊情况）
3. 你的解法是什么？（如果试出来了）

自动收集（仓库自带脚本）

collect-reviews.sh（v1.0.2 起附带）会：
- 调 SkillHub OpenAPI 拉本 skill 的 review 列表
- 落盘到 reviews.json + reviews-summary.md
- 自动按"卡住步骤 + 报错关键词"分类聚合
- 输出"下次升级最该改的前 3 个点"

用法：过审后在 WSL 跑 bash /mnt/d/.../wsl2-offline-install-v1.0.0/collect-reviews.sh。

> 本 skill 的迭代哲学：v1.0.0 → v1.0.1 → v1.0.2 → v1.1.0，每个版本都由真实踩坑与月度生态复查反哺（v1.1.0：Ubuntu 24.04 支持 + WSL 3.0 兼容声明 + 链接全量重验），用户每一条 review 都会进下一个小版本。