| 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 devices
首次连接若显示 unauthorized：
adb pair <手机IP>:<配对端口>
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>:<连接端口>
adb devices
adb connect 挂起/超时是省电状态的正常现象：直接重试即可，通常第二次就能连上。- 只有重新开关了「无线调试」，端口才会变（那时需重新发现端口，见下节）。
自动发现设备（nmap）
关键教训：ping 扫描会漏掉"隐身"设备
nmap -sn 靠主机回包判断存活。OPPO/ColorOS 在屏幕熄灭/空闲省电状态会静默丢弃 ICMP 与陌生 TCP 探测包（DROP 而非 RST），导致在线手机被判定为 down、漏出存活名单，从而不会被后续端口扫描覆盖。
正确流程
nmap -sn -T4 192.168.1.0/24 | grep "Nmap scan report"
nmap -T4 --min-rate 3000 -p 5555,37000-46000 <存活IP列表>
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 隔离 |
