# Adb Wifi Debug

> 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.

- Skill: `expoli/adb-wifi-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add expoli/adb-wifi-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/expoli/adb-wifi-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: expoli (https://skillmd.com/u/expoli)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/expoli/adb-wifi-debug

---


# 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 侧连接
```bash
adb kill-server && adb start-server
adb connect <手机IP>:<连接端口>    # 例: adb connect 192.168.1.15:39455
adb devices                        # 状态为 device = 成功; unauthorized = 需配对/授权
```

首次连接若显示 `unauthorized`：
```bash
adb pair <手机IP>:<配对端口>       # 输入 6 位配对码
adb connect <手机IP>:<连接端口>
```

### 3. 验证
```bash
adb -s <手机IP>:<端口> shell getprop ro.product.model
adb -s <手机IP>:<端口> shell getprop ro.build.version.release
```

### 4. 省电断连（offline）与重连

手机息屏/空闲一段时间后，无线调试连接常变 `offline`（**端口不变**，无需重新配对）。标准恢复流程：

```bash
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、漏出存活名单，从而**不会被后续端口扫描覆盖**。

### 正确流程
```bash
# 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）
```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 侧
```bash
sudo apt install -y linux-tools-generic usbutils hwdata
sudo ln -s /usr/lib/linux-tools/*/usbip /usr/local/bin/usbip
lsusb
```

### usbipd 常见坑（按出现顺序）
1. **Device busy (exported)**：设备被 Windows 占用 → Windows 上 `adb kill-server`、关掉资源管理器 MTP 窗口和手机助手类软件，然后 `usbipd bind --force --busid <ID>` 重新绑定。
2. **A firewall appears to be blocking... TCP 3240**（attach 卡住）：Windows 防火墙拦了 3240 端口 → 管理员 PowerShell：
   ```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`。
3. 手机多 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 隔离 |