---
title: 核心程序疑難排解
description: 設備連接失敗、截圖識別不準、調度卡住或恢復異常、配置改了不生效、遠程訪問不通的定位順序與處理辦法。
updated: 2026-10-20
---

# 核心程序疑難排解

## <DocIcon name="smartphone" /> 設備與 ADB

| 現象 | 原因 | 處理 |
| --- | --- | --- |
| `adb devices` 為空 | 模擬器未開調試，或 adb server 未啟動 | 模擬器設定裏開啟 ADB；`adb start-server` |
| 設備 `offline` | adb 版本衝突（多個模擬器自帶不同版本） | 用模擬器自帶的 adb，或統一版本 |
| 多個設備時連錯 | Serial 寫錯 / `auto` 猜錯 | 手動填 `host:port` |
| 頻繁掉線 | 模擬器省資源、USB 選擇性掛起 | 關閉模擬器省電，改用 `ADB_nc` |
| 重新啟動模擬器無效 | 未登記安裝路徑或實例名 | 填寫 `EmulatorInfo.name` / `path` |

## <DocIcon name="eye" /> 截圖

| 現象 | 原因 | 處理 |
| --- | --- | --- |
| 全黑 | 模擬器用獨立渲染後端，ADB 截圖拿不到 | 換 `DroidCast_raw`、`nemu_ipc`（MuMu）或 `ldopengl`（雷電） |
| 超時 | 後端卡死 | 換方案；開「檢測不到設備時重新啟動 adb」 |
| 花屏/撕裂 | 編碼或縮放問題 | 關閉「去除圖片色彩抖動」再試 |
| 尺寸不是 1280×720 | 模擬器解像度/DPI 被改 | 改成 1280×720，重新啟動遊戲 |
| 截圖正常但點擊偏移 | 縮放與座標映射不一致 | 恢復預設解像度與 DPI，避免系統縮放 |

## <DocIcon name="brain" /> 識別

| 現象 | 原因 | 處理 |
| --- | --- | --- |
| 找不到按鈕 | 皮膚/裝備遮擋、UI 改版 | 恢復預設外觀；更新核心資源 |
| OCR 讀錯數字 | 字色預處理不匹配、字體縮放 | 確認解像度；換模型版本（`OcrModelVersion*`） |
| 卡在未知頁面 | 彈出視窗未處理 | 看錯誤截圖；手動關掉彈出視窗後重跑 |
| 識別在真機正常、模擬器異常 | 渲染差異 | 換截圖方案，而不是改模板 |

::: tip 先看錯誤現場
`log/error/<实例>/<时间戳>/` 裏的截圖就是腳本當時看到的畫面。它比你的記憶可靠。
:::

## <DocIcon name="zap" /> 調度

| 現象 | 原因 | 處理 |
| --- | --- | --- |
| 任務完全不跑 | 未啟用、`NextRun` 在未來、隊列為空 | 檢查 `Enable` 與時間 |
| 總是先跑某個任務 | 優先級更高且已到期 | 調整自定義優先級或時間 |
| 反覆重新啟動遊戲 | `GameStuckError` / 頁面無法識別 | 查截圖與伺服器維護狀態 |
| 實例自己停了 | 敏感任務失敗 / `ScriptError` 3 次 | 看日誌最後 100 行 |
| 卡在同一任務幾小時 | 邏輯死循環，日誌仍在動 | 開運行監護（`Watchdog*`） |
| 任務延後到明天 | 觸發 `TaskRestartLimit` | 修復根因，或臨時調大上限 |
| 多實例互相干擾 | 同一 Serial 或同一實例名 | 一實例一模擬器一進程 |

### 日誌關鍵詞

| 關鍵詞 | 含義 |
| --- | --- |
| `连续失败` | 失敗計數上升，可能升級為重新啟動模擬器 |
| `Restart` | 注入重新啟動任務 |
| `EmulatorOpBusy` | 已有啟停操作在跑，本輪跳過 |
| `ScriptError` | 代碼異常 |
| `RequestHumanTakeover` | 無法安全判斷，嘗試自動恢復 |
| `[服务器检查]` | 維護檢測 |

## <DocIcon name="settings" /> 配置

| 現象 | 原因 | 處理 |
| --- | --- | --- |
| 改了沒生效 | 任務執行中，配置在邊界才重載 | 等任務結束或重新啟動實例 |
| 值自動回退 | 被 `override.yaml` 強制覆蓋 | 查該字段是否用戶可改 |
| 儲存衝突 | 兩個頁面同時編輯 | 刷新後重試 |
| 匯入後缺字段 | 跨版本遷移 | 逐頁檢查關鍵開關 |
| 中文變鍵名 | i18n 缺翻譯 | 更新核心或補翻譯 |

## <DocIcon name="cloud" /> 遠程訪問

| 現象 | 原因 | 處理 |
| --- | --- | --- |
| 區域網絡打不開 | 監聽 `127.0.0.1` 或防火牆 | 改 `WebuiHost`，放行連接埠 |
| 固定入口 302 到 `/error` | 設備離線、租約過期、Tunnel 失效 | 看遠程訪問頁狀態 |
| 一直轉圈 | WebSocket 被中間網絡阻斷 | 換網絡；確認 7844 連接埠 |
| 配對碼過期 | 超過 5 分鐘 | 重新生成 |
| 撤銷後仍能連 | 只在本機移除了入口 | 在主機側撤銷配對 |
| MCP 401 | 未帶密碼或改密碼後未重新啟動 | 帶 Bearer；重新啟動 WebUI |

## <DocIcon name="badge-dollar" /> 性能

| 現象 | 原因 | 處理 |
| --- | --- | --- |
| 識別慢 | 截圖方案慢、OCR 用 CPU | 跑性能測試；換方案；調 OCR 設備 |
| CPU 打滿 | 多實例 + 高幀率 | 降併發，錯開任務 |
| 記憶體增長 | 長時間運行、截圖快取 | 開每日重新啟動，限制錯誤現場保留 |
| 磁盤滿 | 日誌/截圖/備份堆積 | 調 `RetentionDays`、`KeepDays` |

## <DocIcon name="refresh" /> 更新後異常

1. 記錄更新前的提交（`git log`）。
2. 看 `frontend/dist` 是否重建成功。
3. 檢查 `pip`/`uv` 依賴是否同步。
4. 回滾代碼後 `uv sync --frozen` 再啟動。

```bash
git log --oneline -5
git checkout <上一个可用提交>
uv sync --frozen
```

不要用 `git reset --hard` 清掉本地修改。

## <DocIcon name="compass" /> 升級疑難排解順序（推薦）

```text
1. 截图测试 → 能拿到画面？
2. 手动点一次 → 控制方案有效？
3. 单任务「立即执行」→ 能完成？
4. 开调度 → 能按时触发？
5. 加第二个任务 → 不互相干扰？
6. 加第二个实例 → 资源够？
```

每一步通過後再進下一步，比一次性開滿所有任務更容易定位問題。