Flutter：FCM后台消息模拟器可用真机报错找不到my_fcm.dart库

报错说明 #

真机运行时出现以下Dart库找不到的错误：

E flutter : [ERROR:flutter/shell/common/shell.cc(93)] Dart Error: Dart_LookupLibrary: library 'package:flutter_starter/starterlib/my_fcm.dart' not found.

核心问题是打包后的APK无法定位到包含FCM后台处理函数的文件，大概率是代码声明不规范、打包混淆或配置错误导致的。

具体解决办法 #

1. 规范后台处理函数的声明与注册 #

• 必须保证firebaseMessagingBackgroundHandler是全局顶级函数（完全写在类和其他函数外部），不能是类的静态方法或实例方法，示例：

  // my_fcm.dart 文件最外层
  Future<void> firebaseMessagingBackgroundHandler(RemoteMessage message) async {
    await Firebase.initializeApp();
    // 这里写后台消息处理逻辑
  }
  

• 注册函数时直接引用这个全局方法，且要在main函数初始化阶段调用，示例：

  void main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    // 注册后台消息处理器
    FirebaseMessaging.onBackgroundMessage(firebaseMessagingBackgroundHandler);
    runApp(MyApp());
  }
  

2. 关闭或配置代码混淆规则 #

如果开启了R8/ProGuard混淆，会导致FCM相关代码被误删，需要在android/app/proguard-rules.pro中添加保护规则：

# 保留Firebase Messaging核心类
-keep class com.google.firebase.messaging.** { *; }
-keep class io.flutter.plugins.firebase.messaging.** { *; }
# 保留你的后台处理函数所在的文件
-keep class com.yourproject.starterlib.my_fcm.** { *; }
# 保留Flutter核心代码避免被混淆
-keep class io.flutter.** { *; }
-keep class io.flutter.plugins.** { *; }

注意把com.yourproject替换成你项目的实际包名。

3. 修复打包缓存与配置 #

• 执行flutter clean清除旧缓存，再运行flutter pub get确保依赖完整，最后重新打包：flutter build apk --release。
• 检查pubspec.yaml中firebase_messaging的版本是否适配当前Flutter版本，避免版本不兼容问题。
• 确认my_fcm.dart的路径和导入时的package:flutter_starter/starterlib/my_fcm.dart完全一致，没有拼写错误。

4. 验证真机配置 #

• 确保android/app目录下的google-services.json是Firebase控制台对应项目的正确文件，包名必须和项目一致。
• 检查真机系统设置，开启应用的通知权限和后台活动权限，禁止后台限制会导致FCM后台消息无法触发。

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