Flutter正式版FCM纯数据消息无法即时接收问题求助

问题背景 #

开发Flutter聊天功能时，最初使用FCM普通通知，遇到用户离线时通知被合并、仅推送最后一条的问题。改为纯数据消息后，Debug/Profile模式下前后台均正常接收，但Release模式下，APP后台或终止状态时必须打开APP才能触发消息接收，而普通通知能正常即时推送。

原因分析 #

Android端 #

1. 后台进程限制：Release模式下Android系统电池优化、后台进程查杀策略更严格，纯数据消息的高优先级配置无法触发APP唤醒
2. 代码混淆：ProGuard/R8混淆了FCM相关类，导致消息接收逻辑失效
3. 无系统通知触发：纯数据消息不会主动触发系统通知，系统无动力唤醒APP处理

iOS端 #

1. 静默推送限制：iOS对纯数据的静默推送（content-available:1）有严格频率和延迟限制，Release模式下系统优先省电，不会即时唤醒APP
2. 生产环境配置问题：推送证书、后台权限在Release模式下未正确设置
3. 系统挂起策略：APP终止后，iOS不会主动唤醒APP处理静默推送

解决方案 #

1. 后端调整：使用「通知+数据」混合消息（最优方案） #

兼顾通知即时性和数据更新需求，同时避免通知合并：

• 保留通知部分，用消息ID作为tag（Android）和apns-collapse-id（iOS），确保每条聊天消息都是独立通知
• 数据部分携带聊天更新所需负载，APP可通过消息回调获取数据更新本地内容

修改Laravel的FCM函数，恢复通知配置：

public function sendDataMessage($deviceTokens, $data = [], $priority = "high")
{
    $messaging = app('firebase.messaging');
    $clean_data = $data;
    $chat_message = null;
    if (isset($data["type"]) && $data["type"] == "chat" && $data["action"] == "receiveMessage") {
        $chat_message = $data["fcm_message"];
        unset($clean_data["fcm_message"]);
        $clean_data["title"] = Chats::select("name")->find($data["chat_id"])->name;
        $clean_data["body"] = $chat_message["sender"]["name"] . ": " . ($chat_message["content"]["type"] == "Text" ? $chat_message["content"]["body"] : $chat_message["content"]["type"]);
    }
    
    $messages = [];
    foreach ($deviceTokens as $token) {
        try {
            $messageBuilder = CloudMessage::withTarget('token', $token)
                ->withData($clean_data)
                // 添加通知内容
                ->withNotification(Notification::create(
                    $clean_data["title"] ?? '新消息',
                    $clean_data["body"] ?? '您收到一条新消息'
                ))
                ->withAndroidConfig(AndroidConfig::fromArray([
                    'priority' => 'high',
                    'ttl' => 86400 * 28,
                    'notification' => [
                        'tag' => $chat_message ? strval($chat_message["id"]) : uniqid(),
                        'sound' => 'default',
                        'channel_id' => 'high_importance',
                    ],
                ]))
                ->withApnsConfig(ApnsConfig::fromArray([
                    'headers' => [
                        'apns-collapse-id' => $chat_message ? strval($chat_message["id"]) : uniqid(),
                        'apns-expiration' => strval(time() + 86400 * 28),
                        'apns-priority' => '10',
                    ],
                    'payload' => [
                        'aps' => [
                            'sound' => 'default',
                            "content-available" => 1,
                            "mutable-content" => 1,
                            'alert' => [
                                'title' => $clean_data["title"] ?? '新消息',
                                'body' => $clean_data["body"] ?? '您收到一条新消息'
                            ]
                        ],
                    ],
                ]));
                
            $messages[] = $messageBuilder;
        } catch (Exception $e) {
            return $e;
        }
    }
    
    try {
        $report = $messaging->sendAll($messages);
    } catch (NotFound $e) {
        return $e;
    } catch (Exception $e) {
        return $e;
    }

    return $report->successes()->count();
}

2. Android端Release模式优化 #

• 添加ProGuard规则：在proguard-rules.pro中保留FCM相关类：

-keep class com.google.firebase.** { *; }
-keep class com.google.android.gms.** { *; }
-dontwarn com.google.firebase.**

• 创建高优先级通知渠道：APP启动时初始化通知渠道：

void _createNotificationChannel() {
  if (Platform.isAndroid) {
    const channel = AndroidNotificationChannel(
      'high_importance',
      '聊天消息',
      description: '接收聊天消息通知',
      importance: Importance.max,
      playSound: true,
    );
    FlutterLocalNotificationsPlugin().createNotificationChannel(channel);
  }
}

// 在main函数中调用
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  _createNotificationChannel();
  // ...其他初始化
  runApp(const MyApp());
}

• 请求忽略电池优化：引导用户关闭APP的电池优化，或代码中请求权限：

Future<void> _requestIgnoreBatteryOptimizations() async {
  if (Platform.isAndroid) {
    final packageName = await PackageInfo.fromPackageName(await PackageInfo().packageName);
    final status = await AndroidIntent(
      action: 'android.settings.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS',
      data: 'package:${packageName.packageName}',
    ).launch();
  }
}

3. iOS端Release模式优化 #

• 确认生产环境证书：使用APNs生产证书推送，而非开发证书
• 开启后台推送权限：在Info.plist中添加：

<key>UIBackgroundModes</key>
<array>
    <string>remote-notification</string>
</array>

• 避免过度依赖静默推送：iOS的静默推送无法保证即时性，聊天场景优先用带alert的混合消息

4. Flutter端消息处理优化 #

• 确保后台消息回调是顶层函数：Release模式下必须用@pragma('vm:entry-point')标记：

@pragma('vm:entry-point')
Future<void> _firebaseBackgroundMessageHandler(RemoteMessage message) async {
  await Firebase.initializeApp();
  // 处理消息：更新本地数据库、触发本地通知等
  if (message.data['type'] == 'chat') {
    // 更新聊天数据逻辑
    // 触发本地通知
    await FlutterLocalNotificationsPlugin().show(
      int.parse(message.data['chat_message_id']),
      message.data['title'],
      message.data['body'],
      const NotificationDetails(
        android: AndroidNotificationDetails('high_importance', '聊天消息'),
      ),
    );
  }
}

// 在main中注册
FirebaseMessaging.onBackgroundMessage(_firebaseBackgroundMessageHandler);

关键注意点 #

• Release模式下，Android的后台限制、iOS的推送策略远严格于Debug/Profile，很多Debug下正常的逻辑会失效
• 纯数据消息（静默推送）仅适合非即时场景，聊天这种需要即时触达的场景，混合消息是最优选择
• 测试Release模式必须用真实设备和生产环境配置（如iOS AdHoc包、Android Release APK），模拟器无法模拟真实推送行为

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