PWA开发专家指南：Service Worker缓存、离线功能与Web应用安装全攻略

pwa-expert by erichowens/some_claude_skills

125 周安装量

76 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/erichowens/some_claude_skills --skill pwa-expert

前端优化 Web应用性能优化

🇨🇳中文介绍

渐进式 Web 应用专家

使用 Service Workers、智能缓存和类原生体验，构建可安装、支持离线功能的 Web 应用。

何时使用此技能

让 Web 应用可在移动设备/桌面端安装
实现离线功能
设置 Service Worker 缓存策略
处理安装提示 (beforeinstallprompt)
为离线优先应用实现后台同步
管理 PWA 更新流程
创建 Web 应用清单

何时不应使用此技能

原生应用开发 → 使用 React Native、Flutter 或原生 SDK
通用 Web 性能优化 → 使用 Lighthouse/性能审计工具
服务端渲染问题 → 使用 Next.js/特定框架文档
仅需推送通知 → 考虑专门的推送通知服务
简单的静态网站 → PWA 的开销可能不值得

核心概念

使 PWA 可安装的条件

HTTPS（开发时可用 localhost）
包含必需字段的 Web 应用清单
带有 fetch 处理程序的 Service Worker
图标（至少 192×192 和 512×512）

PWA 技术栈

    ┌─────────────────────────────────────────┐
    │           您的应用 (React/Next.js)       │
    ├─────────────────────────────────────────┤
    │         Service Worker (sw.js)          │
    │  ┌─────────────┐  ┌─────────────────┐   │
    │  │     缓存     │  │   网络请求处理    │   │
    │  │     存储     │  │                │   │
    │  └─────────────┘  └─────────────────┘   │
    ├─────────────────────────────────────────┤
    │          manifest.json                  │
    │  (应用标识、图标、显示模式)                │
    └─────────────────────────────────────────┘

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

完整的 manifest.json

{
  "name": "Junkie Buds 4 Life",
  "short_name": "JB4L",
  "description": "Recovery support app",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "orientation": "portrait-primary",
  "background_color": "#1a1410",
  "theme_color": "#1a1410",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-maskable-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ],
  "shortcuts": [
    {
      "name": "Find Meetings",
      "short_name": "Meetings",
      "url": "/meetings?source=shortcut",
      "icons": [{ "src": "/icons/meetings-96.png", "sizes": "96x96" }]
    }
  ]
}

模式	描述
`fullscreen`	无浏览器 UI，全屏显示
`standalone`	类应用模式，无地址栏（推荐）
`minimal-ui`	保留部分浏览器控件
`browser`	普通浏览器标签页

<head>
  <link rel="manifest" href="/manifest.json" />
  <meta name="theme-color" content="#1a1410" />
  <meta name="apple-mobile-web-app-capable" content="yes" />
  <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
  <link rel="apple-touch-icon" href="/icons/apple-touch-icon.png" />
</head>

Service Worker 基础

// lib/pwa.ts
export async function registerServiceWorker() {
  if ('serviceWorker' in navigator) {
    try {
      const registration = await navigator.serviceWorker.register('/sw.js', {
        scope: '/',
      });
      return registration;
    } catch (error) {
      console.error('SW registration failed:', error);
    }
  }
}

// Call on app mount
useEffect(() => {
  registerServiceWorker();
}, []);

基本 Service Worker 结构

// public/sw.js
const CACHE_NAME = 'myapp-v1';
const STATIC_ASSETS = ['/', '/offline', '/manifest.json'];

// Install: Cache static assets
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(STATIC_ASSETS))
  );
  self.skipWaiting();
});

// Activate: Clean old caches
self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
    )
  );
  self.clients.claim();
});

// Fetch: Handle requests (see references for strategies)
self.addEventListener('fetch', (event) => {
  event.respondWith(handleFetch(event.request));
});

参见： references/service-worker-patterns.md 获取缓存策略实现

策略	最适合	权衡点
Cache-First	静态资源、字体、图像	缓存更新前内容可能过时
Network-First	API 数据、用户内容	较慢，需要网络连接
Stale-While-Revalidate	平衡新鲜度与速度	后台更新
Network-Only	认证、实时数据	无离线支持
Cache-Only	版本化资源	永不更新

参见： references/service-worker-patterns.md 获取完整实现

处理 beforeinstallprompt 事件以显示自定义安装 UI：

// Basic pattern
const [deferredPrompt, setDeferredPrompt] = useState(null);

useEffect(() => {
  window.addEventListener('beforeinstallprompt', (e) => {
    e.preventDefault();
    setDeferredPrompt(e);
  });
}, []);

const handleInstall = async () => {
  if (deferredPrompt) {
    deferredPrompt.prompt();
    const { outcome } = await deferredPrompt.userChoice;
    // outcome: 'accepted' or 'dismissed'
  }
};

参见： references/install-prompt.md 获取完整的 usePWAInstall 钩子和组件

导航失败时的离线页面回退
检测连接状态的 useOnlineStatus 钩子
通知用户的离线横幅

参见： references/offline-handling.md 获取实现

离线时排队操作，连接恢复后执行：

// In Service Worker
self.addEventListener('sync', (event) => {
  if (event.tag === 'sync-data') {
    event.waitUntil(syncPendingData());
  }
});

// In App - trigger sync
const registration = await navigator.serviceWorker.ready;
await registration.sync.register('sync-data');

参见： references/background-sync.md 获取完整的 IndexedDB 集成

当有新版本可用时通知用户：

// Basic pattern
registration.addEventListener('updatefound', () => {
  const newWorker = registration.installing;
  newWorker?.addEventListener('statechange', () => {
    if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
      // New version available - show update prompt
    }
  });
});

参见： references/update-flow.md 获取 usePWAUpdate 钩子和更新策略

Next.js PWA 的选项：

next-pwa - 适用于标准 Next.js 服务器
自定义 SW - output: 'export'（静态站点）必需
Workbox CLI - 构建后生成 SW

参见： references/nextjs-integration.md 获取详细配置

任务	解决方案
检查是否已安装	`window.matchMedia('(display-mode: standalone)').matches`
强制 SW 更新	`registration.update()`
清除所有缓存	`caches.keys().then(keys => keys.forEach(k => caches.delete(k)))`
检查在线状态	`navigator.onLine`
获取 SW 注册	`navigator.serviceWorker.ready`
跳过等待	在 SW 中使用 `self.skipWaiting()`
接管控制权	在 SW 中使用 `self.clients.claim()`

Application 标签页 → Manifest、Service Workers、Cache Storage
Lighthouse → PWA 审计
Network → Offline 复选框以模拟离线

清单加载（Application → Manifest）
SW 已注册（Application → Service Workers）
缓存已填充（Application → Cache Storage）
安装提示触发（Console 查看 beforeinstallprompt）
离线页面工作（Network → Offline）
更新流程工作（触发更新，验证提示）

/references/ 目录下的详细实现：

service-worker-patterns.md - 缓存策略实现
install-prompt.md - usePWAInstall 钩子和安装组件
offline-handling.md - 离线页面、状态钩子、横幅
background-sync.md - 与 IndexedDB 的后台同步
update-flow.md - 更新检测和用户提示
nextjs-integration.md - Next.js PWA 配置选项

🇺🇸English

Progressive Web App Expert

Build installable, offline-capable web apps with Service Workers, smart caching, and native-like experiences.

When to Use This Skill

Making a web app installable on mobile/desktop
Implementing offline functionality
Setting up Service Worker caching strategies
Handling install prompts (beforeinstallprompt)
Background sync for offline-first apps
Managing PWA update flows
Creating web app manifests

When NOT to Use This Skill

Native app development → Use React Native, Flutter, or native SDKs
General web performance → Use Lighthouse/performance auditing tools
Server-side rendering issues → Use Next.js/framework-specific docs
Push notifications only → Consider dedicated push notification services
Simple static sites → PWA overhead may not be worth it

Core Concepts

What Makes a PWA Installable

HTTPS (or localhost for dev)
Web App Manifest with required fields
Service Worker with fetch handler
Icons (192×192 and 512×512 minimum)

The PWA Stack

┌─────────────────────────────────────────┐
│           Your App (React/Next.js)      │
├─────────────────────────────────────────┤
│         Service Worker (sw.js)          │
│  ┌─────────────┐  ┌─────────────────┐   │
│  │   Cache     │  │  Network Fetch  │   │
│  │   Storage   │  │    Handling     │   │
│  └─────────────┘  └─────────────────┘   │
├─────────────────────────────────────────┤
│          manifest.json                  │
│  (App identity, icons, display mode)    │
└─────────────────────────────────────────┘

Web App Manifest

Complete manifest.json

{
  "name": "Junkie Buds 4 Life",
  "short_name": "JB4L",
  "description": "Recovery support app",
  "start_url": "/",
  "scope": "/",
  "display": "standalone",
  "orientation": "portrait-primary",
  "background_color": "#1a1410",
  "theme_color": "#1a1410",
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-maskable-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ],
  "shortcuts": [
    {
      "name": "Find Meetings",
      "short_name": "Meetings",
      "url": "/meetings?source=shortcut",
      "icons": [{ "src": "/icons/meetings-96.png", "sizes": "96x96" }]
    }
  ]
}

Display Modes

Mode	Description
`fullscreen`	No browser UI, full screen
`standalone`	App-like, no URL bar (recommended)
`minimal-ui`	Some browser controls
`browser`	Normal browser tab

Link in HTML

<head>
  <link rel="manifest" href="/manifest.json" />
  <meta name="theme-color" content="#1a1410" />
  <meta name="apple-mobile-web-app-capable" content="yes" />
  <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
  <link rel="apple-touch-icon" href="/icons/apple-touch-icon.png" />
</head>

Service Worker Basics

Registration

// lib/pwa.ts
export async function registerServiceWorker() {
  if ('serviceWorker' in navigator) {
    try {
      const registration = await navigator.serviceWorker.register('/sw.js', {
        scope: '/',
      });
      return registration;
    } catch (error) {
      console.error('SW registration failed:', error);
    }
  }
}

// Call on app mount
useEffect(() => {
  registerServiceWorker();
}, []);

Basic Service Worker Structure

// public/sw.js
const CACHE_NAME = 'myapp-v1';
const STATIC_ASSETS = ['/', '/offline', '/manifest.json'];

// Install: Cache static assets
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(STATIC_ASSETS))
  );
  self.skipWaiting();
});

// Activate: Clean old caches
self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((k) => k !== CACHE_NAME).map((k) => caches.delete(k)))
    )
  );
  self.clients.claim();
});

// Fetch: Handle requests (see references for strategies)
self.addEventListener('fetch', (event) => {
  event.respondWith(handleFetch(event.request));
});

See: references/service-worker-patterns.md for caching strategy implementations

Caching Strategies

Strategy	Best For	Tradeoff
Cache-First	Static assets, fonts, images	Stale until cache updated
Network-First	API data, user content	Slower, needs connectivity
Stale-While-Revalidate	Balance freshness/speed	Background updates
Network-Only	Auth, real-time data	No offline support
Cache-Only	Versioned assets	Never updates

See: references/service-worker-patterns.md for full implementations

Install Prompts

Handle the beforeinstallprompt event to show a custom install UI:

// Basic pattern
const [deferredPrompt, setDeferredPrompt] = useState(null);

useEffect(() => {
  window.addEventListener('beforeinstallprompt', (e) => {
    e.preventDefault();
    setDeferredPrompt(e);
  });
}, []);

const handleInstall = async () => {
  if (deferredPrompt) {
    deferredPrompt.prompt();
    const { outcome } = await deferredPrompt.userChoice;
    // outcome: 'accepted' or 'dismissed'
  }
};

See: references/install-prompt.md for full usePWAInstall hook and component

Offline Experience

Key patterns:

Offline page fallback for navigation failures
useOnlineStatus hook to detect connectivity
Offline banner to inform users

See: references/offline-handling.md for implementations

Background Sync

Queue actions while offline, execute when connectivity returns:

// In Service Worker
self.addEventListener('sync', (event) => {
  if (event.tag === 'sync-data') {
    event.waitUntil(syncPendingData());
  }
});

// In App - trigger sync
const registration = await navigator.serviceWorker.ready;
await registration.sync.register('sync-data');

See: references/background-sync.md for full IndexedDB integration

Update Flow

Notify users when a new version is available:

// Basic pattern
registration.addEventListener('updatefound', () => {
  const newWorker = registration.installing;
  newWorker?.addEventListener('statechange', () => {
    if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
      // New version available - show update prompt
    }
  });
});

See: references/update-flow.md for usePWAUpdate hook and update strategies

Next.js Integration

Options for Next.js PWA:

next-pwa - Works with standard Next.js server
Custom SW - Required for output: 'export' (static sites)
Workbox CLI - Generate SW after build

See: references/nextjs-integration.md for detailed configurations

Quick Reference

Task	Solution
Check if installed	`window.matchMedia('(display-mode: standalone)').matches`
Force SW update	`registration.update()`
Clear all caches	`caches.keys().then(keys => keys.forEach(k => caches.delete(k)))`
Check online	`navigator.onLine`
Get SW registration	`navigator.serviceWorker.ready`
Skip waiting	`self.skipWaiting()` in SW

Testing PWA

Chrome DevTools

Application tab → Manifest, Service Workers, Cache Storage
Lighthouse → PWA audit
Network → Offline checkbox to simulate

Debug Checklist

Manifest loads (Application → Manifest)
SW registered (Application → Service Workers)
Cache populated (Application → Cache Storage)
Install prompt fires (Console for beforeinstallprompt)
Offline page works (Network → Offline)
Update flow works (trigger update, verify prompt)

References

Detailed implementations in /references/:

service-worker-patterns.md - Caching strategy implementations
install-prompt.md - usePWAInstall hook and install component
offline-handling.md - Offline page, status hooks, banners
background-sync.md - Background sync with IndexedDB
update-flow.md - Update detection and user prompts
nextjs-integration.md - Next.js PWA configuration options

Weekly Installs

125

Repository

erichowens/some…e_skills

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

gemini-cli114

opencode109

codex107

github-copilot103

cursor100

claude-code89

TanStack Query v5 完全指南：React 数据管理、乐观更新、离线支持

2,500 周安装

PWA开发专家指南：Service Worker缓存、离线功能与Web应用安装全攻略

🇨🇳中文介绍

渐进式 Web 应用专家

何时使用此技能

何时不应使用此技能

核心概念

使 PWA 可安装的条件

PWA 技术栈

相关 Skills

Web 应用清单

完整的 manifest.json

显示模式

在 HTML 中链接

Service Worker 基础

注册

基本 Service Worker 结构

缓存策略

安装提示

离线体验

后台同步

更新流程

Next.js 集成

快速参考

测试 PWA

Chrome DevTools

调试清单

参考资料

🇺🇸English

Progressive Web App Expert

When to Use This Skill

When NOT to Use This Skill

Core Concepts

What Makes a PWA Installable

The PWA Stack

Web App Manifest

Complete manifest.json

Display Modes

Link in HTML

Service Worker Basics

Registration

Basic Service Worker Structure

Caching Strategies

Install Prompts

Offline Experience

Background Sync

Update Flow

Next.js Integration

Quick Reference

Testing PWA

Chrome DevTools

Debug Checklist

References

最新 Skills