Flutter集成FCM后自定义后端推送仅前台接收问题排查求助

针对你遇到的自定义后端发送FCM消息后，Flutter应用仅前台能接收、后台无推送的问题，以下是核心排查点和修复方案：

1. Android端通知通道配置缺失（核心原因） #

Android 8.0（API 26）及以上版本要求所有通知必须关联通知通道，FCM控制台发送时会自动使用默认通道，但自定义后端发送时如果未指定通道ID，系统会拦截后台通知。

修复： #

在后端的android.notification字段中添加channel_id，确保和Flutter端创建的通道ID一致：

{
  "message": {
    // ... 其他字段
    "android": {
      "notification": {
        "click_action": "FLUTTER_NOTIFICATION_CLICK",
        "title": params[:title],
        "body": params[:body],
        "channel_id": "your_app_default_channel" // 新增：与Flutter端通道ID匹配
      }
    }
  }
}

同时在Flutter端初始化时创建对应通知通道（需依赖flutter_local_notifications库）：

Future<void> createNotificationChannel() async {
  const AndroidNotificationChannel channel = AndroidNotificationChannel(
    'your_app_default_channel', // 必须和后端的channel_id一致
    'Default Notification Channel',
    description: 'Channel for general notifications',
    importance: Importance.max,
  );

  final FlutterLocalNotificationsPlugin flutterLocalNotificationsPlugin =
      FlutterLocalNotificationsPlugin();
  await flutterLocalNotificationsPlugin.createNotificationChannel(channel);
}

2. iOS端APNs payload配置不完整 #

你的后端APNs配置仅包含category，缺少iOS系统展示通知必需的alert字段，导致后台无法触发通知托盘展示。

修复： #

在apns.payload.aps中补充alert对象：

{
  "message": {
    // ... 其他字段
    "apns": {
      "payload": {
        "aps": {
          "category": "NEW_MESSAGE_CATEGORY",
          "alert": { // 新增：iOS需要此字段展示通知
            "title": params[:title],
            "body": params[:body]
          },
          "sound": "default" // 可选：添加通知音效
        }
      }
    }
  }
}

3. Flutter端后台消息处理基础配置 #

即使你的消息包含notification字段（由系统托盘处理），仍需确保已配置后台消息处理器，避免极端场景下的接收异常：

@pragma('vm:entry-point')
Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  await Firebase.initializeApp();
  // 后台消息处理逻辑（按需添加）
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  FirebaseMessaging.onBackgroundMessage(firebaseMessagingBackgroundHandler);
  runApp(MyApp());
}

4. 关于tag字段的说明 #

你提到的message.notification?.android?.tag仅用于通知折叠（相同tag的通知会合并展示），不会导致后台无法接收消息，因此不是核心问题。如果需要实现通知折叠功能，可在后端android.notification中手动添加：

"tag": "your_custom_collapse_tag"

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