Flutter Background Locator 2：Android13发布模式后台启动定位服务报错求助

问题详情 #

在Android 13系统下，使用Flutter Background Locator 2实现后台位置追踪时，启动定位服务出现以下崩溃错误：

Unable to start service yukams.app.background_locator_2.IsolateHolderService@d327f59 with Intent { act=START cmp=com.smarthcm.mobile/yukams.app.background_locator_2.IsolateHolderService (has extras) }: java.lang.RuntimeException: Missing type parameter

已完成的排查步骤：

• 确认包的使用方式符合官方文档
• 验证AndroidManifest.xml中位置权限配置正确
• 确认包依赖及初始化配置已完成
• 查阅包的Android 13适配更新及Bug报告
• 尝试调整包内各项配置参数

预期效果：

• 应用后台时可正常启动定位服务
• 能接收并处理位置更新
• Android 13下启动服务无崩溃或错误

原因分析 #

该错误本质是Android端的IsolateHolderService无法解析Intent中传递的泛型类型参数，通常由以下场景导致：

1. 启动定位时传递的回调函数签名不匹配，或未明确指定泛型类型，导致Isolate序列化数据时丢失类型信息
2. 包版本未适配Android 13的Intent序列化规则，旧版本存在参数传递漏洞
3. 服务初始化或权限请求不完整，间接导致参数传递流程异常

解决方案 #

1. 确认回调函数签名与类型匹配 #

启动定位服务时，确保callback和disposeCallback的签名严格符合要求，避免类型模糊：

// 位置更新回调，必须为void Function(LocationData?)类型
void locationCallback(LocationData? location) {
  // 处理位置数据
}

// 销毁回调，必须为void Function()类型
void disposeCallback() {
  // 清理资源
}

// 启动定位的正确调用方式
void startBackgroundLocation() async {
  await LocatorService.startLocator(
    LocatorOptions(
      interval: 5,
      distanceFilter: 0,
      android: AndroidOptions(
        isForegroundMode: true,
        notificationTitle: '后台定位',
        notificationMsg: '正在获取位置',
        notificationIcon: '@mipmap/ic_launcher',
      ),
    ),
    callback: locationCallback,
    disposeCallback: disposeCallback,
  );
}

2. 升级包到最新版本 #

旧版本的Background Locator 2可能存在Android 13适配问题，升级到最新版可修复已知的参数传递Bug：
在pubspec.yaml中更新依赖：

dependencies:
  background_locator_2: ^最新版本号

执行flutter pub get完成更新后，重新编译项目。

3. 检查AndroidManifest.xml服务配置 #

确保IsolateHolderService的声明包含Android 13要求的前台服务权限：

<service
    android:name="yukams.app.background_locator_2.IsolateHolderService"
    android:permission="android.permission.FOREGROUND_SERVICE_LOCATION"
    android:exported="false" />

<!-- 同时确保已声明必要的位置权限 -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />

4. 确保服务初始化与权限请求完整 #

• 在main函数中提前初始化Locator服务：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // 初始化Locator服务，必须在runApp之前调用
  await LocatorService.initialize();
  runApp(const MyApp());
}

• 启动定位前，动态请求所有必要权限（Android 13要求后台权限需单独请求）：

Future<bool> requestLocationPermissions() async {
  // 请求前台定位权限
  final foregroundStatus = await Permission.location.request();
  if (!foregroundStatus.isGranted) return false;
  
  // 请求后台定位权限
  final backgroundStatus = await Permission.locationAlways.request();
  return backgroundStatus.isGranted;
}

// 启动定位前先校验权限
void initBackgroundLocation() async {
  final hasPermissions = await requestLocationPermissions();
  if (hasPermissions) {
    await startBackgroundLocation();
  }
}

5. 清除缓存后重新编译 #

如果以上步骤无效，尝试清除项目缓存并重新编译：

# 清除Flutter缓存
flutter clean
# 重新获取依赖
flutter pub get
# 重新编译Android项目
cd android && ./gradlew clean build

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