鸿蒙开发常见问题 3：LocationKit 定位服务踩坑实录与最佳实践

基于 HarmonyOS 6.1 真实项目经验总结

---

一、定位请求超时或无回调

问题描述

调用 geoLocationManager.getCurrentLocation() 后等了十几秒没有任何回调，既不返回位置也不抛错。

原因分析

1. 设备未开启位置服务 — 系统级开关没开
2. 定位超时时间设置太短 — 鸿蒙定位在某些室内场景需要较长时间
3. 权限未申请或用户拒绝了 — 虽然不抛异常，但定位会一直 pending

解决方案

第一步：检查设备位置服务是否开启

import { geoLocationManager } from '@kit.LocationKit';

static async getCurrentLocation(): Promise<LocationResult> {
  // 先检查设备位置开关
  if (!geoLocationManager.isLocationEnabled()) {
    return {
      success: false,
      errorCode: 3301100,
      errorMessage: '设备位置服务未开启，请先打开系统位置开关'
    };
  }
  
  // 设置合理的超时
  const request: geoLocationManager.CurrentLocationRequest = {
    priority: geoLocationManager.LocationRequestPriority.ACCURACY,
    scenario: geoLocationManager.LocationRequestScenario.UNSAFE_GEO_LOCATION,
    maxAccuracy: 100
  };
  
  try {
    const location = await geoLocationManager.getCurrentLocation(
      request,
      10000 // 10秒超时，不要设置太短
    );
    return this.buildSuccess(location);
  } catch (error) {
    return this.buildFailure(
      (error as BusinessError).code ?? -1,
      '获取位置失败，请检查网络或位置开关是否开启'
    );
  }
}

---

二、定位成功但精度不足 ＞100m

问题描述

定位回调成功了，但 accuracyMeters 显示 500 甚至 1000+ 米，在地图上 Marker 位置偏差很大。

原因分析

• GPS 信号差（室内、地下、高楼群）
• 刚启动应用时定位还没收敛
• 使用了快速模式（低精度高速度）

解决方案

方案一：优先使用缓存位置（如果够新鲜）

private static readonly FRESH_LOCATION_MAX_AGE_MS: number = 2 * 60 * 1000; // 2分钟

private static getUsableLastLocation(): LocationResult | null {
  const lastLocation = this.getCachedLastLocation();
  if (lastLocation && this.isFreshLocation(lastLocation)) {
    return lastLocation; // 返回缓存的精准位置
  }
  return null;
}

private static isFreshLocation(location: LocationResult): boolean {
  return (Date.now() - location.timeStamp) < FRESH_LOCATION_MAX_AGE_MS;
}

方案二：首次定位成功后主动再刷新一次

// 在 onPageShow 中，首次定位后延迟再刷一次
async refreshCurrentLocation(firstTime: boolean): Promise<void> {
  const location = await this.fetchLocation();
  if (firstTime && location.accuracyMeters > 100) {
    // 精度不够，等 3 秒后再试一次
    setTimeout(() => {
      void this.refreshCurrentLocation(false);
    }, 3000);
  }
}

方案三：向用户展示精度状态

@State private currentLocationStatus: string = '定位后自动刷新附近影像记忆';
@State private currentLocationAccuracyMeters: number = Number.POSITIVE_INFINITY;

private updateLocationUI(location: LocationResult): void {
  if (location.accuracyMeters < 30) {
    this.currentLocationStatus = '定位精准';
  } else if (location.accuracyMeters < 100) {
    this.currentLocationStatus = `位置精度约${Math.round(location.accuracyMeters)}米`;
  } else {
    this.currentLocationStatus = '位置精度较低，建议到开阔地刷新';
  }
  this.currentLocationAccuracyMeters = location.accuracyMeters;
}

---

三、坐标转换：GCJ-02 vs WGS-84 vs 高德坐标

问题描述

使用 geoLocationManager 获取的坐标是 GCJ-02（国测局坐标系），但地图组件或第三方服务（如高德、百度）可能需要其他坐标系。直接使用会导致 Marker 位置偏差几百米。

解决方案

定义完整的坐标模型，支持多坐标系：

export class LocationSnapshot {
  success: boolean = false;
  latitude: number = 0;
  longitude: number = 0;
  wgs84Latitude: number = 0;    // GPS 原始坐标
  wgs84Longitude: number = 0;
  amapLatitude: number = 0;      // 高德坐标（如果需要）
  amapLongitude: number = 0;
  coordinateSystem: string = 'GCJ-02';
  accuracyMeters: number = 0;
  timeStamp: number = 0;
  errorCode: number = 0;
  errorMessage: string = '';
}

坐标转换建议：

• 鸿蒙 MapKit 自带的 MapComponent 直接使用 GCJ-02，不需要转换
• 如果传入 WGS-84 坐标到 GCJ-02 地图，需要调用 geoLocationManager 的坐标转换 API
• 第三方服务（高德地图 SDK）需要按对方要求传入对应坐标系

---

四、退后台/切换 Tab 后定位仍然在跑

问题描述

用户切到拍照 Tab 或按 Home 键后，定位监听一直在运行，导致耗电和权限弹窗问题。

解决方案

使用生命周期管理，离开地图时停止定位：

// Index.ets 中
private startLocationAwareness(): void {
  if (this.activeTab !== 'map') return;
  // 开始定位刷新
  void this.refreshCurrentLocation(true);
}

private stopLocationAwareness(): void {
  // 停止定位监听
  this.locationWatcherActive = false;
}

在 onPageHide() 和 switchTab() 离开地图分支中调用 stopLocationAwareness()。

---

五、定位失败时应用卡死或崩溃

问题描述

很多新手开发者直接在 aboutToAppear() 中同步 await 定位结果，设备不支持或用户拒绝定位时，页面一直卡在加载状态。

解决方案

失败时仍然显示可浏览的首页，降级为默认位置：

// 默认杭州坐标（西湖附近）
private currentLatitude: number = 30.25113;
private currentLongitude: number = 120.15515;
private currentLocationFresh: boolean = false;

private async refreshCurrentLocation(firstTime: boolean): Promise<void> {
  if (this.locationBusy) return;
  this.locationBusy = true;
  
  try {
    const result = await AgentLocationService.getCurrentLocation();
    if (result.success) {
      this.currentLatitude = result.latitude;
      this.currentLongitude = result.longitude;
      this.currentLocationFresh = true;
    } else {
      // 不更新位置，使用默认坐标
      this.currentLocationFresh = false;
      if (firstTime) {
        // 首次失败给出提示
        this.currentLocationStatus = result.errorMessage;
      }
    }
  } finally {
    this.locationBusy = false;
  }
}

这样定位失败时，地图仍然可以显示，只是停留在默认位置，用户不会觉得应用死亡。

---

总结

问题	解决方案
定位无回调	先检查 isLocationEnabled()，设 10s 超时
精度不足	优先使用新鲜缓存，主动二次刷新，展示精度
坐标偏差	明确坐标系，使用 GCJ-02 配合 MapKit
耗电问题	结合生命周期，离开地图时停止定位
失败卡死	降级为默认坐标，保持地图可浏览

---

参考来源： 大雷神「21 天智能相机开发实战」训练营第 4 天第 1 篇
https://blog.csdn.net/ldc121xy716