RNFirebase中isHeadless始终为undefined的iOS后台消息处理问题

问题概述 #

我正在给React Native移动端应用开发FCM通知功能，要求设备收到FCM通知时执行特定操作，重点是应用在后台状态下收到通知也要触发该操作。但在iOS平台实现无头（headless）注入时碰到两个问题：

1. 设备能正常接收通知（后台/退出状态都可以），但setMessageBackgroundHandler不是每次都执行，需要搞懂它的工作机制。
2. AppWithHeadless组件里打印的isHeadless始终是undefined，而且后续不再输出，哪怕setBackgroundMessageHandler正常执行。

我还在学习React Native，求指导！

相关代码 #

AppWithHeadless组件代码 #

function AppWithHeadless({ isHeadless }) {
  console.log("isHeadless: ", isHeadless); // 这里打印undefined
  if (isHeadless) {
    // iOS后台启动应用时，忽略渲染
    return null;
  }

  return (
        <App />
  );
}

AppDelegate.mm摘要 #

#import <Firebase.h>
#import "RNFBMessagingModule.h"
#import "AppDelegate.h"

.
.
.

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  RCTAppSetupPrepareApp(application);

  RCTBridge *bridge = [self.reactDelegate createBridgeWithDelegate:self launchOptions:launchOptions];

#if RCT_NEW_ARCH_ENABLED
  _contextContainer = std::make_shared<facebook::react::ContextContainer const>();
  _reactNativeConfig = std::make_shared<facebook::react::EmptyReactNativeConfig const>();
  _contextContainer->insert("ReactNativeConfig", _reactNativeConfig);
  _bridgeAdapter = [[RCTSurfacePresenterBridgeAdapter alloc] initWithBridge:bridge contextContainer:_contextContainer];
  bridge.surfacePresenter = _bridgeAdapter.surfacePresenter;
#endif

  if ([FIRApp defaultApp] == nil) {
    [FIRApp configure];
  }

  NSDictionary *initProps = [self prepareInitialProps];
  NSDictionary *appProperties = [RNFBMessagingModule addCustomPropsToUserProps:nil withLaunchOptions:launchOptions];
  NSMutableDictionary *initialProps = [initProps mutableCopy];
  [initialProps addEntriesFromDictionary:appProperties];

.
.
.

- (NSDictionary *)prepareInitialProps
{
  NSMutableDictionary *initProps = [NSMutableDictionary new];

#ifdef RCT_NEW_ARCH_ENABLED
  initProps[kRNConcurrentRoot] = @([self concurrentRootEnabled]);
#endif

  return initProps;
}

.
.
.

@end

问题排查与解决方案 #

1. isHeadless为undefined的原因 #

isHeadless是通过React Native初始props传递的，但你的代码里没有把合并后的initialProps传给根组件。在didFinishLaunchingWithOptions方法末尾，需要确保把initialProps传入React Native根视图：

修改AppDelegate.mm的didFinishLaunchingWithOptions方法，找到创建根视图的代码，补充initialProperties参数：

// 替换成你实际的应用模块名
UIViewController *rootViewController = [self.reactDelegate createRootViewController];
rootViewController.view = [self.reactDelegate createRootViewWithBridge:bridge moduleName:@"YourAppName" initialProperties:initialProps];

RNFBMessagingModule的addCustomPropsToUserProps方法会自动添加isHeadless到props中，只要正确传递合并后的props到根组件，就能拿到该值。

2. setMessageBackgroundHandler不总是执行的原因 #

iOS上FCM后台消息触发有严格限制：

• 通知payload必须包含content-available: 1（在FCM的apns.payload.aps字段设置），否则系统不会唤醒应用执行后台处理。
• 应用必须开启后台刷新权限：在Xcode项目设置 -> Signing & Capabilities -> Background Modes中勾选"Remote notifications"。
• 后台处理代码必须在30秒内完成，否则系统会终止进程。
• 如果应用被用户强制退出（划掉），iOS不会唤醒应用执行后台消息处理，除非用户重新打开应用。

正确的FCM通知payload示例：

{
  "to": "DEVICE_TOKEN",
  "content_available": true,
  "apns": {
    "payload": {
      "aps": {
        "content-available": 1
      }
    }
  },
  "data": {
    "key": "value"
  }
}

额外注意事项 #

• 测试后台消息时，不能用Xcode直接运行应用，需将应用安装到设备后断开调试，再发送通知测试（调试状态下后台行为会有差异）。
• 确保setMessageBackgroundHandler在应用启动时就注册，比如在index.js最顶部：

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

messaging().setBackgroundMessageHandler(async remoteMessage => {
  console.log('后台收到消息:', remoteMessage);
  // 执行你的操作
});

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