Flutter中Firebase Messaging后台通知无法获取内容的问题

针对你遇到的前台通知正常、后台FirebaseMessaging.onBackgroundMessage不生效的问题，从核心维度逐一排查解决：

1. 确认后台消息处理器的定义规则 #

你的backgroundMessageHandler已经是全局顶级函数，符合要求，但需牢记两个关键限制：

• 不能是类的成员方法，必须定义在全局作用域
• 函数内部不能调用Flutter框架API（比如UI更新、状态管理相关代码），因为后台消息运行在独立的隔离进程，无法访问Flutter主环境，仅能执行原生兼容逻辑（如调用Firebase API、操作本地存储）

2. 区分FCM消息类型的不同处理逻辑 #

FCM消息分两类，后台行为差异极大：

• 纯通知消息：仅包含notification字段，后台时由系统直接弹出通知，不会触发onBackgroundMessage，只有用户点击通知时，才会通过onMessageOpenedApp（后台唤醒）或getInitialMessage（冷启动）回调
• 纯数据消息：仅包含data字段，后台时会触发onBackgroundMessage，需你在处理器中自行实现通知展示逻辑
• 混合消息：同时包含notification和data字段，Android后台会触发onBackgroundMessage，但iOS后台仍由系统展示通知，点击后才会把data传递给唤醒回调

若需后台主动处理消息，发送方必须使用纯数据消息格式，或针对Android单独处理混合消息。

3. 平台端配置检查 #

Android #

• 确认android/app/src/main/AndroidManifest.xml中存在FirebaseMessagingService配置（firebase_messaging插件通常自动生成，可手动验证）：

<service
    android:name="com.google.firebase.messaging.FirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

• 确保项目build.gradle中Firebase依赖版本与flutterfire插件版本匹配，避免版本冲突

iOS #

• 在Xcode中开启后台模式：进入项目配置 -> Signing & Capabilities -> 添加Background Modes -> 勾选Remote notifications
• 确认APNs证书已上传至Firebase控制台，且设备已正确配置推送权限
• iOS后台消息触发可能受系统低功耗模式限制，测试时确保设备处于正常联网状态

4. 正确查看后台日志 #

后台消息中的print语句不会出现在Flutter DevTools控制台，需使用平台原生工具查看：

• Android：用Android Studio的Logcat，过滤FirebaseMessaging或你的日志关键词
• iOS：用Xcode的Console应用，查看设备的系统日志

5. 调整初始化时机 #

FirebaseMessaging.onBackgroundMessage的注册必须在Firebase.initializeApp()之后，且尽量早于runApp()，避免因初始化顺序导致注册失效：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  // 先注册后台消息处理器
  FirebaseMessaging.onBackgroundMessage(backgroundMessageHandler);
  // 再初始化通知管理类
  await PushNotificationManager().initNotifications();
  runApp(const MyApp());
}

6. 补充权限配置 #

• Android 13及以上：除FCM权限外，需单独请求POST_NOTIFICATIONS权限：

if (Platform.isAndroid) {
  await Permission.notification.request();
}

• iOS：在Info.plist中添加后台刷新配置（已通过Xcode开启Background Modes可跳过）：

<key>UIBackgroundModes</key>
<array>
    <string>remote-notification</string>
</array>

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