Flutter中Firebase onBackgroundMessage未触发问题求助

问题描述 #

已按Firebase官方文档配置后台推送处理逻辑，iOS设备后台可接收推送消息，但firebaseMessagingBackgroundHandler方法未被调用，前台onMessage功能正常。

相关配置代码 #

Firebase初始化代码

await Firebase.initializeApp();
await FirebaseMessaging.instance.requestPermission();

FirebaseMessaging.onBackgroundMessage(firebaseMessagingBackgroundHandler);
FirebaseMessaging.onMessage.listen(
        (RemoteMessage message) => _firebaseMessagingForgrounHandler(message));

后台处理方法

@pragma('vm:entry-point')
Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  print("---------------------On Background Message--------------------");
}

依赖版本（pubspec.yaml）

#firebase
firebase_core: ^2.7.1
firebase_messaging: ^14.2.6

Flutter环境信息

[✓] Flutter (Channel stable, 3.10.1, on macOS 13.4 22F66 darwin-arm64, locale de-DE)
[✓] Android toolchain - develop for Android devices (Android SDK version 32.0.0-rc1)
[✓] Xcode - develop for iOS and macOS (Xcode 14.3)
[✓] Chrome - develop for the web
[!] Android Studio (not installed)
[✓] VS Code (version 1.78.2)
[✓] Connected device (4 available)
[✓] Network resources

解决建议 #

• 检查推送消息的APNs字段：iOS后台触发firebaseMessagingBackgroundHandler要求推送消息必须携带content-available: 1字段。普通通知（仅带alert、sound等）只会显示通知栏，不会触发后台处理。发送时需添加该字段：Firebase控制台发送时在「高级选项」勾选「启用后台模式」；API发送时在apns.payload中加入{"content-available":1}。

• 确认iOS项目后台权限：在Xcode中进入项目的Signing & Capabilities，添加Background Modes权限并勾选Remote notifications选项，无此权限即使消息带content-available也无法触发后台逻辑。

• 验证后台方法的定义规范：确保@pragma('vm:entry-point')注解无拼写错误，且方法是全局顶级函数（不能是类成员方法或嵌套在其他函数内），否则Flutter无法在后台环境找到入口点。

• 排查Firebase配置与依赖：

  1. 确认GoogleService-Info.plist已正确添加到iOS项目，且Bundle ID与Firebase控制台完全一致。
  2. 执行flutter clean后重新编译项目，清理缓存可能导致的配置不生效问题。
  3. 尝试升级Firebase依赖到最新稳定版，旧版本可能存在iOS后台处理的已知Bug，需注意firebase_core与firebase_messaging版本兼容性。

• 规范测试方式：

  • 避免用Xcode直接运行后切后台测试，建议用flutter run --release编译正式包安装到设备测试，Debug模式下iOS后台行为会受系统限制。
  • 关闭设备低电量模式，该模式会限制后台任务执行。
  • 检查iOS设置->通知中，应用的推送权限（包括后台通知）已完全开启。

• 正确查看后台日志：iOS后台处理的print日志无法直接通过Flutter控制台查看，需连接设备到Xcode，打开Window->Devices and Simulators，选择设备后点击View Device Logs搜索应用相关条目；或在后台方法中添加Firebase Analytics日志验证是否被调用。

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