使用Firebase Admin SDK发送带图片推送通知时图片无法显示问题

算力阿峰

2026-9-27

问题说明

通过firebase admin sdk发送推送通知时，通知内图片无法正常展示。已验证notification配置的imageUrl字段符合官方规范，代码可成功推送通知，但终端设备接收后无图片展示。
你使用的示例代码如下：

const admin = require('firebase-admin');
const app = admin.initializeApp({...}); // authenticated with credentials json file

await app.messaging().sendMulticast({
  notification: {
    title: "hello User",
    body: "This is a push notification with an image",
    imageUrl: "https://example.com/myPublicImage.png",
  },
  tokens: ["device_token_1", "device_token_2","..."]
});

解决方案

你可以按照以下优先级逐一排查问题：

检查图片资源本身是否符合要求
- 图片地址必须为HTTPS协议，HTTP地址会被大部分系统的安全策略拦截，无法加载
- 图片必须是公网可直接访问的资源，不能有跳转、登录鉴权、反爬限制，示例中的example.com域名下的图片为占位资源，需要替换为你自己真实托管的、开了公共读权限的图片，建议测试时优先托管在公开的云存储桶中验证
- 图片格式和大小需符合平台要求：安卓端要求图片为JPG/PNG格式，尺寸不超过4096*4096，大小不超过1MB；iOS端支持JPG/PNG/GIF格式，大小不超过10MB
补全多平台专属推送配置
仅在顶层notification字段配置imageUrl无法兼容所有设备，需要分别补充安卓、iOS的专属图片配置，修改后的代码参考：

const admin = require('firebase-admin');
const app = admin.initializeApp({...}); // 已通过凭据文件完成鉴权

await app.messaging().sendMulticast({
  notification: {
    title: "您好用户",
    body: "这是一条带图片的推送通知",
    imageUrl: "https://你的真实可公开访问的图片地址.png",
  },
  // 安卓专属配置
  android: {
    notification: {
      imageUrl: "https://你的真实可公开访问的图片地址.png"
    }
  },
  // iOS专属配置
  apns: {
    payload: {
      aps: {
        'mutable-content': 1 // 必须开启，允许iOS修改通知内容加载图片
      }
    },
    fcm_options: {
      image: "https://你的真实可公开访问的图片地址.png"
    }
  },
  tokens: ["device_token_1", "device_token_2","..."]
});

检查客户端配置
- 安卓端：确保App已完全开启通知权限，部分国产安卓系统需要额外开启通知横幅、大图样式展示权限；集成的firebase messaging SDK需升级到最新稳定版，避免旧版本不支持大图通知
- iOS端：必须实现通知扩展服务（Notification Service Extension），用来下载并渲染通知附带的图片，同时确认App已开启通知横幅、提醒权限，且后台刷新权限正常开启
测试环境验证
不要在模拟器上测试通知图片展示功能，必须使用真机测试，测试时确保设备网络正常，弱网环境下部分系统会默认不加载通知图片资源

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