React Native iOS端Firebase推送通知无法接收问题排查求助

一、核心配置排查点 #

• Xcode Capabilities 验证
  • 确认Push Notifications开关已开启
  • 确认Background Modes下的Remote notifications选项已勾选
• Firebase 控制台配置检查
  • 上传的APNs认证密钥需与Apple开发者后台的密钥ID、团队ID完全匹配，且对应当前使用的开发/生产环境
  • Firebase项目中iOS应用的Bundle ID必须与Xcode项目的Bundle ID完全一致
• 依赖版本兼容性
  • 确保@react-native-firebase/app与@react-native-firebase/messaging版本匹配，避免跨版本冲突
  • 确认React Native版本与Firebase依赖版本兼容（例如RN 0.7x对应Firebase 18.x及以上版本）

二、AppDelegate 代码校验 #

正确的 Objective-C 实现示例 #

#import <Firebase.h>
#import <UserNotifications/UserNotifications.h>
#import <RNFBApp/RNFBAppModule.h>
#import <RNFBMessaging/RNFBMessagingModule.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // 初始化Firebase
  [FIRApp configure];
  
  // 配置通知中心并请求权限
  UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
  center.delegate = self;
  [center requestAuthorizationWithOptions:(UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge)
                        completionHandler:^(BOOL granted, NSError * _Nullable error) {
                          if (!error && granted) {
                            [application registerForRemoteNotifications];
                          }
                        }];
  
  // 原有项目代码...
  return YES;
}

// 传递设备Token给Firebase
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
  [RNFBMessagingModule didRegisterForRemoteNotificationsWithDeviceToken:deviceToken];
}

// 处理注册失败日志
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
  [RNFBMessagingModule didFailToRegisterForRemoteNotificationsWithError:error];
}

// 前台展示通知
- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {
  completionHandler(UNNotificationPresentationOptionAlert | UNNotificationPresentationOptionSound | UNNotificationPresentationOptionBadge);
}

// 处理通知点击事件
- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void(^)(void))completionHandler {
  [RNFBMessagingModule didReceiveNotificationResponse:response];
  completionHandler();
}

@end

Swift版本需对应调整语法，确保Firebase初始化、权限请求、Token回调逻辑一致。

三、客户端代码实现校验 #

正确的 Messaging 初始化与监听逻辑 #

import messaging from '@react-native-firebase/messaging';

// 请求通知权限并获取Token
const setupPushNotifications = async () => {
  const authStatus = await messaging().requestPermission({
    alert: true,
    badge: true,
    sound: true,
  });

  const isAuthorized = authStatus === messaging.AuthorizationStatus.AUTHORIZED || authStatus === messaging.AuthorizationStatus.PROVISIONAL;
  
  if (isAuthorized) {
    const token = await messaging().getToken();
    if (token) {
      // 将Token上传至你的服务端
      console.log('FCM Token:', token);
    }
  }
};

// 监听前台通知
messaging().onMessage(remoteMessage => {
  console.log('前台收到通知:', remoteMessage);
  // 自定义通知展示逻辑
});

// 监听后台通知点击
messaging().onNotificationOpenedApp(remoteMessage => {
  console.log('点击后台通知进入App:', remoteMessage);
});

// 监听未启动状态下的通知点击
messaging().getInitialNotification().then(remoteMessage => {
  if (remoteMessage) {
    console.log('未启动时点击通知:', remoteMessage);
  }
});

// 在App启动时执行配置
useEffect(() => {
  setupPushNotifications();
}, []);

必须在Info.plist中添加以下字段，否则iOS 10+会拒绝权限请求：

<key>NSUserNotificationUsageDescription</key>
<string>需要推送通知提醒您相关消息</string>
<key>NSRemoteNotificationUsageDescription</key>
<string>需要推送通知提醒您相关消息</string>

四、服务端推送 Payload 校验 #

符合iOS要求的FCM推送Payload格式 #

{
  "to": "DEVICE_FCM_TOKEN",
  "notification": {
    "title": "测试通知",
    "body": "这是一条测试推送",
    "sound": "default"
  },
  "apns": {
    "payload": {
      "aps": {
        "alert": {
          "title": "测试通知",
          "body": "这是一条测试推送"
        },
        "sound": "default",
        "badge": 1
      }
    },
    "headers": {
      "apns-priority": "5" // 后台静默推送用5，即时推送用10
    }
  }
}

注意：仅包含data字段的推送在iOS后台状态下不会主动展示通知，必须包含notification或apns.payload.aps字段；生产环境推送需使用Firebase生产密钥，且App已签名为生产证书。

五、快速排查步骤 #

1. 检查客户端获取的FCM Token是否有效，且已正确上传至服务端
2. 区分开发/生产环境：调试时使用Firebase开发配置，发布时切换为生产配置
3. 查看Xcode控制台日志，确认是否有didFailToRegisterForRemoteNotificationsWithError错误信息
4. 检查Firebase控制台的推送记录，查看是否有推送失败的错误提示
5. 确认iOS设备网络可正常访问FCM服务

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