Files

294 lines
15 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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),无推断项。*