一、技术选型与前期准备

FCM作为行业主流的跨平台消息推送方案，其核心优势在于支持Android/iOS双端统一接口、低延迟消息传递及丰富的消息类型（通知/数据消息）。在Flutter生态中，推荐使用firebase_messaging插件（最新稳定版）作为核心实现组件，该插件已通过社区长期验证，支持消息接收、点击事件处理及后台状态管理。

1.1 环境要求

Flutter SDK版本：3.0+（推荐使用最新稳定版）
Android Studio：2022.1+（含Gradle 8.x支持）
CocoaPods：1.11+（仅iOS端需要）
操作系统：macOS（iOS开发必备）/Windows/Linux

1.2 开发者账号配置

访问控制台创建项目，启用FCM服务
生成google-services.json（Android）和GoogleService-Info.plist（iOS）配置文件
配置服务器密钥（用于服务端推送）

二、依赖集成与冲突解决

2.1 插件安装与版本锁定

在pubspec.yaml中添加核心依赖：

dependencies:
  firebase_messaging: ^14.6.5  # 版本需与Flutter SDK兼容
  firebase_core: ^2.15.1      # 基础依赖
dev_dependencies:
  flutter_local_notifications: ^15.1.1  # 本地通知增强

执行flutter pub get后，需重点检查以下依赖冲突：

Kotlin版本：建议锁定1.9.0（与Gradle 8.x兼容）
Android Gradle插件：需≥8.1.0
Compose编译器：若项目使用Jetpack Compose，需保持版本同步

2.2 Gradle配置优化

Android端配置

修改android/build.gradle：

buildscript {
    ext.kotlin_version = '1.9.0'  // 版本锁定
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/central' }
        google()
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:8.1.0'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
        classpath 'com.google.gms:google-services:4.4.0'  // 关键插件
    }
}

在android/app/build.gradle末尾添加：

apply plugin: 'com.google.gms.google-services'  // 必须放在最后

Gradle Wrapper升级

修改gradle/wrapper/gradle-wrapper.properties：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip

2.3 常见冲突解决方案

Kotlin版本不兼容：
- 统一build.gradle与gradle.properties中的kotlin版本
- 执行File > Invalidate Caches / Restart
Google Services插件缺失：
- 确保顶级build.gradle包含classpath 'com.google.gms4.4.0'
- 检查google-services.json是否放置在android/app目录

多模块项目配置：

在根目录settings.gradle中添加：

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

三、核心代码实现

3.1 初始化配置

// main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  // 配置消息处理
  FirebaseMessaging.onMessage.listen((RemoteMessage message) {
    print('收到前台消息: ${message.notification?.title}');
    // 显示本地通知（需flutter_local_notifications配合）
  });
  // 后台消息处理
  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
  runApp(MyApp());
}
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  print('处理后台消息: ${message.data}');
  // 执行后台任务（如数据库更新）
}

3.2 通知权限处理

// 请求通知权限（Android）
Future<void> requestNotificationPermission() async {
  final settings = await FirebaseMessaging.instance.requestPermission(
    alert: true,
    announcement: false,
    badge: true,
    carPlay: false,
    criticalAlert: false,
    provisional: false,
    sound: true,
  );
  print('用户授权状态: $settings');
}
// iOS配置（Info.plist添加）
/*
<key>UIBackgroundModes</key>
<array>
    <string>remote-notification</string>
</array>
*/

3.3 设备令牌管理

// 获取FCM令牌
Future<String?> getFCMToken() async {
  String? token = await FirebaseMessaging.instance.getToken();
  print('设备令牌: $token');
  return token;
}
// 监听令牌变化
FirebaseMessaging.instance.onTokenRefresh.listen((token) {
  print('令牌更新: $token');
  // 同步到服务器
});

四、高级功能实现

4.1 消息分类处理

// 根据消息类型分发处理
void handleMessage(RemoteMessage message) {
  if (message.notification != null) {
    // 处理通知消息
    _showNotification(message);
  } else if (message.data.isNotEmpty) {
    // 处理数据消息
    _handleDataMessage(message.data);
  }
}
void _showNotification(RemoteMessage message) {
  // 使用flutter_local_notifications显示通知
  flutterLocalNotificationsPlugin.show(
    message.hashCode,
    message.notification?.title,
    message.notification?.body,
    NotificationDetails(
      android: AndroidNotificationDetails(
        'channel_id',
        'channel_name',
        importance: Importance.max,
      ),
    ),
    payload: message.data.toString(),
  );
}

4.2 消息点击事件处理

// 配置点击回调
void setupNotificationClick() {
  flutterLocalNotificationsPlugin.initialize(
    InitializationSettings(
      android: AndroidInitializationSettings('@mipmap/ic_launcher'),
    ),
    onSelectNotification: (payload) {
      print('通知点击: $payload');
      // 跳转到指定页面
      Navigator.push(
        context,
        MaterialPageRoute(builder: (_) => DetailPage(data: payload)),
      );
    },
  );
}

五、测试与调优

5.1 测试方案

Android测试：
- 使用FCM控制台发送测试消息
- 验证前台/后台/杀进程三种状态下的接收情况
- 检查日志输出：adb logcat | grep FirebaseMessaging
iOS测试：
- 配置开发证书
- 使用真实设备测试（模拟器可能无法接收推送）
- 检查控制台输出：xcrun simctl spawn booted log stream --predicate 'sender == "apsd"'

5.2 性能优化

消息合并：对高频消息实现合并显示逻辑
省电策略：
- 设置setForegroundNotificationPresentationOptions控制前台显示方式
- 使用android_channel配置振动/声音策略
离线消息：确保服务器端设置正确的TTL（生存时间）

六、常见问题处理

iOS收不到推送：
- 检查AppDelegate.swift是否配置UNUserNotificationCenter.current().delegate
- 验证Capabilities中是否开启Push Notifications

Android后台崩溃：

在AndroidManifest.xml中添加：

<service
    android:name=".java.MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

消息延迟：
- 检查服务器端是否使用HTTP/2协议
- 优化网络环境（避免弱网环境测试）

通过以上系统化配置，开发者可构建出稳定可靠的跨平台消息推送系统。实际开发中建议结合日志服务（如Sentry）监控消息送达率，持续优化用户体验。对于企业级应用，可考虑集成消息队列服务实现消息存储与重试机制，进一步提升系统可靠性。

Flutter与FCM集成：构建高效跨平台推送系统