故障排查 | Droidline

按症状列出最常见问题的解决办法：服务器、配对、手机离线、权限、找不到元素、输入文字、截图和设置快捷操作。

每次排查都从这两条命令开始。doctor 检查安装和配置；serve --verbose 实时显示每一次连接尝试：

droidline doctor
droidline serve --verbose

在下面找到你遇到的症状。只在离开你的 Wi-Fi 时才出现的问题，见连接故障排查。

代码提示服务器没有运行

SERVER_NOT_RUNNING（Python 中为 ServerNotRunningError）表示 127.0.0.1:8780 上没有任何程序响应。

启动 droidline serve，并保持它的窗口打开。关闭窗口会停止服务器。
如果你修改了 config.toml 中的 client.listen，或者设置了 DROIDLINE_HOST 或 DROIDLINE_PORT，请确认你的代码使用的是同一个地址。
droidline doctor 会显示它尝试连接的地址，以及 agent 端口是否空闲。

服务器无法启动

出现“address already in use”之类的错误，表示另一个程序占用了 Droidline 的某个端口：8779 供手机连接，8780 供你的代码连接，8778 用于在 Wi-Fi 上发现电脑。

可能已经有另一个 droidline serve 在运行，也许在另一个窗口中，或者作为服务运行。先停止它。
要使用其他端口，请修改 config.toml 中的 agent.listen、client.listen 或 discovery.listen。手机会在下次配对时得知新的 agent 端口。

手机找不到电脑

点击在此 Wi-Fi 下配对后提示“没有电脑响应”，或者配对后手机始终连接不上。

确认两者连接的是同一个 Wi-Fi 网络。访客网络和某些 Mesh 系统会把设备相互隔开；请使用主网络。
在 Windows 上，把网络设为专用网络：依次打开设置、网络和 Internet、WLAN、你的网络，把网络配置文件类型设为专用网络。Windows 会在公用网络上阻止传入连接。
在专用网络上允许 droidline 通过防火墙。如果你关掉了提示，请依次打开 Windows 安全中心、防火墙和网络保护、允许应用通过防火墙，为 droidline 勾选专用。也可以在以管理员身份运行的 PowerShell 中执行：
```
New-NetFirewallRule -DisplayName "Droidline" -Direction Inbound -Action Allow -Profile Private -Program "C:\Tools\droidline\droidline.exe"
```
在 macOS 上，依次打开系统设置、网络、防火墙、选项，允许 droidline 的传入连接。
电脑上运行的 VPN 可能让电脑在局域网中不可见。配对时暂停 VPN，或者用二维码配对，因为二维码中包含电脑的地址。

如果 6 位代码的方式仍然失败，二维码通常可行：运行 droidline pair 并扫描它。

配对失败

电脑上出现 PAIRING_FAILED，表示没有手机在用这个代码等待。代码 5 分钟后过期；再次点击在此 Wi-Fi 下配对获取新代码。
二维码 10 分钟内有效，只能配对一部手机。配对下一部手机时，请再次运行 droidline pair。
应用提示电脑无法识别这部手机：说明这部手机已被 droidline revoke 移除，或者服务器的设置文件夹被删除或移动了。重新配对即可。

屏幕关闭后手机离线

Android 和许多手机品牌会停止后台应用以节省电量。Droidline 需要一直保持连接。

在 Droidline 的设置标签页中，把电池优化设为不受限制。

找到你的手机品牌针对后台应用的额外设置，并在每一项中允许 Droidline。它们通常是这样的：

品牌	查找位置
Samsung	设置、电池、后台使用限制：把 Droidline 从 Sleeping apps 和 Deep sleeping apps 中移除，或者把它加入 Never sleeping apps
Xiaomi、Redmi、POCO	应用信息，开启自启动，并把省电策略设为无限制
OPPO、OnePlus、realme	应用信息、电池使用，开启 Allow background activity 和 Allow auto launch
vivo	设置、电池、Background power consumption management：允许 Droidline
Huawei、Honor	设置、电池、应用启动管理：把 Droidline 设为手动管理，并打开所有开关

菜单名称因版本而异；如果与上面不同，请在设置中搜索“电池”或“后台”。

如果手机无人值守运行，请让它一直充电。

应用的状态标签页显示连接状态和正在使用的线路，有助于分辨是应用进入了休眠，还是网络出了问题。

无障碍开关是灰色的

在 Android 13 及以上版本上，从文件安装的应用无法使用无障碍功能，直到你允许受限制的设置：

依次打开设置、应用、Droidline（或者在设置标签页中点击应用信息）。
点击右上角的三点菜单，选择允许受限制的设置。
返回无障碍设置，开启 Droidline。

如果找不到这个菜单项，先打开一次无障碍设置，让 Android 记录下这次尝试，然后再找。

无障碍服务总是自动关闭

此时命令会以 NO_ACCESSIBILITY 失败。有些手机会在应用更新后、崩溃后，或者省电功能杀掉应用时，关闭无障碍服务。

在设置标签页中重新开启。
执行上面的电池设置步骤；它们能避免大多数情况。
安装 Droidline 应用的更新后，查看一次设置标签页。

命令找不到我能看到的元素

元素明明在屏幕上，却返回 NOT_FOUND。按查找元素中的清单逐项检查。常见原因：

文字略有不同：大小写、末尾的空格、不同的语言。从 droidline dump 中复制值。
元素位于权限对话框等系统窗口中。使用 all_windows=True 进行 dump。
界面上根本没有元素（游戏、地图、canvas 页面）。使用带坐标的 tap。

无法输入文字

NO_IME：Droidline 键盘没有启用或没有被选中。在设置标签页中启用并选择它。
文字出现了，但应用没有反应，例如等待按 Enter 的搜索框：在 input 之后调用 sendkey("enter")。
input 替换掉了你想保留的文字：传入 append=True。

Android 9 或 10 上截图失败

在 Android 11 之前，截图需要 Android 的屏幕录制权限。第一次调用 screenshot 时，手机上会出现提示；点击立即开始。在有人接受之前，screenshot 会以 NO_PERMISSION 失败，droidline devices 的 MISSING 下也会出现 capture。

kill、clear_data 或网络开关失败

这些命令会替你点击 Android 设置应用中的按钮，而设置应用因品牌和 Android 版本而异。MACRO_FAILED 会说明找不到哪一步。

确认屏幕已点亮并已解锁；先调用 wake()。
再试一次：这个错误被标记为可重试，速度慢的手机可能只是反应晚了。
如果它在某个机型上每次都失败，请报告问题，并附上机型、Android 版本和语言。正是这样的报告，让这些快捷操作能够支持新的手机。

多部手机在线时命令失败

DEVICE_AMBIGUOUS 表示有多部手机在线，而命令没有指明使用哪一部。请指定手机：connect("shelf-01")、--device shelf-01、/devices/shelf-01/...，或者设置 DROIDLINE_DEVICE。

命令以 AGENT_RESTARTED 失败

命令执行期间，手机上的 Droidline 应用重启了，所以 Droidline 无法判断命令是否已经执行。先检查屏幕，再决定重新执行是否安全。频繁重启通常与上面提到的电池设置有关。

仍然无法解决

在 GitHub 上提交 issue，附上 droidline doctor 的输出、手机的型号和 Android 版本，以及能重现问题的最小脚本。请不要包含令牌、密码和个人数据。