SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场pwa-development

pwa-development

前端与建站

查看项目

更新于 10-15 12:26

技能介绍

用途

PWA Development 用于为 React 和 Svelte 应用实现渐进式 Web 应用（PWA）功能，包括 Service Worker、缓存策略、离线支持和安装提示。该技能应在用户要求“make a PWA”“add offline support”等场景时使用。

核心原则：当离线行为是事后才考虑时，PWA 就会失败。PWA 不是“给现有应用加一个 Service Worker”，而是关于数据流、缓存和连接失败的根本性架构决策。

何时使用

  • 为 Web 应用添加 PWA 能力
  • 实现离线支持
  • 创建 Service Worker 缓存策略
  • 调试 PWA 安装问题
  • 处理 iOS 特有的 PWA 怪癖

何时不使用

  • 构建后端 API
  • 处理需求/设计（先使用那些技能）
  • 需要复杂的离线优先架构（先设计）

诊断状态

技能将 PWA 实现划分为多个诊断状态，每个状态包含症状与干预措施：

  • P0：无 PWA 设置。症状为没有 manifest.json、没有 Service Worker、仅在线。干预：运行 scripts/manifest-generator.ts 创建 manifest；在 HTML head 中添加 <link rel="manifest">；用 scripts/sw-scaffolder.ts 生成最小 SW。
  • P1：仅有基础 Manifest。症状为 Manifest 存在但缺少 SW，离线时出错。关键问题：哪些内容必须离线可用？哪些应始终保持新鲜（network-first）？干预：使用 scripts/cache-strategy-advisor.ts；实现 app shell 模式；添加离线回退页面。
  • P2：缓存问题。症状为内容陈旧、缓存行为异常。干预：用 scripts/pwa-audit.ts 审计；使用 data/caching-strategies.json 将资源映射到策略；添加缓存过期与清理。
  • P3：更新问题。症状为用户停留在旧版本、需要多次刷新。干预：适当实现 skipWaiting/clients.claim；添加更新通知 UI（assets/update-prompt.tsx）；正确处理“waiting”状态。
  • P4：离线数据缺口。症状为离线时用户操作丢失、没有同步指示器。干预：使用 IndexedDB 实现离线存储；添加 Background Sync API；创建同步状态 UI。
  • P5：iOS 问题。症状为在 Android 上正常，在 iOS 上出错。干预：查看 data/ios-quirks.json；添加 apple-mobile-web-app meta 标签；优雅处理存储驱逐。
  • P6：生产就绪。指标：Lighthouse PWA 100、可离线工作、更新干净。

缓存策略

  • Cache First：用于静态资源、字体。行为：从缓存提供，后台更新。
  • Network First：用于 API 数据、用户内容。行为：先尝试网络，失败回退缓存。
  • Stale While Revalidate：用于半静态内容。行为：提供陈旧内容，为下次更新缓存。
  • Network Only：用于认证、实时数据。行为：始终走网络，不缓存。

可用脚本

  • manifest-generator.ts：生成 manifest.json
  • sw-scaffolder.ts：生成 Service Worker
  • cache-strategy-advisor.ts：推荐缓存策略
  • pwa-audit.ts：验证 PWA 配置

反模式

  • 全部缓存（The Everything Cache）：预缓存每个资源，导致初始下载量巨大。修复：只预缓存关键 app shell，运行时缓存内容。
  • 不朽缓存（The Immortal Cache）：缓存永不过期，内容永远陈旧。修复：缓存版本化，激活时删除旧缓存，设置最大年龄。
  • 静默更新（The Silent Update）：强制更新而不通知。修复：通知用户，让其选择何时刷新。
  • iOS 事后考虑（The iOS Afterthought）：为 Chrome 构建，最后才测试 iOS。修复：尽早测试 iOS，接受 iOS 限制。

框架快速参考

  • React + Vite：npm i -D vite-plugin-pwa
  • SvelteKit：npm i -D @vite-pwa/sveltekit
  • Next.js：npm i next-pwa

配置参见 data/framework-patterns.json。

调试清单

  • DevTools > Application > Manifest：是否有效？
  • DevTools > Application > Service Workers：是否已注册？
  • DevTools > Application > Cache Storage：缓存了什么？
  • DevTools > Network > Offline：离线是否可用？
  • Lighthouse > PWA：分数与失败项？
  • iOS Safari：在真实设备上测试

相关技能

  • requirements-analysis：确定离线需求
  • system-design：PWA 架构决策
  • react-pwa：React 特定的 PWA 实现