Flutter应用终止时接收FCM Data Message无法显示通知的解决方案

• Flutter应用在前台/仅最小化时，能正常接收FCM Data Message并显示通知，但完全终止后无法触发通知
• 当前FCM核心配置代码：

_handleFCMMessage(RemoteMessage message, [bool onBackgroundIsolate = false]) {
  Map<String, dynamic> data = message.data;
  String type = data["type"];
  switch (type) {
    case "post_ready":
      // 通知显示逻辑（仅前台生效）
      flutterLocalNotificationsPlugin.show();
      break;
    default:
      // 无操作
      break;
  }
}

_firebaseMessagingForegroundHandler() {
  FirebaseMessaging.onMessage.listen(
    (message) => _handleFCMMessage(message, false),
  );
}

@pragma('vm:entry-point')
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  _handleFCMMessage(message, true);
}

main() async {
  ...
  _firebaseMessagingForegroundHandler();
  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
 ...
}

• 疑问：FCM后台消息在独立isolate运行，是不是导致现有flutterLocalNotificationsPlugin.show()失效的原因？如何复用现有通知配置解决问题？

核心原因 #

没错，问题根源就是独立isolate隔离机制：

• FCM后台消息handler运行在完全独立的隔离线程（isolate）中，和主应用isolate完全分离
• 主isolate初始化的flutterLocalNotificationsPlugin实例无法被后台isolate访问，直接调用show()自然无效
• 后台isolate没有预初始化Flutter环境，必须单独初始化通知插件

解决方法（复用配置，无需重复编写逻辑） #

步骤1：重构通用通知工具函数 #

把通知初始化、显示逻辑拆成独立可复用的函数，同时支持主isolate和后台isolate调用：

import 'package:flutter_local_notifications/flutter_local_notifications.dart';

// 每个isolate会创建自己的插件实例，无需担心冲突
FlutterLocalNotificationsPlugin flutterLocalNotificationsPlugin = FlutterLocalNotificationsPlugin();

// 通用初始化函数，主/后台isolate通用
Future<void> initLocalNotifications() async {
  const AndroidInitializationSettings androidSettings = AndroidInitializationSettings('@mipmap/ic_launcher');
  const DarwinInitializationSettings iosSettings = DarwinInitializationSettings();
  const InitializationSettings settings = InitializationSettings(
    android: androidSettings,
    iOS: iosSettings,
  );
  await flutterLocalNotificationsPlugin.initialize(settings);
}

// 通用通知显示函数，复用统一配置
Future<void> showPostReadyNotification() async {
  const AndroidNotificationDetails androidDetails = AndroidNotificationDetails(
    'post_ready_channel',
    '内容更新通知',
    importance: Importance.max,
    priority: Priority.high,
  );
  const NotificationDetails notificationDetails = NotificationDetails(android: androidDetails);
  await flutterLocalNotificationsPlugin.show(
    0,
    '新内容已就绪',
    '点击查看最新发布内容',
    notificationDetails,
  );
}

步骤2：修改后台消息handler #

在后台handler中先初始化Firebase和通知插件，再调用显示逻辑：

@pragma('vm:entry-point')
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  // 后台isolate不会自动初始化Firebase，必须手动调用
  await Firebase.initializeApp();
  // 初始化本地通知插件（后台isolate专属实例）
  await initLocalNotifications();
  
  Map<String, dynamic> data = message.data;
  String type = data["type"];
  if (type == "post_ready") {
    await showPostReadyNotification();
  }
}

步骤3：更新主应用初始化逻辑 #

在main函数中调用通用初始化函数，保持前台通知功能正常：

main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  // 初始化主isolate的通知插件
  await initLocalNotifications();
  
  _firebaseMessagingForegroundHandler();
  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
  
  runApp(const MyApp());
}

// 前台消息处理简化，直接调用通用函数
void _firebaseMessagingForegroundHandler() {
  FirebaseMessaging.onMessage.listen((message) {
    Map<String, dynamic> data = message.data;
    String type = data["type"];
    if (type == "post_ready") {
      showPostReadyNotification();
    }
  });
}

关键注意事项 #

• 保留@pragma('vm:entry-point')注解：防止编译器混淆或移除后台handler函数，否则Android/iOS系统无法触发后台消息处理
• FCM消息格式验证：确保发送的是纯Data Message（无notification字段），带notification字段的消息会由系统自动显示，完全终止时只有纯Data Message会触发后台handler
• 系统权限配置：
  • Android 13+：在AndroidManifest.xml中添加POST_NOTIFICATIONS权限
  • iOS：在Info.plist中开启Remote notifications后台模式，并请求用户通知权限

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