mcpField
C
connecting-over-wifi

connecting-over-wifi

github.com/skydoves开发33967 次安装22 周前更新
代码仓库

关于 connecting-over-wifi

面向 Android 开发者的无线 ADB 连接技能，介绍 Android 11 及以上版本的配对连接流程、旧式 TCP 连接及 mDNS 发现。还提供连接故障诊断和无线调试安全注意事项。

主要功能

  1. 01介绍 adb pair 与 adb connect 流程
  2. 02说明旧式 adb tcpip 连接
  3. 03通过 mDNS 发现已配对设备
  4. 04诊断配对和连接问题
  5. 05比较连接方式的安全特性

适用场景

  1. 01不使用 USB 线连接 Android 设备
  2. 02排查配对成功后无法连接的问题
  3. 03诊断 mDNS 服务发现或后端差异
  4. 04判断何时使用旧式 TCP 连接

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/skydoves/android-testing-skills --skill connecting-over-wifi

安装后在 Claude Code 中输入/connecting-over-wifi确认已加载。

详细介绍

通过 Wi-Fi 连接 — adb pair（现代方式）和 adb tcpip（旧方式）

Android 11 引入了配对式无线调试流程，取代了旧版 adb tcpip 操作。现代方式使用由配对码派生的共享密钥，通过 TLS 加密并进行身份验证，且使用临时端口；旧方式则会在一个众所周知的端口上开启未经身份验证的 TCP 监听器。本技能涵盖这两种方式，以及主机服务器用于发现已配对设备的 mDNS 配置。

何时使用本技能

  • 用户希望在不使用 USB 线缆的情况下将手机连接到 ADB。
  • 用户提到 adb pair、二维码配对、「开发者选项」中的「无线调试」开关或配对码。
  • 用户从旧博客复制了 adb tcpip 5555 && adb connect 192.168.1.100:5555，并询问为什么现代手机会将其视为不安全。
  • 用户配对后看到 connection refused，且使用的是企业 Wi-Fi。
  • 用户在 adb mdns check 中遇到 mDNS Bonjour 与 Openscreen 之间的困惑。

何时不使用本技能

  • 用户想了解 USB 设备基础知识（选择器标志、RSA 对话框、udev 规则）——使用 ../connecting-to-devices/SKILL.md。
  • 用户想了解架构／环境变量速查表——使用 ../../architecture/understanding-adb-architecture/SKILL.md。
  • 用户想在无线连接的设备上运行测试——使用 ../../tests/running-instrumented-tests-via-adb/SKILL.md。

前置条件

  • 工作站和设备处于同一 Wi-Fi 网络。企业网络经常会阻止点对点连接——请参阅步骤 6。
  • 手机／平板电脑： Android 11（API 30）及以上版本。电视／Wear OS： Android 13（API 33）及以上版本。
  • ADB 服务器正常运行（请参阅 ../../architecture/understanding-adb-architecture/SKILL.md）。
  • 设备已启用无线调试：设置 → 系统 → 开发者选项 → 无线调试。

工作流

  • 1. Android 11 及以上版本优先使用现代 adb pair 流程。 来自 developer.android.com/tools/adb#wireless：

    “Android 11（API 级别 30）及以上版本支持通过 Android Debug Bridge（adb）从工作站以无线方式部署和调试应用。例如，你可以将可调试的应用部署到多个远程设备，而无需通过 USB 线缆实际连接设备。”

    使用配对码的用户操作流程：

    1. 在设备上打开 设置 → 开发者选项 → 无线调试 并将其开启。
    2. 点按使用配对码配对设备。设备会显示一个 IP:PORT 和一个六位数配对码。
    3. 在工作站上： 
      adb pair 192.168.1.42:42999
# Enter pairing code: 123456
# Successfully paired to 192.168.1.42:42999 [guid=adb-...-RQAZWM]

    二维码配对使用相同的协议，通过 Android Studio 的「使用 Wi-Fi 配对设备」界面启动。

  • 2. 连接到配对后显示的单独调试端口。 配对端口只能使用一次；设备会公开另一个用于实际调试的 IP:PORT：

    adb connect 192.168.1.42:39555
adb devices
# 192.168.1.42:39555  device

    adb disconnect [<host:port>] 会断开单个主机的连接；不带参数时则会断开所有 TCP 设备的连接。

  • 3. 使用 mDNS 自动发现，实现免操作连接。 ADB 服务器可以发现已配对设备并自动连接：

    adb mdns check
# mdns daemon version [openscreen discovery 0.0.0]

adb mdns services
# List of discovered mdns services
# adb-XXXXXXXX-RQAZWM   _adb-tls-pairing._tcp  192.168.1.42:42999
# adb-XXXXXXXX-RQAZWM   _adb-tls-connect._tcp  192.168.1.42:39555

    服务类型：

    • _adb._tcp — 旧版 adb tcpip。
    • _adb-tls-pairing._tcp — 临时配对端口（点按「使用配对码配对设备」后）。
    • _adb-tls-connect._tcp — 配对后的调试端口。默认情况下会自动连接这些端口（ADB_MDNS_AUTO_CONNECT=adb-tls-connect）。

  • 4. 了解当前使用的 mDNS 后端。 文档称 Bonjour 是默认后端，但从 ADB v34+ 开始，Linux/Windows 上的默认后端已改为 Openscreen（公开文档尚未更新）。需要确保结果可复现时，请通过环境变量明确指定后端：

    ADB_MDNS_OPENSCREEN=1 adb start-server     # 强制使用 Openscreen
ADB_MDNS_OPENSCREEN=0 adb start-server     # 强制使用 Bonjour

    完整的环境变量表（ADB_MDNS_AUTO_CONNECT、ADB_MDNS_OPENSCREEN）请参阅 ../../architecture/understanding-adb-architecture/SKILL.md。

  • 5. 仅在无法配对时使用旧版 adb tcpip 方式。 适用于 Android 11 之前的设备（Android 11+ 仍支持此方式作为备用方案）：

    # 1. 通过 USB 连接设备，接受 RSA 对话框，并使用 `adb devices` 确认。
adb tcpip 5555
# 2. 拔掉 USB。
adb connect 192.168.1.42:5555

    这是旧版方式的原因：

    • 需要先通过实体 USB 连接完成初始化，无法实现“无需线缆”的便利。
    • 5555 是众所周知的端口，无需配对即可访问——在重启前，局域网中的任何人都能连接。
    • 设备重启后会恢复为仅支持 USB 连接（可手动执行 adb usb 重置）。
    • 没有 mDNS 自动发现功能；用户必须知道 IP 地址。

    新版 adb pair 流程使用基于配对码派生的共享密钥，通过 TLS 加密并进行身份验证，同时使用临时端口，安全性高得多。

  • 6. 按以下顺序排查配对或连接失败：

    “成功配对后设备仍无法连接：adb 依赖 mDNS 来发现并自动连接已配对的设备。如果你的网络或设备配置不支持 mDNS 或已将其禁用，则需要使用 adb connect ip:port 手动连接设备。”

    1. 是否连接了同一个 Wi-Fi？ 确认两端连接的是同一个 SSID，且位于同一个 VLAN/子网。
    2. 是否使用企业 Wi-Fi？ 原文如下：

      “企业 Wi-Fi 等安全 Wi-Fi 网络可能会阻止 p2p 连接，导致无法通过 Wi-Fi 连接。请尝试使用线缆或其他（非企业）Wi-Fi 网络连接。”

    3. 是否禁用了 mDNS？ 运行 adb mdns check。如果显示“mDNS is not running”，请使用设备“无线调试”界面中的连接端口，通过 adb connect <ip:port> 手动连接。
    4. 执行 adb connect 后出现 connection refused？ 无线调试端口已关闭（无线调试已关闭、设备已重启，或使用了配对端口而不是连接端口）。请重新启用无线调试；必要时重新配对；并从 adb mdns services 复制 _adb-tls-connect._tcp 端口。
    5. 切换 Wi-Fi 后自动断开连接？ 原文如下：

      “adb 的 Wi-Fi 连接有时会自动关闭：如果设备切换了 Wi-Fi 网络或与网络断开连接，就可能发生这种情况。要解决此问题，请重新连接到网络。”

  • 7. 将无线 ADB 视为“信任局域网”的功能。

    • 任何能够访问网络且拥有配对码的人都可以配对。
    • 配对后，只有持有加密密钥才能访问；但在没有网络隔离的办公室局域网中，所有连接 Wi-Fi 的人都可能构成攻击面。
    • 不使用时请关闭无线调试。“设置”中的开关会立即关闭监听套接字。
    • 完全避免在公共场所、咖啡馆或酒店的 Wi-Fi 上使用无线 ADB。
    • 旧版 adb tcpip 模式会启动一个没有身份验证的 TCP 监听器——只要设备支持，就应优先使用 adb pair。

模式

模式：错误做法与正确做法 — 在 Android 13 上使用 adb tcpip
# WRONG
adb tcpip 5555
adb connect 192.168.1.100:5555
# WRONG because: on Android 11+ the modern `adb pair` flow is available and
# encrypts/authenticates over TLS. The tcpip path bypasses pairing, exposes a
# well-known unauthenticated TCP listener until reboot, and is often blocked
# on managed Wi-Fi. Many corporate networks drop port 5555 traffic outright.

# RIGHT
# On the device: Settings -> Developer options -> Wireless debugging -> ON
# Then "Pair device with pairing code" — note the displayed IP:PORT and code.
adb pair 192.168.1.100:42999
# Enter pairing code: 123456
# Then connect on the device's separate connect-port (also shown in Wireless debugging):
adb connect 192.168.1.100:39555
adb devices
# 192.168.1.100:39555  device
模式：错误做法与正确做法 — 混淆配对端口与连接端口
# WRONG
adb pair 192.168.1.100:42999
# (succeeds)
adb connect 192.168.1.100:42999
# error: failed to connect to '192.168.1.100:42999': Connection refused
# WRONG because: the pairing port is one-shot. After successful pairing, the
# device exposes a different IP:PORT (the "Pair devices over Wi-Fi" main screen
# shows it under the device's IP). Trying to connect to the pairing port fails.

# RIGHT
# Read the connect port from the Wireless debugging main screen (NOT the
# "Pair device with pairing code" dialog), or:
adb mdns services
# adb-...  _adb-tls-connect._tcp  192.168.1.100:39555
adb connect 192.168.1.100:39555
模式：错误做法与正确做法 — 对 mDNS Openscreen 与 Bonjour 的预期
# WRONG (script makes assumptions about mdnsResponder / Bonjour being default)
# CI script greps for "bonjour" in `adb mdns check` output and aborts when it
# does not find it.
adb mdns check | grep -q bonjour || exit 1
# WRONG because: ADB v34+ defaults to the Openscreen backend on Linux/Windows.
# Output is "mdns daemon version [openscreen discovery 0.0.0]" on those hosts.
# The script breaks on every modern CI runner.

# RIGHT
# Either accept either backend, or pin one with the env var:
ADB_MDNS_OPENSCREEN=1 adb start-server
adb mdns check                       # confirm "openscreen discovery"
# Or for environments that still need Bonjour:
ADB_MDNS_OPENSCREEN=0 adb start-server

强制规则

  • 必须在 Android 11（API 30）手机和 Android 13（API 33）电视 + Wear 设备上优先使用 adb pair + adb connect。adb tcpip 路径是旧版回退方案。
  • 必须在 adb connect 中使用连接端口（来自 _adb-tls-connect._tcp 或无线调试主界面），而不是配对码对话框中显示的配对端口。
  • 必须在不主动使用无线调试时将其关闭。设备上的“设置”开关会立即关闭监听套接字。
  • 不得假设 mDNS 后端是 Bonjour。ADB v34+ 在 Linux/Windows 上默认使用 Openscreen。如需保证可复现性，请通过 ADB_MDNS_OPENSCREEN=0|1 固定设置。
  • 不得在共享/公共 Wi-Fi 上运行 adb tcpip 5555。此操作会创建一个未经身份验证的开放 TCP 监听器，并持续到设备重启。
  • **优先选择：**连接到办公室以太网，或使用个人热点，以应对企业 Wi-Fi 阻止 p2p 的情况。
  • **优先选择：**当无线调试“突然无法使用”时，先运行 adb mdns check 和 adb mdns services 进行诊断。

验证

  • adb pair <host:port> 会输出 Successfully paired to <host:port>。
  • adb connect <host:port> 会返回 connected to <host:port>，且 adb devices 会列出状态为 device 的 IP 传输。
  • adb mdns check 会输出守护进程版本（Openscreen 或 Bonjour），且不报错。
  • 对于已配对的设备，adb mdns services 至少会列出一个 _adb-tls-connect._tcp 条目。
  • 在设备上关闭无线调试后，IP 传输会在几秒内从 adb devices 中移除。
  • 对于 API 30+ 手机，开发者首选的路径是 adb pair（而不是 adb tcpip）。
  • 调试失败时，用户已先运行 adb mdns check，再重新生成主机 RSA 密钥。

参考资料

  • 无线 ADB（developer.android.com/tools/adb#wireless）：https://developer.android.com/tools/adb#wireless
  • ADB 用户指南主页：https://developer.android.com/tools/adb
  • Platform-tools 发行说明（mDNS 后端默认设置）：https://developer.android.com/tools/releases/platform-tools
  • AOSP adb 手册页：https://android.googlesource.com/platform/packages/modules/adb/+/refs/heads/main/docs/user/adb.1.md
  • tasks/research/A1-adb-architecture-devices.md — ADB v34+ 在 Linux/Windows 上默认从 Bonjour 切换到 Openscreen、mDNS 服务类型分类，以及原文“配对成功后设备无法连接”指南。
  • docs/CORPUS.md §I.4（无线 ADB）。
  • 相关技能：
    • 高级架构和环境变量：../../architecture/understanding-adb-architecture/SKILL.md
    • USB 设备基础知识：../connecting-to-devices/SKILL.md
    • 应用安装/清除：../../apps/installing-and-managing-apps/SKILL.md
    • 通过无线传输运行插桩测试：../../tests/running-instrumented-tests-via-adb/SKILL.md
  • 跨集合相关内容：
    • 使用 AndroidJUnit4 运行插桩测试：../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md
    • 在 Android 上配置 JUnit4：../../../jvm-tests/runner/configuring-junit4-on-android/SKILL.md
    • 源集策略：../../../fundamentals/strategies/organizing-test-source-sets/SKILL.md

评论

支持 Markdown