Flutter集成FCM报PlatformException通道连接错误致应用白屏

问题现象 #

• 为Flutter移动应用接入Firebase Cloud Messaging能力时，添加Firebase相关代码前应用可正常启动运行，添加FCM功能代码后启动直接白屏，持续抛出PlatformException类错误。
• 已排除依赖版本不匹配因素，核心报错信息如下：

E/flutter ( 3318): [ERROR:flutter/lib/ui/ui_dart_state.cc(198)] Unhandled Exception: PlatformException(channel-error, Unable to establish connection on channel., null, null)
E/flutter ( 3318): #0      FirebaseCoreHostApi.initializeCore (package:firebase_core_platform_interface/src/pigeon/messages.pigeon.dart:205:7)
E/flutter ( 3318): <asynchronous suspension>
E/flutter ( 3318): #1      MethodChannelFirebase._initializeCore (package:firebase_core_platform_interface/src/method_channel/method_channel_firebase.dart:29:44)
E/flutter ( 3318): <asynchronous suspension>
E/flutter ( 3318): #2      MethodChannelFirebase.initializeApp (package:firebase_core_platform_interface/src/method_channel/method_channel_firebase.dart:73:7)
E/flutter ( 3318): <asynchronous suspension>
E/flutter ( 3318): #3      Firebase.initializeApp (package:firebase_core/src/firebase.dart:40:31)
E/flutter ( 3318): <asynchronous suspension>
E/flutter ( 3318): #4      main (package:activepeers_app_internship/main.dart:23:3)
E/flutter ( 3318): <asynchronous suspension>

• 报错堆栈指向main函数中Firebase.initializeApp()调用环节，对应业务代码如下：

import 'package:flutter/material.dart';
import 'package:flutter_local_notifications/flutter_local_notifications.dart';
import 'package:get/get_navigation/src/root/get_material_app.dart';
import 'splashScreen.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_messaging/firebase_messaging.dart';

const AndroidNotificationChannel channel = AndroidNotificationChannel('high_importance_channel',
    'High Importance Notifications',
importance: Importance.high,
playSound: true);

final FlutterLocalNotificationsPlugin flutterLocalNotificationsPlugin =
    FlutterLocalNotificationsPlugin();

Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async{
  await Firebase.initializeApp();
  print('A bg message just showed up: ${message.messageId}');
}

Future<void> main() async{
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);

  await flutterLocalNotificationsPlugin
        .resolvePlatformSpecificImplementation<AndroidFlutterLocalNotificationsPlugin>()
        ?.createNotificationChannel(channel);

  await FirebaseMessaging.instance.setForegroundNotificationPresentationOptions(
    alert: true,
    badge: true,
    sound: true,
  );
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState(){
    super.initState();
    FirebaseMessaging.onMessage.listen((RemoteMessage message){
    RemoteNotification? notification = message.notification;
    AndroidNotification? android = message.notification?.android;
    if(notification!=null && android!=null){
      flutterLocalNotificationsPlugin.show(
        notification.hashCode,
        notification.title,
        notification.body,
        NotificationDetails(
          android: AndroidNotificationDetails(
            channel.id,
            channel.name,
            color: Colors.blue,
            playSound: true,
            icon: '@ipmap/ic_launcher',

          )
        )
      );
    }
    });
    
    FirebaseMessaging.onMessageOpenedApp.listen((RemoteMessage message) {
    print('A new onMessageOpenedApp event was published');
    RemoteNotification? notification = message.notification;
    AndroidNotification? android = message.notification?.android;
    if(notification!=null && android!=null){
      showDialog
        (context: context,
          builder: (_){
        return AlertDialog(
          title: Text(notification.title??''),
          content: SingleChildScrollView(
            child: Column(
              crossAxisAlignment: CrossAxisAlignment.start,
              children: [
                Text(notification.body??'')
              ],
            ),
          ),
        );
      });
    }
    }
    );
  }

  @override
  Widget build(BuildContext context) {
    return GetMaterialApp(
      home: SplashScreen(),
    );
  }
}

问题根因 #

该报错和Dart层业务代码无关，本质是Flutter和原生Android侧的Method Channel通信建立失败，绝大多数情况是原生端Firebase配置缺失、配置不匹配，或者旧构建缓存脏数据导致。

排查解决步骤 #

按优先级从高到低依次排查：

• 校验Android端Google服务配置
  • 确认google-services.json文件路径正确：必须放在android/app/目录下，不能放Android根目录或者src子目录
  • 确认google-services.json内的package_name字段值，和android/app/build.gradle中配置的applicationId完全一致，大小写、字符都不能有偏差
  • 确认Gradle插件配置正确：
    • 项目级android/build.gradle的dependencies块中添加classpath 'com.google.gms:google-services:4.3.15'，不要使用4.3.10以下的旧版本，会和新版FlutterFire不兼容
    • app级android/app/build.gradle文件最末尾，必须添加apply plugin: 'com.google.gms.google-services'，这行漏加会100%触发当前channel连接错误
• 全量清理构建缓存重新编译
  配置修改后如果不清理缓存，旧的构建产物仍会导致报错，按顺序执行以下命令：

  flutter clean
  cd android && ./gradlew clean
  cd ..
  flutter pub get
  flutter run
  

• 修正代码中隐藏的后续崩溃点
  这些问题不会触发当前初始化报错，但会在后续运行时导致崩溃：
  • 通知图标路径拼写错误：'@ipmap/ic_launcher'改为'@mipmap/ic_launcher'，少写了开头的m
  • Android 13及以上版本需要额外申请通知权限，否则前台通知无法弹出，可在initState中补充权限申请逻辑：

    FirebaseMessaging.instance.requestPermission(
      alert: true,
      badge: true,
      sound: true,
    );
    

• 自动补全配置
  如果手动排查找不到配置漏项，直接在项目根目录执行FlutterFire自动配置命令，按提示选择对应Firebase项目、应用包名，命令会自动覆盖更新所有原生侧配置文件、补全Gradle配置，避免手动配置的疏漏。

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