在 Windows 上设置 WSL 并安装 Ubuntu

​

验证 Windows 主机系统要求

​

启用 WSL 并安装 Ubuntu

​

在 WSL 中配置 Ubuntu 设置

• [automount] options = "metadata"：启用 Linux 风格的文件权限
• [boot] systemd = true：在 WSL 中启用 systemd
• [boot] command = systemctl start docker：在 WSL 启动时自动启动 Docker 服务

1. 在 Ubuntu 终端中，使用 sudo 命令在 /etc/wsl.conf 文件中添加以下内容：
   /etc/wsl.conf

   [automount]
   options = "metadata"
   
   [boot]
   systemd=true
   command = systemctl start docker
   
2. 在 Windows PowerShell 中，运行以下命令以重启 WSL：
   PowerShell

   wsl --shutdown
   

​

为 WSL 启用 USB 设备访问

1. 以管理员身份打开 Windows PowerShell，并运行以下命令安装 usbipd-win：
   PowerShell

   winget install --interactive --exact dorssel.usbipd-win
   
2. 可选：要启用镜像网络（mirrored networking），请在 Windows PowerShell 中运行以下命令，在您的用户配置文件中创建 .wslconfig 文件：
   PowerShell

   @"
   [wsl2]
   networkingMode=mirrored
   "@ | Set-Content -Encoding ASCII $env:USERPROFILE\.wslconfig
   
   在企业或由组策略（Group Policy）管理的计算机上，默认的网络地址转换（NAT）网络模式可能会阻止 usbipd 所需的防火墙规则，导致设备连接失败。切换到镜像网络会通过环回（loopback）路由连接，从而绕过该限制。
   文件名必须严格为 .wslconfig，而不是 .wslconfig.txt。记事本可能会附加 .txt 扩展名。因此，请使用 Windows PowerShell 创建该文件并应用正确的扩展名。
3. 要重启 WSL，请运行以下命令：
   PowerShell

   wsl --shutdown
   
4. 在 Ubuntu 终端中，运行以下命令安装 USB/IP 客户端工具：
   Ubuntu terminal

   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

   usbipd list
   
6. 记下要烧录的设备的 BUSID。对于烧录 Qualcomm 设备，BUSID 通常是 QDLoader 9008 设备（05c6:9008，EDL 模式）或 Fastboot 设备。
   Sample output

   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，并运行以下命令绑定该设备一次：
   PowerShell

   usbipd bind --busid 1-4
   

8. 将 1-4 替换为您实际的 BUSID。设备的 STATE 会变为 Shared。
9. 在 Windows PowerShell 中，运行以下命令将设备附加到 WSL：
   PowerShell

   usbipd attach --wsl --busid 1-4
   
   • 每次重新插拔或模式切换后需重新附加：当设备在烧录过程中切换模式时（例如，正常 → EDL 9008，或 → fastboot），Windows 会重新枚举该设备，通常会分配新的 BUSID，并且 WSL 附加会断开。请重新运行 usbipd list，然后运行 usbipd attach --wsl --busid <new-busid>。这是在 WSL 中烧录 Qualcomm 设备时常见的错误来源。
   • 每次 WSL 重启后需重新附加：附加在 wsl --shutdown 或系统重启后不会保留；只有绑定会保留。
10. 在 Ubuntu 终端中，运行以下命令确认 Ubuntu 检测到该设备：
    Ubuntu terminal

    lsusb
    
    设备必须出现在列表中，例如如下所示：
    Bus 001 Device 002: ID 05c6:9008 Qualcomm, Inc. Gobi Wireless Modem (QDL mode)
    
    在 WSL 中运行的烧录工具现在可以检测到该设备。有关烧录说明，请参阅 Qualcomm Linux 构建指南。
11. 要在烧录后分离设备，请在 Windows PowerShell 中运行以下命令：
    PowerShell

    usbipd detach --busid 1-4
    

​

排查 WSL 问题

​

WSL 中的性能问题

​

C 盘磁盘空间不足以进行 Qualcomm Linux 构建

wsl --manage Ubuntu-22.04 --move <new_drive_path>

wsl --manage Ubuntu-22.04 --move D:\WSL\Ubuntu

​

WSL 中的 DNS 解析失败

1. 要禁用自动生成 resolv.conf，请在 Ubuntu 终端中运行 sudo 命令，在 /etc/wsl.conf 文件中添加以下内容：
   /etc/wsl.conf

   [network]
   generateResolvConf = false
   
2. 要在 resolv.conf 中设置 DNS 服务器，请在 Ubuntu 终端中运行 sudo 命令，将 /etc/resolv.conf 的内容替换为您的内部 DNS 服务器，后跟一个公共 DNS 服务器作为备用：
   /etc/resolv.conf

   nameserver <your-internal-dns-ip>
   nameserver 8.8.8.8
   
   WSL 会按顺序查询名称服务器。将内部 DNS 服务器列在首位可确保域名、私有软件包注册表以及仅限虚拟专用网络（VPN）访问的资源能够正确解析。
3. 要重启 WSL 并应用更改，请在 Windows PowerShell 中运行以下命令：
   PowerShell

   wsl --shutdown
   

​

Yocto 构建中的 Git Filename too long 错误

git config --global core.longpaths true

​

USB 设备无法附加到 WSL

1. 要确认 usbipd 已绑定设备，请以管理员身份在 Windows PowerShell 中运行 usbipd list，并验证 STATE 列显示为 Shared。如果为 Not shared，则附加会失败。请以管理员身份在 Windows PowerShell 中使用 usbipd bind --busid <busid> 命令进行绑定。
2. 要检查网络模式，请确认 usbipd attach 输出报告 Detected networking mode mirrored。如果报告为 nat，则说明在受管理的计算机上，企业防火墙或组策略正在阻止连接。要解决此问题，请执行以下操作： a. 按照为 WSL 启用 USB 设备访问中步骤 2 的描述启用镜像网络。 b. 验证 .wslconfig 文件名和路径是否正确。 c. 运行 wsl --shutdown 使更改生效。
3. 当您拔出设备或切换模式时，BUSID 可能会发生变化。如果 BUSID 已更改，请执行以下操作： a. 重新运行 usbipd list 以确认当前的 BUSID。 b. 重新运行 usbipd attach --wsl --busid <new-busid>。 c. 确认 WSL 已安装 USB/IP 客户端工具。

​

后续步骤

• 同步、构建和烧录 Qualcomm Linux