Flutter iOS端FirebaseMessaging.onBackgroundMessage不触发如何解决？

iOS端FirebaseMessaging.onBackgroundMessage不触发解决方案 #

1. 调整推送payload配置 #

iOS要触发后台消息回调，必须在推送的APNs配置中添加content-available: 1字段，参考标准Firebase推送结构：

{
  "data": {
    "status": "call"
    // 其余自定义字段
  },
  "apns": {
    "payload": {
      "aps": {
        "content-available": 1,
        // 需要展示通知的场景下，再补充alert、sound、badge字段即可
      }
    },
    "headers": {
      "apns-priority": "10"
    }
  },
  "token": "目标设备推送token"
}

注意：如果payload仅包含notification字段未携带content-available，iOS只会展示系统通知，不会触发后台消息回调。

2. 核对Xcode配置 #

• 检查Signing & Capabilities下的Background Modes已同时勾选Background fetch和Remote notifications
• 确认Push Notifications能力已正常添加，签名所属Team与APNs证书所属Team完全一致
• 检查Info.plist中FirebaseAppDelegateProxyEnabled字段值为YES，如果手动关闭了Firebase代理，需要在AppDelegate中手动实现APNs回调方法，将设备token、收到的推送消息传给FirebaseMessaging处理。

3. 补充通知权限申请逻辑 #

iOS必须先获取用户的通知授权才能正常触发后台推送回调，在应用启动后尽早调用权限申请代码：

FirebaseMessaging.instance.requestPermission(
  alert: true,
  badge: true,
  sound: true,
  provisional: false,
);

4. 验证后台处理函数规则 #

当前你写的_backgroundHandler符合要求的顶级异步函数规范，注意不要将其修改为类的实例方法，同时函数内不要执行超过30秒的耗时操作，iOS会强制终止超时的后台任务。

5. 测试注意事项 #

• 测试时断开Xcode连接，直接在真机启动应用后退到后台/杀死应用测试，Xcode调试模式会修改iOS后台唤醒策略，可能导致回调不触发
• 不要使用iOS模拟器测试后台推送，必须使用真机验证

内容的提问来源于stack exchange，提问作者Md Mahmudul Islam