iOS远程通知Payload异常：Firebase推送兼容Flutter跨端求助

问题梳理 #

• 含notification字段的Payload可正常触发iOS通知，但会导致Android端出现异常
• 直接使用Apple官方aps字段的Payload，推送状态显示成功，但iOS设备无法接收通知

问题根源 #

1. FCM与APNs格式不匹配：直接在Payload根节点放置aps不符合FCM的转发规则，FCM要求将APNs专属的aps配置封装在apns.payload字段中，否则无法正确转发给苹果推送服务。
2. notification字段跨端行为冲突：
   • iOS端：FCM会自动将notification字段转换为APNs的aps格式，因此能正常接收
   • Android端：notification字段的消息会被系统直接接管并显示在通知栏，若你的Flutter代码需要自定义通知逻辑（如点击跳转、自定义UI），会与系统默认行为冲突，引发异常

跨端兼容的Payload写法 #

要同时满足iOS和Android的需求，需使用FCM的混合消息格式，结合通用字段与平台专属配置：

示例Payload #

{
    "to": "你的设备Token",
    "notification": {
        "title": "10-inch Aggretsuko Rage #24 (Jumbo Size)",
        "subtitle": "Test notification Krunal"
    },
    "data": {
        "gameID": "12345678",
        "category": "GAME_INVITATION"
    },
    "apns": {
        "payload": {
            "aps": {
                "category": "GAME_INVITATION",
                "sound": "default"
            }
        }
    }
}

关键配置说明 #

• notification字段：保证iOS端通过FCM自动转换为APNs格式正常接收；若Android端不需要系统默认通知栏展示，可移除该字段，改用纯Data消息（需Flutter代码手动构建通知）
• data字段：存放跨端通用的业务自定义数据，Flutter可通过FirebaseMessaging回调获取并处理
• apns.payload.aps字段：配置iOS专属的APNs参数（如分类、提示音、角标等），FCM会将这部分内容转发给APNs，确保iOS能识别并处理专属配置

Android端异常修复方案 #

若notification字段导致Android端异常，建议改用纯Data消息：

1. 移除Payload中的notification字段
2. 在Flutter代码中监听消息回调，手动构建并显示通知

示例Flutter代码（Android手动构建通知） #

import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:flutter_local_notifications/flutter_local_notifications.dart';

final FlutterLocalNotificationsPlugin _notificationsPlugin = FlutterLocalNotificationsPlugin();

void setupFirebaseMessaging() async {
  // 初始化本地通知插件
  const AndroidInitializationSettings initializationSettingsAndroid =
      AndroidInitializationSettings('@mipmap/ic_launcher');
  const InitializationSettings initializationSettings =
      InitializationSettings(android: initializationSettingsAndroid);
  await _notificationsPlugin.initialize(initializationSettings);

  // 监听前台消息
  FirebaseMessaging.onMessage.listen((RemoteMessage message) {
    final title = message.data['title'];
    final subtitle = message.data['subtitle'];
    final gameID = message.data['gameID'];

    if (title != null && subtitle != null) {
      _notificationsPlugin.show(
        DateTime.now().millisecondsSinceEpoch,
        title,
        subtitle,
        NotificationDetails(
          android: AndroidNotificationDetails(
            'game_notification_channel',
            '游戏通知',
            channelDescription: '游戏相关通知渠道',
            icon: '@mipmap/ic_launcher',
          ),
        ),
        payload: gameID,
      );
    }
  });

  // 监听后台点击通知
  FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
    // 处理通知点击逻辑，如跳转至游戏页面
    final gameID = message.data['gameID'];
    // Navigator.pushNamed(context, '/game', arguments: gameID);
  });
}

额外注意事项 #

• iOS端需确保已正确配置APNs证书，并在Firebase控制台完成证书上传
• Android端需创建通知渠道（Android 8.0及以上系统要求）
• 测试时需覆盖前台、后台、锁屏等多种状态，避免因系统限制导致通知无法接收

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