Flutter中FCM与Awesome Notifications重复通知问题排查

问题现象 #

使用Firebase Cloud Messaging(FCM)结合Awesome Notifications包时，接收单条推送通知会显示两条，且在应用前台、后台、终止状态下均出现该问题。

重复原因分析 #

1. 前台状态：FCM默认通过setForegroundNotificationPresentationOptions开启了alert: true，会自动弹出系统通知；同时你的_fcmForegroundHandler又调用Awesome Notifications发送了一条本地通知，导致两条重复。
2. 后台/终止状态：当FCM收到包含notification字段的推送时，系统会自动展示一条通知；同时你的_fcmBackgroundHandler再次调用Awesome Notifications发送通知，造成重复。

解决方案 #

1. 关闭FCM前台自动展示通知 #

修改FcmHelper中的_setupFcmNotificationSettings方法，将alert设为false，让前台通知完全由Awesome Notifications处理：

static Future<void> _setupFcmNotificationSettings() async {
  // 关闭FCM前台自动弹出通知，由Awesome Notifications统一处理
  messaging.setForegroundNotificationPresentationOptions(
    alert: false, 
    sound: true,
    badge: true,
  );

  await messaging.requestPermission(
    alert: true,
    badge: true,
    sound: true,
    provisional: true,
  );
}

2. 统一后台/终止状态的通知处理 #

方案A：发送纯数据消息（推荐）

让服务器推送仅包含data字段的消息，不包含notification字段。这种情况下FCM不会自动展示系统通知，所有通知都由你的handler通过Awesome Notifications发送，避免重复。

方案B：保留notification字段时的处理

如果必须发送notification字段，修改_fcmBackgroundHandler，不再调用Awesome Notifications发送通知（因为系统已经自动展示了notification字段对应的通知）：

@pragma('vm:entry-point')
static Future<void> _fcmBackgroundHandler(RemoteMessage message) async {
  // 仅处理数据逻辑，不发送重复通知
  // 如需自定义通知内容，建议改用纯数据消息方案
  Logger().d('后台收到FCM数据: ${message.data}');
}

3. 统一通知ID生成规则 #

将_fcmBackgroundHandler中的固定ID1改为动态唯一ID，避免新通知覆盖旧通知：

@pragma('vm:entry-point')
static Future<void> _fcmBackgroundHandler(RemoteMessage message) async {
  AwesomeNotificationsHelper.showNotification(
    id: DateTime.now().microsecond, // 使用动态唯一ID
    title: message.notification?.title ?? '标题',
    body: message.notification?.body ?? '内容',
    payload: message.data.cast(),
  );
}

4. 确认Awesome Notifications初始化唯一 #

确保AwesomeNotificationsHelper.init()在应用启动时只调用一次，避免重复注册通道导致的异常。

额外说明 #

FCM与Awesome Notifications本身没有已知的固有冲突，重复通知的核心原因是FCM自动展示的系统通知与Awesome Notifications发送的本地通知重复触发，只要统一通知的触发逻辑即可解决。

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