2026-06-06 — PWA stale shell 白屏债(部分修复,残余风险记账)

导读

事故

用户报「主站无法打开,白屏一直加载」。链条(实测取证):

  1. 国内到 pages.dev 链路当时 TTFB ~6s(curl 实测),超过 SW 的 1.5s network-first 超时
  2. SW 回退缓存的旧主页 index.html(根 / 是 dashboard SPA shell 的拷贝)
  3. 旧 shell 引用旧 vite hash 资产(index-DSAhpeVW.css 等),当日 deploy 已轮换 hash → 404
  4. /app/ 被 SW 旁路(sw.js 注释自己点名了这个白屏风险),但根 / 的同一 SPA shell 不在旁路内 → 白屏

已修(commit 见 git log 2026-06-06)
  • deploy-pages.sh 在 wrangler 上传前 stamp out/sw.js 的 CACHE_VERSION 为 HEAD sha7, 与 CF CI 的 stamp-sw.mjs 行为对齐 → 本地手动 deploy 不再让 SW 版本永久停在 85dda9c, 旧 HTML cache 随每次 deploy 被 evict。

残余风险(未修,记账)

stamp 只把 stale 窗口从「无限期」缩到「一个 SW 更新周期」。首次坏加载仍可能发生: 慢网络 + 缓存 shell + 当次 deploy 轮换了 /app 资产 hash → 这一次打开仍白屏,刷新自愈。

候选根治方向(按改动面排序,做之前评估):

  1. 根 / 文档加入 SW 旁路(同 /app/ 待遇)——代价:PWA 启动秒开特性退化为受网速制约
  2. SPA shell 侧加 chunk-load-error → location.reload() 兜底(vite 常见模式)——动 app 代码 + 重建产物
  3. deploy 时保留上一版 /app/assets(双版本共存)——脚本复杂度↑

触发条件再现(慢网络 + 部署轮换窗口期打开)再投入;非高频路径不预支。