Frontend Academy · 课时

推送通知

请求权限，使用 Push API 订阅推送，在 Service Worker 中接收消息，并使用 showNotification 显示通知。

推送通知 是 CoddyKit 上的免费 Frontend Academy 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Frontend Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Frontend Academy 课程共包含 4 节课。

推送通知为何重要

应用未打开时，推送通知可以重新吸引用户——例如消息提醒、新闻更新和弃购提醒。它由服务工作线程提供支持，因此即使页面已关闭也能工作。

Push API 与通知 API

两个浏览器 API 协同工作。Push API 通过推送订阅接收服务器发送的消息。Notifications API 将消息显示给用户。

请求权限

订阅前请先向用户请求 permission——只能在明确的用户操作（例如点击按钮）响应中执行，不要在页面加载时执行。

async function enableNotifications() {
  const permission = await Notification.requestPermission();
  if (permission !== 'granted') {
    alert('Notifications denied');
    return;
  }
  // proceed to subscribe...
}

推送订阅

通过活动的服务工作线程注册信息进行订阅。服务器的 VAPID 公钥用于验证该订阅。

async function subscribeToPush() {
  const reg = await navigator.serviceWorker.ready;
  const sub = await reg.pushManager.subscribe({
    userVisibleOnly: true, // required: every push must show a notification
    applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY)
  });
  // Send sub to your server:
  await fetch('/api/save-subscription', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(sub)
  });
}

VAPID 密钥

VAPID（自愿应用服务器标识）密钥用于向推送服务（FCM、Mozilla 等）标识您的服务器。请生成一次，并将私钥存储在服务器上。

# Generate VAPID keys with web-push CLI:
npx web-push generate-vapid-keys

# Output:
# Public Key: BJ...
# Private Key: ka...

服务器端推送

使用 web-push npm 库向已存储的订阅发送推送。

import webpush from 'web-push';

webpush.setVapidDetails(
  'mailto:you@example.com',
  process.env.VAPID_PUBLIC,
  process.env.VAPID_PRIVATE
);

await webpush.sendNotification(savedSubscription, JSON.stringify({
  title: 'New message',
  body: 'Alice sent you a message',
  url: '/inbox/123'
}));

在服务工作线程中处理推送

SW 接收推送事件并显示通知。

// sw.js
self.addEventListener('push', (event) => {
  const data = event.data ? event.data.json() : {};
  event.waitUntil(
    self.registration.showNotification(data.title || 'Notification', {
      body: data.body,
      icon: '/icons/192.png',
      badge: '/icons/badge.png',
      data: { url: data.url }
    })
  );
});

通知点击处理程序

用户点击通知时，打开应用或将应用置于焦点。

self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  const url = event.notification.data.url || '/';
  event.waitUntil(
    clients.matchAll({ type: 'window' }).then(clientList => {
      for (const client of clientList) {
        if (client.url.endsWith(url) && 'focus' in client) return client.focus();
      }
      return clients.openWindow(url);
    })
  );
});

通知选项

可以自定义：图标、徽章（小型通知区域图标）、图像（大图）、操作（按钮）、标签（使用相同标签替换较早的通知）、requireInteraction（一直保留到用户关闭）以及静默模式。

self.registration.showNotification('Message', {
  body: 'Alice sent you a photo',
  icon: '/icons/192.png',
  image: '/images/alice-photo.jpg',
  actions: [
    { action: 'view', title: 'View' },
    { action: 'reply', title: 'Reply' }
  ],
  tag: 'message-from-alice', // replaces earlier 'message-from-alice'
  requireInteraction: false
});

取消订阅

请允许用户选择退出——调用 pushSubscription.unsubscribe()，并从服务器移除该订阅。

async function disablePush() {
  const reg = await navigator.serviceWorker.ready;
  const sub = await reg.pushManager.getSubscription();
  if (sub) {
    await sub.unsubscribe();
    await fetch('/api/delete-subscription', {
      method: 'POST',
      body: JSON.stringify({ endpoint: sub.endpoint })
    });
  }
}

iOS 支持

iOS 16.4 及更高版本支持 Web Push，但仅限安装到主屏幕的 PWA。iOS 16.4 之前的设备，以及 iPhone 上 Safari 中的网页，完全不支持 Web Push。

最佳实践

1）仅在明确的用户操作后请求权限。2）发送有意义且不过于频繁的通知。3）推送事件发生时务必显示通知（如果不这样做，浏览器可能会撤销权限）。4）提供简单易用的取消订阅方式。5）使用全部 3 种推送服务进行测试（FCM、Mozilla、WindowsPush）。

常见陷阱

以下情况会导致推送无提示地失败：userVisibleOnly 为 false（Chrome 要求为 true）、VAPID 密钥不匹配、订阅已过期（请重新订阅），以及推送事件发生时未显示通知（浏览器会撤销权限）。

快速检查

为什么每条推送消息都必须产生可见通知（并设置 userVisibleOnly: true）？

回顾：推送通知

只能通过用户操作请求权限。使用 VAPID 公钥，通过 reg.pushManager.subscribe 进行订阅。服务器使用 web-push 库发送推送。SW 的推送事件会调用 showNotification。notificationclick 会打开应用或将应用置于焦点。可以自定义图标、徽章、图像、操作和标签。务必显示通知（必须使用 userVisibleOnly: true）。iOS 16.4 及更高版本支持此功能，但仅限已安装为 PWA 的情况。

常见问题解答

「推送通知」课时是免费的吗？

是的 — 「推送通知」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Frontend Academy 课程的其余内容，请升级到 CoddyKit PRO。 Frontend Academy 课程共包含 4 节课。

「推送通知」这节课中我会学到什么？

请求权限，使用 Push API 订阅推送，在 Service Worker 中接收消息，并使用 showNotification 显示通知。你通过在浏览器中直接运行的动手代码来练习 Frontend Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Frontend Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Frontend Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「推送通知」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Frontend Academy 课中编写并运行代码吗？

能。每节 Frontend Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Frontend Academy