iOS集成FCM：测试通知正常但服务器推送失效，求排查方向

1. 服务器请求格式问题 #

• 区分通知消息和数据消息：FCM控制台默认发送的是通知消息，iOS会自动弹窗；但如果服务器只发纯数据消息（仅data字段），后台状态下不会主动触发通知，需要客户端在didReceiveRemoteNotification回调里手动处理弹窗逻辑。
• 核对apns字段配置：针对iOS设备，服务器请求必须正确设置apns.payload.aps.alert（包含title和body），如果只传顶层notification字段，要确保格式符合FCM要求，不能缺少核心字段。
• 确认FCM令牌有效性：服务器发送时必须使用设备的FCM注册令牌（不是APNs原生令牌），要保证令牌是客户端最新上报的，没有过期或被注销。

2. APNs授权配置验证 #

• 检查Firebase控制台的APNs凭证：如果用证书，确认证书未过期、包含正确的App Bundle ID；如果用密钥，确保Team ID、Key ID与Apple开发者后台一致，且密钥已开启APNs权限。
• 匹配推送环境：开发环境（Debug包）对应APNs沙箱环境，生产环境（Release包）对应生产环境，Firebase会自动适配，但如果服务器手动指定了APNs环境参数，必须和当前App打包环境一致。

3. 客户端关键配置检查 #

• 确认推送权限已授予：App启动时必须通过UNUserNotificationCenter请求alert、sound等权限，即使控制台能推送，也要保证用户没有禁用App的推送权限。
• 手动处理数据消息：如果服务器发纯数据消息，需在AppDelegate的didReceiveRemoteNotification:fetchCompletionHandler:或UNUserNotificationCenterDelegate的didReceiveNotificationResponse:中实现自定义弹窗逻辑，否则后台不会展示通知。
• 关闭Swizzling后的手动配置：如果禁用了FCM的Swizzling功能，必须手动完成以下操作：
  • 在application:didRegisterForRemoteNotificationsWithDeviceToken:中调用Messaging.messaging().apnsToken = deviceToken
  • 实现messaging:didReceiveRegistrationToken:来获取并更新FCM令牌到你的服务器
  • 正确设置UNUserNotificationCenter的代理对象

4. 消息优先级与请求端点 #

• 设置正确的消息优先级：iOS后台推送需要将FCM请求的priority设为"high"（对应APNs的10级优先级），如果用normal优先级，消息可能被系统延迟或丢弃。
• 验证请求端点与授权：服务器必须使用正确的FCM接口（旧版https://fcm.googleapis.com/fcm/send或HTTP v1接口https://fcm.googleapis.com/v1/projects/{project-id}/messages:send），请求头的Authorization必须是有效的服务器密钥（旧版）或OAuth2令牌（HTTP v1）。

5. 日志与错误排查 #

• 查看Firebase控制台的消息报告：进入云消息传递模块，检查服务器发送的消息状态，查看是否有"未送达"记录及具体错误原因（如InvalidRegistration、MismatchSenderId）。
• 监控Xcode控制台日志：过滤FirebaseMessaging、APNs关键词，排查令牌注册失败、消息接收被拦截的日志信息。
• 检查服务器请求响应：发送推送后查看FCM返回的响应体，根据错误码直接定位问题（比如令牌无效、权限不足）。

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