Node.js端通过FCM发送通知后Android客户端无法接收问题求助

我帮你梳理下这个场景下最常见的几个排查方向，一步步来定位问题：

1. 先确认设备令牌（Token）的有效性 #

• 首先要保证服务端message里的to字段对应的令牌，是客户端当前真实注册的有效令牌。客户端的FCM令牌会因为卸载重装、系统更新、应用清除数据等情况失效，你可以在客户端注册FCM时打印令牌，和服务端用的做严格对比，别出现拼写错误、多余空格这类低级问题。
• 如果服务端回调返回的response里有InvalidRegistration或NotRegistered错误，那百分百是令牌的问题，得让客户端重新获取并更新到服务端。

2. 检查消息Payload的格式是否合规 #

FCM对通知和数据消息的格式有明确要求，你的message结构可能有问题：

• 如果是要系统自动展示的通知消息，必须包含notification字段：

  var message = {
    to: "你的设备令牌",
    notification: {
      title: "新通知",
      body: "这是一条测试通知内容"
    }
  };
  

• 如果是需要客户端自己处理的数据消息，要把内容放在data字段里：

  var message = {
    to: "你的设备令牌",
    data: {
      orderId: "12345",
      type: "payment_success"
    }
  };
  

• 注意：如果同时包含notification和data，后台时系统自动弹通知，前台需要客户端监听onMessageReceived处理；如果只有data，无论前后台都得客户端手动处理展示。

3. 验证fcm-node的发送逻辑是否正确 #

别只看服务端打印的“发送成功”，一定要监听发送回调，看返回的详细结果：

fcm.send(message, function(err, response){
  if (err) {
    console.log("发送失败：", err);
  } else {
    console.log("发送响应：", response);
    // 重点看response.results里的状态，如果有error字段，直接对应具体问题
  }
});

有时候服务端返回的“成功”只是请求发送到了FCM服务器，但FCM服务器无法推送到设备，这时候results里会给出具体错误原因。

4. 客户端的FCM配置和权限是否到位 #

• 确认Android客户端已经正确集成FCM：有没有放对google-services.json，Manifest里有没有配置自定义的FirebaseMessagingService子类，重写onMessageReceived方法（前台接收消息必须靠这个）。
• 针对Android 13及以上版本，必须动态申请POST_NOTIFICATIONS权限，不然系统会拦截通知。
• 检查应用有没有被系统后台杀死：很多国产厂商的后台管控很严，比如小米、华为，需要把应用加入“后台白名单”或者“自启动权限”，不然FCM推送无法到达。

5. 考虑迁移到官方的firebase-admin SDK #

fcm-node已经很久没维护了，兼容性可能有问题，官方推荐用firebase-admin SDK，稳定性更好，迁移也简单：

const admin = require('firebase-admin');
const serviceAccount = require('./myapplication3-efc5b-firebase-adminsdk-haq21-361858e343.json');

admin.initializeApp({
  credential: admin.credential.cert(serviceAccount)
});

const message = {
  token: "你的设备令牌",
  notification: {
    title: "测试通知",
    body: "来自firebase-admin的推送"
  }
};

admin.messaging().send(message)
  .then((response) => {
    console.log('推送成功：', response);
  })
  .catch((error) => {
    console.log('推送失败：', error);
  });

6. 去Firebase控制台看详细日志 #

登录Firebase控制台，进入Cloud Messaging模块，查看发送记录和错误统计，那里会有更直观的失败原因分析，比如令牌无效、设备离线、配额不足等。

按上面的步骤逐一排查，应该能快速定位到问题~

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