iOS 11设备使用Firebase无法接收自定义通知的排查方法

开发者阿泽

2026-5-15

我来帮你一步步排查这个自定义推送通知的问题——毕竟iOS 11在APNs和Firebase的适配细节上确实有几个容易踩的坑。咱们先分Firebase控制台配置和iOS开发端实现两部分来排查，这样能快速定位问题：

一、先排查Firebase控制台的自定义通知配置

确认自定义参数的位置：发通知时，自定义键值对必须放在**「Additional options」->「Custom data」**模块里，别误写到通知标题/内容的输入框里——这是最常见的错误，控制台不会把标题栏的内容当作自定义数据转发给APNs。
检查参数格式：iOS 11的APNs对自定义数据的兼容性有限，必须用纯字符串键值对，不能用嵌套对象、数组或者数字类型（比如直接填123不行，要写成"123"）。Firebase转发复杂格式数据时，很可能会被APNs过滤掉。
验证静默推送配置：如果你的自定义通知是后台静默推送（不弹通知栏，只给App传数据），一定要勾选**「Background notification」**选项，同时确保在控制台的「Notification settings」里开启了后台推送权限——iOS 11对静默推送的校验非常严格，缺了这个配置根本收不到。

二、再排查iOS开发端的实现问题

检查推送回调方法的正确性：iOS 11主要依赖两个回调处理推送，你要确保这两个方法都正确提取了自定义数据：

// 处理前台收到通知、用户点击通知的场景
- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void(^)(void))completionHandler {
    NSDictionary *userInfo = response.notification.request.content.userInfo;
    // 提取自定义字段，替换成你的键名
    NSString *customData = userInfo[@"your_custom_key"];
    NSLog(@"收到自定义数据：%@", customData);
    completionHandler();
}

// 处理后台推送的场景
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    NSString *customData = userInfo[@"your_custom_key"];
    NSLog(@"后台收到自定义数据：%@", customData);
    completionHandler(UIBackgroundFetchResultNewData);
}

Swift项目对应方法是userNotificationCenter(_:didReceive:withCompletionHandler:)和application(_:didReceiveRemoteNotification:fetchCompletionHandler:)，别写错了。

确认推送权限与后台模式：iOS 11需要明确请求alert、badge、sound权限，同时要在Xcode的「Signing & Capabilities」里开启「Background Modes」下的「Remote notifications」选项。你可以在didFinishLaunchingWithOptions里检查权限请求代码：

UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
[center requestAuthorizationWithOptions:(UNAuthorizationOptionAlert | UNAuthorizationOptionBadge | UNAuthorizationOptionSound) completionHandler:^(BOOL granted, NSError * _Nullable error) {
    if (granted) {
        [[UIApplication sharedApplication] registerForRemoteNotifications];
    }
}];

用Xcode调试日志：连接设备打开Xcode控制台，发送自定义通知后，查看userInfo的输出。如果能看到你的自定义键，说明推送已经到了App，只是你没处理；如果userInfo里没有自定义字段，那大概率是控制台配置或者APNs转发的问题。
检查payload大小：iOS 11的APNs限制推送payload最大为4KB，如果你的自定义数据太大（比如包含长文本、图片链接），APNs会直接丢弃这条推送，建议精简数据后再测试。

三、快速定位问题的小技巧

用FCM API替代控制台测试：写个简单的curl命令调用FCM API发送自定义通知，能快速区分是控制台还是App的问题：

curl -X POST -H "Authorization: key=你的服务器密钥" -H "Content-Type: application/json" -d '{
  "to": "你的设备Token",
  "notification": {
    "title": "测试自定义通知",
    "body": "测试内容"
  },
  "data": {
    "custom_key": "custom_value"
  }
}' https://fcm.googleapis.com/fcm/send

如果API能收到自定义数据，那就是控制台的配置问题；如果API也收不到，那肯定是iOS端的代码或权限问题。

查看Firebase通知报告：在控制台「Notifications」->「Reporting」里，查看自定义通知的「Delivered」状态。如果显示已送达但App没收到，就是iOS端的问题；如果显示未送达，可能是设备Token失效或者FCM到APNs的转发异常。

按照这个步骤排查，应该能很快找到问题所在——iOS 11的推送逻辑和高版本略有不同，很多时候都是细节没注意到。

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