Flutter集成FCM点击通知无法获取payload跳转页面问题

安全阿岳

2026-8-28

Flutter FCM点击通知无法读取data字段、跳转失效排查方案

按以下优先级逐一排查修复：

调用时机错误（最高发原因）
getInitialMessage 仅在应用完全被杀掉、点击通知冷启动时才会返回结果，且必须满足两个前提才能正常拿到数据：

main 函数中必须先调用 WidgetsFlutterBinding.ensureInitialized()，再等待 Firebase.initializeApp() 完成初始化后再runApp，否则Firebase SDK未就绪时拿不到消息对象。
不能在initState执行早期直接调用Navigator做跳转，必须等首帧渲染完成后再执行逻辑，否则context未挂载会导致路由跳转失败，且拿不到有效的Navigator状态。

正确初始化示例：

// main.dart 入口配置
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // 必须等待Firebase初始化完成
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  runApp(const MyApp());
}

// 根首页（即通知点击默认打开的首页）的initState中配置
@override
void initState() {
  super.initState();
  WidgetsBinding.instance.addPostFrameCallback((_) async {
    // 处理冷启动场景
    RemoteMessage? initialMsg = await FirebaseMessaging.instance.getInitialMessage();
    if (initialMsg != null) _handleNotificationRoute(initialMsg);

    // 处理应用在后台挂起（未被杀）时点击通知的场景，你当前代码完全漏了这个监听
    FirebaseMessaging.onMessageOpenedApp.listen(_handleNotificationRoute);
  });
}

// 抽离统一的路由跳转逻辑，两个场景复用
void _handleNotificationRoute(RemoteMessage message) {
  // 先打印全量data排查字段是否正确传递
  debugPrint('通知携带payload: ${message.data}');
  switch (message.data['type']) {
    case 'noti':
      Navigator.of(context).push(
        MaterialPageRoute(
          builder: (_) => PostDetailScreen(postid: message.data['postid']),
        ),
      );
      break;
    case 'active':
      Navigator.of(context).push(
        MaterialPageRoute(
          builder: (_) => const PostDetailScreen(postid: '456'),
        ),
      );
      break;
  }
}

场景覆盖不全
你当前只实现了冷启动场景的处理，应用在后台存活（未划掉被杀）时点击通知，不会触发getInitialMessage，必须监听FirebaseMessaging.onMessageOpenedApp流才能拿到该场景下的消息对象。如果是应用在前台时收到通知，需要额外配置flutter_local_notifications插件展示本地通知，同时注册插件的通知点击回调处理跳转。
Android端配置校验
检查android/app/src/main/AndroidManifest.xml中MainActivity的配置：

确保添加了对应点击action的intent-filter：

<intent-filter>
  <action android:name="FLUTTER_NOTIFICATION_CLICK" />
  <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

如果你使用了flutter_local_notifications插件展示前台通知，必须在初始化插件时配置通知点击的监听，将payload传入统一跳转逻辑，否则前台场景点击通知不会触发FCM自带的回调。

测试方式与发送参数校验

测试冷启动场景时，必须先把应用从最近任务列表完全划掉杀掉，再发送通知点击，否则不会触发getInitialMessage逻辑。
发送通知时不要在notification字段下配置click_action，保持click_action仅存在于data字段中，避免字段被覆盖。
调试时先打印全量message.data内容，如果message本身为null，优先排查初始化时机与后台配置问题，不要直接读取单个字段排查。

iOS端额外配置校验
如果在iOS设备测试：

Xcode中开启Push Notifications能力，同时在Background Modes中勾选Remote notifications选项。
初始化FCM时调用FirebaseMessaging.instance.setForegroundNotificationPresentationOptions(alert: true, badge: true, sound: true)，确保前台通知可以正常展示。
首次启动时正确申请通知权限，确保用户允许了通知权限。

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