故障排查
安装、连接、ADB、模拟器、截图识别、调度、更新、远程画面和文档站常见问题。
排查 BAAS 问题时，先判断问题发生在哪一层：安装器、Tauri 客户端、后端服务、ADB/模拟器、游戏画面识别、调度配置或更新源。不要只看最终症状，日志通常能指出真正失败的位置。
安装器卡住或失败
安装器执行时会显示步骤图和 Installation Logs。
优先检查：
- 安装目录是否可写。
- 路径是否包含异常字符或权限受限目录。
- 网络是否能访问当前更新源和 PyPI 源。
- MirrorC CDK 是否有效。
- 日志停在哪一步，例如仓库、PyPI 源、依赖同步或启动后端。
安装路径包含中文导致 UI 无法启动
旧版后端文档记录过 Qt 插件路径相关报错：如果 BAAS 安装目录包含中文或特殊字符，可能导致 UI 启动失败、Qt platform plugin 无法加载或窗口无法显示。
处理方式：
- 优先把 BAAS 安装到不含中文、空格和特殊符号的路径，例如
D:\BAAS。 - 如果必须保留当前路径，检查系统环境变量
QT_QPA_PLATFORM_PLUGIN_PATH是否指向可用 Qt plugins 目录。 - 不建议长期把自己安装的 Qt 目录写入全局环境变量；它可能和 MuMu 等模拟器自带 Qt 冲突。
双击安装器后黑屏无反应
如果双击安装器或启动程序后只出现黑色命令行窗口：
- 先等待几分钟，确认不是依赖下载或解压较慢。
- 检查 Windows 安全中心是否拦截了安装器、Python 或后端文件。
- 临时将 BAAS 目录加入安全软件白名单后重试。
- 保留安装器日志；不要反复删除目录重装，否则会丢失关键错误信息。
安装时报网络或仓库错误
如果安装日志显示远程仓库下载失败、HTTP 400、超时或被拒绝：
- 在安装器高级设置或
setup.toml中切换更新源。 - GitHub 不稳定时测试 GitCode、Gitee、BAAS CDN 或 MirrorC。
- 如果使用 MirrorC，先确认 CDK 有效且没有复制多余空格。
- 网络代理会影响 Git、PyPI 和更新源，代理环境下应保持安装器、终端和系统代理一致。
服务一直连接中
主页左下角如果一直显示连接中，说明客户端没有完成后端连接或认证。
检查顺序：
- 后端进程是否已经启动。
- 本地端口是否被占用或被防火墙拦截。
- BAAS 密钥是否与后端一致。
- 安装器或后端日志是否有崩溃信息。
- 是否刚更新完，后端还在准备环境。
ADB 无法连接
服务器配置中的 ADB 检测按钮用于查看可用设备。
常见原因：
- 模拟器 ADB 或开发者调试没有打开。
- 多开端口填错。
- 目标模拟器没有启动完成。
- 其他 ADB 服务占用连接。
- WSA 网络或开发者模式没有打开。
- 后端没有权限访问 ADB。
排查时先只保留一个模拟器实例，确认能连接后再配置多开。
常见模拟器 ADB 端口
自动扫描找不到设备时，手动填写 ADB IP 和端口。常见单开端口如下：
| 模拟器 | 常见端口 |
|---|---|
| MuMu 模拟器 12 5.0+ | 5555 |
| MuMu 模拟器 12 | 16384 |
| MuMu 模拟器旧版 | 7555 |
| 雷电模拟器 | 5555 |
| 蓝叠模拟器 | 5555 |
| 逍遥模拟器 | 21503 |
| 夜神模拟器 | 62001 或 59865 |
多开场景需要按实例计算端口：
| 模拟器 | 端口规则 |
|---|---|
| MuMu 模拟器 12 5.0+ | 5555 + 多开编号 * 2 |
| MuMu 模拟器 12 | 16384 + 多开编号 * 32，也可在 MuMu 多开器的 ADB 面板查看 |
| 蓝叠 / 雷电 / 夜神 / 逍遥 | 以模拟器多开器或 ADB 检测结果为准 |
蓝叠和雷电通常需要在模拟器设置中打开 ADB 调试。端口配置正确但仍连接失败时，重启模拟器和后端，再只保留一个实例测试。
截图或识别异常
如果日志显示识别失败、页面不匹配、点击坐标异常：
- 确认游戏画面比例接近 16:9。
- PC 端关闭 HDR。
- 避免系统缩放或窗口缩放导致截图比例异常。
- 切换截图方式。
- 切换控制方式。
- 确认游戏不被遮挡、不在最小化状态。
如果只是远程画面看不到，不代表脚本一定无法截图；远程画面和脚本截图方式是两套问题，应分别排查。
截图方式怎么选
常见截图方式大致取舍：
| 截图方式 | 适用场景 | 注意事项 |
|---|---|---|
nemu | MuMu 模拟器 12，追求速度 | 只适合 MuMu 相关环境；路径和模拟器版本要匹配 |
scrcpy | 需要较快截图且环境支持 scrcpy | 依赖 scrcpy 通道，异常时切回保守方案 |
uiautomator2 | 保守排查、兼容优先 | 速度较慢但稳定 |
adb | 最保守的通用方案 | 速度较慢，适合先确认基础连接 |
排查识别问题时，不要同时改很多项。先用 adb 或 uiautomator2 确认能稳定截图，再切换到更快方式。
控制方式怎么选
常见控制方式包括 adb、uiautomator2、scrcpy 和 nemu。如果点击无效或坐标明显偏移：
- 先确认截图画面比例正确。
- 使用
uiautomator2或adb做保守测试。 nemu控制方式只建议在 MuMu 模拟器 12 且相关路径配置正确时使用。- PC 客户端场景应使用桌面截图和鼠标控制相关配置，不要套用 ADB 模拟器方案。
日志持续输出 tentative click
旧版 FAQ 中的典型原因是 MuMu 后台保活或游戏设置导致脚本无法进入预期页面。处理方式：
- 如果使用 MuMu，进入模拟器设置，关闭“后台保活”。
- 确认游戏内画面比例、语言、服务器和画质设置符合推荐配置。
- 检查当前任务是否需要先手动进入某个页面。
- 导出日志并截图当前游戏画面，确认脚本实际卡在哪个识别步骤。
任务不执行
任务不执行通常来自调度配置。
检查：
- 任务是否在“启用的任务”列。
- 下次执行时间是否已经到达。
- 是否设置了禁用时间段。
- 是否被前置任务阻塞。
- 任务间隔是否过长。
- 当前配置档是否是你正在查看的配置档。
- 调度器是否已经启动。
任务执行但结果不对
如果任务执行了但买错、扫错或进入错误关卡：
- 停止调度器，避免继续消耗资源。
- 导出日志。
- 截图当前游戏页面和配置弹窗。
- 检查任务配置中的关卡格式、次数、购买优先级、队伍编号。
- 活动相关任务确认当前活动名称和关卡编号。
远程模拟器画面异常
远程画面卡顿或黑屏时，先打开高级设置降低参数。
处理方式：
- 降低最大宽度和最大高度。
- 降低最大帧率。
- 降低比特率。
- 切换解码器。
- 关闭安全流后测试，确认是否是加密流兼容问题。
- 检查后端日志是否有 stream 错误。
更新失败
更新失败时不要反复点击同一个源。先切换到设置页查看更新源和 SHA 测试结果。
建议：
- GitHub 不通时测试 Gitee、GitCode、BAAS CDN、MirrorC。
- MirrorC 源失败时验证 CDK。
- SHA 测试超时时切换另一个 SHA 获取方式。
- 客户端更新失败时重启 Tauri 客户端后再试。
- 后端更新失败时保留安装器和后端日志。
Android 客户端异常
v0.0.7 起新增 Android 客户端。如果 Android 端无法启动、无法切换脚本或后端反复重启：
- 确认 APK 是最新版本，且 Android 系统允许安装和运行该应用。
- 打开无障碍服务权限，否则脚本无法完成部分自动化控制。
- 保持前台服务通知存在；如果系统杀后台，后端和脚本都会中断。
- 通知栏脚本开关无效时，先打开应用确认后端已启动，再重试通知操作。
- Android 后端更新后如果界面未恢复，关闭应用后重新打开。
传输和系统日志异常
v0.0.7 起桌面端优先支持命名管道传输，WebSocket 仍用于兼容场景。如果连接反复恢复或日志断层：
- 先查看系统日志设置，确认是否开启前端系统日志。
- 切换传输方式后重启后端，避免旧连接残留。
- 如果命名管道失败，临时切回 WebSocket 并保留日志。
- 反馈时同时提供后端日志、系统日志和当时的传输方式。
文档站 404 或资源缺失
本地开发地址应为：
http://localhost:3000/docs/zh/
http://localhost:3000/docs/en/如果侧边栏链接跳到 /zh/docs/...，说明 Fumadocs 的 i18n URL 生成配置有问题；当前项目应生成 /docs/zh/... 和 /docs/en/...。
如果图片不显示：
- 确认图片位于
docs/public/cn或docs/public/en。 - MDX 中使用以
/cn/...或/en/...开头的路径。 - GitHub Pages 部署时确认
NEXT_PUBLIC_BASE_PATH已传入构建。
反馈问题需要提供
请尽量提供：
- BAAS Tauri 版本和后端版本。
- 操作系统和模拟器类型。
- 游戏服务器。
- 当前任务名。
- 导出的日志。
- 对应配置弹窗截图。
- 出错时游戏画面截图或远程画面截图。
- 是否刚更新过客户端或后端。