安装 WSL2 与 Ubuntu：从零到可验收

1. 先分清 WSL2 与 Ubuntu

因此，下面四种状态含义不同：

2. 安装前检查

当前说明面向 64 位 Windows 10 版本 2004（内部版本 19041）及以上，或 Windows 11。企业精简版、受组织策略管理的电脑，可能禁止可选功能、Microsoft Store、虚拟化或管理员提权。

2.1 在普通 PowerShell 查看系统

Get-ComputerInfo -Property WindowsProductName,WindowsVersion,OsBuildNumber
wsl --status
wsl --list --verbose

• wsl --status能输出状态，说明 WSL 命令入口已存在。
• wsl --list --verbose会列出发行版、运行状态和 WSL 版本。名称必须原样保留，例如 Ubuntu或Ubuntu-24.04。
• 旧版系统上的 wsl --version可能不支持；这不等于 Ubuntu 已损坏，先运行 wsl --update。

2.2 确认硬件虚拟化

1. 按 Ctrl + Shift + Esc打开任务管理器。
2. 进入“性能”→“CPU”。
3. 右下方“虚拟化”应显示“已启用”。

若显示“已禁用”，需要在 BIOS/UEFI 中开启 Intel VT-x、Intel Virtualization Technology、AMD-V 或 SVM Mode。不同主板名称和入口不同；修改前查电脑/主板厂商说明。云桌面或虚拟机还需要宿主机允许嵌套虚拟化。

2.3 其他准备

• 能批准 Windows UAC 管理员提示的账户。
• 稳定网络和足够磁盘空间；建议至少预留 10 GB，实际项目和缓存可能需要更多。
• 保存未完成工作，安装 Windows 功能后可能必须重启。
• 若电脑已有工作用 WSL，先运行 wsl --list --verbose记录发行版名称，不要随意注销。

3. 方式 A：客户端自动安装

这是普通用户的首选。进入 “Agent 设置”后，客户端先枚举 WSL 发行版，并排除 docker-desktop、docker-desktop-data和podman-machine-default等工具专用环境。

1. 让客户端先检查

   若已找到真实用户发行版，客户端不会重装 WSL/Ubuntu。多套环境时优先选择已安装当前 Agent CLI 的一套。

2. 点击安装 WSL 和 Ubuntu

   Windows 弹出管理员确认时选择“是”。拒绝 UAC 后安装不会发生，客户端会保留错误提示。

3. 等待下载和功能启用

   默认先尝试微软 Web 下载：wsl --install --web-download -d Ubuntu --no-launch；不支持时回退到微软默认安装源。

4. 按提示重启 Windows

   需要重启时，客户端会登记一次性恢复入口。重启登录后重新打开 Woodox，继续原来的检查。

5. 打开 Ubuntu 完成初始化

   点击客户端提供的打开按钮，在终端中创建 Linux 用户。看到 Shell 提示符后返回客户端重新检查。

3.1 大陆网络较慢时客户端怎样处理

维护者可以给安装器配置自己的 HTTPS 下载源，托管微软 WSL MSI 和 Ubuntu .wsl文件。但它不是“随便换一个镜像地址”：客户端只有在清单完整并全部验证通过时才使用。

• 根据 Windows 架构区分 x64 与 arm64。
• 下载地址必须是 HTTPS，文件名、精确字节数和 SHA256 必须与发布清单一致。
• WSL MSI 还会核对 Microsoft 发布者身份。
• 校验失败会停止使用镜像并回退到微软来源，不会继续运行未知文件。
• 镜像默认可以保持关闭；未配置时客户端只使用微软来源。

4. 方式 B：微软标准命令手动安装

适用于客户端自动流程因下载、UAC 或系统状态失败，但 Windows 的 wsl.exe仍可用的情况。以下命令在管理员 PowerShell执行。

4.1 先查看是否已有 Ubuntu

wsl --list --verbose
wsl --list --online

如果第一条已列出 Ubuntu，不要再次安装。若版本为 1，跳到“4.4 转换到 WSL2”；若状态正常且版本为 2，直接跳到“第一次启动 Ubuntu”。

4.2 安装 WSL 平台和 Ubuntu

wsl --install --web-download -d Ubuntu --no-launch

--web-download表示从在线来源下载，而不依赖 Microsoft Store；-d Ubuntu指定发行版；--no-launch表示安装后先不自动进入首次初始化。命令提示重启时执行：

Restart-Computer

如果当前 WSL 不认识 --web-download，先尝试：

wsl --update
wsl --install -d Ubuntu --no-launch

4.3 已有 WSL、只是没有发行版

wsl --list --online
wsl --install --web-download -d Ubuntu --no-launch

在线列表中的名称可能包含版本，例如 Ubuntu-24.04。若你选择该名称，后续所有 -d参数也必须使用同一个名称。

4.4 转换到 WSL2

wsl --set-default-version 2
wsl --set-version Ubuntu 2
wsl --list --verbose

转换可能需要几分钟。最后一条的 VERSION列必须为 2。发行版不是“Ubuntu”时，用列表中的真实名称替换。

4.5 更新 WSL 后重启其虚拟机

wsl --update --web-download
wsl --shutdown

wsl --shutdown会结束所有正在运行的 WSL 发行版和其中的进程。已经在 WSL 中工作的用户要先保存任务；它不是日常安装前必须执行的命令。

5. 方式 C：手动启用 Windows 功能

仅在 wsl.exe缺失，或标准安装没有正确启用功能时使用。打开管理员 PowerShell：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
Restart-Computer

重启并重新登录 Windows 后，再打开管理员 PowerShell：

wsl --update --web-download
wsl --set-default-version 2
wsl --install --web-download -d Ubuntu --no-launch

可以分别检查两个功能是否已启用：

Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform

两条结果的 State应为 Enabled。若企业策略阻止 DISM、UAC 或虚拟化，普通用户无法在客户端内部绕过，需要电脑管理员处理。

6. 第一次启动 Ubuntu

安装包完成不代表 Linux 用户环境已经完成。第一次启动会解压根文件系统，并要求创建默认 Linux 用户。

6.1 从 Windows 启动指定发行版

在普通 PowerShell 或 Windows Terminal 中执行：

wsl -d Ubuntu

若列表名称为 Ubuntu-24.04，执行 wsl -d Ubuntu-24.04。第一次启动可能先显示安装/解压进度。

6.2 创建 Linux 用户

1. 看到 Enter new UNIX username:时输入一个简短英文用户名，例如 chen。
2. 看到 New password:时输入 Linux 密码。
3. 再次输入同一密码确认。
4. 看到类似 chen@PC:~$的提示符，说明初始化完成。

6.3 在 Ubuntu 内验证身份和系统

下面命令必须在Ubuntu Shell执行：

whoami
pwd
cat /etc/os-release
uname -m
sudo -v

• whoami应输出刚创建的用户名，而不是 root。
• pwd通常输出 /home/用户名。
• /etc/os-release应显示 Ubuntu。
• sudo -v要求输入刚才设置的 Linux 密码；成功时通常不输出内容。

7. 安装 Linux 组件与 Node.js

完成 Ubuntu 初始化后，客户端仍需验证运行 Agent 所需的工具。点击 “自动安装基础组件”等价于在当前 Ubuntu 中执行：

sudo apt-get update
sudo apt-get install -y ca-certificates curl tmux bubblewrap xz-utils

Node.js/npm 检测和安装发生在当前选中的 Ubuntu，与 Windows 上是否有 npm 无关。客户端自动安装会：

1. 从 nodejs.org/dist/latest-v22.x读取 Node.js 22 的官方归档和 SHASUMS256.txt。
2. 按 CPU 架构选择归档并核对 SHA256。
3. 安装到 ~/.local/share/codex-mobile/node。
4. 把 node、npm、npx和corepack链接到 ~/.local/bin。
5. 在 ~/.profile中加入当前用户的 PATH，不覆盖 Windows Node.js。

安装后重新打开 Ubuntu，或执行：

export PATH="$HOME/.local/bin:$PATH"
node --version
npm --version
command -v node
command -v npm

两个版本命令都必须成功。客户端当前接受 Node.js 18 及以上，自动流程使用经过校验的 Node.js 22。继续安装 Agent 见Agent 设置。

8. Windows 与 Ubuntu 文件路径

WSL 同时能访问 Windows 盘符和自己的 Linux 文件系统，但路径写法不同：

• 桌面客户端选择 Windows 项目文件夹后，会把盘符路径转换成 WSL 可访问的 /mnt/盘符路径。
• 不要直接进入 %LOCALAPPDATA%\Packages\…修改 Ubuntu 虚拟磁盘内部文件，可能损坏发行版。
• 操作 Linux 家目录时，优先在 Ubuntu 中使用命令，或从资源管理器的 \\wsl$入口访问。
• 文件权限、大小写和符号链接在 Windows 挂载盘与 Linux 原生目录中的语义不完全相同。对权限敏感的项目可放在 Linux 家目录。

9. 完整验收清单

9.1 Windows PowerShell 验收

wsl --status
wsl --list --verbose
wsl -d Ubuntu --exec bash -lc "printf 'codex-mobile-ready\n'"

预期结果：

• 列表中至少有一个真实用户发行版。
• 该发行版的 VERSION 为 2。
• 第三条打印 codex-mobile-ready且没有首次初始化提示。

9.2 Ubuntu Shell 验收

whoami
test "$USER" != root && echo "user-ok"
command -v curl
command -v tmux
command -v bwrap
node --version
npm --version

选择 Codex 时，curl、tmux、bwrap、node和npm都应返回路径或版本。选择 Kimi/Qwen 时，bubblewrap 不阻止就绪。

9.3 客户端验收

10. 错误代码和恢复方法

仍失败时，先保留 wsl --status、wsl --list --verbose和完整错误，再到问题排查页生成支持包。

11. 备份、迁移与危险操作

准备重装或迁移前，在 PowerShell 导出发行版：

wsl --shutdown
wsl --export Ubuntu D:\Backup\Ubuntu-2026-07-23.tar

在另一个名称和目录中恢复：

wsl --import Ubuntu-Restored D:\WSL\Ubuntu-Restored D:\Backup\Ubuntu-2026-07-23.tar --version 2
wsl --list --verbose

官方参考

• Microsoft：安装 WSL ↗
• Microsoft：WSL 基本命令 ↗
• Microsoft：旧系统手动安装步骤 ↗
• Microsoft：WSL 故障排除 ↗
• Canonical：在 WSL2 安装 Ubuntu ↗