> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 在 Windows 上设置 WSL 并安装 Ubuntu
适用于 Linux 的 Windows 子系统（WSL）是一项 Windows 功能，可在不使用虚拟化软件的情况下在 Windows 上运行 Linux 发行版。WSL 允许 Linux 用户空间与 Windows 应用程序在同一主机上并行运行，无需单独的虚拟机。
下图显示了设置 WSL 并安装 Ubuntu 所涉及的任务：
## 验证 Windows 主机系统要求
下表列出了 WSL 环境进行 Qualcomm Linux 构建所需的最低硬件资源：
| 要求 | 规格 |
| ------ | ----------- |
| 处理器架构 | X64 |
| CPU 核心 | 8 个或更多 |
| RAM | 16 GB 或更多 |
| 存储 | 400 GB 可用空间 |
## 启用 WSL 并安装 Ubuntu
Qualcomm Linux 使用 Ubuntu 22.04 Linux 发行版。启用 WSL 和安装 Ubuntu 的步骤因 Windows 版本而异。请按照适用于您版本的说明操作：
有关如何启用 WSL 2 并安装 Ubuntu 22.04 的说明，请参阅[在 WSL 2 上安装 Ubuntu](https://documentation.ubuntu.com/wsl/latest/howto/install-ubuntu-wsl2/)。
较旧版本的 Windows 不支持通过 Microsoft Store 安装 WSL，需要手动安装。有关说明，请参阅[较旧版本 WSL 的手动安装步骤](https://learn.microsoft.com/en-us/windows/wsl/install-manual?source=recommendations)。
## 在 WSL 中配置 Ubuntu 设置
要设置 WSL 环境，请在 WSL 中配置 WSL 特定设置。使用 `wsl.conf` 文件为您安装的 Linux 发行版配置以下 WSL 特定设置：
* `[automount] options = "metadata"`：启用 Linux 风格的文件权限
* `[boot] systemd = true`：在 WSL 中启用 systemd
* `[boot] command = systemctl start docker`：在 WSL 启动时自动启动 Docker 服务
每次打开 WSL 时，WSL 都会自动应用 `wsl.conf` 文件中的设置。
要配置 WSL 特定设置，请执行以下操作：
1. 在 Ubuntu 终端中，使用 `sudo` 命令将以下内容添加到 `/etc/wsl.conf` 文件中：
```ini title="/etc/wsl.conf" theme={null}
[automount]
options = "metadata"
[boot]
systemd=true
command = systemctl start docker
```
2. 在 Windows PowerShell 中，运行以下命令以重启 WSL：
```powershell title="PowerShell" theme={null}
wsl --shutdown
```
## 为 WSL 启用 USB 设备访问
WSL 2 运行在一个轻量级 VM 中，默认无法访问 USB 设备。因此，`lsusb` 等命令和烧录工具无法检测到目标设备。
要为 WSL 启用 USB 访问，请使用 [usbipd-win](https://github.com/dorssel/usbipd-win) 通过 USB/IP 将 USB 设备的流量从 Windows 传递到 WSL：
1. 以管理员身份打开 Windows PowerShell，并运行以下命令来安装 `usbipd-win`：
```powershell title="PowerShell" theme={null}
winget install --interactive --exact dorssel.usbipd-win
```
2. 可选：要启用镜像网络（mirrored networking），请在 Windows PowerShell 中运行以下命令，在您的用户配置文件中创建 `.wslconfig` 文件：
```powershell title="PowerShell" theme={null}
@"
[wsl2]
networkingMode=mirrored
"@ | Set-Content -Encoding ASCII $env:USERPROFILE\.wslconfig
```
在公司管理或受组策略管理的计算机上，默认的网络地址转换（NAT）网络模式可能会阻止 usbipd 所需的防火墙规则，导致设备附加失败。切换到镜像网络会通过环回（loopback）路由连接，从而绕过该限制。
文件必须命名为 `.wslconfig`，而不是 `.wslconfig.txt`。记事本可能会附加 `.txt` 扩展名。因此，请使用 Windows PowerShell 创建文件并应用正确的扩展名。
3. 要重启 WSL，请运行以下命令：
```powershell title="PowerShell" theme={null}
wsl --shutdown
```
4. 在 Ubuntu 终端中，运行以下命令来安装 USB/IP 客户端工具：
```bash title="Ubuntu terminal" theme={null}
sudo apt update
sudo apt install -y linux-tools-virtual hwdata
sudo update-alternatives --install /usr/local/bin/usbip usbip "$(ls /usr/lib/linux-tools/*/usbip | tail -n1)" 20
```
5. 以管理员身份打开 Windows PowerShell，并运行以下命令列出已连接的 USB 设备：
```powershell title="PowerShell" theme={null}
usbipd list
```
6. 记下要烧录设备的 `BUSID`。对于烧录 Qualcomm 设备，`BUSID` 通常是 QDLoader 9008 设备（`05c6:9008`，EDL 模式）或 Fastboot 设备。
```text title="Sample output" theme={null}
BUSID VID:PID DEVICE STATE
1-4 05c6:9008 Qualcomm HS-USB QDLoader 9008 Not shared
2-1 18d1:4ee7 Android / Fastboot device Not shared
```
7. 以管理员身份打开 Windows PowerShell，并运行以下命令绑定设备一次。将 `` 替换为第 6 步中的 `BUSID`（例如 `1-4`）：
```powershell title="PowerShell" theme={null}
usbipd bind --busid
```
绑定在重启后仍然有效，因此每个设备只需绑定一次。
8. 验证设备的 `STATE` 是否变为 `Shared`。
9. 在 Windows PowerShell 中，运行以下命令将设备附加到 WSL：
```powershell title="PowerShell" theme={null}
usbipd attach --wsl --busid
```
* 每次重新插拔或模式切换后需重新附加：当设备在烧录期间更改模式时（例如正常 → EDL 9008，或 → fastboot），Windows 会重新枚举该设备，通常会分配新的 `BUSID`，并且 WSL 附加会断开。请重新运行 `usbipd list`，然后运行 `usbipd attach --wsl --busid `。这是在 WSL 中烧录 Qualcomm 设备时的常见错误来源。
* 每次 WSL 重启后需重新附加：附加不会在 `wsl --shutdown` 或系统重启后保留；只有绑定会保留。
10. 在 Ubuntu 终端中，运行以下命令确认 Ubuntu 检测到该设备：
```bash title="Ubuntu terminal" theme={null}
lsusb
```
该设备必须出现在列表中，例如如下所示：
```
Bus 001 Device 002: ID 05c6:9008 Qualcomm, Inc. Gobi Wireless Modem (QDL mode)
```
在 WSL 内运行的烧录工具现在可以检测到该设备。有关烧录说明，请参阅[烧录软件镜像](/zh/Key-Documents/Flash-Guide/flash-with-qdl)。
11. 要在烧录后分离设备，请在 Windows PowerShell 中运行以下命令：
```powershell title="PowerShell" theme={null}
usbipd detach --busid
```
## 排查 WSL 问题
解决在使用 WSL 进行 Qualcomm Linux 构建时可能出现的与性能、磁盘空间、域名系统（DNS）、构建错误和 USB 直通相关的常见问题。
### WSL 中的性能问题
如果您在 WSL 中遇到性能问题，请使用 `.wslconfig` 文件调整全局资源限制，例如内存、CPU 和交换空间。这些资源限制适用于所有 WSL 2 发行版。
请逐步调整设置，并在每次更改后验证结果。有关更多信息，请参阅 [WSL 中的高级设置配置](https://learn.microsoft.com/en-us/windows/wsl/wsl-config)。
不要将内存和 CPU 值配置为与主机规格一致。过度分配可能会降低稳定性并对 Windows 性能产生不利影响。
### C 盘磁盘空间不足以进行 Qualcomm Linux 构建
默认情况下，Ubuntu 安装在 C 盘上。如果 C 盘没有足够的可用空间进行 Qualcomm Linux 构建，请将 Ubuntu 安装移动到其他驱动器。
要移动 Ubuntu 安装，请以管理员身份在 Windows PowerShell 中运行以下命令：
```powershell title="PowerShell" theme={null}
wsl --manage Ubuntu-22.04 --move
```
例如：
```powershell title="PowerShell" theme={null}
wsl --manage Ubuntu-22.04 --move D:\WSL\Ubuntu
```
### WSL 中的 DNS 解析失败
WSL 可能无法解析域名，导致依赖网络的操作（例如获取软件包或克隆仓库）因 DNS 错误而失败。
要修复 DNS 解析失败，请使用 `resolv.conf` 文件手动配置 DNS 设置：
1. 要禁用自动生成 `resolv.conf`，请在 Ubuntu 终端中运行 `sudo` 命令，将以下内容添加到 `/etc/wsl.conf` 文件中：
```ini title="/etc/wsl.conf" theme={null}
[network]
generateResolvConf = false
```
2. 要在 `resolv.conf` 中设置 DNS 服务器，请在 Ubuntu 终端中运行 `sudo` 命令，将 `/etc/resolv.conf` 的内容替换为您的内部 DNS 服务器，并以公共 DNS 服务器作为后备：
```bash title="/etc/resolv.conf" theme={null}
nameserver
nameserver 8.8.8.8
```
WSL 会按顺序查询 nameserver。将内部 DNS 服务器放在前面可确保域名、私有软件包注册表和仅限虚拟专用网络（VPN）的资源能够正确解析。
3. 要重启 WSL 并应用更改，请在 Windows PowerShell 中运行以下命令：
```powershell title="PowerShell" theme={null}
wsl --shutdown
```
### Yocto 构建中的 Git `Filename too long` 错误
在 WSL 中运行 Qualcomm Linux Yocto 构建时，Git 可能会失败并报 `Filename too long` 错误。发生此错误的原因是 Windows 强制执行默认的 `MAX_PATH` 限制（260 个字符），而 Yocto 构建路径可能会超过该限制。
要修复此错误，请在 Ubuntu 终端中运行以下命令为 Git 启用长路径支持：
```bash title="Ubuntu terminal" theme={null}
git config --global core.longpaths true
```
### USB 设备无法附加到 WSL
如果 `usbipd attach` 失败、无响应，或设备未出现在 `lsusb` 中，请执行以下操作：
1. 要确认 usbipd 已绑定设备，请以管理员身份在 Windows PowerShell 中运行 `usbipd list`，并验证 `STATE` 列显示 `Shared`。如果显示 `Not shared`，则附加会失败。请以管理员身份在 Windows PowerShell 中使用 `usbipd bind --busid ` 命令进行绑定。
2. 要检查网络模式，请确认 `usbipd attach` 输出报告 `Detected networking mode mirrored`。如果报告 `nat`，则在受管计算机上是公司防火墙或组策略正在阻止连接。要解决此问题，请执行以下操作：
a. 按照[为 WSL 启用 USB 设备访问](#enable-usb-device-access-for-wsl)第 2 步中的说明启用镜像网络。
b. 验证 `.wslconfig` 文件名和路径是否正确。
c. 运行 `wsl --shutdown` 使更改生效。
3. 拔下设备或切换模式时，`BUSID` 可能会改变。如果 BUSID 已更改，请执行以下操作：
a. 重新运行 `usbipd list` 以确认当前的 `BUSID`。
b. 重新运行 `usbipd attach --wsl --busid `。
c. 确认 WSL 已安装 USB/IP 客户端工具。
如果启用镜像网络后附加仍然失败，则可能是组策略完全阻止了 `usbipd` 防火墙规则。在这种情况下，请改为在原生 Ubuntu 主机上进行烧录，因为那里不需要 USB 直通。
## **下一步**
* [同步、构建和烧录 Qualcomm Linux](https://dragonwingdocs.qualcomm.com/Key-Documents/Flash-Guide/flash-with-qdl)