接入指南
    定位Flutter插件
    地图Flutter插件
接入指南
定位Flutter插件
参考
错误码

错误码

腾讯定位 Flutter 插件使用统一的错误对象 TencentLocationError 表达所有异步错误。本文档列出全部错误码、含义、可能的触发场景与处理建议。


错误对象结构

class TencentLocationError implements Exception {
  /// 插件层错误码（详见下方表格）
  final TencentLocationErrorCode code;

  /// 错误消息（可读）
  final String message;

  /// 原生 SDK 回传的原始错误码（可为空，便于排查）
  final int? nativeCode;

  /// 原生 SDK 回传的原始错误消息（可为空）
  final String? nativeMessage;

  /// 附加数据（例如出错的围栏 ID 等）
  final Object? details;
}

code 字段是一个枚举值（TencentLocationErrorCode），其字符串名（code.name）也用作日志中的稳定标识。建议在业务侧使用枚举值进行判断。

通用错误

错误码 含义 处理建议
unsupportedOnThisPlatform 当前平台不支持该 API 或参数组合 在调用前判断平台，或对调用进行 try / on 包裹
invalidArgument 入参非法（取值越界、必填字段缺失等） 检查请求参数
timeout 调用超时（常见于单次定位） 适当延长 firstLocationTimeout / singleLocationTimeout 后重试
nativeError 原生侧未分类的兜底错误 记录 nativeCode / nativeMessage 协助排查，必要时联系技术支持

初始化与权限

错误码 含义 处理建议
privacyNotAgreed 未同意隐私政策 在用户同意你的应用隐私政策后调用 TencentLocationSDK.setPrivacyPolicyAgreement(true)
apiKeyInvalid ApiKey 无效（未配置 / 拼写错误 / 平台不匹配 / 已被吊销） 在 腾讯位置服务开放平台 检查 ApiKey 有效性，确保为 Android / iOS / HarmonyOS 分别申请并使用对应的 Key
sdkInitFailed SDK 初始化失败 检查依赖完整性，如错误持续请提供 nativeCode / nativeMessage 联系技术支持
permissionDenied 系统定位权限被拒 引导用户在系统设置中开启定位权限
locationSwitchOff 设备的定位总开关已关闭 引导用户在系统设置中开启定位服务

运行时

错误码 含义 处理建议
alreadyStarted 同一管理器实例上重复启动连续定位 先调用 stopContinuousLocation() 再重新启动；或用同一实例时不要重复 start
locationFailed 定位失败（网络异常、信号弱、未搜到星等） 监听 onLocationError，根据 nativeCode / nativeMessage 判断；对临时性失败可适当重试

围栏

错误码 含义 处理建议
geofenceInvalidRegion 围栏区域非法（多边形点数不足、经纬度超范围等）。Android 上行政区划关键字找不到时 SDK 复用该错误码，可通过 message（如 no valid district found）区分 校验顶点数量、坐标范围以及半径取值；district 场景确认 keyword 为有效 adcode 或行政区中文名称
geofenceDistrictNotFound 行政区划关键字未匹配到任何区域（Android 上也可能收到上方的 geofenceInvalidRegion，以 message 为准） 确认 keyword 为有效 adcode 或行政区中文名称
geofenceDuplicateId 围栏 ID 与已添加的围栏冲突 移除旧围栏或换用新 ID
geofenceNetworkFailed 围栏网络请求失败 检查网络状态后重试
geofenceLimitExceeded 单实例围栏数量超限 业务上控制并发围栏数，或拆分到多个 TencentGeofenceManager 实例
geofenceIdNotFound 待移除 / 查询的围栏 ID 不存在 确认 ID 拼写，或在调用前先用 getAllGeofences 校验

错误处理示例

import 'package:tencent_location_flutter_plugin/tencent_location_flutter_plugin.dart';

Future<void> safeRequestLocation(TencentLocationManager manager) async {
  try {
    final location = await manager.startSingleLocation(
      TencentLocationRequest.create()..setRequestLevel(RequestLevel.adminArea),
    );
    print('定位成功：${location.latitude}, ${location.longitude}');
  } on TencentLocationError catch (error) {
    switch (error.code) {
      case TencentLocationErrorCode.privacyNotAgreed:
        // 引导用户同意隐私政策
        break;
      case TencentLocationErrorCode.apiKeyInvalid:
        // 提示开发者检查 ApiKey 配置
        break;
      case TencentLocationErrorCode.permissionDenied:
        // 引导用户在系统设置中授予定位权限
        break;
      case TencentLocationErrorCode.locationSwitchOff:
        // 引导用户开启系统定位总开关
        break;
      case TencentLocationErrorCode.timeout:
        // 网络 / 信号差，可让用户重试
        break;
      case TencentLocationErrorCode.unsupportedOnThisPlatform:
        // 当前平台不支持该 API
        break;
      default:
        // 其它错误，记录到日志系统并上报
        print('定位失败：${error.code} ${error.message} '
            '(native=${error.nativeCode} ${error.nativeMessage})');
        break;
    }
  }
}

调试建议

  • 在日志中同时输出 code、message、nativeCode、nativeMessage，便于跨端排查。

  • 对偶发的 locationFailed / timeout 错误可以在 UI 上给出「重新定位」按钮，让用户主动触发重试。

  • 如果某个错误码长期无法定位原因，可在 腾讯位置服务开放平台 提交工单，并提供完整的 TencentLocationError.toString() 输出与复现步骤。

本页内容