声明式 Web Push

所有核心浏览器均可用W3C

声明式 Web Push 让浏览器直接读取标准 JSON 推送消息并显示通知，不必调用 Service Worker。Service Worker 仍可处理消息；如果它没有给出替代通知，浏览器可以显示声明内容作为兜底。

工作原理

Push API 在窗口上暴露 window.pushManager，用于管理窗口作用域的订阅。subscribe() 的选项均可省略，userVisibleOnly 默认为 false，applicationServerKey 默认为 null；用户代理可以要求前者为 true，推送服务也可以要求后者不是 null。

声明式消息顶层的 web_push 值为 8030，并带有 notification 对象。Push API 要求该对象包含字符串类型的 title 与 navigate。用户激活通知时，浏览器打开 navigate 指定的 URL。body、lang、dir、tag、icon 和 actions 等通知选项也可按规范定义的类型加入对象。

警告

窗口作用域管理器的 URL 不使用 HTTPS 时，Push API 让 subscribe() 以 NotAllowedError DOMException 拒绝。载荷不是 JSON、缺少 web_push、其值不等于 8030、notification 不是对象，或者 title、navigate 缺失或不是字符串时，解析器返回失败（PushManager.subscribe()，W3C；Declarative push message parser，W3C）。

支持范围

WebKit 从 iOS 与 iPadOS 18.4 起在主屏幕 Web App 中支持声明式 Web Push，macOS 则从 Safari 18.5 起支持。WebKit 把同一份 JSON 设计成向后兼容的载荷：支持声明式处理的浏览器直接读取它，其余浏览器可由 Service Worker 把 notification 对象交给 showNotification()（Meet Declarative Web Push，WebKit）。

示例

部署时可优先使用窗口作用域订阅，同时保留注册作用域管理器与 push 处理函数作为兜底。

检测窗口作用域的推送管理器

使用声明式订阅路径前，先检查 Notification 与 window.pushManager。兜底分支会取得 Service Worker 注册，并检查它是否有 pushManager。如果没有找到任何一种管理器，则返回 null。

async function getPushManager() {
  if ('Notification' in window && 'pushManager' in window) {
    return window.pushManager;
  }

  if ('serviceWorker' in navigator) {
    const registration = await navigator.serviceWorker.getRegistration();
    if (registration && 'pushManager' in registration) {
      return registration.pushManager;
    }
  }

  return null;
}

把选中的管理器交给应用现有的 subscribe() 流程，取得并保存 PushSubscription。

发送标准 JSON 结构

在应用服务器上创建载荷，再沿现有 Web Push 投递路径发送序列化的 JSON。浏览器会验证 navigate 是字符串，并在创建通知时解析其 URL。用户激活通知时，浏览器会导航到这个先前已经验证的 URL。

const message = {
  web_push: 8030,
  notification: {
    title: '构建完成',
    body: '生产环境构建已可供检查。',
    lang: 'zh-CN',
    dir: 'ltr',
    navigate: 'https://example.com/builds/482',
  },
};

const payload = JSON.stringify(message);

将 payload 发往接收者 PushSubscription 中的 endpoint。浏览器可以显示声明的标题与正文，并在激活时使用 navigate。

在 Service Worker 中处理同一载荷

保留 push 处理函数，让通过 JavaScript 接收消息的浏览器也能显示通知。WebKit 的迁移示例从 notification 取出标题，再把其余成员传给 showNotification()。

self.addEventListener('push', (event) => {
  event.waitUntil((async () => {
    const { notification } = event.data.json();
    const { title, ...options } = notification;
    await self.registration.showNotification(title, options);
  })());
});

支持声明式 Web Push 时，浏览器直接处理标准载荷；否则由该处理函数沿原有 Service Worker 路径显示相同的通知数据。

另请参阅

• Push API: Declarative push message（W3C）
• Meet Declarative Web Push（WebKit）
• Web Push 与 PushManager.subscribe()
• iOS 与 iPadOS 上的 Web Push
• Notifications API

规范

规范	状态
Web Push（网页推送）	W3C
Push API: Declarative push message	W3C 草案

• 图例
• 支持
• 部分支持
• 需开启标志
• 不支持
• 未知

浏览器 / 平台	支持	版本	置信度	来源	备注
Chrome (Desktop)#	支持	42	高	来源	1
Chrome (Android)#	支持	42	高	来源	23
Edge (Desktop)#	支持	17	高	来源	4
Firefox (Desktop)#	支持	44	高	来源	5
Firefox (Android)#	支持	48	高	来源	6
Safari (macOS)#	支持	16	高	来源	7
Safari (iOS)#	支持	16.4	高	来源	8
Samsung Internet#	支持	4.0	高	来源	910
WebView (Android)#	不支持	—	高	来源	11
Safari（iOS） · 声明式 Web Push#	支持	18.4	中	来源	121314

1. 必须传入带 `applicationServerKey` 值的 `options` 参数。
2. 必须传入带 `applicationServerKey` 值的 `options` 参数。
3. 由 browser-compat-data 镜像自 Chrome 的数据推导。
4. 必须传入带 `applicationServerKey` 值的 `options` 参数。
5. 从 Firefox 72 起，只能在响应用户手势（例如 `click` 事件）时调用。
6. 从 Firefox Android 79 起，只能在响应用户手势（例如 `click` 事件）时调用。
7. macOS Ventura 及更高版本支持通知。
8. 添加到主屏幕的 Web 应用支持通知。
9. 必须传入带 `applicationServerKey` 值的 `options` 参数。
10. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
11. browser-compat-data 未记录 WebView Android 的支持。
12. WebKit 的 Safari 18.4 文章写道："Declarative Web Push is now available on iOS and iPadOS 18.4 for web apps added to the Home Screen."（译文：声明式 Web Push 现已在 iOS 与 iPadOS 18.4 上提供给添加到主屏幕的 Web 应用。）文章把声明式 Web Push 描述为不需要 service worker 也能显示的推送通知。
13. browser-compat-data 没有声明式 Web Push 的条目。最接近的键 `api.Window.pushManager` 记录 iOS 版 Safari 18.4 起支持，并标记为实验性。
14. OpenPWA device test, 2026-10-20, iPhone 16 Pro, iOS 18.6.2 (22G100)：普通 Safari 标签页中同样暴露 `window.pushManager`；在 Service Worker 作用域为子路径的主屏应用中，worker 的注册已有订阅，`window.pushManager.getSubscription()` 却返回 `null`，与 WebKit「只有根作用域的 worker 与 window 共享订阅」的说法一致。

生态与商业政策

主体	类型	场景	状态	赞助	备注
Apple Push (APNs)#	delivery_policy	iOS	部分支持	否	iOS 上的 Web Push 要求用户先把应用添加到主屏幕。

源数据: /compatibility/web-push.json · 全球使用占比: 96 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-20 · 置信度: 中 (由来源计算)

在线试用

在 OpenPWA 演示应用中运行此能力： /demo/#push