诊断工具和电源管理

调试后台地理定位非常困难，尤其是在具有积极节电功能的碎片化 Android 设备上。 Tracelet 提供了一套工具来帮助您可视化引擎正在执行的操作并减轻 OEM 限制。

追踪医生

Tracelet Doctor (tracelet_doctor) 是一个嵌入式 UI 仪表板，可实时可视化 Tracelet 引擎的内部状态。这对于现场测试至关重要。

🩺

切勿将 Tracelet Doctor 部署给生产中的常规最终用户。使用隐藏的开发者菜单保护入口点（例如，点击版本号 7 次）。

安装

Tracelet Doctor 是一个 调试工具，因此将其添加为 开发依赖项 — 而不是定期依赖。 Flutter 从发布版本中排除了开发依赖包，因此医生会自动排除在您向用户发送的内容之外：


flutter pub add dev:tracelet_doctor

这会将其添加到 pubspec.yaml 中的 dev_dependencies 下：


dev_dependencies:
  tracelet_doctor: ^3.6.6

一体化

因为它是一个开发依赖项，所以在 kDebugMode 后面保护对它的每个引用，以便 import is tree-shaken out of release builds and your app still compiles in release mode:


import 'package:flutter/foundation.dart' show kDebugMode;
import 'package:tracelet_doctor/tracelet_doctor.dart';
 
// Show the interactive diagnostic overlay — debug builds only:
if (kDebugMode) {
  TraceletDoctor.show(context);
}

核心特点

仪表板提供了 5 个用于调试的关键选项卡：

概览仪表板 显示实时 isMoving 状态、当前 GPS 坐标、精度（以米为单位）、电池电量和活动的 TraceletProfile。如果引擎处于 STATIONARY 状态，此屏幕将明确显示 GPS 硬件已关闭。
地理围栏实时地图 呈现您当前位置、stationaryRadius 边界和所有已注册地理围栏（圆形和复杂多边形区域）的可视化地图。至关重要的是，它可以可视化 geofenceProximityRadius，以便您可以验证地理围栏在您移动时是否动态加载和卸载。
数据库检查器 直接检查原始 SQLite 行。您可以查看有多少位置在排队等待 HTTP 同步，验证增量压缩逻辑是否成功收缩坐标，并手动触发刷新。
日志控制台 本机 SDK 日志的实时、颜色编码流（跟踪、调试、信息、警告、错误）。您可以在此处看到引擎做出的决定：“检测到 65 英里/小时，将距离过滤器拉伸至 50m”。
配置检查器 JSON 树查看器显示当前注入本机引擎的确切 Config 对象，确保您的 Dart 配置成功跨越平台通道。

OEM 电源管理器（设置运行状况）

中国 OEM（小米、华为、Oppo、Vivo、OnePlus）配备了高度激进的专有电池管理器，完全忽略标准 Android 前台服务规则。