web-pwa

web-pwa

用途

此技能通过管理 service worker、缓存、清单、离线功能、后台同步和推送通知，帮助构建渐进式 Web 应用（PWA）。重点是让 Web 应用像原生应用一样可安装、可靠且引人入胜。

适用场景

开发需要离线访问功能的 Web 应用（例如新闻阅读器或电商网站）、需要推送通知的应用（例如聊天应用），或通过后台同步更新数据来提升用户体验时，都可以使用此技能。在用户期待移动或桌面浏览器具备类似应用的行为时，也可以应用此技能。

主要功能

• Service Worker：使用 Cache API 拦截网络请求并缓存响应（例如，caches.open('my-cache')）。
• 清单：在 JSON 文件中定义应用元数据（例如，{ "name": "My PWA", "start_url": "/" }），以便安装。
• 离线支持：通过 service worker 和 IndexedDB，让应用在没有网络时也能运行。
• 后台同步：使用 Background Sync API 将任务加入队列，以便联网后执行（例如，registration.sync.register('my-sync')）。
• 推送通知：通过 Push API 和 Service Worker API 处理订阅与消息（例如，使用 subscription.endpoint 与服务端通信）。

使用模式

要实现 PWA，首先创建 service worker 文件（例如，sw.js），并在主脚本中注册。要缓存离线内容，请使用 Cache API 存储资源。注册前务必检查是否支持 service worker。集成 Web 应用清单，以便显示安装提示。在浏览器开发者工具的 Application 标签页中测试相关模式。

常用命令/API

• 注册 service worker：在 JavaScript 文件中使用 if ('serviceWorker' in navigator) { navigator.serviceWorker.register('/sw.js'); }。
• 缓存资源：在 sw.js 中添加 event.respondWith(caches.match(event.request).then(response => response || fetch(event.request))); 来处理请求。
• 添加到主屏幕：确保 manifest.json 中包含 "display": "standalone"，并从根目录提供该文件。
• 处理推送通知：使用 registration.pushManager.subscribe({ userVisibleOnly: true }) 进行订阅，并通过 https://yourserver.com/push 这类服务端端点发送（需要使用 $VAPID_PUBLIC_KEY 进行身份验证）。
• 后台同步：使用 navigator.serviceWorker.ready.then(reg => reg.sync.register('sync-tag')) 注册；使用 workbox-cli build 等命令行工具进行打包（例如，npx workbox generateSW workbox-config.js）。 清单的配置格式：使用类似 { "short_name": "App", "icons": [{ "src": "icon.png", "sizes": "192x192" }] } 的 JSON 对象。

集成说明

在现有 Web 项目中添加 service worker 脚本和清单文件，即可集成此技能。要实现推送通知，请使用 Web Push 库搭建服务端，并使用 $VAPID_PRIVATE_KEY 等环境变量进行签名。如果使用框架，可通过 useEffect(() => { if ('serviceWorker' in navigator) navigator.serviceWorker.register(); }, []); 在 React 中导入。缓存可与 Fetch API 配合使用；service worker 需要 HTTPS。为避免冲突，请在注册前检查是否已有 worker。

错误处理

注册 service worker 时，使用 .then(() => console.log('Registered')).catch(err => console.error('Registration failed:', err)) 捕获错误。对于缓存操作，请处理 Promise 拒绝（例如，caches.open('cache-name').then(cache => cache.addAll(['/'])).catch(err => console.error(err))）。如果推送订阅失败，请检查用户权限，并先使用 Notification.requestPermission()。对于后台同步，请在 service worker 中监听 sync 事件，并通过重试或使用 event.tag 记录日志来处理失败。使用浏览器特定的错误代码（例如安全错误的 DOMException），并在应用中设置全局错误处理程序。

具体用法示例

1. 基本 PWA 设置：创建服务工作线程以缓存静态资源。在 index.js 中：if ('serviceWorker' in navigator) { navigator.serviceWorker.register('/sw.js').then(reg => console.log('SW registered')); }。在 sw.js 中：self.addEventListener('install', event => event.waitUntil(caches.open('static').then(cache => cache.add('/'))));。这样即可离线加载主页。
2. 集成推送通知：订阅用户并处理消息。在应用中：registration.pushManager.subscribe().then(sub => fetch('/subscribe', { method: 'POST', body: JSON.stringify(sub) }));。在服务端，使用类似 POST /subscribe 的端点和 $VAPID_PUBLIC_KEY，通过 Push API 发送通知。

图谱关系

• 相关集群：web-dev（例如，与 web-frontend、web-backend 等技能共享依赖项）。
• 通过标签关联：pwa（关联到 mobile-app）、service-worker（关联到 web-performance）、offline（关联到 data-sync）、web（关联到 full-stack-dev）。
• 依赖项：需要 Web API；可与 Workbox 等工具集成以生成服务工作线程。