SuperAPI AI 工具集

pwa-offline-cache-contracts

通用与其它

查看项目

更新于 10-16 06:44

技能介绍

用途:审查 PWA 的缓存契约是否被破坏,即预缓存的完整性、缓存版本与清理、安装原子性、更新/等待流程、导航回退,以及哪些响应绝不能缓存。适用于“部署后用户仍是旧构建”“ChunkLoadError 或动态导入失败”“离线资源缺失”“安装被中止”“跨会话读到缓存数据”等用户可见故障。

主要能力与要点:

  1. HTML 应设 Cache-Control: no-cache 或在 SW 走 Network First,带哈希的资源保持 immutable/Cache First;为动态导入失败加一次性重载处理并设重试上限。
  2. 新 worker 会停在 waiting,直到旧 worker 控制的所有客户端关闭;需通过 updatefound/statechange 或注册时的 registration.waiting 检测更新并让用户激活。registration.update() 只重新抓取脚本,字节不同的 worker 仍会等待。
  3. 在 activate 中按显式版本名清理旧缓存(遍历 caches.keys() 删除不在允许列表的项),不要在 install 中清理。
  4. cache.addAll 是全有或全无:任一请求失败(404、重定向、opaque 跨域)即拒绝,导致安装失败、worker 不激活;只预缓存预期返回 200 的同源 URL,可选或第三方资源单独用 cache.put 并逐项处理错误。
  5. 自定义 globPatterns 会覆盖默认匹配集,需完整枚举扩展名,并注意 maximumFileSizeToCacheInBytes 会静默跳过过大文件;可用构建产物清单断言(HTML+JS+CSS+图标+字体)防回归。
  6. skipWaiting/clients.claim 与提示刷新需有意选择:立即激活会造成新旧版本混用。
  7. 为 SPA 导航注册 NavigationRoute 提供预缓存 shell,并设置允许/拒绝列表,另备离线回退页。
  8. 绝不要预缓存或运行时缓存需认证的 HTML/API 响应:Cache Storage 按源而非按用户,Cache API 忽略 HTTP 缓存头,只对 status 200 的响应写入缓存。

用法与限制:该技能面向代码审查与修复,具体命令如 rg -n "skipWaiting|clients.claim|registration.waiting|updatefound|controllerchange" src/ app/ 等可用于定位问题;可借助 DevTools Application 面板查看 waiting worker 与缓存内容。Lighthouse v12 已移除 PWA 分类,不应作为检查入口。仅当缓存契约确实被破坏且用户可见时才提出发现;已正确版本化、activate 清理、完整预缓存并带更新提示的实现不应误报。具体 max-age 取值属部署调优,资料未提供统一标准。