Apple Push Notification service 证书有效期为一年，必须每年在 Apple Developer Portal 中续期，以免中断设备通信。如果你负责一个 Capacitor 应用，凭证过期或被吊销可能导致通知停止，即使应用本身看起来运行正常。
故障往往在最糟糕的时刻暴露。版本刚发布，营销活动已排期，通知投递却突然中断。应用服务器可能仍在接收任务，但 APNs 可能在消息到达设备前就拒绝 TLS 连接。实际的解决方案不只是再创建一张证书。你需要弄清系统使用的是哪种 APNs 凭证，保管好私钥，规划续期，并将适合的工作负载迁移到基于 Token 的认证。
目录
为什么推送通知会失效
APNs 位于您的服务端与用户的 Apple 设备之间。您的服务器向 Apple 验证身份并提交通知，然后依靠 APNs 将其路由到已注册的应用和设备。如果凭证已过期、被撤销、关联到错误的身份或安装有误，请求可能在投递开始前就失败。
Apple 表示，APNs 会维护已撤销证书列表，并拒绝来自使用该列表中证书的服务器的 TLS 连接。因此，证书维护是投递的必要条件，而不只是管理偏好。在 Apple 拒绝提供方连接的同时，服务器可能仍在本地继续处理通知任务。
区分应用推送与 MDM 推送
第一个诊断问题很简单： 您正尝试操作哪项服务？
| 凭证路径 | 功能说明 | 通常负责人 |
|---|---|---|
| App 推送 | 向终端用户设备发送提醒和其他应用通知 | 移动端或后端工程 |
| MDM 推送 | 让设备管理平台能够与受管理的 Apple 设备通信 | IT、终端或企业移动管理 |
这些凭据不可互换。MDM 推送凭据过期时，MDM 平台可能会与已注册设备失联；而 App Push 凭据无效时，应用后端则可能无法送达通知。把两者都当成“Apple 推送证书”问题，会把排查引向错误方向。
对于 Capacitor 和 Ionic 团队，面向用户的提醒通常走 App 推送。应用仍需具备 Push Notifications 能力、正确的签名、设备注册，以及能通过相应 APNs 环境发送通知的后端。如果你的团队也在发布 OTA Web 资源，请把该发布工作流与推送认证分开。 Capacitor 通知插件文档 介绍了应用端集成，而 APNs 凭据应放在服务商配置中。
从拒绝原因入手，而非 UI
在修改通知文案或重新构建应用之前，先检查服务商服务器返回的 APNs 响应。然后验证 bundle identifier、凭据身份、环境和证书状态。通知权限问题会影响用户看到提醒，但解释不了 APNs 的 TLS 拒绝。
如果故障是在发布后出现的，请对比新 build 与上一个 build 的签名和 entitlements。如果应用没有改动也出现故障，优先检查证书是否过期、是否被吊销、信任库变更以及部署密钥。如需更全面的实施路径，请参阅这份指南： Expo 推送通知配置.
创建并下载您的 APNs 证书
如果证书是为错误的 App ID 签发的，或者私钥仍留在另一台 Mac 上，推送上线可能在发送第一条通知之前就失败。Apple 的工作流分为两部分：你的机器会创建一个 证书签名请求，或 CSR，Apple 会为选定的 App ID 对其进行签名。CSR 并非服务器凭证，而是将签发的证书与本地生成的私钥关联起来。
准备 App ID
登录 Apple Developer 门户并打开 Certificates, Identifiers & Profiles。选择 标识符，选择应用的 bundle identifier，并打开其配置。在签发任何内容之前，请确认 推送通知 已启用。
APNs 凭证与应用程序身份绑定。请勿选择名称相似但不同的 bundle identifier。请独立配置每个单独的应用程序，并签发对应的凭证。
在将保留密钥的 Mac 上，打开 钥匙串访问 并创建 CSR，或使用贵组织批准的证书工具。请确保请求文件和私钥由同一受控主体保管。如果由另一位管理员创建 CSR，该管理员可能持有后续生成可用服务器 bundle 所需的私钥。
签发已签名证书
在 证书，选择 Apple Push Notification service 证书选项。选择 App ID，上传 CSR，然后提交请求。下载 Apple 签发的证书。
在拥有私钥的 Mac 上双击下载的文件。它应该会安装到 钥匙串访问，你可以在其中验证证书及其匹配的私钥。缺少该私钥导入的证书无法提供后端所需的完整凭据。
使用能记录应用标识、环境、所有者和过期详情的命名规范。将原始证书、CSR 所有权信息和门户账号详情存入团队的凭据管理系统。开发者的 Downloads 文件夹或个人笔记本电脑不能当作运维备份。
该证书只覆盖投递流程的一部分。App 必须注册远程通知，服务器必须保存生成的 device token，推送服务商必须使用匹配的 topic 和环境发送。请把这些依赖项放在同一个 runbook 中。客户端配置请参阅 Capacitor 通知集成指南。请将此证书视为受管理的凭据，而不是一次性下载的文件，因为后续的导出、token 迁移、续期和恢复都取决于是否清楚谁掌控其密钥。
将证书导出为私钥
下载的 Apple 证书不能直接用于 Node.js 服务或托管推送服务商。服务器需要证书及其对应的私钥，通常打包为 PKCS#12 .p12 文件.
打开 钥匙串访问 在安装了该证书的 Mac 上。搜索 APNs 证书，展开或检查它，找到身份和过期信息相匹配的私钥。同时选中证书和私钥，然后使用导出操作将其保存为 .p12 文件。
部署前验证 bundle
为导出文件设置一个强密码。该密码用于保护 bundle 中的私钥，因此请勿将其放入代码仓库、工单、聊天消息或构建日志中。通过密钥管理系统上传该文件和密码，然后仅授予发送通知的服务访问权限。
实战规则： 一套
.p12没有对应私钥的文件不是完整的提供商凭据。
在生产环境使用前，请在受控环境中测试 bundle。确认您的后端能够加载该文件，建立 APNs 连接，并在 Apple 拒绝请求时返回结构化错误。如果像 Capgo 这样的提供商需要 iOS 推送凭据，请上传 .p12 及其密码，通过指定的密钥配置进行管理，而不是将这两个值嵌入应用 code 中。
这种格式还暴露了传统工作流的弱点。您必须保留原始私钥，重复手动导出，保护文件，并在续期时替换部署密钥。运营多个应用的团队很容易搞混哪个 bundle 属于哪个 App ID。
使用 在 CI/CD pipeline 中实施安全的密钥管理 以控制谁可以读取或替换凭据。保留上传和轮换的审计日志，但切勿记录私钥或 .p12 密码。
对于新的后端工作，请评估证书认证是否仍然合适。现有集成可能需要 .p12，但令牌认证通常可以从提供商连接中移除年度证书替换。这并没有消除凭据治理，而是改变了您需要保护和轮换的内容。
迁移至新的 Token 身份验证方式
Apple 已将 APNs 认证转向 provider token，通常称为 p8 工作流。不再使用证书和私钥来维持长期 TLS 身份，而是由你的 provider 使用 Apple Push Notification service Authentication Key 对认证 token 进行签名。
在 Apple Developer 门户的 Certificates, Identifiers & Profiles下创建密钥，然后打开 密钥 并注册 APNs 认证密钥。下载 .p8 文件，并在你的 secret store 中记录对应的 Key ID 和 Team ID。将下载的文件视为高价值签名密钥。
有计划地进行迁移
不要靠替换未测试环境中的文件来切换生产流量。请在保留现有证书路径的同时搭建 token 认证，验证沙盒和生产环境中的行为，并比较 APNs 响应。然后在受控部署期间更改提供商配置。
迁移移除了发送路径中的证书续期和 Keychain 导出步骤，但团队仍需明确责任归属模型。明确谁可以创建、撤销和部署密钥。限制对签发提供商 token 的后端服务的访问，并确保在当前密钥不可用前已有紧急替换流程。
对于 Capacitor 应用，客户端仍需正确的通知注册和 entitlements。迁移主要改变的是 服务器到 APNs 的认证，而不是设备 token 注册 code。你的后端必须继续将 token 关联到正确的应用和环境。
了解何时仍需使用证书
一些企业级工具和成熟的集成仍会暴露基于证书的配置。在接收系统支持 p8 且团队已测试完整链路之前，不要强行迁移到 p8。过渡期间要保护好旧凭据，但如果 token 认证适用，不要对它产生新的依赖。
如果你需要了解相关的应用流程，请查看 Ionic 与 Capacitor 的 Firebase 推送通知。Firebase 可以提供应用交付层，但 Apple 凭据、entitlements、注册以及 APNs 响应仍需要进行精细配置。
续期与管理证书生命周期
从创建 APNs 证书的那天起，就应将其视为具有时效性的生产环境依赖。Apple 表示这些证书的有效期为 创建之日起一年 且必须在过期前续期以维持设备通信。Apple 还警告称，如果未能及时续期，可能需要用户重新向 APNs 注册 iOS、iPadOS 和 Mac 设备，并可能导致服务中断。请参阅 Apple 的 推送通知证书续期文档.
续期流程如下：
- 生成新的 CSR： 通过你批准的工作流创建请求，并妥善保存相关的密钥材料。
- 使用原来的 Apple ID： 使用创建现有证书时的同一 Apple ID 登录。
- 选择即将过期的证书： 选择前请核对 App ID、Subject DN、UID 和过期信息是否匹配 续期.
- 上传 CSR： 在 Apple Push Certificates Portal 中提交新请求。
- 下载并重新安装： 获取续期后的证书
.pem，将其安装到私钥所在的位置，并导出替换证书.p12（如果您的服务商要求）。 - 部署并测试： 更新服务器密钥，发送受控通知，并检查 APNs 响应。
对比不同供应商的格式
| 要求 | 证书工作流 | Token 工作流 |
|---|---|---|
| 主密钥 | 证书及私钥 | .p8 认证密钥 |
| 续期问题 | 证书过期需定期更换 | 无需每年更换证书 |
| 部署工作 | 安装、配对、导出并上传 | 存储签名密钥并配置 Token 生成 |
| 主要故障风险 | 证书错误、私钥缺失、过期或被吊销 | 认证密钥丢失、泄露或被吊销 |
Apple 的证书生态系统也要求定期进行信任链维护。Apple 宣布沙盒环境的 APNs 服务器证书更新将于 2025 年 1 月 20 日 ，生产环境则于 2025年2月24日，要求信任存储包含 SHA-2 根证书 USERTrust RSA 认证机构 证书。阅读 Apple APNs 服务器证书公告 并将信任库所有权纳入你的平台检查清单。
使用共享的续期日历、指定负责人和部署 runbook。 Capgo 证书管理文档 可以与该 runbook 配合使用，适合在移动发布流程中管理 iOS 交付凭证的团队。
故障排除与凭据丢失处理
棘手的事故并不总是过期警告。它可能发生在某个早晨：创建证书的管理员已经离职，私钥只存在于一台旧 Mac 上，或者证书在尝试清理时被撤销。标准续期流程依赖原始 Apple ID 和正确的证书身份，因此访问权限和来源与文件本身同样重要。
先对故障分类：
- 证书已过期： 通过原始账号生成替代证书，用匹配的私钥重新安装，更新提供商并测试投递。如果设备通信已经中断，请遵循 Apple 的恢复指南，不要以为在服务端更换证书就能立即恢复所有设备。
- 证书已撤销： 不要再把旧凭证当作可恢复的。Apple 会拒绝来自使用已撤销证书的服务器的 TLS 连接，因此请创建有效的替代证书，并从活跃部署中移除已撤销的密钥。查清是谁撤销的，以及其他系统是否复制了同一凭证。
- 丢失
.p12密码： 没有可用密码的证书文件可能在操作上不可用。请获取已批准的备份或签发替代证书，而不是削弱生产环境的密钥控制。 - 丢失私钥： 重新下载公钥证书无法重建私钥。请在受控机器上创建新的 CSR 并签发替代凭证。
- 丢失 Apple ID 访问权限： 确认组织能否通过其身份和部署流程恢复账户。Apple 将相关门户创建的 APNs 证书支持请求引导至 部署计划支持.
恢复需要身份验证，而不仅仅是文件名。 在事故发生前，记录 Apple ID 所有者、App ID、证书身份、私钥位置、提供商配置和替换流程。
构建运维安全网
将证书和 .p8 密钥存放在共享的、访问受控的保险库中。将 .p12 密码与文件分开存储，限制生产环境访问权限，并记录用于续期的确切门户账户。您的 CI/CD 系统应在部署时注入密钥，并运行健康检查，在用户报告缺失警报之前检测身份验证失败。
在平台允许时，受控替换期间保留旧凭据可用，但不要无限期让过时密钥保持有效。在生产使用的同一后端路径中测试替换凭据，包括提供商环境、bundle identifier 和 device-token 存储。
故障已经发生时，保留 APNs 响应体和时间戳，找出第一个被拒绝的请求，并对比事故前后的部署密钥。不要用无效凭据无限重试。先解决身份或认证问题，再向已知测试设备发送一条简短的验证通知。
Capgo 可以将 iOS 推送凭据作为 Capacitor 通知工作流的一部分进行存储和配置，而您的团队仍需负责 Apple 账号访问、密钥保管及续期决策。请访问 Capgo 以了解其移动端交付工具如何配合您的 APNs 凭据生命周期和发布流程。
常见问题
当 App 转移到另一个 Apple 账号时，推送通知的客户端 SSL 证书会随之转移吗？
不会。Apple 的 App 转移文档指出，推送通知的客户端 SSL 证书不会被转移。转移完成后，接收方团队必须创建新的 APNs 证书，或者更好的做法是使用其自有账号的基于 token 的 .p8 密钥，然后更新推送提供商。请参阅 迁移到基于 token 的认证.
