Flutter firebase_messaging的onMessage监听在iOS端不触发问题咨询

1. 补全iOS原生端前台通知配置 #

iOS系统默认拦截前台状态下的通知消息，不会自动抛给Flutter层，必须在原生AppDelegate文件中添加对应配置，否则所有前台推送都不会触发onMessage监听。

若项目使用Swift（AppDelegate.swift） #

在didFinishLaunchingWithOptions方法中，注册Flutter插件的逻辑之后添加如下代码：

if #available(iOS 10.0, *) {
  UNUserNotificationCenter.current().delegate = self
  let authOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
  UNUserNotificationCenter.current().requestAuthorization(options: authOptions) { _, _ in }
} else {
  let settings = UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
  application.registerUserNotificationSettings(settings)
}
application.registerForRemoteNotifications()

同时在AppDelegate类中实现通知前台展示的代理方法，确保系统收到通知后主动回调给Flutter：

func userNotificationCenter(
  _ center: UNUserNotificationCenter,
  willPresent notification: UNNotification,
  withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
) {
  // 必须传入非空的展示选项，传空会拦截消息不触发回调
  completionHandler([.alert, .sound, .badge])
}

若项目使用Objective-C（AppDelegate.m） #

在didFinishLaunchingWithOptions方法中添加：

if (@available(iOS 10.0, *)) {
  [UNUserNotificationCenter currentNotificationCenter].delegate = self;
  UNAuthorizationOptions authOptions = UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge;
  [[UNUserNotificationCenter currentNotificationCenter] requestAuthorizationWithOptions:authOptions completionHandler:^(BOOL granted, NSError * _Nullable error) {}];
} else {
  UIUserNotificationType types = UIUserNotificationTypeAlert | UIUserNotificationTypeBadge | UIUserNotificationTypeSound;
  UIUserNotificationSettings *settings = [UIUserNotificationSettings settingsForTypes:types categories:nil];
  [application registerUserNotificationSettings:settings];
}
[application registerForRemoteNotifications];

对应添加代理方法：

- (void)userNotificationCenter:(UNUserNotificationCenter *)center
       willPresentNotification:(UNNotification *)notification
         withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
  completionHandler(UNNotificationPresentationOptionAlert | UNNotificationPresentationOptionSound | UNNotificationPresentationOptionBadge);
}

2. 调整Flutter层权限申请与监听注册逻辑 #

• 必须确保onMessage监听注册前，已经完成Firebase初始化、且用户已经授予通知权限，未授权状态下iOS不会推送任何消息，自然不会触发回调。参考正确写法：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  // 主动申请通知权限
  NotificationSettings settings = await FirebaseMessaging.instance.requestPermission(
    alert: true,
    badge: true,
    sound: true,
  );
  // 仅在授权状态下注册消息监听
  if (settings.authorizationStatus == AuthorizationStatus.authorized 
      || settings.authorizationStatus == AuthorizationStatus.provisional) {
    FirebaseMessaging.onMessage.listen((RemoteMessage message) {
      print('onMessage: ${message.data}');
    });
  }
  runApp(const MyApp());
}

• 若用户之前拒绝过通知权限，需要引导用户到系统设置页手动打开通知权限，否则监听永远不会触发。

3. 排查推送载荷与测试环境问题 #

• 必须使用真机调试：iOS模拟器不支持APNs推送，无法收到真实通知，所有推送相关测试不要在模拟器上进行。
• 检查推送载荷格式：iOS端如果推送载荷仅携带data字段、没有notification字段且未配置mutable_content: true，会被判定为静默推送，前台状态下不会触发onMessage回调；如果载荷中content_available设为true但缺少通知字段，也会出现回调不触发的问题。
• 不要用Release/TestFlight包调试前台回调：Release模式下Flutter的print日志会被屏蔽，容易误以为回调没触发，优先用Debug包连接Xcode查看完整日志。

4. 缓存与版本问题排查 #

• 升级firebase_messaging到14.0.0以上的稳定版本，低于该版本的插件存在iOS前台消息回调丢失的已知bug。
• 执行flutter clean清空缓存，进入iOS目录执行pod install --repo-update更新原生依赖，重新编译运行即可。

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