IONIC Firebase推送IOS端未送达的排查方法及常见问题咨询

一、调试定位步骤 #

• 首先通过Xcode连接测试iPhone，选择和TestFlight打包一致的Release方案运行应用，查看Xcode控制台日志，重点关注APNs注册结果、Firebase token获取的相关日志，若存在报错信息可直接对应错误根源。
• 查看Firebase Cloud Messaging发送报告的详细错误码：Firebase控制台推送发送记录中，iOS推送会返回明确的错误标识，比如InvalidApnsCredential对应APNs配置错误、DeviceUnregistered对应设备token无效，可直接根据错误码缩小排查范围。
• 绕开Firebase直接测试APNs链路：使用APNs测试工具，使用生产环境配置向目标设备的APNs token发送测试推送，若能收到则问题出在Firebase和APNs的联动配置，若收不到则问题出在应用本身或苹果侧的权限配置。
• 验证权限状态：在iOS系统设置中查看对应应用的通知权限是否正常开启，同时在代码中打印权限请求的返回结果，确认已获取用户的推送授权。

二、常见问题清单 #

• 环境配置不匹配：TestFlight对应的是苹果生产推送环境，若上传到Firebase控制台的是开发环境的APNs证书/密钥，或打包时使用的是开发环境的推送配置，会直接导致推送被APNs拦截。
• Xcode能力配置缺失：项目中未开启Push Notifications能力，或未在Background Modes中勾选Remote notifications选项，导致应用无法完成APNs注册。
• 标识不匹配：Firebase控制台注册的iOS应用Bundle ID与实际打包使用的Bundle ID不一致，或项目中导入的GoogleService-Info.plist不是对应当前Bundle ID的版本。
• 证书/配置文件异常：打包使用的Provisioning Profile未包含推送权限，或苹果开发者账号的推送服务已过期、被禁用。
• 设备token无效：iOS端获取的推送token未正确上报到Firebase，或对应设备已卸载应用、重置系统标识，被Firebase标记为无效设备。
• 推送 payload 格式错误：推送内容不符合APNs规范，缺少必填的aps字段，或字段内容格式非法，被APNs直接丢弃。
• 插件配置异常：capacitor.config.ts中未正确配置iOS推送相关参数，或Capacitor推送插件版本过低，存在已知的iOS兼容问题。
• 用户权限未获取：应用未触发推送权限申请弹窗，或用户首次启动时拒绝了推送权限，导致系统不会向该设备下发通知。

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