mcpField
P
pwa-development

pwa-development

github.com/jwynia开发180441 次安装36 周前更新
代码仓库

关于 pwa-development

pwa-development 面向 React 和 Svelte 项目，指导渐进式 Web 应用功能的实现与排查，涵盖服务工作线程、缓存、离线行为、更新和 iOS 特有问题。

主要功能

  1. 01Manifest 与服务工作线程配置指导
  2. 02缓存策略建议
  3. 03离线存储与同步指导
  4. 04PWA 审核与调试
  5. 05iOS 特有问题排查

适用场景

  1. 01为 Web 应用添加离线支持
  2. 02排查内容过期或缓存异常
  3. 03修复服务工作线程更新行为
  4. 04调查 iOS 上的 PWA 问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jwynia/agent-skills --skill pwa-development

安装后在 Claude Code 中输入/pwa-development确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/
manifest.json.template
offline-page.html
service-worker-workbox.ts
update-prompt.svelte
update-prompt.tsx
data/
caching-strategies.json
framework-patterns.json
ios-quirks.json
manifest-options.json
scripts/
cache-strategy-advisor.ts
manifest-generator.ts
pwa-audit.ts
sw-scaffolder.ts

详细介绍

PWA 开发

为 React 和 Svelte 应用实现渐进式 Web 应用功能，包括 Service Worker、缓存策略、离线支持和安装提示。

何时使用此技能

在以下情况下使用此技能：

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

在以下情况下不要使用此技能：

  • 构建后端 API
  • 处理需求／设计（先使用相应技能）
  • 需要复杂的离线优先架构（先进行设计）

核心原则

如果事后才考虑离线行为，PWA 就会失败。 PWA 不是“给现有应用添加 Service Worker”，而是关乎数据流、缓存和连接故障的根本性架构决策。

诊断状态

P0：未设置 PWA

症状： 没有 manifest.json，没有 Service Worker，只能在线使用

处理措施：

  • 运行 scripts/manifest-generator.ts 创建清单
  • 在 HTML head 中添加 <link rel="manifest">
  • 使用 scripts/sw-scaffolder.ts 生成最简 Service Worker
P1：仅有基础清单

症状： 清单存在，但缺少 Service Worker，离线时无法使用

关键问题：

  • 哪些内容必须在离线时可用？
  • 哪些内容应始终保持最新（网络优先）？

处理措施：

  • 使用 scripts/cache-strategy-advisor.ts
  • 实现应用外壳模式
  • 添加离线备用页面
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、支持离线使用、更新过程顺畅

缓存策略

策略适用内容行为
缓存优先静态资源、字体从缓存提供内容，并在后台更新
网络优先API 数据、用户内容尝试访问网络，失败时回退到缓存
过时内容重新验证半静态内容提供过时内容，并更新缓存供下次使用
仅网络身份验证、实时数据始终访问网络，不进行缓存

可用脚本

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

反模式

缓存一切

预缓存每个资源——导致首次下载量巨大。 修复方法： 只预缓存关键的应用外壳内容。运行时再缓存内容。

永不过期的缓存

缓存永不过期——内容会一直过时。 修复方法： 对缓存进行版本管理，在激活时删除旧缓存，并设置最长缓存时间。

静默更新

在不通知用户的情况下强制更新。 修复方法： 通知用户，让他们选择何时刷新。

事后才考虑 iOS

先针对 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。

调试检查清单

  1. DevTools > Application > Manifest - 是否有效？
  2. DevTools > Application > Service Workers - 是否已注册？
  3. DevTools > Application > Cache Storage - 缓存了什么？
  4. DevTools > Network > Offline - 能否离线运行？
  5. Lighthouse > PWA - 得分和失败项是什么？
  6. iOS Safari - 在实际设备上测试

相关技能

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

评论

支持 Markdown