iOS 16.4+ PWA应用原生推送通知完整实现指南

通过 iOS 主屏幕原生安装的 PWA，无法直接调用 Notification.requestPermission() 来触发系统级的通知授权弹窗。正确的做法是借助 WebKit 消息桥接机制，向宿主 Safari 或 iOS 运行环境发起权限请求。本文将详细解析这一实现路径及必须留意的关键要点。

先说一个核心要点：对于已经“添加到主屏幕”的原生安装版 PWA 应用，直接执行 Notification.requestPermission() 来唤起系统的通知授权弹窗，这条路是行不通的。正确的实现方案，必须通过 WebKit 的消息桥接机制，向宿主 Safari 或 iOS 底层环境发起权限申请。接下来，我们逐步拆解正确的实现方法以及那些需要特别关注的细节。

自 iOS 16.4 起，苹果为“原生安装的 PWA”（即用户通过 Safari“添加到主屏幕”功能完成安装的应用）提供了有限的推送通知支持。但请注意，这一能力并非基于标准的 Web Push API 来实现，也不依赖 Service Worker 的 pushManager。它的底层原理，实际上是利用 WebKit 提供的一个专用消息通道（webkit.messageHandlers）与 iOS 系统层进行通信交互。

✅ 正确触发通知权限弹窗的代码实现

你需要在 PWA 的前端 JavaScript 代码中，主动检测并调用 iOS 特有的权限请求接口。代码实现逻辑很清晰，如下所示：

// 检测是否运行在支持 iOS PWA 推送的环境（iOS 16.4+ + 原生安装）
if (
  window.webkit &&
  window.webkit.messageHandlers &&
  window.webkit.messageHandlers['push-permission-request']
) {
  // 标记环境支持 iOS 推送能力
  (window as any).iOSPushCapability = true;
  // 发起权限请求（这将触发系统级的通知授权弹窗）
  window.webkit.messageHandlers['push-permission-request'].postMessage('push-permission-request');
} else {
  console.warn('iOS PWA push permission is not a vailable in this context.');
}

⚠️ 注意：该逻辑仅在用户将 PWA 添加到主屏幕并以全屏模式启动时有效。如果你在普通的 Safari 标签页中调用它，不会报错，只会静默失败，无法产生任何效果。

? 关键前提条件（缺一不可）

想要让这套机制正常运行，以下前提条件必须全部满足：

• ✅ 应用必须通过 Safari 浏览器访问，并且用户需要依次点击“共享 → 添加到主屏幕”完成安装流程；
• ✅ iOS 系统版本需 ≥ 16.4（iOS 17.4+ 的稳定性更优，推荐优先采用）；
• ✅ 在 Apple Developer Account 中，对应的 App ID 必须开启 "Push Notifications" 功能——请务必注意，即使你并未使用 APNs 后端，这个开关也必须提前打开；
• ✅ 网站必须通过 HTTPS 提供服务，并且 manifest.json 中需包含有效的 display: "standalone" 或 "minimal-ui" 配置；
• ❌ 切勿调用 Notification.requestPermission() —— 在 iOS PWA 环境下，该调用始终会返回 'denied' 或干脆没有任何响应。

? 权限状态与后续处理

目前 iOS 不提供 JS API 来查询推送权限的实际状态（例如授权或拒绝），也无法直接获取设备令牌。一旦用户点击了“允许”，系统会自动将设备注册到 Apple 的推送服务（APNs）。后续你需要配合后端集成 APNs 来发送通知（可以使用通用的 Push Certificate 或 Token-based Authentication）。

在实际开发中，建议在调用 postMessage 后，通过 UI 引导用户理解操作的意图。例如，可以提示用户：“正在请求通知权限，请在弹出的窗口中点击‘允许’”，并设置合理的超时提示，避免用户长时间等待。

? 总结

总的来说，iOS PWA 的通知机制本质上并非“Web Push”，而是一个由 WebKit 封装的、面向原生系统的快捷入口。它绕过了传统 Web Push 的复杂流程，但也带来了平台层面的强约束。作为开发者，可能需要放弃“跨平台统一逻辑”的既有设想。针对 iOS 平台，你需要单独实现这个桥接调用，并严格满足相应的配置与运行时条件。只有把这些细节都落实到位，那个熟悉的 iOS 蓝色授权弹窗（如图）才能真正弹出来。