定位功能“偶尔失效“怎么查：HarmonyOS Location Kit 权限、订阅与地理围栏实践

第一次进入地图页，定位完全正常。切到后台、锁屏、切回来、重新进入页面以后，开始出现：拿不到位置、位置很久不更新、一次变化触发两三次回调、退出页面以后日志还在刷、重新进入又注册一套监听。

这种"偶尔失效"最难查，因为本地第一次测试几乎永远正常。问题全在组合场景里：前后台切换、页面反复进入、权限状态变化、订阅没有正确清理。

一、最难查的不是完全不能定位，而是"偶尔失效"

完全不能定位反而好查——权限没开、定位关了，一眼就能看到。偶尔失效才麻烦：第一次进页面定位正常，退出再进就拿不到位置了；或者位置信息更新了，但 UI 没刷新。

顺着链路查了一圈，发现问题不在 Location Kit 本身，而在我们对订阅生命周期的管理。页面退出时没有正确取消订阅，重新进入又注册了新的，结果旧的监听还在跑，新的也注册了，一次位置变化就触发两三次回调。

二、先把权限和系统定位状态查干净

定位开始之前要确认两件事：应用有没有定位权限，系统定位开关是不是打开的。权限有了但系统定位关了，一样拿不到位置。

用户拒绝权限以后不能直接报错就完了，要降级处理——显示一个提示，告诉用户需要开启定位权限才能使用地图功能，提供一个跳转系统设置的入口。

权限和定位服务状态要在每次页面 onPageShow 时重新检查。用户可能在系统设置里改了权限，或者关了定位开关再开，这些变化页面里是感知不到的，必须主动查。

三、位置订阅一定要和页面生命周期分开管理

页面进入时开始订阅位置，页面退出时停止订阅。这个逻辑看起来简单，但实际出问题的就是这里。

之前直接在页面里 startLocating()，aboutToDisappear 里 stopLocating()。但如果页面切到后台再回来，aboutToDisappear 不一定触发（HarmonyOS 里页面切后台不一定走 aboutToDisappear），订阅就一直在跑。等用户切回来，又 startLocating 一次，就变成两个订阅了。

后来把订阅管理收到了一个 LocationManager 里，页面只调用 start 和 stop，Manager 内部维护订阅状态，防止重复注册。

下面这段代码放在 LocationManager.ets 里，解决的问题：统一管理定位订阅的开始和停止，防止重复注册，页面退出时正确清理。

export class LocationManager {
private static instance: LocationManager | null = null;
private subscribed: boolean = false;
private listenerCount: number = 0;

static getInstance(): LocationManager {
if (!this.instance) {
this.instance = new LocationManager();
}
return this.instance;
}

startLocation(callback: (location: Location) => void): boolean {
if (this.subscribed) {
console.warn('[Location] already subscribed, skip duplicate start');
return false;
}
// 调用 Location Kit 开始订阅
this.subscribed = true;
this.listenerCount++;
console.info(`[Location] subscribed, listener count=${this.listenerCount}`);
return true;
}

stopLocation(): void {
if (!this.subscribed) return;
// 调用 Location Kit 停止订阅
this.subscribed = false;
this.listenerCount = 0;
console.info('[Location] unsubscribed');
}

isSubscribed(): boolean {
return this.subscribed;
}
}

这段代码要解决的问题：startLocation 内部先检查是否已经订阅，已订阅就直接返回，不重复注册。stopLocation 把状态重置，下次 start 是干净的。页面 aboutToDisappear 里调 stopLocation，onPageShow 里重新检查状态再决定要不要 start。实际使用时要注意：LocationManager 做成单例，页面不自己持有订阅句柄；onPageHide 和 onPageShow 里也要管理订阅状态，切后台时可以暂停订阅，回前台再确认；listenerCount 用来排查为什么一次回调触发了多次。

四、重复监听会让一次定位变成两三次回调

上面说的重复订阅问题，表现出来就是：位置更新了一次，页面收到两三次回调，UI 刷新了好几遍。严重的时候日志里全是重复的位置更新，而且退出页面以后日志还在刷——旧的监听根本没停。

排查的时候先看 listenerCount 是不是大于 1。如果大于 1，说明重复注册了。这时候不要急着修回调逻辑，先找到哪里重复调了 startLocation。通常是页面反复进入、或者 onPageShow 里没判断状态就直接 start。

五、地理围栏更适合交给独立 Manager 管

地理围栏和普通位置订阅不一样——它不是连续更新位置，而是进入或离开某个区域时触发回调。围栏注册了以后，即使用户没在地图页面，App 也可能收到围栏事件。

所以围栏管理不要放在页面里，应该放到一个独立的 GeofenceManager 里。页面只调"注册围栏"和"移除围栏"，围栏的生命周期由 Manager 管。App 重启以后也要能恢复之前注册的围栏列表，不能重启就丢了。

围栏重复注册是另一个常见坑：同一个围栏 ID 注册两次，进入围栏时就触发两次回调。注册前先检查这个 ID 是不是已经存在了。

六、后台回来以后不要默认旧订阅还正常

页面切到后台一段时间再回来，原来的定位订阅可能已经失效了——系统为了省电可能停掉了位置更新。这时候不要假设订阅还在工作，要主动检查。

我的做法是在 onPageShow 里调一次 isSubscribed()，如果订阅状态异常或者长时间没收到更新，就重新 startLocation。不要盲目重新订阅（会导致重复），先检查状态再决定。

下面这张表是排查时整理的常见现象和对应检查点：

七、最后用一组异常场景把定位链路重新测一遍

修完以后把这几个场景都过了一遍：正常前后台切换、锁屏再解锁、权限拒绝后再授予、定位开关关了再开、快速反复进入地图页、围栏注册和退出。这些场景单独测一个没问题，组合起来才容易暴露订阅没清理、重复注册、状态失效的问题。

定位这个功能，单独看 API 调用很简单，真正出问题的全在生命周期和状态管理。谁开始订阅、谁持有引用、谁负责停止——这三件事明确了，"偶尔失效"的问题基本就能控制住。