苹果推送 p8 证书制作与配置说明本文单独说明 iOS 端 APNs 的 p8 证书制作与配置流程供当前项目接入 uni-push 2.0 时使用。如果你要看当前项目完整的推送总流程、云函数参数和厂商字段映射请结合 uniCloud-alipay/uni-push-2.0-vendor-guide.md 一起看。1. 这份文档解决什么问题苹果离线推送最终走的是 APNs。在 uni-push 2.0 场景下如果 iOS 端要收到系统通知栏消息就需要把苹果推送证书配置到 DCloud 开发者中心。当前更推荐使用 p8 方式而不是旧的 p12 方式主要原因是- p8 是苹果官方推荐的 Auth Key 方式- 不需要像 p12 那样频繁维护证书更新- 一个 p8 Key 可以用于同一 Apple Developer 团队下的多个 App2. 制作前先准备好这些信息制作和配置 p8 证书前至少要准备以下内容- Apple Developer 账号- 已创建好的 iOS App ID- 该 App ID 已开启 Push Notifications 能力- 当前应用最终要使用的 Bundle ID后面实际填写到 DCloud 开发者中心时会用到这 4 类关键信息- Key ID- Team ID- Bundle ID- AuthKey_XXXXXXXXXX.p8 文件注意- p8 文件只允许下载一次- 如果下载后丢失不能重新下载原文件只能删除旧 Key 后重新创建3. 先在苹果后台开启推送能力如果 App ID 还没开通推送能力先做这一步。操作路径1. 登录 Apple Developer 后台https://developer.apple.com/account/resources/certificates/list2. 进入 Certificates, IDs Profiles3. 打开 Identifiers4. 找到当前 App 对应的 App ID5. 确认已启用 Push Notifications如果这里没开后面即使把 p8 上传到 DCloudiOS 离线推送通常也还是不通。4. 在苹果后台创建 p8 证书操作路径1. 登录 Apple Developer 后台https://developer.apple.com/account/resources/certificates/list2. 进入 Certificates, IDs Profiles3. 打开 Keys4. 点击右上角 5. 输入一个便于识别的名称例如 UniPush_APNs6. 勾选 Apple Push Notifications service (APNs)7. 继续并完成注册创建完成后要马上保存两样东西- 页面上的 Key ID- 下载得到的 .p8 文件然后再去 Apple Developer 的账号信息页确认- Team ID到这里DCloud 配置所需的核心材料就齐了。5. 在 DCloud 开发者中心配置 p8相关入口- 厂商配置文档https://uniapp.dcloud.net.cn/unipush_vendor_config.html- 厂商推送配置入口https://dev.dcloud.net.cn/pages/app/push2/thirdparty配置时重点填写- Key ID- Team ID- Bundle ID- 上传 .p8 文件这里最关键的是 Bundle ID 必须完全一致至少要和以下位置保持一致- Apple Developer 后台里的 App ID- DCloud 开发者中心里填写的 iOS 包名- HBuilderX 云打包实际使用的 iOS Bundle ID只要这几个地方有一个不一致就很容易出现“接口调用成功但 iOS 收不到离线推送”的情况。6. 当前项目接入时要重点核对的地方结合当前项目建议重点确认下面几项- manifest.json:89 已启用 iOS 侧 uni-push 模块- HBuilderX 云打包里的 iOS 包名要和苹果后台 App ID 保持一致- DCloud 开发者中心里配置的 Bundle ID 要和打包配置一致- 证书配置改完后要重新云打包旧包通常不会自动带上新配置这份文档只负责说明苹果 p8 证书制作与配置。当前项目的推送发送逻辑、CID 绑定、厂商参数映射仍然以 uniCloud-alipay/uni-push-2.0-vendor-guide.md 和 uniCloud-alipay/cloudfunctions/push/index.js 为准。7. 怎么验证 p8 配置有没有生效建议按下面顺序验证1. 重新云打包 iOS 安装包并安装到真机2. 首次启动时允许通知权限3. 确认客户端能正常获取当前设备 cid4. 到 DCloud 开发者中心状态查询里检查该 cid 是否已具备推送基础能力5. 用单个 cid 发一条测试通知6. 分别验证前台在线和离线场景状态查询入口- https://dev.dcloud.net.cn/pages/app/push2/index建议重点看两个结果- 是否能查到当前设备对应状态- iOS 真机在退到后台或杀掉进程后是否还能收到系统通知栏消息注意- iOS 推送必须用真机测试- 模拟器不能作为离线推送验证依据8. 最常见的几个问题8.1 Bundle ID 不一致这是最常见的问题之一。只要苹果后台、DCloud 后台、云打包配置三处不一致就容易导致推送失败。8.2 只配了证书但没有重新云打包厂商推送相关配置改完后必须重新云打包App 端才能带上最新配置。8.3 p8 文件丢了p8 文件不能重复下载。如果已经丢失只能废弃旧 Key重新创建一个新的 APNs Auth Key然后重新在 DCloud 后台配置。8.4 App 没有通知权限即使服务端配置都正确如果 iPhone 上没有授权通知权限系统通知也不会正常展示。8.5 只验证了在线消息没有验证离线通知在线能收到不代表 APNs 离线链路已经打通。必须额外验证- App 退到后台时是否能收到- App 被杀掉后是否还能收到系统通知栏消息8.6 打 p8 证书后是否需要重新做描述文件大多数情况下不需要因为创建了 p8 文件就重新做描述文件。原因是- p8 是苹果 APNs Auth Key主要用于服务端推送鉴权- 描述文件 Provisioning Profile 主要和应用签名、设备安装、能力声明有关- 只要当前 App ID 之前已经开启了 Push Notifications通常补配 p8 不会要求你重做描述文件但以下情况建议重新生成或重新下载描述文件后再打包- 之前 App ID 没有开启 Push Notifications现在才刚开启- Bundle ID 发生过变更- 你同时调整了签名能力或相关 entitlements- 当前打包流程本身就是手动签名并且依赖新的 profile实操建议- 如果只是新增或更换 p8通常不必重做描述文件- 但无论是否重做描述文件DCloud 后台改完 iOS 推送配置后都要重新云打包9. 建议的落地顺序如果你准备开始做当前项目的 iOS 推送配置建议按这个顺序执行1. 确认 Apple Developer App ID 已开启 Push Notifications2. 创建并下载 p8 文件同时记录 Key ID3. 记录 Apple 账号对应的 Team ID4. 在 DCloud 开发者中心填写 iOS 推送配置5. 重新云打包 iOS 安装包6. 真机安装并获取 cid7. 用单个 cid 发送测试通知8. 再回到当前项目的总流程文档继续联调后端推送链路