使用Firebase发送主题通知后设备无法接收，请求排查

问题背景 #

我有一台移动设备，通过FirebaseMessaging.instance.subscribeToTopic("newTopic")订阅了FCM主题。使用OAuth 2.0 Playground获取访问令牌后，发送以下POST请求返回200 OK状态码，但订阅该主题的设备未收到通知：

curl -X POST -k -H 'Authorization: Bearer access_token_goes_here' -H 'Content-Type: application/json' -i 'https://fcm.googleapis.com/v1/projects/projectId/messages:send' --data '{
  "message":{
    "topic" : "newTopic",
    "notification" : {
      "body" : "This is a Firebase Cloud Messaging Topic Message!",
      "title" : "FCM Message"
      }
   }
}'

我通过以下代码监听前台通知以确认接收情况，但未捕获到任何消息：

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
      print('Got a message whilst in the foreground!');
      print('Message data: ${message.data}');

      if (message.notification != null) {
        print('Message also contained a notification: ${message.notification}');
      }
    });

排查与解决步骤 #

1. 验证设备的FCM基础连通性 #

• 调用FirebaseMessaging.instance.getToken()获取当前设备的FCM令牌，直接在Firebase控制台的「Cloud Messaging」模块中，使用该令牌发送单设备测试通知，确认设备能否正常接收。如果单设备通知也收不到，优先排查设备端的FCM配置问题（如google-services.json/GoogleService-Info.plist是否正确、通知权限是否开启）。
• 调用FirebaseMessaging.instance.getTopicSubscriptions()，确认设备确实成功订阅了newTopic主题——订阅操作可能因网络波动或权限问题静默失败，无异常抛出。

2. 检查OAuth 2.0令牌的权限范围 #

• 使用OAuth 2.0 Playground获取令牌时，必须勾选https://www.googleapis.com/auth/firebase.messaging权限。若缺少该权限，即使请求返回200 OK，FCM服务会静默拒绝消息下发。
• 可解码JWT令牌（通过本地工具或离线解码方式），查看scope字段是否包含上述权限。

3. 优化FCM V1 API请求格式 #

• 仅包含notification字段的消息，在Android前台不会自动弹出通知，需依赖onMessage监听；iOS则需确保已完成推送权限申请（UNUserNotificationCenter请求授权）。
• 建议在请求中添加data字段，即使通知未触发弹窗，也能通过onMessage的message.data打印确认消息是否到达：

  {
    "message":{
      "topic" : "newTopic",
      "notification" : {
        "body" : "This is a Firebase Cloud Messaging Topic Message!",
        "title" : "FCM Message"
      },
      "data": {
        "test_key": "test_value"
      }
    }
  }
  

4. 核对Firebase项目配置一致性 #

• 确认CURL请求中的projectId与设备端连接的Firebase项目ID完全一致。
• 检查Android的google-services.json和iOS的GoogleService-Info.plist，确保项目ID、API密钥等核心字段与Firebase控制台的配置匹配。

5. 排查设备端系统限制 #

• Android：检查App是否开启通知权限，同时注意部分厂商的省电/后台限制（如小米、华为的应用后台清理策略），需将App加入系统白名单。
• iOS：确认已调用UNUserNotificationCenter.current().requestAuthorization申请通知权限，且用户已授权；同时确保FirebaseMessaging.onMessage的监听代码在App启动时（如initState）正确注册。

6. 查看FCM官方日志 #

• 登录Firebase控制台，进入「Cloud Messaging」→「报告」→「消息分析」，查看发送记录的状态细节，若存在“已发送但未送达”的条目，日志会标注具体失败原因。
• 设备端日志：Android查看Logcat中FirebaseMessaging相关输出，iOS查看Xcode控制台的FCM日志，定位是否有消息接收时的报错信息。

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