iOS Firebase推送通知后台模式下后端发送无法接收问题排查
问题核心根因
所有现象的核心矛盾来自你使用的推送载荷结构完全不符合FCM针对iOS端的传输规范,具体拆解:
- 你当前发送的载荷混淆了原生APNs请求结构和FCM中转的请求结构:把本应作为系统通知触发源的展示内容,全部嵌套在了
data自定义字段下,甚至手动把APNs协议内部的aps结构直接塞到了data层级。这种结构的请求被FCM服务端转发到APNs时,只会被识别为纯数据透传消息,不会生成带系统通知展示能力的有效载荷。 - iOS系统对纯数据透传消息的后台接收有严格限制:App在前台活跃时,不管是通知类还是数据类消息都能正常触发回调接收,这也是你前台能收到后端推送的原因;但App退到后台被系统挂起后,纯数据类消息没有系统级的通知载体,既不会在通知中心展示,也没有权限被高优先级唤醒触达App,自然就会出现后台接收失败的现象。
- 之所以Firebase控制台发的通知能正常后台接收,是因为控制台在生成请求时,会自动把你填写的通知内容放到FCM要求的顶级
notification字段,自动生成符合APNs规范的载荷,完全规避了你手写载荷的结构问题;Push Try工具测试失败也是因为你传入的载荷结构本身错误,和工具能力无关。
针对性解决方案
- 修正后端推送的载荷结构,将原来嵌套在
data内的通知展示内容拆分到FCM要求的两个顶级字段:- 顶级
notification字段:承载所有需要系统展示的通知参数(标题、内容、角标、提示音等),FCM会自动根据这个字段生成符合APNs规范的aps结构,不需要你手动写aps相关内容 - 顶级
data字段:承载需要透传给App的自定义业务参数(比如页面跳转路径、业务ID等)
修正后的、可正常在后台接收的标准载荷示例如下:
{ "to": "你的设备FCM Token", "priority": "high", "notification": { "title": "Portugal vs. Denmark", "body": "great match!", "badge": 1, "sound": "default" }, "data": { "route": "match_detail", "match_id": "12345" } } - 顶级
- 注意避坑:不要手动将
aps结构写入data字段,aps是APNs协议层的内部结构,由FCM服务端自动生成,手动写入的aps只会被当成普通自定义数据透传,不会被iOS系统识别为可展示的通知内容。 - 确认Xcode Capabilities中的配置项:已开启
Push Notifications能力,同时在Background Modes中勾选Remote notifications选项,保证系统允许高优先级推送唤醒后台App。
内容的提问来源于stack exchange,提问作者V-Dev
相关产品推荐
相关产品推荐

