Firebase Cloud Messaging推送通知偶发图片不显示问题咨询

核心原因 #

• 错误配置smallIcon属性：Android系统要求通知smallIcon必须是本地打包的drawable资源，你的代码中直接将远程图片URL赋值给smallIcon，会导致系统渲染通知时偶发异常，连带大图加载失败。
• FCM字段未按平台规范设置：仅在顶层notification配置imageUrl不符合平台解析规则，Android需要单独在android.notification.image字段传图片地址，iOS需要在apns配置项中单独指定，部分设备解析顶层imageUrl时会出现偶发读取失败。
• 无图片预加载/重试机制：react-native-push-notification没有内置远程图片加载重试逻辑，网络波动时单次请求失败就会直接显示无图，不会自动重试。
• 图片规格不符合全机型要求：除了1MB大小限制外，FCM要求通知图片宽高比为16:9、最大分辨率不超过1024x768，低版本Android系统还不支持webp、动图格式，部分超规格图片即使大小符合也会加载失败。
• 后台进程权限限制：APP被系统限制后台网络、电池优化时，通知触发时无法请求远程图片资源，导致加载失败。

修复方案 #

1. 修正smallIcon配置，替换为本地资源
   提前将通知小图标放到Android项目的drawable目录下，修改前端代码：

   PushNotification.localNotification({
       message: remoteMessage.notification.body,
       title: remoteMessage.notification.title,
       priority: 'high',
       smallIcon: "ic_notification", // 替换为你的本地通知图标资源名
       // 不要重复配置picture和bigPictureUrl，高版本仅保留bigPictureUrl即可
       ...(imageUrl && { bigPictureUrl: imageUrl }),
   });
   

2. 后台调整FCM payload结构，按平台指定图片字段

   exports.notificationWithImg = async (registrationToken, notification) => {
     try {
       const response = await admin.messaging().sendMulticast({
         tokens: registrationToken,
         notification: {
           title: notification.title,
           body: notification.body
         },
         // 单独配置Android平台字段
         android: {
           notification: {
             ...(notification.imageUrl && { image: notification.imageUrl })
           }
         },
         // iOS需要的话补充对应配置
         apns: {
           payload: {
             aps: {
               "mutable-content": 1
             }
           },
           fcm_options: {
             ...(notification.imageUrl && { image: notification.imageUrl })
           }
         }
       });
       // 原有逻辑不变
     } catch (error) {
       // 原有逻辑不变
     }
   };
   

3. 前端增加图片预加载逻辑，避免网络波动影响
   弹出通知前先预下载图片，失败可重试1-2次：

   import { Image } from 'react-native';
   
   // 收到通知后的处理逻辑
   const imageUrl = remoteMessage.notification.android?.imageUrl;
   let loadSuccess = false;
   if (imageUrl) {
     try {
       await Image.prefetch(imageUrl);
       loadSuccess = true;
     } catch (e) {
       // 重试一次
       try {
         await Image.prefetch(imageUrl);
         loadSuccess = true;
       } catch (err) {
         loadSuccess = false;
       }
     }
   }
   // 确认图片加载成功后再弹出通知
   PushNotification.localNotification({
     message: remoteMessage.notification.body,
     title: remoteMessage.notification.title,
     priority: 'high',
     smallIcon: "ic_notification",
     ...(loadSuccess && { bigPictureUrl: imageUrl }),
   });
   

4. 统一推送图片规格：所有通知图片裁剪为16:9比例，分辨率控制在1024*768以内，格式统一用jpg/png，不要用webp、gif等特殊格式。
5. 引导用户开启APP的后台活动权限、关闭电池优化，避免后台时资源被系统限制。

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