Flutter Firebase iOS后台消息处理器失效及推送异常问题排查

一、后台切前台未点击通知无法获取数据的问题 #

1. iOS FCM消息的核心规则 #

iOS对FCM消息的处理逻辑和Android存在本质差异：

• 当消息同时包含notification和data字段时：
  • 前台状态：onMessage会正常触发，可直接获取完整消息内容
  • 后台/被杀状态：通知会进入系统托盘，仅当用户点击通知时，onMessageOpenedApp才会触发并传递data数据；若未点击通知直接切前台，App不会主动收到消息数据
• 当消息为纯data字段（无notification）时：
  • 后台状态下，只要aps.content_available=1，系统会短暂唤醒App，触发firebaseMessagingBackgroundHandler处理消息

2. 你的firebaseMessagingBackgroundHandler未触发的原因 #

代码存在致命错误：后台消息处理函数被定义在main函数内部。iOS的后台消息唤醒机制要求该函数必须是顶级函数（不能嵌套在任何函数内），否则系统无法找到入口点，导致handler永远不会触发。

修正后的代码：

// 必须将handler放在main函数外部，作为顶级函数
@pragma('vm:entry-point') 
Future<void>firebaseMessagingBackgroundHandler(RemoteMessage message) async { 
    await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
    print('listener hit (background)...message is received!!!!!!!!!!'); 
    // 此处可将消息数据存储到本地（如SharedPreferences、Hive）
    // 待App切前台时，从本地读取数据更新UI
} 

void main() async{
  WidgetsBinding widgetsBinding = WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp( options: DefaultFirebaseOptions.currentPlatform );    
  FirebaseMessaging.onBackgroundMessage(firebaseMessagingBackgroundHandler); 
  runApp(MyApp()); 
}

3. 实现后台切前台获取数据的方案 #

如果需要在未点击通知的情况下，切前台也能拿到消息数据，可选择以下两种方案：

• 方案1：发送纯data消息（移除notification字段），此时后台会触发handler，你可以在handler内将数据存储到本地，App切前台后从本地读取并更新UI
• 方案2：保留notification字段，同时在后台handler内存储数据，前台启动时检查本地存储的未读消息

二、推送图片不显示的问题 #

你的payload存在两个关键问题：

1. JSON语法错误：fcm_options.image的值使用了单引号，JSON规范要求必须使用双引号，这会导致Apple服务器解析失败
2. （可选验证）确认图片符合Apple要求：必须是HTTPS链接、格式为JPG/PNG、文件大小不超过10MB，且Apple服务器能正常访问该图片地址

修正后的payload关键部分：

"apns":{
  "payload":{
     "aps":{
        "mutable-content": 1,                 
        "content_available": 1, 
     }
  }, 
  "headers": {
   "apns-priority": "10",
  },
  "fcm_options": {
     "image": "https://t4.ftcdn.net/jpg/01/43/42/83/240_F_143428338_gcxw3Jcd0tJpkvvb53pfEztwtU9sxsgT.jpg"
  }
}

三、关于firebaseMessagingBackgroundHandler的作用 #

它并非仅适用于Android，在iOS上的触发场景为：

• App处于后台（未被杀）状态
• 收到纯data消息，或带notification且aps.content_available=1的消息
• 系统会短暂唤醒App，允许你在后台处理消息（如存储数据、同步内容等），但不会直接将消息推送到前台的onMessage回调

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