flutter_background_geolocation 位置与地理围栏回调不触发问题

• 你看到的W/Settings( 6400): Setting airplane_mode_on has moved from android.provider.Settings.System to android.provider.Settings.Global, returning read-only value.是Android系统对旧版API的通用兼容警告，和位置更新、地理围栏不触发的故障完全无关，无需处理。
• 核心故障点如下：
  1. 插件启动模式错误：你在初始化完成后仅调用startGeofences()启动纯围栏模式，该模式下不会触发连续的_onLocation位置回调，且配置中开启了useSignificantChangesOnly: true，系统仅在设备移动数公里级的大幅位移时才会唤醒位置服务，常规测试位移根本不会触发事件。
  2. 地理围栏添加时序错误：你在initState中插件未完成初始化、未确认权限状态时就提前调用getZonesPlusLastClocking()拉取围栏数据，同时配置了reset: true每次插件启动会清空已注册围栏，叠加你加了if (monitoredGeofences.isEmpty)的判断逻辑，会导致围栏根本没有被成功注册到系统服务中。另外配置了notifyOnDwell: true但未设置必填的loiteringDelay参数，DWELL事件永远不会触发。
  3. 网络状态判断逻辑错误：isConnectedToInternet()方法是错误的异步写法，会永远同步返回true，无法拿到真实网络状态，会导致无网络时围栏拉取逻辑执行异常。
  4. 权限校验逻辑错误：你在插件初始化完成的回调中直接将isLocationPermissionGranted设为true，没有校验实际授权状态，若用户未授予「始终允许位置权限」，插件后台/围栏服务不会启动，你也无法捕获异常。
  5. 无头模式未注册回调：你开启了enableHeadless: true但未注册无头事件处理函数，应用被系统杀死后触发的事件无人响应。

1. 修正插件初始化与启动逻辑 #

• 删掉initState最开头提前调用的getZonesPlusLastClocking()，等插件初始化完成、确认权限后再拉取围栏数据。
• 将纯围栏启动方法startGeofences()替换为start()启动全量位置+围栏追踪模式。
• 初始化回调中校验实际授权状态，不要直接赋值权限状态为true。
• 将配置项useSignificantChangesOnly改为false，测试阶段将debug改为true，打开插件原生层日志和提示音，方便排查事件状态。
  修正后的初始化代码示例：

@override
void initState() {
  super.initState();
  // 删掉这里提前调用的getZonesPlusLastClocking()
  bg.BackgroundGeolocation.onLocation(_onLocation, _onLocationError);
  bg.BackgroundGeolocation.onGeofence(_onGeofence);
  bg.BackgroundGeolocation.onProviderChange(_onProviderChange);
  bg.BackgroundGeolocation.onConnectivityChange(_onConnectivityChange);

  bg.BackgroundGeolocation.ready(backgroundGeolocationConfig).then((bg.State state) {
    getCurrentUserLocation();
    log("Called get current user location");
    // 校验实际授权状态
    bool hasPermission = state.authorizationStatus == bg.ProviderChangeEvent.AUTHORIZATION_STATUS_ALWAYS;
    setState(() {
      isLocationPermissionGranted = hasPermission;
    });
    log('[ready] BackgroundGeolocation is configured and ready to use');
    // 替换startGeofences为start，启动全量追踪
    if (!state.enabled && hasPermission) {
      bg.BackgroundGeolocation.start().then((_) {
        log('[start] tracking service started');
        // 服务启动后再拉取围栏
        getZonesPlusLastClocking();
      }).catchError((err) {
        log("Start tracking failed: $err");
      });
    }
  }).onError((error, stackTrace) async {
    setState(() {
      locationDescription = kGettingYourLocation;
    });
    showUnableToTrackYourLocationDialog(context);
  });

  // 其余原有Timer、用户信息拉取逻辑保持不变
}

注意：你配置项中stopOnTerminate的注释描述写反了，该参数设为false才是应用终止后继续追踪，设为true会在应用被杀后停止服务，当前配置值是正确的，仅修正注释即可。

2. 修正地理围栏添加逻辑 #

• 去掉if (monitoredGeofences.isEmpty)的判断，每次拉取到最新围栏数据后先清空旧围栏，再添加新围栏，避免重置后围栏丢失、标识冲突问题。
• 为开启notifyOnDwell: true的围栏添加必填的loiteringDelay参数（单位毫秒，如设为5000代表进入围栏停留5秒后触发DWELL事件）。
  修正后的围栏添加代码示例：

// 拉取到zonesTemp、完成setState后
List<bg.Geofence> geofences = [];
for (int i = 0; i < allowedZones.length; i++) {
  geofences.add(bg.Geofence(
      identifier: "${allowedZones[i].zoneName}-in",
      radius: allowedZones[i].radius,
      latitude: allowedZones[i].latitude,
      longitude: allowedZones[i].longitude,
      notifyOnEntry: true,
      notifyOnExit: false,
      notifyOnDwell: true,
      loiteringDelay: 5000, // 新增必填的停留触发延迟
      extras: {kZoneId: allowedZones[i].id}
  ));
  geofences.add(bg.Geofence(
      identifier: "${allowedZones[i].zoneName}-out",
      radius: allowedZones[i].radiusOut,
      latitude: allowedZones[i].latitude,
      longitude: allowedZones[i].longitude,
      notifyOnEntry: false,
      notifyOnExit: true,
      notifyOnDwell: false,
      extras: {kZoneId: allowedZones[i].id}
  ));
}
// 先清空旧围栏再添加新围栏
bg.BackgroundGeolocation.removeGeofences().then((_) {
  bg.BackgroundGeolocation.addGeofences(geofences).then((bool success) {
    log('[addGeofences] success, total count: ${geofences.length}');
    // 打印当前已注册围栏数量，确认添加成功
    bg.BackgroundGeolocation.geofences.then((list) => log('Current monitored geofences: ${list.length}'));
  }).catchError((dynamic error) {
    log('[addGeofences] FAILURE: $error');
  });
});

3. 修正网络状态判断方法 #

原有isConnectedToInternet()为错误的异步同步混用写法，永远返回true，改为标准异步方法：

Future<bool> isConnectedToInternet() async {
  bg.ProviderState state = await bg.BackgroundGeolocation.providerState;
  return state.network;
}

所有调用该方法的位置都需要添加await关键字，比如getZonesPlusLastClocking()开头改为：

Future<void> getZonesPlusLastClocking() async {
  if (await isConnectedToInternet()) {
    // 原有接口拉取逻辑保持不变
  }
}

4. 补充无头模式回调注册 #

在main.dart中注册无头事件处理函数，解决应用被系统杀死后事件不触发的问题：

// 独立的无头任务处理函数
void headlessTask(bg.HeadlessEvent headlessEvent) async {
  switch(headlessEvent.name) {
    case bg.Event.GEOFENCE:
      bg.GeofenceEvent event = headlessEvent.event;
      log('[Headless] Geofence event: ${event.action} ${event.identifier}');
      // 在这里处理围栏事件、弹出通知
      break;
    case bg.Event.LOCATION:
      bg.Location location = headlessEvent.event;
      break;
  }
}

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  // 注册无头任务
  bg.BackgroundGeolocation.registerHeadlessTask(headlessTask);
  runApp(const MyApp());
}

测试注意事项 #

• Android/iOS原生地理围栏服务有最小触发阈值，实际测试需要移动超过围栏边界100米以上才会稳定触发进/出事件，模拟器测试可使用插件提供的模拟位置接口触发事件，不要用室内小范围位移验证。
• 测试阶段保持debug: true，可通过插件日志直接看到底层位置、围栏事件的触发状态，快速定位问题。

内容的提问来源于stack exchange，提问作者Nawra Aradi