故障排查

先确认软件版本、完整解压和小地图框选，再按错误信息定位。

Capture region is outside the virtual desktop bounds

原因：保存的截图区域不在当前 Windows 虚拟桌面的物理像素范围内，常见于更换显示器、缩放比例、主屏幕或窗口模式。

处理：

1. 停止追踪。
2. 将鼠标移到游戏所在显示器。
3. 使用“框选截取范围”重新框选完整小地图。
4. 打开预览确认画面。
5. 重新启动追踪；运行中重新框选时客户端会重启服务。

仍失败时删除 runtime/settings_override.json，重启客户端后重新配置。不要复制其他玩家的区域坐标。

OpenCV recursion / cv2 加载失败

典型日志：

ImportError: ERROR: recursion is detected during loading of "cv2" binary extensions

检查文件：

sift-map-tracker/service/_internal/cv2/cv2.pyd

在官方 0.9.3 包中该文件约为 71.4 MiB。缺失、大小明显异常或被隔离时，重新下载完整包并解压；同时检查安全软件隔离记录。不要从来路不明的位置单独下载 DLL 或 PYD。

服务被应用控制策略阻止

如果日志显示“应用程序控制策略已阻止此文件”，说明 Windows、单位策略或安全软件阻止了 service.exe。确认包体来源后，在系统安全策略中允许该文件或联系设备管理员。客户端无法绕过组织策略。

35 ms 后指针不更新

将刷新间隔恢复为 50 ms 或 60 ms，保存并重启追踪。35 ms 不会让 SIFT 识别更快，反而会增加帧合并、图片解码和 UI 调度压力。

草地、雪地或海面无法定位

这是图像特征不足导致的算法限制，不一定是配置错误。移动到道路、建筑、岸线附近，保持小地图无遮挡，并参考定位风险图。

资源文件加载慢

首次或失效缓存需要后台生成完整 PNG。等待缓存完成；不要连续切换大资源文件。有效缓存仍重复生成时，提交资源 JSON、manifest 和运行日志。

配置页参数为空

确认包体包含默认配置并且客户端与服务来自同一版本。不要把旧版客户端复制进新版服务目录。尝试“恢复默认”，仍为空时保留现场并提交日志和目录结构截图。

需要收集什么

不要只发送“不能用”。请准备：

• 客户端版本；
• Windows 版本、显示器分辨率和缩放比例；
• 当前算法；
• 从启动服务到报错的完整日志；
• settings_override.json 中与截图区域相关的字段；
• 问题能否稳定复现。