前端发布后白屏复盘：Service Worker 缓存旧入口导致 JS 资源 404

前端发布后“只有一部分用户白屏”是很典型的缓存类故障。新用户打开正常，老用户刷新后白屏；回滚后有些人恢复，有些人仍然报错。这种现象往往不是接口挂了，而是浏览器本地缓存、Service Worker 和带哈希的静态资源版本没有对齐。

本文复盘一次真实风格的排查路径：旧 Service Worker 返回了旧 index.html，页面继续请求已经从服务器删除的旧 JS 文件，最终触发 404 和白屏。

影响面：新用户正常，老用户白屏

故障发生在一次正常前端发布后。监控先看到白屏率从 0.2% 升到 3.8%，但接口错误率没有同步上升。客服反馈也很明确：部分老用户刷新页面后白屏，新用户或无痕窗口访问正常。

这类影响面给了一个关键信号：问题更像浏览器本地状态，而不是服务端整体不可用。我们先看浏览器控制台和 Network 面板：

GET /assets/app.9c31a2.js 404
Uncaught TypeError: Failed to load dynamically imported module
ServiceWorker: respondWith cached /index.html

这个证据说明白屏不是首个 HTML 请求失败，而是 HTML 里引用的 JS 资源版本已经和服务器当前资源不一致。

时间线：从发布成功到白屏告警

把时间线拉出来，可以看到几个节点是连续的：

• 13:10：前端新版本发布，生成 app.f82d10.js 和新的 index.html。
• 13:12：CDN 刷新完成，新用户访问正常。
• 13:15：白屏率开始上升，错误集中在旧资源 app.9c31a2.js。
• 13:20：确认白屏用户大多曾安装旧 Service Worker。
• 13:26：临时恢复旧哈希资源后，白屏率开始下降。

注意这里的新旧用户差异。新用户直接拿到新入口和新资源；老用户可能被 Service Worker 命中旧入口，入口里仍然指向旧哈希文件。

触发条件：旧入口 HTML 指向已删除的哈希文件

现代前端构建通常会给 JS 和 CSS 加内容哈希，比如：

发布新版本后，入口会变成：

如果部署流程直接删除旧资源，而某些浏览器仍然拿到旧 index.html，它就会继续请求 app.9c31a2.js。服务器上这个文件已经不存在，于是资源 404，页面无法启动。

所以触发条件有两个：

• 旧入口 HTML 仍可能被 Service Worker 或浏览器缓存返回。
• 旧入口引用的哈希资源已经被部署流程清掉。

根因：Service Worker 缓存策略没有版本切换保护

根因不是“用了 Service Worker”，而是缓存策略没有考虑版本切换。常见问题包括：

• 把 index.html 做了 cache-first，导致入口更新不及时。
• 新版本发布时没有通知旧 Service Worker 切换或失效。
• 静态资源目录只保留最新一版，旧哈希文件立即删除。
• 缺少“入口版本”和“资源版本”不一致时的自恢复逻辑。

入口 HTML 和带哈希资源应该按不同策略处理：入口要尽量新，哈希资源可以长缓存；但历史哈希资源至少要保留一段时间，给旧入口完成过渡。

修复动作：恢复旧资源并清理缓存路径

现场优先止血，按顺序处理：

• 从上一版构建产物恢复旧 app.9c31a2.js，让已缓存旧入口的用户能正常启动。
• 发布一版 Service Worker 更新逻辑，入口 HTML 改为网络优先。
• 在页面启动时检测资源加载失败，提示用户刷新并主动清理旧缓存。
• 延长静态资源保留时间，避免旧入口短时间内指向空文件。

self.addEventListener("activate", event => {
  event.waitUntil((async () => {
    const keep = "app-cache-v20260630";
    const names = await caches.keys();
    await Promise.all(
      names.filter(name => name !== keep).map(name => caches.delete(name))
    );
    await self.clients.claim();
  })());
});

这段只是说明清理思路。生产里要结合当前缓存命名、灰度策略和离线能力，不要粗暴删除所有缓存。

防复发：把资源保留和 SW 更新纳入发布门禁

最后把复盘沉淀成发布门禁：

• 入口 index.html 不做长时间 cache-first，优先保证版本新鲜度。
• 带哈希的 JS/CSS 至少保留最近 N 个版本，不随发布立即删除。
• Service Worker 版本切换要有日志和指标，能看到激活数量和失败数量。
• 白屏监控要记录缺失资源 URL，方便确认是不是旧哈希文件 404。
• 发布前用旧版本页面打开、再发布新版本、再刷新，模拟老用户升级路径。
• 资源加载失败时提供用户可恢复路径，例如提示刷新或自动重新拉取入口。

总结一下：前端白屏不一定是 JS 代码本身错了，也可能是入口 HTML、哈希资源和 Service Worker 缓存版本不一致。处理这类问题要先确认“谁返回了旧入口”，再恢复缺失资源、更新缓存策略，并把老用户升级路径纳入发布测试。