294 lines
15 KiB
Markdown
294 lines
15 KiB
Markdown
# 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)**:
|
||
|
||
1. **零新依赖**——项目一贯原则(对比 PDF 导出 T-076 同样零依赖手写),手写 manifest + SW 只涉及 2 个静态文件 + 一段注册代码,不进入 `package.json`。
|
||
2. **SPA 架构极简**——单页 + pathname 路由 + 构建产物 `dist/` 下 js/css 均带内容哈希,手写 precache 只需在发布时刷新一份资源清单,无复杂集成面。
|
||
3. **可控的缓存策略**——vite-plugin-pwa 默认 generateSW 注入 workbox 运行时(额外 ~20KB),我方离线需求(静态资源 + SPA shell + 离线降级)用原生 Cache API 即可覆盖,策略完全在手。
|
||
4. **迁移成本低**——未来若需要自动资源清单/更细粒度运行时缓存,可平滑升级到 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,实测解码)
|
||
|
||
```json
|
||
{
|
||
"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/`)。
|
||
|
||
```json
|
||
{
|
||
"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-capable` meta 才可全屏。
|
||
|
||
---
|
||
|
||
## 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 关键策略伪代码
|
||
|
||
```js
|
||
// ① 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 均含内容哈希)。提供两种维护法,二选一:
|
||
1. 简单法:发布后在 `dist/` 手动跑 `node scripts/build-precache.mjs`(读取 `dist/index.html` 中 `assets/*` 引用 + 固定项,输出 SW 顶部 `PRECACHE_ASSETS` 数组)。
|
||
2. 保守法:`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 无自定义安装引导;我方建议**温和引导**(不弹窗打扰、不拦截首屏):
|
||
|
||
1. **PWA 资格预检**:`display-mode: standalone` matchMedia 判断已安装态;监听 `beforeinstallprompt`(Chrome 有资格时触发)。
|
||
2. **触发时机**:用户已完成一次完整流程(如下载/生成图纸后)或停留 > 30s,在底部浮出「添加到主屏幕 / 安装到桌面」横幅(可关闭,`localStorage` 记 dismissed)。
|
||
3. **deferredPrompt**:捕获 `beforeinstallprompt` 事件存入变量,点横幅时 `prompt()`;`appinstalled` 后清理横幅。
|
||
4. **iOS Safari**:无 install prompt API,横幅展示「分享 → 添加到主屏幕」图文指引(`navigator.standalone` 判断 iOS)。
|
||
|
||
```ts
|
||
// 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 缓存干扰):
|
||
|
||
```ts
|
||
// 生产环境注册 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. 风险与注意
|
||
|
||
1. **SW 注册失败静默**:注册代码 try/catch 仅告警,绝不阻塞主流程。
|
||
2. **缓存与发版不同步**:SW 有更新滞后窗口(默认 24h 检查,`updateViaCache` 与 `skipWaiting` 已缓解);发布流程需包含「递增 VERSION」动作。
|
||
3. **HTTPS 前置**:SW 仅在 secure context 可用(localhost 例外),生产必须 HTTPS(T-030 已就绪)。
|
||
4. **不要缓存敏感/动态数据**:`/api/*` 与 POST 一律网络优先;支付回调、兑换码相关请求严禁落入 SW 缓存。
|
||
5. **iOS 限制**:iOS Safari 不支持 beforeinstallprompt、SW 更新较激进、旧版本不清理缓存——低优先级适配即可,不做主路径投入。
|
||
6. **离线不等于单机可用**: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),无推断项。*
|