Aura Web Push

VAPID 演示 · Chrome / Firefox / Edge · iOS PWA 16.4+

状态

Service Worker
检测中…
通知权限
—
推送订阅
未订阅
服务器
—

订阅

需 HTTPS 或 localhost；iOS 须先「添加到主屏幕」再从主屏幕图标打开。

发送测试


      

      

    


    

      

      

      

      

        
Web Push 架构概览

        
Aura 演示项目 aura-pwa 展示标准 Web Push + VAPID 流程，适用于自有后端向浏览器（含 iOS PWA）下发通知。

        
角色

        

          
组件职责

          
            
浏览器 / PWA注册 Service Worker，向推送服务订阅，展示通知

            
应用服务器保存 PushSubscription，用 VAPID 私钥签名后调用推送服务

            
推送服务各浏览器厂商 endpoint（FCM、APNs 等），转发到设备

            
VAPID证明应用服务器有权向该订阅发送消息

          
        

        
订阅流程

        
    
          
  1. 用户打开 PWA / 页面
    2. 
          
  2. 前端 register('/sw.js') 注册 Service Worker
    3. 
          
  3. GET /api/vapid-public-key 获取公钥
    4. 
          
  4. pushManager.subscribe({ applicationServerKey }) 向浏览器推送服务订阅
    5. 
          
  5. POST /api/subscribe 将 PushSubscription 存入服务器
    6. 
        

        
订阅对象包含 endpoint 与 keys（p256dh、auth），需原样存库。

        
推送流程

        
    
          
  1. 服务器 web-push.sendNotification(subscription, payload)
    2. 
          
  2. HTTPS 请求推送服务（带 VAPID 签名）
    3. 
          
  3. Service Worker 收到 push 事件
    4. 
          
  4. showNotification() 展示系统通知；点击时在 notificationclick 中打开页面
    5. 
        

        
VAPID 密钥

        
    
          
  • 公钥：下发给前端，参与 PushManager.subscribe
    • 
          
  • 私钥：仅保存在服务器，通过 web-push.setVapidDetails 使用
    • 
          
  • subject：mailto: 或 https: URL，联系运营方
    • 
        

        
演示环境执行 pnpm run vapid 生成；生产环境每个应用/环境应使用独立密钥对并安全存储。

        
与 Aura 业务的关系

        
本仓库仅为技术验证 Demo。产品化时需：将订阅与用户/设备 ID 绑定；推送前做权限与偏好校验；统一 payload 协议（标题、正文、深链等）。

      


      

        
运行 aura-pwa 演示

        
代码路径：aura-pwa/（与 aura-docs 同级）。

        
前置条件

        
  • Node.js ≥ 18
  • pnpm

        
步骤

        
cd aura-pwa
pnpm install
pnpm run vapid
pnpm run icons
pnpm start

        
浏览器访问：http://localhost:3847（端口占用时可 PORT=3848 pnpm start）。

        
验证清单

        
    
          
  1. 「状态」中 Service Worker 为 activated，服务器为「在线」
    2. 
          
  2. 点击 订阅推送，通知权限为 granted
    3. 
          
  3. 向所有订阅发送 后出现系统通知
    4. 
          
  4. data/subscriptions.json 中出现带 endpoint 的 JSON
    5. 
        

        
常用命令

        

          
命令说明

          
            
pnpm run dev监听 server/index.js 变更

            
pnpm run vapid生成或查看 VAPID 密钥

            
pnpm run icons生成占位 PWA 图标

          
        

        
远程 / 手机调试

        
手机无法直接访问本机 localhost，请用 HTTPS 隧道：

        
ngrok http 3847

        
在真机 Safari/Chrome 中打开 ngrok 提供的 https:// 地址后再订阅与推送。

        
故障排查

        

          
现象可能原因

          
            
无法获取 VAPID 公钥未运行 pnpm run vapid 或缺少 .env

            
订阅无反应非安全上下文（需 HTTPS 或 localhost）

            
推送失败 / 0 条未订阅或订阅已失效，请重新订阅

            
端口 EADDRINUSElsof -ti :3847 | xargs kill -9 或换端口

            
iOS 无推送未从主屏幕打开 PWA，或系统 < 16.4

          
        

      


      

        
iOS Safari PWA 与 Web Push

        
Apple 从 iOS / iPadOS 16.4 起，对已安装到主屏幕的 Web App 提供 Web Push（W3C Push API + Service Worker 通知）。

        
必须满足的条件

        
    
          
  1. 系统版本 iOS / iPadOS ≥ 16.4
    2. 
          
  2. Safari 打开站点 → 分享 → 添加到主屏幕
    3. 
          
  3. 必须从主屏幕图标进入（standalone），非普通 Safari 标签
    4. 
          
  4. 站点为 HTTPS（真机可用 ngrok；localhost 仅本机 Mac）
    5. 
          
  5. Notification.requestPermission() 为 granted，且系统设置中允许该 Web App 通知
    6. 
          
  6. userVisibleOnly: true（本演示已配置）
    7. 
        

        
推荐 meta 与 manifest

        
本页 index.html 已包含 apple-mobile-web-app-* 与 apple-touch-icon；manifest.json 使用 display: standalone 及 192/512 图标。

        
真机测试步骤

        
    
          
  1. ngrok 暴露本服务为 HTTPS
    2. 
          
  2. iPhone Safari 打开该 URL → 添加到主屏幕
    3. 
          
  3. 从主屏幕打开 → 切到「演示」Tab → 订阅推送 → 发送测试
    4. 
          
  4. 锁屏或后台验证通知
    5. 
        

        
常见限制

        
    
          
  • 普通 Safari 标签页内无法获得与 PWA 相同的推送能力
    • 
          
  • iOS endpoint 与桌面 Chrome 不同，服务端仍通过 web-push 统一发送
    • 
          
  • 通知文案与频率需符合平台政策
    • 
        

        
参考

        
      


      

        
API 与环境变量

        
环境变量

        

          
变量说明

          
            
PORTHTTP 端口，默认 3847

            
HOST监听地址，默认 0.0.0.0

            
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEYWeb Push 密钥对

            
VAPID_SUBJECTmailto:you@example.com 或 HTTPS URL

          
        

        
HTTP API

        

          
方法路径说明

          
            
GET/api/health健康检查与订阅数量

            
GET/api/vapid-public-key前端订阅用公钥

            
GET/api/subscriptions订阅列表摘要

            
POST/api/subscribe保存 PushSubscription JSON

            
POST/api/unsubscribebody: { endpoint }

            
POST/api/pushbody: { title, body, url?, endpoint? }

          
        

        
项目结构

        
aura-pwa/
├── server/index.js
├── public/          # PWA 前端 + 本文档 Tab
├── scripts/
├── data/            # subscriptions.json
└── .env

        
生产注意

        
    
          
  • 替换 public/icons 为正式 192/512 图标
    • 
          
  • 使用稳定 HTTPS 域名与真实 VAPID_SUBJECT
    • 
          
  • 处理 410/404 失效订阅（演示推送失败时会清理）
    • 
        

        
完整 Markdown 文档见 monorepo：aura-docs/docs/mobile-app/pwa-push/