Files

15 KiB
Raw Permalink Blame History

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,实测解码)

{
  "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-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 关键策略伪代码

// ① 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)。
// 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. 风险与注意

  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),无推断项。