树莓派操作系统中的USB Gadget模式：通过USB进行SSH连接

介绍 rpi-usb-gadget

从2025年10月20日及之后发布的Raspberry Pi OS Trixie镜像开始，系统默认包含一个名为rpi-usb-gadget 的新软件包。只需在树莓派镜像工具中切换一个开关即可启用它，这使得USB网络设置变得极其简单。

启用后：

• 你的树莓派连接到PC时，会将自己呈现为一个USB以太网设备。

• 你可以直接使用在树莓派镜像工具中设置的主机名进行SSH连接——无需任何Wi-Fi或以太网设置。

• 如果你的PC有活跃的互联网连接并启用了ICS，树莓派将通过同一根USB线缆自动获得网络访问。

• 树莓派上会运行一个轻量级的后台服务，用于检测主机连接状态，并自动在独立模式和ICS支持的网络模式之间切换。

• 实际上，它的行为非常类似于智能手机上的USB网络共享——但这是为树莓派设计的。

该软件包支持所有主流主机系统：Windows、macOS和Linux。

重要硬件说明

要使用USB Gadget模式，树莓派必须连接到支持OTG（设备模式）的USB端口：

树莓派型号需使用的USB端口Raspberry Pi Zero, Zero W, Zero 2 W靠近HDMI的micro USB端口——不是“PWR IN”口Raspberry Pi 4, 5, 500, 500+板载的USB-C端口Compute Module 5树莓派 CM5 IO板上的USB-C端口Compute Module 4需要额外手动设置，不支持自动配置

警告：
一旦启用Gadget模式，所选端口将专门用作USB网络连接和电源输入；它将不再作为常规的USB主机端口工作。这意味着在Gadget模式激活时，无法在该端口连接键盘、存储设备或其他外设。

支持的板卡：

• Raspberry Pi Zero (W) 和 Zero 2 W

• Raspberry Pi 3 Model A+

• Raspberry Pi 4 Model B

• Raspberry Pi 5, 500, 和 500+

• Compute Module 5

• Compute Module 4（技术上支持，但需要额外手动设置）

为了获得最佳稳定性——尤其是在Raspberry Pi 4, 5 和 500/500+上——请将树莓派直接连接到电脑的USB端口。某些笔记本电脑USB端口可能无法提供足够的电力，可能导致设备重启或USB链路断开。

推荐配件： 树莓派USB 3集线器允许你通过外部电源为设备供电，同时仅通过USB连接传输数据；这对于USB供电能力较弱的笔记本电脑来说非常理想。

轻松启用Gadget模式：使用Raspberry Pi Imager 2.0

1. 生成一个功能增强的清单。

2. 双击生成的os_list_local.rpi-manifest 文件。

3. 选择一个Raspberry Pi OS Trixie镜像（2025年10月20日或更新版本）。

4. 在“自定义”菜单中，设置一个主机名。

   • 这将是你用来SSH连接树莓派的名字。

   • 如果主机上禁用了ICS，回退IP将是 10.12.194.1。

5. 进入“接口与功能”，切换“启用USB Gadget模式”。

6. 写入镜像，将存储卡插入树莓派，并使用正确的USB/OTG端口（不仅仅是电源输入口）将其连接到你的电脑。

7. 启动树莓派（首次启动可能比平时长，并可能重启一次——这属于正常情况）。

8. 启动完成后，你的树莓派应作为新的以太网适配器出现在主机上。

   现在你可以使用你设置的主机名进行SSH连接了。

   

Windows驱动要求

Windows不包含通用的USB以太网Gadget设备驱动。为了避免依赖仿冒的供应商ID或非官方驱动，我们提供了一个专用的安装程序：从GitHub项目发布页面下载并运行rpi-usb-gadget-driver-setup.exe。

每台Windows电脑只需执行一次此操作。

互联网连接共享 (ICS)

如果你希望树莓派通过USB连接访问互联网，请在主机电脑上启用互联网连接共享 (ICS)。

在Windows上：

1. 插入树莓派，确认它显示为新的以太网适配器。

   • → 它将显示为类似“以太网 7 — Raspberry Pi USB Remote NDIS Network Device”的名称。

2. 打开“网络连接”：

   • → 控制面板 → 网络和 Internet → 网络和共享中心 → 更改适配器设置

   • → 或者按 Win + R 键，输入 ncpa.cpl。

3. 找到你主要的互联网连接适配器（例如Wi-Fi），打开“属性”。

4. 转到“共享”选项卡，勾选“允许其他网络用户通过此计算机的Internet连接来连接…”，并在下拉菜单中选择树莓派USB以太网适配器。

5. 确认你的选择；大约60秒内，树莓派应该会获得一个IP地址。

   

关于Windows ICS行为的注意事项：
如果树莓派未连接时为它的适配器启用了ICS，Windows可能会将其DHCP服务绑定到另一个接口（例如Hyper-V适配器）。在这种情况下，树莓派接口可能显示为“已共享”，但无法获得DHCP租约。要解决此问题，请完全禁用你共享网络来源的所有适配器上的ICS，插入树莓派，然后重新启用ICS。

在macOS上：

1. 连接树莓派，等待其显示为新的USB以太网设备。

2. 打开系统设置 → 通用 → 共享 → 互联网共享。

3. 启用前，点击信息图标进行配置：

   • → 你的互联网来源（例如Wi-Fi）

   • → 选择树莓派USB Gadget接口作为共享目标

4. 保存并打开“互联网共享”开关。

   

在Linux上：
使用你发行版的NetworkManager或等效工具，启用从你的主要互联网连接到树莓派USB Gadget网络接口的路由和NAT。具体说明因桌面环境或初始化系统而异。

不使用Imager启用USB Gadget模式

这仅适用于基于Raspberry Pi OS Trixie的镜像。

全新镜像（首次启动前）：
Cloud-init可以在首次启动时自动启用USB Gadget模式：

1. 挂载启动分区：boot。

2. 编辑并补充：user-data 。

   rpi:
     enable_usb_gadget: true
   enable_ssh: true  # 可选，但在使用Gadget模式时建议启用

3. 建议你在同一文件中定义用户和SSH密钥，因为设置向导无法通过SSH使用，并且在Gadget模式激活时，Zero系列板卡无法连接USB外设。

现有系统：

1. 确认你正在运行Raspberry Pi OS Trixie：

   bash
   cat /etc/os-release

   • → 确认 VERSION_CODENAME=trixie。

2. 安装并启用Gadget模式：

   bash
   sudo apt update
   sudo apt install rpi-usb-gadget
   sudo rpi-usb-gadget on
   sudo reboot

   重启后，USB端口将切换到Gadget模式。任何活动的SSH会话会暂时断开，待USB以太网接口可用后会重新连接。根据主机系统情况，可能需要等待长达一分钟，以完成DHCP/ICS协商。

技术细节

rpi-usb-gadget软件包配置了g_ether USB Gadget内核模块，该模块根据主机操作系统的能力暴露一个虚拟以太网接口：

• Windows主机 → RNDIS 模式

• macOS/Linux主机 → CDC-ECM 模式

正确的模式会在运行时根据USB描述符协商自动选择——无需手动干预。

为何没有USB串口控制台？
未包含CDC-ACM（基于USB的串口），是因为在不使用特定供应商驱动的情况下，Windows无法用一个.inf文件将RNDIS/ECM和ACM同时绑定到单个复合USB设备上。

树莓派上运行着一个轻量级后台服务，持续监控：

• USB链路状态

• 主机上DHCP/ICS的可用性

• 路由和DNS状态

如果检测到主机启用了ICS，会自动应用网关和DNS配置，以提供通过USB的无缝互联网访问。

故障排除

如果连接没有立即生效，请按以下步骤检查：

硬件与线缆

• 确保你使用了正确的USB/OTG端口：

  • → 在Zero型号上，必须是标有USB的端口，而不是PWR IN。

• 直接连接到主机PC的USB端口——避免使用可能阻碍OTG协商或限制供电的集线器或扩展坞。

• 一次仅连接一个处于Gadget模式的树莓派，以避免主机端接口冲突。

• 如果树莓派反复重启或断开连接，可能是供电不足。

  • → 使用有源USB集线器或树莓派USB 3集线器来提供外部电源，同时保持数据通过主机路由。

ICS与DHCP行为

• 启用ICS后，请等待最多一分钟，以便DHCP分配IP地址，并让主机名解析开始工作。

• 在Windows上，如果Gadget适配器显示为“已共享”但未分配IP：

  • → 在所有接口上完全禁用ICS，插入树莓派，然后重新启用ICS并分配正确的适配器。

• Windows可能会列出多次尝试后产生的多个“以太网 X”适配器。

  • → 考虑删除或禁用未使用的适配器，以防止路由冲突。

主机名与mDNS

• 如果在Windows上 ssh pi@主机名。local 无法解析，请安装Bonjour/mDNS支持，或直接使用分配的IP地址（可通过 arp -a 命令查看）。

源代码与驱动下载

此功能现已默认包含在Raspberry Pi OS Trixie镜像中，但所有代码和工具仍保持开放，可供检查和贡献。你可以在此找到完整源代码、文档和Windows驱动程序安装程序（rpi-usb-gadget-driver-setup.exe）。

该仓库还包含问题追踪器以及来自实际设置的报告——特别是涉及Windows和macOS上ICS的报告——这些信息极具价值。不同主机系统在分配DHCP、设置路由或防火墙规则时行为略有差异，因此社区的反馈有助于为所有人提供更可靠的体验。

总结

USB Gadget模式让树莓派更接近于一个即插即用的开发设备——无需设置Wi-Fi、无需扫描IP、无需HDMI、也无需键盘。只需连接一根USB线缆，通过SSH接入，即可开始构建。

此功能设计得足够简单，便于初学者使用，同时也足够稳健和可编写脚本，以满足高级用户和大规模部署的需求。未来的更新将继续优化主机检测、ICS处理和诊断功能。如果你有想法或遇到边缘案例想要分享，GitHub问题追踪器和树莓派论坛随时开放。