如何在iOS 14及以上版本中正确实现Flutter FCM 9+？

云上老周

2026-4-30

刚折腾完iOS 14+环境下Flutter集成FCM 9+的全流程，踩了好几个容易忽略的坑，整理了一套能保证推送正常跑的步骤，分享给你：

前置准备

确保你的Flutter环境是稳定版本（建议2.0+），Xcode版本至少12.0（对应iOS 14的最低要求）
已经在Firebase控制台创建好项目，并且为iOS应用生成了GoogleService-Info.plist文件
你的Apple开发者账号已经配置好Push Notifications相关权限（有有效证书或APNs密钥）

Flutter端配置

添加依赖到pubspec.yaml：

dependencies:
  flutter:
    sdk: flutter
  firebase_messaging: ^9.0.0  # 或者更高的9+版本

执行flutter pub get安装依赖。

初始化FCM并处理消息：
在你的main.dart里做基础初始化，记得要处理前台、后台以及终止状态的消息：

import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:flutter/widgets.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  
  // 获取FCM token
  String? token = await FirebaseMessaging.instance.getToken();
  print("FCM Token: $token");

  // 请求推送权限（iOS 14+必须显式请求）
  NotificationSettings settings = await FirebaseMessaging.instance.requestPermission(
    alert: true,
    badge: true,
    sound: true,
    provisional: false,
  );
  print("权限状态: ${settings.authorizationStatus}");

  // 监听前台消息
  FirebaseMessaging.onMessage.listen((RemoteMessage message) {
    print("收到前台消息: ${message.notification?.title}");
    // 这里可以自定义弹窗展示消息，比如用flutter_local_notifications
  });

  // 监听后台点击消息
  FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
    print("点击后台消息进入应用: ${message.data}");
    // 处理路由跳转等逻辑
  });

  runApp(MyApp());
}

iOS原生端关键配置（iOS 14+必看）

这部分是最容易出问题的地方，一定要仔细核对：

添加推送相关Capabilities
打开Xcode的Runner项目，进入Signing & Capabilities标签：

点击+ Capability，添加Push Notifications
再添加Background Modes，勾选Remote notifications（后台接收推送必须）

正确放置GoogleService-Info.plist
不要直接把文件拖到文件夹里，右键点击Runner项目 -> Add Files to "Runner"，选择你的GoogleService-Info.plist，确保勾选Copy items if needed和Create groups，然后检查Build Phases -> Copy Bundle Resources里是否包含这个文件。
配置APNs密钥到Firebase
在Firebase控制台进入项目设置 -> Cloud Messaging -> iOS应用部分：

上传你的APNs Auth Key（从Apple开发者中心生成，注意Team ID要和Xcode里的一致）
确保Bundle ID和Xcode里的完全匹配

处理iOS 14+的静默推送（如果需要）
如果你的应用需要接收静默推送（不显示通知，只后台处理），要确保：

推送payload里包含content-available: 1
在Flutter端开启后台消息处理：

Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  await Firebase.initializeApp();
  print("处理后台静默消息: ${message.data}");
}

void main() async {
  // ...其他初始化代码
  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
  // ...
}

测试验证

先获取到设备的FCM Token（从控制台打印的日志里复制）
用Firebase控制台发送测试消息：进入Cloud Messaging -> Send your first message，填写标题内容，选择目标设备粘贴Token发送
或者用curl命令测试（替换你的Server Key和Token）：

curl -X POST "https://fcm.googleapis.com/fcm/send" \
     -H "Authorization: key=YOUR_SERVER_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "to": "YOUR_DEVICE_TOKEN",
           "notification": {
             "title": "测试推送",
             "body": "这是一条来自FCM的测试消息"
           },
           "data": {
             "type": "test",
             "id": "123"
           }
         }'

常见问题排查

收不到推送：检查Xcode里的Bundle ID和Firebase项目是否一致；检查APNs密钥是否有效；检查设备是否允许通知（设置->通知->你的应用）；检查Background Modes是否勾选了Remote notifications
前台收不到消息提示：iOS默认前台不会弹通知，需要自己用Flutter的弹窗组件（比如flutter_local_notifications）来展示
后台消息不触发处理：确保payload里有content-available:1，并且已经配置了onBackgroundMessage回调

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