Firebase Cloud Message推送带图片通知无法正常生效问题排查求助

故障原因排查及修复方案 #

1. 通知图片参数名错误 #

你当前使用的imageURL是错误的字段名，Firebase Cloud Messaging legacy API（sendToDevice对应的接口）中，通知负载的图片字段应为image，修改调用代码中的字段名即可解决大部分场景的不显示问题。

2. 缺少富媒体通知必要配置 #

• iOS端必须在通知推送参数中开启mutable-content配置，否则系统会拦截富媒体内容加载，无法展示图片
• 安卓端需要确保目标设备的FCM SDK版本不低于20.0.0，否则不支持通知图片自动加载

3. 图片资源不符合要求 #

通知图片需要满足以下条件才能正常展示：

• 必须是公网可直接访问的HTTPS链接，不能设置鉴权、3xx重定向规则
• 图片大小建议控制在1MB以内，格式为JPG/PNG/WebP等通用格式
• 域名不能被Firebase或目标设备的网络拦截

修复后的代码示例 #

调用通知代码修改

notification(user.fcmToken, {
    notification: {
      title: title,
      body: message,
      image: "https://.../avatar/avatar1.png", // 替换为正确的image字段
    },
  },
  // 新增富媒体通知必要配置
  {
    apns: {
      payload: {
        aps: {
          "mutable-content": 1
        }
      }
    }
  }
);

可选优化：替换废弃API

sendToDevice是Firebase官方已标记为废弃的legacy API，建议替换为最新的send方法，兼容性和功能支持更好，示例如下：

// 修改后的通知实现函数
exports.notification = async (registrationToken, message = message_notification) => {
  try {
    const response = await admin.messaging().send({
      token: registrationToken,
      ...message
    });
    console.log('Notification response:', JSON.stringify(response));
    return {
      statusMessage: 'SUCCESS',
      message: 'Sent Successfully',
      statusCode: 200,
    };
  } catch (error) {
    console.log("Error", error)
    return {
      statusMessage: 'ERROR',
      message: error.message || 'SERVER ERROR',
      statusCode: 400,
    }
  }
};

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