15 KiB
PWA-PLAN — PERLER LAB PWA 接入评估与实施方案
任务: T-105 PWA 接入评估:manifest 与离线缓存方案 角色: Oracle-Architect-Agent 日期: 2026-08-14 输入依据:
- 竞品 manifest 实测:
competitor-analysis/raw/manifest-decoded.json(PixelBeads:standalone / 192+512 maskable 图标 / 白底)- 我方现状:
perler-lab/vite.config.ts(Vite+React SPA)、perler-lab/index.html、src/main.tsx(客户端路由按 pathname 分发)、public/(仅 favicon.svg,无 PNG 图标)- 约束: 不引入不必要新依赖(优先手写)、不做原生应用(竞品 Chrome 插件 + Android/iOS 生态不在本次范围)
0. 结论速览(推荐方案)
| 维度 | 结论 |
|---|---|
| 方案 | 手写 public/manifest.webmanifest + public/sw.js + 手动注册(零新依赖) |
| 备选 | vite-plugin-pwa(工作区缓存 + 自动注入,但新增构建依赖) |
| 首期落地 | P0 前置(PNG 图标 + HTTPS 就绪)→ P1 manifest + 注册 → P2 SW precache + 运行时缓存 → P3 安装提示 |
| 收益 | 安装到桌面/主屏、离线可用、首屏加速(SW 接管静态资源)、竞品对齐(standalone 体验) |
| 风险 | 缓存失效/版本管理、图标缺失导致不可安装、SW 需 HTTPS(localhost 例外) |
推荐理由(手写 vs vite-plugin-pwa):
- 零新依赖——项目一贯原则(对比 PDF 导出 T-076 同样零依赖手写),手写 manifest + SW 只涉及 2 个静态文件 + 一段注册代码,不进入
package.json。 - SPA 架构极简——单页 + pathname 路由 + 构建产物
dist/下 js/css 均带内容哈希,手写 precache 只需在发布时刷新一份资源清单,无复杂集成面。 - 可控的缓存策略——vite-plugin-pwa 默认 generateSW 注入 workbox 运行时(额外 ~20KB),我方离线需求(静态资源 + SPA shell + 离线降级)用原生 Cache API 即可覆盖,策略完全在手。
- 迁移成本低——未来若需要自动资源清单/更细粒度运行时缓存,可平滑升级到 vite-plugin-pwa,manifest 与 sw.js 内容可直接复用。
竞品对齐边界:竞品 manifest 仅 4 个核心字段(name/short_name/display/icons/theme+background)。我方在其基础上补齐
start_url/scope/id,保证安装与离线行为确定;不做竞品的三端应用生态。
1. 现状与竞品对比
1.1 我方现状
| 项 | 现状 | 对 PWA 的影响 |
|---|---|---|
| 构建 | Vite + React SPA,dist/ 输出 |
产物含哈希,适合 SW precache |
| 路由 | App.tsx 按 window.location.pathname 分发(/、/chibi、/color-chart、/showcase、/library、/help) |
离线需导航请求 fallback 到 SPA shell |
| 图标 | 仅 public/favicon.svg |
缺少 192/512 PNG,阻断安装提示(P0 前置) |
| 传输 | 静态部署(nginx/Docker,见 DEPLOY.md) | 需确认 HTTPS(T-030 已含域名与 HTTPS 章节) |
| 数据 | 图片处理在浏览器本地完成(FAQ-33),无用户体系 | 离线缓存不涉及敏感数据,风险低 |
1.2 竞品 manifest(pixel-beads,实测解码)
{
"name": "PixelBeads – Perler Bead Pattern Generator",
"short_name": "PixelBeads",
"description": "Create, edit, and export Perler bead patterns and pixel art in your browser.",
"start_url": "/",
"scope": "/",
"icons": [
{ "src": "/web-app-manifest-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" },
{ "src": "/web-app-manifest-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
],
"theme_color": "#ffffff",
"background_color": "#ffffff",
"display": "standalone"
}
竞品要点:display: standalone(独立窗口,无地址栏)、maskable 图标、白底主题。我方沿用这一字段基线。
2. manifest 字段设计(建议落地值)
文件:perler-lab/public/manifest.webmanifest(MIME application/manifest+json,Vite 会自动把 public/ 拷入 dist/)。
{
"id": "/",
"name": "PERLER LAB · 拼豆图纸生成器",
"short_name": "PERLER LAB",
"description": "把喜欢的图片,变成一颗颗拼豆。免费生成、调整拼豆图纸,支持六品牌色号速查。",
"start_url": "/",
"scope": "/",
"display": "standalone",
"orientation": "portrait-primary",
"background_color": "#f4f3ef",
"theme_color": "#f4f3ef",
"lang": "zh-CN",
"categories": ["design", "art", "photography"],
"icons": [
{ "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
{ "src": "/icons/icon-192-maskable.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" },
{ "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
{ "src": "/icons/icon-512-maskable.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
],
"shortcuts": [
{ "name": "品牌色号表", "short_name": "色号表", "url": "/color-chart", "icons": [{ "src": "/icons/icon-192.png", "sizes": "192x192" }] },
{ "name": "AI 拼豆专区", "short_name": "AI 专区", "url": "/chibi", "icons": [{ "src": "/icons/icon-192.png", "sizes": "192x192" }] }
]
}
字段说明:
| 字段 | 值 | 理由 |
|---|---|---|
id |
/ |
Chrome 120+ 安装身份标识,固定根路径避免随 start_url 变化重复安装 |
display |
standalone |
对齐竞品,独立窗口体验 |
theme_color / background_color |
#f4f3ef |
对齐 DESIGN.md 页面底色(--bg-page),启动屏与浏览器 UI 观感一致 |
start_url / scope |
/ |
全站可安装、可离线;scope 收紧到站内,禁止 SW 越界 |
icons |
192/512 any+maskable | Chrome 安装硬性要求;maskable 保证圆形裁剪安全区(图标主体留 ≥ 20% 安全边距) |
shortcuts |
色号表 / AI 专区 | 长按/右键跳转深链,复用已有路由,成本≈0 |
index.html 配套改动:
<link rel="manifest" href="/manifest.webmanifest">+<meta name="theme-color" content="#f4f3ef">+<link rel="apple-touch-icon" href="/icons/icon-192.png">(iOS 主屏)。iOS 需额外apple-mobile-web-app-capablemeta 才可全屏。
3. Service Worker 缓存策略
文件:perler-lab/public/sw.js(手写,原生 Cache API,无 workbox)。版本号 const VERSION = 'v1',每次发布递增缓存名 perler-precache-${VERSION} / perler-runtime-${VERSION}。
3.1 缓存分层
| 缓存 | 内容 | 策略 |
|---|---|---|
perler-precache-v1 |
index.html + assets/*.js + assets/*.css(构建产物,发布时刷新清单) |
install 时预缓存(precache) |
perler-runtime-v1 |
图片/字体//color-chart 等静态资源 |
stale-while-revalidate |
导航请求(mode: 'navigate') |
— | network-first → fallback 缓存的 index.html(离线 SPA shell) |
/api/*、POST、fetch(XHR) |
— | 网络优先,不缓存(后端动态数据;POST 含支付/兑换,绝不下 SW 缓存) |
3.2 关键策略伪代码
// ① install:预缓存静态资源,任何一项失败即整体失败(安装不完整则中断)
self.addEventListener('install', (e) => {
e.waitUntil(
caches.open(PRECACHE).then((c) => c.addAll(PRECACHE_ASSETS)),
);
self.skipWaiting();
});
// ② activate:清理旧版本缓存,立即接管页面
self.addEventListener('activate', (e) => {
e.waitUntil(
caches.keys().then((keys) =>
Promise.all(keys.filter((k) => k !== PRECACHE && k !== RUNTIME).map((k) => caches.delete(k))),
),
);
self.clients.claim();
});
// ③ fetch:三类分流
self.addEventListener('fetch', (e) => {
const req = e.request;
if (req.method !== 'GET') return; // 非 GET 一律放行
const url = new URL(req.url);
if (url.origin !== location.origin) return; // 跨域放行(可另加白名单运行时缓存)
if (req.mode === 'navigate') {
// 导航:network-first,离线回退 SPA shell
e.respondWith(
fetch(req).then((res) => {
const copy = res.clone();
caches.open(RUNTIME).then((c) => c.put(req, copy));
return res;
}).catch(() => caches.match('/index.html')),
);
return;
}
if (url.pathname.startsWith('/api/')) return; // API 网络优先,不缓存
// 静态资源:stale-while-revalidate(秒开体验 + 后台更新)
e.respondWith(
caches.match(req).then((cached) => {
const network = fetch(req)
.then((res) => {
if (res.ok) {
const copy = res.clone();
caches.open(RUNTIME).then((c) => c.put(req, copy));
}
return res;
})
.catch(() => cached);
return cached || network;
}),
);
});
3.3 资源清单(precache)维护方式
推荐:发布时生成(dist/ 内 js/css 均含内容哈希)。提供两种维护法,二选一:
- 简单法:发布后在
dist/手动跑node scripts/build-precache.mjs(读取dist/index.html中assets/*引用 + 固定项,输出 SW 顶部PRECACHE_ASSETS数组)。 - 保守法:
index.html永远在清单首项(离线 shell),js/css 每次发布整体更新VERSION并重建清单,保证原子切换。
⚠️ 不用 cache-first 缓存
index.html:开发/灰度时 html 变化需即时生效,故导航用 network-first。
4. 离线页面
SPA 客户端渲染架构下,导航 fallback 到缓存的 index.html 即自动获得离线页面——React 应用本身可完整渲染,无需独立 /offline.html。
离线降级路径:
| 场景 | 行为 |
|---|---|
| 已访问过任意页面 + 离线 | 导航请求失败 → 返回缓存的 index.html → 应用正常渲染(静态资源命中 precache/runtime) |
| 首次安装后未访问 + 离线 | 缓存中无 shell → 浏览器默认「无法连接」页(预期内,P2 后可加 first-visit 预缓存) |
离线时请求 /api/* |
放行到网络失败,前端 api.ts 现有错误提示兜底(不缓存敏感数据) |
可选增强(P3):hero 区顶部 banner「当前离线,显示缓存内容」——通过 navigator.onLine + SW message 检测,成本低、体验完整。
5. 安装提示(Install Prompt)
竞品纯 Web 无自定义安装引导;我方建议温和引导(不弹窗打扰、不拦截首屏):
- PWA 资格预检:
display-mode: standalonematchMedia 判断已安装态;监听beforeinstallprompt(Chrome 有资格时触发)。 - 触发时机:用户已完成一次完整流程(如下载/生成图纸后)或停留 > 30s,在底部浮出「添加到主屏幕 / 安装到桌面」横幅(可关闭,
localStorage记 dismissed)。 - deferredPrompt:捕获
beforeinstallprompt事件存入变量,点横幅时prompt();appinstalled后清理横幅。 - iOS Safari:无 install prompt API,横幅展示「分享 → 添加到主屏幕」图文指引(
navigator.standalone判断 iOS)。
// src/lib/pwa-install.ts(P3 落地,示意)
let deferred: BeforeInstallPromptEvent | null = null;
window.addEventListener('beforeinstallprompt', (e) => {
e.preventDefault();
deferred = e as BeforeInstallPromptEvent;
window.dispatchEvent(new CustomEvent('pwa-installable', { detail: { deferred } }));
});
window.addEventListener('appinstalled', () => {
window.dispatchEvent(new CustomEvent('pwa-installed'));
});
6. 注册代码
文件:perler-lab/src/main.tsx 追加(仅生产环境注册,避免 dev 热更替被 SW 缓存干扰):
// 生产环境注册 Service Worker(public/sw.js 构建后自动复制到 dist/)
if (import.meta.env.PROD && 'serviceWorker' in navigator) {
window.addEventListener('load', () => {
navigator.serviceWorker.register('/sw.js').catch((err) => {
console.warn('[PWA] SW 注册失败:', err);
});
});
}
dev 模式不注册:Vite HMR 与 SW 缓存冲突;仅
dist/生产构建验证。
7. 实施拆解(建议任务拆分)
| ID | 优先级 | 任务 | 验收标准 |
|---|---|---|---|
| P0-1 | P0 | 生成 192/512 PNG 图标(any+maskable,主题色 #f4f3ef,可基于 favicon.svg 导出) |
4 个文件入 public/icons/,Chrome DevTools 安装资格无图标报错 |
| P0-2 | P0 | 确认生产 HTTPS 就绪(T-030 已含) | 生产域名证书有效,SW 可在 https 注册 |
| P1-1 | P1 | public/manifest.webmanifest + index.html 注入 link/meta |
DevTools Application 面板读取正常,字段无警告 |
| P1-2 | P1 | src/main.tsx 注册 SW(PROD 守卫) |
生产构建 dist/ 部署后 navigator.serviceWorker.controller 非空 |
| P2-1 | P2 | public/sw.js precache + 运行时缓存 + 离线 fallback |
离线模式(Network offline)刷新可打开站点并看到缓存内容 |
| P2-2 | P2 | 资源清单生成脚本 scripts/build-precache.mjs |
发布后 dist 清单与实际产物一致 |
| P3-1 | P3 | 安装提示横幅 + 已安装态检测 | beforeinstallprompt 触发、横幅可关闭、已安装不再出现 |
| P3-2 | P3 | 离线 banner + 版本更新提示(skipWaiting 后刷新引导) | 新版本发布后旧标签页收到更新提示 |
本任务(T-105)交付本评估文档;P0–P3 拆为独立任务由前端承接实施。
8. 风险与注意
- SW 注册失败静默:注册代码 try/catch 仅告警,绝不阻塞主流程。
- 缓存与发版不同步:SW 有更新滞后窗口(默认 24h 检查,
updateViaCache与skipWaiting已缓解);发布流程需包含「递增 VERSION」动作。 - HTTPS 前置:SW 仅在 secure context 可用(localhost 例外),生产必须 HTTPS(T-030 已就绪)。
- 不要缓存敏感/动态数据:
/api/*与 POST 一律网络优先;支付回调、兑换码相关请求严禁落入 SW 缓存。 - iOS 限制:iOS Safari 不支持 beforeinstallprompt、SW 更新较激进、旧版本不清理缓存——低优先级适配即可,不做主路径投入。
- 离线不等于单机可用:AI 生成等后端能力离线不可用属预期,离线收益聚焦「浏览/查阅色号表/已缓存图纸」。
9. 部署配套(对接 T-110)
nginx需为/.webmanifest/manifest.webmanifest返回application/manifest+json,/sw.js返回application/javascript且 禁止协商缓存(Cache-Control: no-cache,SW 自身更新依赖每次校验)。index.html建议no-cache(网络优先策略前提)。dist/assets/*内容哈希 + 长缓存不变。
文档完。方案基于竞品 manifest 实测(manifest-decoded.json)与我方源码实读(vite.config.ts / index.html / main.tsx / App.tsx),无推断项。