前端发版后页面白屏？一套解决用户停留旧页面问题的完整方案

场景

在单页面应用（SPA）项目中，有一个问题非常常见，但又经常被低估：系统明明已经发布了新版本，部分用户却依然停留在旧页面中继续操作。

大多数时候，这种状态并不会立刻出问题，所以团队往往不太在意。但一旦用户继续进行路由跳转、访问懒加载页面，或者触发某些依赖新资源的操作，就可能出现下面这些现象：

页面跳转失败
控制台出现 Loading chunk failed
Failed to fetch dynamically imported module
页面局部报错，甚至直接白屏
用户不知道系统已经更新，只会觉得"网页坏了"
新功能已经上线，但用户却迟迟体验不到

这类问题在线上系统里并不少见，尤其是管理后台、教学平台、运营平台这类用户会长时间挂着页面不刷新的 SPA 应用。如果处理不好，不仅影响用户体验，还会带来很多"难定位、难复现"的线上问题。

这篇文章，我想系统讲清楚三件事：

为什么 SPA 发版后，旧页面容易出问题
这类白屏问题的根因到底是什么
如何从前端运行时、缓存策略和部署方式三个层面，设计一套完整的解决方案

一、把问题链路拆开看，就很清楚了

这个问题的完整链路可以概括为：

js 复制代码

用户打开旧页面
   ↓
系统发布新版本
   ↓
用户仍然停留在旧页面中
   ↓
用户触发路由跳转 / 懒加载页面
   ↓
浏览器请求某个 chunk 资源
   ↓
旧资源已失效或请求地址不匹配
   ↓
动态 import 失败
   ↓
页面报错、跳转失败甚至白屏

也就是说，这不是某一个孤立 bug，而是一个典型的版本切换时机问题。

二、解决思路：从三个层面一起治理

这个问题不能只靠某一个点状方案解决。更合理的方式，是从以下四个层面同时考虑：

1. 让用户知道"线上有新版本了""建议刷新页面"

也就是建立版本检测机制 、更新提示机制。

2. 在资源加载失败时自动自救

也就是建立chunk 加载失败兜底机制。

3. 从缓存层降低问题发生概率

也就是建立缓存与发布治理策略。

下面分别展开说。

方案一：建立版本检测机制

整个机制可以这样设计：

构建时把版本号注入到 index.html
当前页面启动后读取 HTML 中的版本号，作为"当前版本"
定时重新请求最新的 index.html，解析其中的版本号，作为"线上最新版本"
如果两者不同，则提示用户刷新页面

完整示例：

html 复制代码

<meta name="app-version" content="20260317-abc123" />

js 复制代码

function getCurrentVersion() {
  return document
    .querySelector('meta[name="app-version"]')
    ?.getAttribute('content');
}

async function fetchLatestVersionFromHtml() {
  const res = await fetch(`/index.html?t=${Date.now()}`, {
    cache: 'no-store'
  });
  const html = await res.text();

  const match = html.match(
    /<meta\s+name=["']app-version["']\s+content=["']([^"']+)["']/
  );

  return match ? match[1] : null;
}

// 发现新版本后，友好地提示用户刷新
function showUpdateDialog() {
  const ok = window.confirm('系统已更新，是否立即刷新页面？');
  if (ok) {
    window.location.reload();
  }
}

async function checkVersion() {
  try {
    const currentVersion = getCurrentVersion();
    const latestVersion = await fetchLatestVersionFromHtml();

    if (currentVersion && latestVersion && currentVersion !== latestVersion) {
      showUpdateDialog();
    }
  } catch (err) {
    console.error('版本检测失败:', err);
  }
}

checkVersion();
setInterval(checkVersion, 5 * 60 * 1000);

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible') {
    checkVersion();
  }
});

方案二：捕获 chunk 加载失败，作为最终兜底

如果说"版本检测 + 刷新提示"是在事前预防 ，

那么"chunk 加载失败自动恢复"就是最关键的事后兜底。

这一层非常重要，因为现实中总会遇到这样的情况：

版本检测还没来得及执行
用户刚好在检测间隔内点击了菜单
服务端刚完成发布
某个懒加载 chunk 已经失效

这时候，问题已经发生了。

如果没有兜底机制，用户就会直接看到报错或白屏。

常见错误形式

不同构建工具、浏览器环境下，报错信息可能略有差异，但常见的有：

Loading chunk xxx failed
ChunkLoadError
Failed to fetch dynamically imported module

这类错误本质上都可以理解为：

动态加载的资源拿不到了。

监听全局错误

可以通过以下方式统一拦截：

js 复制代码

function isChunkLoadError(error) {
  const message = error?.message || error?.reason?.message || '';
  return (
    message.includes('Loading chunk') ||
    message.includes('ChunkLoadError') ||
    message.includes('Failed to fetch dynamically imported module')
  );
}

监听 error：

js 复制代码

window.addEventListener('error', (event) => {
  if (isChunkLoadError(event.error || event)) {
    handleChunkLoadError();
  }
});

监听 unhandledrejection：

js 复制代码

window.addEventListener('unhandledrejection', (event) => {
  if (isChunkLoadError(event.reason || event)) {
    handleChunkLoadError();
  }
});

使用 vite 则不用监听全局错误

vite官网已经提供了预加载错误的事件，可以直接使用

js 复制代码

// 监听 vite 预加载错误，如果发生错误，则重新加载页面
window.addEventListener('vite:preloadError', () => {
  window.location.reload();
});

自动刷新一次，但一定要防止死循环

如果遇到这类错误，可以尝试自动刷新页面一次。

因为刷新后，浏览器会重新请求最新的 index.html 和资源入口，大多数情况下问题就能恢复。

js 复制代码

function handleChunkLoadError() {
  const key = 'app_chunk_reload_once';

  if (!sessionStorage.getItem(key)) {
    sessionStorage.setItem(key, '1');
    alert('系统资源已更新，正在为您刷新页面');
    window.location.reload();
  } else {
    console.error('刷新后仍然失败，请提示用户手动刷新或联系管理员');
  }
}

页面正常加载成功后清理标记：

js 复制代码

window.addEventListener('load', () => {
  sessionStorage.removeItem('app_chunk_reload_once');
});

为什么只自动刷新一次

因为如果失败原因不是"版本切换"，而是：

网络异常
CDN 故障
资源服务器不可用
权限拦截

那么无限刷新只会让问题更严重，甚至让用户完全无法操作。

所以最佳实践是：

自动刷新一次尝试恢复
如果仍失败，再提示用户手动处理或联系支持人员

方案三：缓存策略要正确，否则问题会被放大

很多时候，问题不是前端代码没写，而是缓存策略没配好。

一个很典型的原则是：

入口文件要尽快更新，静态资源要放心缓存，版本文件要实时可读。

1）index.html 不要强缓存

index.html 是整个 SPA 的入口。

如果它被长时间缓存，用户就可能始终拿不到新的资源入口映射。

推荐策略：

no-cache
或更严格的 no-store

例如 Nginx：

js 复制代码

location = /index.html {
    add_header Cache-Control "no-cache, no-store, must-revalidate";
}

2）带 hash 的 js/css 可以强缓存

这类资源天然适合长期缓存，因为文件名已经包含内容签名。

只要内容变化，hash 就会变，浏览器就会自动拉新文件。

例如：

js 复制代码

location /assets/ {
    add_header Cache-Control "public, max-age=31536000, immutable";
}

这样可以显著提升加载性能。

总结

回到最初的问题：

前端 SPA 发版后，为什么用户停留在旧页面会导致白屏？又该如何更好地解决？

答案是：

因为 SPA 页面会长期运行在浏览器中，而新版本发布后静态资源文件名、资源映射和懒加载 chunk 都可能发生变化。如果用户仍停留在旧页面中继续操作，就很容易在后续资源请求中触发加载失败，从而导致页面报错甚至白屏。

而更好的解决方式，不是单纯依赖"让用户手动刷新"，而是建立一套完整的更新治理方案：

版本检测：前端主动感知线上是否已更新
刷新提示：让用户在合适时机切换到新版本
异常兜底：chunk 加载失败时自动刷新恢复
缓存优化：保证入口及时更新、资源合理缓存

如果只能先做一步，我最建议优先落地的是：

捕获 chunk 加载失败并自动刷新一次

因为它最直接解决"白屏止血"问题。

如果想把体验做得更完整，再逐步补上版本检测、刷新提示和部署优化。