Flutter连接Firebase初始化失败报channel-error异常

问题现象 #

按照官方Android手动安装流程为Flutter应用接入Firebase时，运行抛出异常，无法完成初始化连接。

• 模拟器报错截图：
  
• 问题对应main.dart代码：

import 'package:flutter/material.dart';
import 'package:barbellplus/routes.dart';

// Import the firebase_core plugin
import 'package:firebase_core/firebase_core.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const App());
}

/// We are using a StatefulWidget such that we only create the [Future] once,
/// no matter how many times our widget rebuild.
/// If we used a [StatelessWidget], in the event where [App] is rebuilt, that
/// would re-initialize FlutterFire and make our application re-enter loading state,
/// which is undesired.
class App extends StatefulWidget {
  const App({super.key});

  @override
  State<App> createState() => _AppState();
}

class _AppState extends State<App> {
  /// The future is part of state of our widget. We should not call `initializeApp`
  /// directly inside [build].
  final Future<FirebaseApp> _initialization = Firebase.initializeApp();

  @override
  Widget build(BuildContext context) {
    return FutureBuilder(
      // Initialize FlutterFire:
      future: _initialization,
      builder: (context, snapshot) {
        // Check for errors
        if (snapshot.hasError) {
          return const Text('error', textDirection: TextDirection.ltr);
        }

        // Once complete, show your application
        if (snapshot.connectionState == ConnectionState.done) {
          return MaterialApp(
            routes: appRoutes,
          );
        }

        // Otherwise, show something whilst waiting for initialization to complete
        return const Text('loading', textDirection: TextDirection.ltr);
      },
    );
  }
}

• 运行抛出的错误日志：

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

根因与排查解决步骤 #

该错误本质是Flutter Dart层和Android原生层的MethodChannel通信建立失败，Firebase原生侧SDK没有正确加载初始化，按以下优先级排查即可解决：

• 优先排查版本兼容问题（占该类报错的80%以上）
  • 先执行基础清理命令，排除缓存导致的版本不一致：

    flutter clean
    flutter pub get
    

  • 检查firebase_core版本：Flutter 3.0及以上版本不要使用1.20.0以下的firebase_core，旧版本使用的Pigeon通信协议和新Flutter引擎不兼容，直接在pubspec.yaml中指定兼容稳定版：

    dependencies:
      firebase_core: ^2.15.1
    

  • 检查Android端Gradle配置：
    • 项目级build.gradle中Google服务插件版本不低于4.3.15：classpath 'com.google.gms:google-services:4.3.15'
    • app级build.gradle文件末尾必须添加插件应用配置：apply plugin: 'com.google.gms.google-services'，手动配置时遗漏该配置是高频错误
• 校验配置文件位置与内容
  • 确认Firebase控制台下载的google-services.json文件存放在android/app/目录下，不要放在项目根目录、android根目录或其他子目录
  • 校验google-services.json中声明的package_name字段，和app级build.gradle中的applicationId完全一致，大小写、包名分段不能有任何差异
• 清理原生构建缓存
  • 进入android目录执行Gradle清理：

    ./gradlew clean
    

  • 完全关闭模拟器后冷启动，全量重新构建运行应用，不要使用热重载/热重启：Firebase初始化相关的原生配置改动必须全量打包才能生效，热重载不会更新原生侧代码
• 校验编译配置
  • 确认app级build.gradle中minSdkVersion不低于19，Firebase核心SDK最低支持Android API 19，低于该版本无法正常加载
  • 如果开启了代码混淆（minifyEnabled true），在proguard-rules.pro中添加以下规则，防止通信相关类被混淆裁剪：

    -keep class com.google.firebase.** { *; }
    -keep class io.flutter.plugins.firebase.core.** { *; }
    

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