Service Worker 是推送通知的必经通道，必须在 HTTPS 或 localhost 下注册成功才能启用 PushManager；Notification.requestPermission() 需用户手势触发，且需在授权后调用 pushManager.subscribe()，其 applicationServerKey 必须为 Uint8Array 格式的 VAPID 公钥。
Service Worker 是推送通知的必经通道
没有注册成功的 Service Worker，PushManager 就无法工作——这不是代码问题，而是浏览器强制限制。它必须在 HTTPS（或 localhost）环境下运行，HTTP 站点即使调用了 navigator.serviceWorker.register('/sw.js')，后续的 navigator.serviceWorker.ready 也会一直 pending，所有推送逻辑卡死。
常见错误现象：
-
Failed to register a ServiceWorker：脚本 404 或响应头Content-Type不是text/javascript -
navigator.serviceWorker.ready永远不 resolve：页面用 HTTP 访问、部署在非受信任的自签名证书下、或注册脚本被延迟到window.onload之后执行
实操建议：
- 开发阶段只用
http://localhost或http://127.0.0.1，别碰http://example.com - 上线前必须使用由可信 CA 签发的 HTTPS 证书（Let’s Encrypt 可行，自签名不行）
- 注册脚本放在
<head>底部或DOMContentLoaded回调里，越早执行越稳
Notification.requestPermission() 必须由用户主动触发
Chrome、Edge、Firefox 等现代浏览器已禁用静默授权，Notification.requestPermission() 若不在用户手势（如 click、tap）回调中调用，会直接抛出 DOMException: Permission denied，且不会弹出授权弹窗。
立即学习“前端免费学习笔记（深入）”；
容易踩的坑：
- 在页面加载时自动调用，或在定时器、
setTimeout中触发 - 把权限请求和
pushManager.subscribe()写在同一个then链里，没等用户点“允许”就继续执行订阅
正确做法：
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 绑定到按钮点击：
button.addEventListener('click', async () => { await Notification.requestPermission(); ... }) - 权限返回
'granted'后，再获取navigator.serviceWorker.ready并调用pushManager.subscribe() - 别跳过
userVisibleOnly: true—— 缺少这个参数会报错，这是 Web Push 协议硬性要求
pushManager.subscribe() 依赖 VAPID 公钥且必须转成 Uint8Array
pushManager.subscribe() 的 applicationServerKey 参数不能直接传 Base64 字符串，必须是 Uint8Array 类型，否则会失败并提示 InvalidAccessError 或静默无响应。
为什么必须转换？
- VAPID 协议要求服务端用私钥签名，浏览器用公钥验签，而 Web Crypto API 只接受二进制格式的密钥
- Base64 编码的公钥含填充字符（
=）和 URL 安全变体（-、_），需先标准化再解码
常用转换函数示例：
function urlBase64ToUint8Array(base64String) {
const padding = '='.repeat((4 - base64String.length % 4) % 4);
const base64 = (base64String + padding)
.replace(/-/g, '+')
.replace(/_/g, '/');
const rawData = window.atob(base64);
const outputArray = new Uint8Array(rawData.length);
for (let i = 0; i < rawData.length; ++i) {
outputArray[i] = rawData.charCodeAt(i);
}
return outputArray;
}
注意：urlBase64ToUint8Array('your-vapid-public-key') 必须和后端生成 VAPID 密钥对时用的公钥完全一致，前后端密钥不匹配会导致后续推送 400 或 410 错误。
后端推送失败常因 Authorization 和 Encryption 头缺失或格式错误
前端成功拿到 subscription.endpoint，不代表后端能顺利发消息。Web Push 协议强制要求每个 POST 请求携带两个关键头：
-
Authorization：格式为VAPID v=...; k=...，含签名和公钥 -
Encryption：含keyid、salt、dh等加密参数，由前端订阅时生成的keys.p256dh和keys.auth推导而来
典型错误：
- 只传
Authorization，漏掉Encryption→ 返回 400 Bad Request - 用错前端 subscription.keys 中的
p256dh或auth→ 加密失败，服务端返回 400 或 410 Gone（表示 endpoint 已失效） - 后端未按 RFC 8291 实现 payload 加密，直接发明文 → 浏览器拒绝接收
最易被忽略的一点：订阅对象中的 endpoint 是有时效性的。用户清除浏览器数据、重装系统、或长期不访问站点，都可能导致 endpoint 失效。后端必须在发送前校验其有效性，并在收到 410 响应后及时清理数据库记录。
