adb-wifi-debug

name adb-wifi-debug description Connect an Android phone to WSL2 via adb over WiFi (Android 11+ wireless debugging), including LAN discovery with nmap, pairing, troubleshooting, and the usbipd USB-passthrough fallback path. Use when the user needs adb access to a phone from WSL, phone not visible in adb devices, or USB passthrough issues. allowed-tools Bash license MIT metadata {"author":"pi","version":"1.1"} adb 无线调试连接（WSL2 ↔ Android 手机） 背景与关键事实 环境 ：WSL2 (Ubuntu 24.04, NAT 网络模式), Windows 主机, adb 已装于 /usr/bin/adb (version 34.0.4)。 WSL2 是虚拟机，默认看不到 Windows 上连接的 USB 设备 —— 需要 usbipd-win 透传，或直接用 WiFi 无线调试。 结论（本项目首选） ：只要需求是 adb 调试（shell/装应用/日志/scrcpy）， 优先走 WiFi 无线调试 ，零配置、无防火墙问题。usbipd 只留给 MTP 传文件、刷机等 USB 专属需求。 已知设备 ：OPPO PKT110 (Android 16)，局域网网段 192.168.1.0/24 ，路由器 192.168.1.1 。 主路径：WiFi 无线调试（Android 11+，推荐） 1. 手机端开启 设置 → 开发者选项 → 无线调试 → 开启。 主界面显示 「IP 地址和端口」 （如 192.168.1.15:39455 ）→ 连接用 「使用配对码配对设备」 → 配对端口 + 6 位配对码（仅首次/重新授权时需要） 2. WSL 侧连接 adb kill-server && adb start-server adb connect <手机IP>:<连接端口> # 例: adb connect 192.168.1.15:39455 adb devices # 状态为 device = 成功; unauthorized = 需配对/授权 首次连接若显示 unauthorized ： adb pair <手机IP>:<配对端口> # 输入 6 位配对码 adb connect <手机IP>:<连接端口> 3. 验证 adb -s <手机IP>:<端口> shell getprop ro.product.model adb -s <手机IP>:<端口> shell getprop ro.build.version.release 4. 省电断连（offline）与重连 手机息屏/空闲一段时间后，无线调试连接常变 offline （ 端口不变 ，无需重新配对）。标准恢复流程： adb kill-server && adb start-server timeout 15 adb connect <手机IP>:<连接端口> # connect 可能挂起，用 timeout 兜底 adb devices adb connect 挂起/超时 是省电状态的正常现象：直接重试即可，通常第二次就能连上。 只有重新开关了「无线调试」，端口才会变（那时需重新发现端口，见下节）。 自动发现设备（nmap） 关键教训：ping 扫描会漏掉"隐身"设备 nmap -sn 靠主机 回包 判断存活。OPPO/ColorOS 在 屏幕熄灭/空闲省电状态 会静默丢弃 ICMP 与陌生 TCP 探测包（DROP 而非 RST），导致在线手机被判定为 down、漏出存活名单，从而 不会被后续端口扫描覆盖 。 正确流程 # 0) 前置：确保手机屏幕亮着、无线调试已开启（省电模式会隐身） # 1) 确定网段：ping 常见网关（192.168.1.1 / 192.168.0.1 / 10.0.0.1） # 2) 找存活主机 nmap -sn -T4 192.168.1.0/24 | grep "Nmap scan report" # 3) 对存活主机扫 adb 端口（5555 传统 + 37000-46000 无线调试随机段） nmap -T4 --min-rate 3000 -p 5555,37000-46000 <存活IP列表> # 4) 兜底：跳过主机发现直接全子网扫（慢但可靠） nmap -Pn -p 5555,37000-46000 192.168.1.0/24 注意事项 mDNS 在 WSL NAT 下不可用 ： adb mdns services 返回空是正常的（NAT 不转发组播），别浪费时间。 无线调试端口每次重新开启都会变（37000-46000 内随机），重连前重新确认手机上的 IP:端口。 手机必须与电脑在同一局域网；AP 隔离/访客网络会导致连不上。 扫描阴性 ≠ 连不上 ：实测 nmap 对 37000-46000 全扫无开放端口、5555 filtered，但 adb connect 立即成功——省电状态手机会丢弃快速 SYN 探测（高速扫描尤其容易漏）。扫描无果时，直接 adb connect <IP>:<已知端口> 试一次，别轻易下结论。 备选路径：usbipd USB 透传（仅 USB 专属需求） Windows 侧（管理员 PowerShell） winget install --interactive --exact dorssel.usbipd-win # 或 GitHub .msi usbipd list # 记下手机 BUSID usbipd bind --busid 2-2 # 设备被占用时用 bind --force usbipd attach --wsl --busid 2-2 # 需先保持一个 WSL 终端开着 usbipd detach --busid 2-2 # 归还设备给 Windows WSL 侧 sudo apt install -y linux-tools-generic usbutils hwdata sudo ln -s /usr/lib/linux-tools/*/usbip /usr/local/bin/usbip lsusb usbipd 常见坑（按出现顺序） Device busy (exported) ：设备被 Windows 占用 → Windows 上 adb kill-server 、关掉资源管理器 MTP 窗口和手机助手类软件，然后 usbipd bind --force --busid <ID> 重新绑定。 A firewall appears to be blocking... TCP 3240 （attach 卡住）：Windows 防火墙拦了 3240 端口 → 管理员 PowerShell： netsh advfirewall firewall show rule name=usbipd netsh advfirewall firewall add rule name="usbipd" dir=in action=allow protocol=TCP localport=3240 Get-NetConnectionProfile # 若 NetworkCategory 是 Public，改成 Private: Set-NetConnectionProfile -InterfaceAlias "<接口名>" -NetworkCategory Private 仍不行可改 .wslconfig 的 networkingMode=mirrored + wsl --shutdown 。 手机多 USB 接口（MTP/ADB/RNDIS）会整体移交；附加成功后 Windows 侧暂时失去该设备属正常。 快速排查清单（phone 不在 adb devices 时） 症状 处理 adb devices 空 手机开无线调试 → adb connect ；或走 usbipd unauthorized 手机弹窗点允许；或 adb pair 配对 offline 息屏省电导致： adb kill-server && adb start-server → 重试 adb connect （端口不变） adb connect 挂起/超时 省电状态正常现象，直接重试即可（可用 timeout 15 兜底） nmap 扫不到端口 阴性结果不可信（省电丢 SYN 探测）：直接 adb connect 试 扫描找不到手机 亮屏/解锁后重扫；确认同一网段； -Pn 全子网扫 WSL 内连不上但 Windows 能连 确认手机与电脑同一 Wi-Fi，无 AP 隔离