关于
构建支持离线、可安装和缓存策略的渐进式 Web 应用（PWA）。适用于涉及 PWA、Service Worker、Web App Manifest、Workbox、添加到主屏幕，或需要 Web 应用离线工作、原生体验或可安装的场景。
name: progressive-web-app description: "构建具有离线支持、可安装性和缓存策略的渐进式 Web 应用 (PWA)。当用户提到 PWA、Service Worker、Web App Manifest、Workbox、'添加到主屏幕'，或希望 Web 应用离线工作、感觉像原生应用或可安装时触发。" risk: safe source: community date_added: "2026-03-17" tags: [pwa, web-dev, service-worker, frontend, offline, caching] tools: [gemini, cursor, claude]
渐进式 Web 应用 (PWA)
概述
渐进式 Web 应用是使用现代浏览器能力来提供快速、可靠和可安装体验的 Web 应用——即使在不可靠的网络上也能工作。三个必需支柱是：
- HTTPS — 生产环境中 Service Worker 注册所必需（localhost 在开发中免除）。
- Web App Manifest (
manifest.json) — 使应用可安装并定义其在设备主屏幕上的外观。 - Service Worker (
sw.js) — 拦截网络请求、管理缓存并启用离线功能的后台脚本。
何时使用本技能
- 当用户希望 Web 应用在离线或不可靠网络上工作时使用。
- 构建移动优先的 Web 项目，用户应能将应用安装到主屏幕时使用。
- 当用户询问缓存策略、Service Worker 或改善 Web 应用性能和弹性时使用。
- 当用户提到 Workbox、Web App Manifest、后台同步或 Web 推送通知时使用。
- 当用户问"我的网站能像应用一样安装吗？"或"如何让我的网站离线工作？"时使用——即使他们没有使用 PWA 这个词。
交付物检查清单
每个 PWA 实现至少必须包含这些文件：
- [ ]
index.html— 链接 manifest，注册 Service Worker - [ ]
manifest.json— 完整应用元数据和图标集 - [ ]
sw.js— 包含 install、activate 和 fetch 处理器的 Service Worker - [ ]
app.js— 主应用逻辑，包含 SW 注册和安装提示处理 - [ ]
offline.html— 离线导航失败时显示的回退页面（必需——缺少此文件将导致安装失败）
步骤 1：Web App Manifest (manifest.json)
定义应用安装后的外观。必须通过 <link rel="manifest"> 从 <head> 链接。
{
"name": "My Awesome PWA",
"short_name": "MyPWA",
"description": "A fast, offline-capable Progressive Web App.",
"start_url": "/",
"scope": "/",
"display": "standalone",
"orientation": "portrait-primary",
"background_color": "#ffffff",
"theme_color": "#0055ff",
"icons": [
{
"src": "/assets/icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any maskable"
},
{
"src": "/assets/icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "any maskable"
}
],
"screenshots": [
{
"src": "/assets/screenshots/desktop.png",
"sizes": "1280x720",
"type": "image/png",
"form_factor": "wide"
}
]
}
关键字段：
display：standalone隐藏浏览器 UI；minimal-ui显示最少控件；browser是标准标签页。- 图标上的
purpose: "maskable"在 Android 上启用自适应图标（安全区域很重要——将内容保持在中心 80%）。 screenshots是可选的，但 Chrome 桌面增强安装对话框需要它。
步骤 2：HTML Shell (index.html)
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My Awesome PWA</title>
<!-- PWA manifest -->
<link rel="manifest" href="/manifest.json">
<!-- 浏览器 chrome 的主题色 -->
<meta name="theme-color" content="#0055ff">
<!-- iOS 特定（Safari 不完全使用 manifest） -->
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="default">
<meta name="apple-mobile-web-app-title" content="MyPWA">
<link rel="apple-touch-icon" href="/assets/icons/icon-192x192.png">
<link rel="stylesheet" href="/styles.css">
</head>
<body>
<div id="app">
<header><h1>My PWA</h1></header>
<main id="content">Loading...</main>
<!-- 可选：安装按钮，默认隐藏 -->
<button id="install-btn" hidden>Install App</button>
</div>
<script src="/app.js"></script>
</body>
</html>
步骤 3：Service Worker 注册和安装提示 (app.js)
// ─── Service Worker 注册 ───────────────────────────────────────────
if ('serviceWorker' in navigator) {
window.addEventListener('load', async () => {
try {
const registration = await navigator.serviceWorker.register('/sw.js');
console.log('[App] SW registered, scope:', registration.scope);
} catch (err) {
console.error('[App] SW registration failed:', err);
}
});
}
// ─── 安装提示 (添加到主屏幕)
兼容工具
Claude CodeCursor
标签
前端开发