设备连不上

有两种表现相似但成因完全不同的故障。先判断属于哪一种，可以省下一半的排查时间。

• 设备完全没有出现在列表中 → 连接或授权问题。
• 设备已在列表中但没有页面 → 检查器开关或页面状态问题。

设备未出现在列表中

1. 数据线与接口

这是最常见、也最容易被忽略的原因。许多数据线仅支持充电。

• 更换一根确认支持数据传输的数据线。
• 更换 USB 接口，优先使用主机直连的接口，避免经过 USB hub。
• 台式机请优先使用机箱后部的接口。

2. 解锁并信任设备

• iOS —— 解锁设备，在「是否信任此电脑？」提示中点击信任并输入密码。如果此前选择了「不信任」，请拔出数据线、锁屏后重新连接。若需彻底重置该状态：设置 → 通用 → 传输或还原 iPhone → 还原 → 还原位置与隐私，然后重新连接并确认信任。
• Android —— 下拉 USB 通知并选择文件传输，同时确认是否允许 USB 调试？。如果该提示始终不出现，请前往开发者选项 → 撤销 USB 调试授权，然后重新插拔数据线。

3. 平台驱动（Windows）

缺少 Apple 的 USB 驱动时，Windows 无法识别 iPhone。请从 Microsoft Store 安装 Apple 设备（或 iTunes），然后重新连接。部分 Android 厂商也提供各自的驱动程序。

4. 刷新设备列表

在设备列表中点击刷新。在设备上开启的调试开关不会追溯应用到已经枚举过的设备。

5. 确认问题是否来自 WebDebugX

先确认平台原生工具能否识别该设备：

adb devices     # Android —— 应列出序列号，且状态为 device 而非 unauthorized

• 显示 unauthorized → 授权提示未被确认。
• 列表为空 → 问题出在数据线、接口、驱动或连接模式上，任何调试工具都无法识别该设备。

6. 按此顺序重启

从代价最小的操作开始：重新插拔数据线 → 重启 WebDebugX → 重启设备 → 重启电脑。

设备已在列表中但没有页面

1. 确认检查器开关已开启

• iOS Safari —— 设置 → Safari → 高级 → 网页检查器。
• iOS Chrome —— Chrome → ⋯ → 设置 → 内容设置 → 网页检查器。这与 Safari 的开关相互独立。
• Android 浏览器标签页 —— 开启 USB 调试即可，无需额外开关。
• App 内页面 —— 需要在应用代码中开启，详见调试 App 内页面。

2. 确认页面处于打开状态

设备上必须存在一个可调试的页面。请将标签页切换至前台，或将应用导航到承载 web view 的界面。被系统回收以释放内存的标签页，在重新加载之前不会暴露任何调试目标。

3. 先刷新列表，再重新加载页面

在 WebDebugX 中点击刷新。如果调试开关是在页面打开之后才开启的，还需要在设备上重新加载该页面。

4. 确认是同一个应用、同一个安装包

未开启调试开关的旧版本安装包，从外部无法分辨。请重新安装已开启该开关的版本。

页面可以打开但会话频繁断开

• 设备锁屏。 锁屏会结束调试会话。调试期间请保持屏幕常亮，并延长自动锁定时间。
• 数据线松动。 接触不良的数据线可能因自身重量导致连接中断。
• 页面发生跳转。 整页导航会替换调试目标，刷新设备列表即可重新连接。

自定义设备（浏览器）相关问题

详见调试浏览器。最常见的原因是浏览器在已有 profile 上启动、未指定 --user-data-dir，导致调试端口无法开启且不会给出提示。