Flutter FCM后台重复收通知、iOS终止态无法接收推送问题咨询

• 重复通知问题：当FCM推送payload同时携带notification字段和data字段时，Android/iOS系统会自动渲染一条默认样式的系统通知，此时你在onBackgroundMessage回调里调用createNotification手动创建awesome_notifications通知，就会出现两条重复通知。
• iOS终止态收不到纯data推送问题：这是iOS APNs的底层机制限制，纯data类型的静默推送，仅在应用处于前台、后台状态时会唤醒应用触发回调，应用终止状态下系统不会处理这类消息，只有携带标准notification字段的推送，才会被系统级通道接收，在应用未启动的状态下也能正常展示。
• 你之前的测试代码存在明显错误：curl请求里把notification拼成了notificaton（少了字母i），Ruby代码里title字段重复定义，这也会导致推送字段解析异常。

客户端调整 #

1. 修正后台消息回调逻辑，不要无条件创建自定义通知，仅当消息无系统自带通知字段时才手动创建，避免重复，示例代码：

Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  // 后台环境下先初始化通知插件，保证插件可用
  await AwesomeNotifications().initialize(
    // 替换为你自己的应用通知图标资源
    'resource://drawable/res_app_icon',
  );
  // 仅纯data消息时手动创建通知，避免和系统通知重复
  if (message.notification == null) {
    createNotification(message);
  }
}

void main() {
  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
  runApp(MyApp());
}

2. iOS端完成必填配置：在Xcode中开启Push Notifications能力，在Background Modes中勾选Remote notifications，初始化FCM和awesome_notifications时正确申请通知权限，确保APNs token能正常同步给FCM。

服务端推送Payload格式 #

不要使用纯data或者纯notification的单字段结构，采用混合payload兼容双平台所有状态，正确curl示例如下：

curl --location --request POST 'https://fcm.googleapis.com/fcm/send' \
--header 'Authorization: key=替换为你的FCM服务端密钥' \
--header 'Content-Type: application/json' \
--data-raw '{
  "to": "替换为目标用户的FCM token",
  "priority": "high",
  "content_available": true,
  "mutable_content": true,
  "notification": {
    "title": "消息标题",
    "body": "消息内容",
    "sound": "default",
    "android_channel_id": "session_alert"
  },
  "data": {
    "channelId": "session_alert",
    "title": "消息标题",
    "body": "消息内容",
    "click_action": "FLUTTER_NOTIFICATION_CLICK"
    // 其余自定义业务参数可加在data块内
  }
}'

关键字段说明 #

• content_available: true：iOS端后台唤醒应用的必填字段，对应APNs协议的content-available=1
• mutable_content: true：iOS端支持通知服务扩展修改通知内容的必填字段，需要展示图片、自定义按钮等高级通知样式时必须配置
• 混合payload的兼容逻辑：
  • Android端：应用在前台时系统不会自动弹出通知，消息会传递到onMessage回调，你可以用awesome_notifications展示自定义样式通知；应用在后台/终止态时系统展示默认通知，用户点击后进入应用传递业务参数，不会出现重复通知问题
  • iOS端：无论应用处于前台、后台、终止状态，系统通道都能正常接收推送，终止状态下无需唤醒应用即可展示通知，用户点击后正常触发应用内回调

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