Flutter FCM通知：后台/终止状态无横幅弹窗问题排查

问题现象 #

Flutter应用前台接收FCM通知时，横幅弹窗正常显示；但后台或应用终止状态下，通知仅出现在通知栏，无法弹出横幅。

核心问题分析与修复方案 #

Android端问题 #

1. 通知通道未提前创建
   你的代码仅在前台展示通知时定义了high_importance_channel，但未调用API实际创建该通道。后台状态下FCM直接通过系统推送通知，找不到预设的高优先级通道，只能使用默认低优先级通道，导致无法弹出横幅。

   • 修复：在LocalNotifications初始化阶段就创建通道，修改initLocalNotifications方法：

     static void initLocalNotifications(RemoteMessage? message) async {
       var androidInitializationSettings = const AndroidInitializationSettings('@mipmap/launcher_icon');
       var iosInitializationSettings = const DarwinInitializationSettings();
       var initializationSetting = InitializationSettings(
           android: androidInitializationSettings, iOS: iosInitializationSettings);
       
       // 提前创建高优先级通道
       const AndroidNotificationChannel androidNotificationChannel = AndroidNotificationChannel(
           "high_importance_channel", "High Importance Notifications",
           description: 'This channel is used for important notifications.',
           importance: Importance.max);
       await _flutterLocalNotificationsPlugin.resolvePlatformSpecificImplementation<AndroidFlutterLocalNotificationsPlugin>()?.createNotificationChannel(androidNotificationChannel);
     
       await _flutterLocalNotificationsPlugin.initialize(
         initializationSetting,
         onDidReceiveNotificationResponse: (payload) {
           if(message != null) handleMessage(message);
         },
       );
     }
     

   • 同时在firebaseInit中提前调用初始化，而非仅在前台收到消息时执行：

     Future<void> firebaseInit() async {
       await initLocalNotifications(null);
       // 后续监听逻辑...
     }
     

2. FCM Payload Android配置不完整
   后台状态下FCM直接处理通知，需明确指定通道ID和最高优先级，修改Payload的android字段：

   "android": {
     "priority": "high",
     "notification": {
       "channel_id": "high_importance_channel",
       "visibility": "public",
       "priority": "max"
     }
   }
   

iOS端问题 #

1. APNs Payload缺少横幅触发配置
   当前Payload仅设置了contentAvailable: true，未配置alert字段，后台/终止状态下APNs不会触发横幅。修改apns配置：

   "apns": {
     "payload": {
       "aps": {
         "contentAvailable": true,
         "alert": {
           "title": groupChat? groupName:senderName,
           "body": groupChat?'$senderName : $msg':msg
         },
         "sound": "default",
         "badge": 1
       }
     },
     "headers": {
       "apns-priority": "10"
     }
   }
   

   • apns-priority: 10确保通知为最高优先级，避免被系统节流。

2. 系统权限验证
   确认iOS系统设置中，应用的通知样式已开启“横幅”选项（用户授权alert权限不代表自动开启横幅展示）。

通用代码补充 #

添加应用终止状态下的通知启动监听，完善点击逻辑（不影响横幅显示，但提升体验）：

Future<void> firebaseInit() async {
  // 处理应用终止时点击通知启动的情况
  FirebaseMessaging.instance.getInitialMessage().then((message) {
    if (message != null) {
      handleMessage(message);
    }
  });
  // 其他监听逻辑...
}

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