·更新于 2026年11月22日· 40 次浏览 NuxtVue3BUG解决工程实践前端稳定性

Nuxt 3 发版后旧页面 chunk 404:我用路由重试、版本探测和强制刷新修好白屏

发版后最怕用户停在旧页面,一切路由就白屏。这篇记录我从 chunk 404 出发,如何用加载失败捕获、路由重试、版本比对和刷新兜底,把白屏收敛成一次尽量无感的恢复。

Nuxt 3 发版后旧页面 chunk 404:我用路由重试、版本探测和强制刷新修好白屏 封面
ZHOUYI

作者

ZHOUYI

有一次晚上发版后,群里有人反馈博客突然白屏。控制台一看,是某个路由懒加载的 chunk 返回 404。原因并不玄学:用户浏览器里还拿着上一次构建生成的入口文件,发版后文件名 hash 变了,旧入口继续按旧路径请求新路由代码,自然找不到。

为什么旧页面会加载不存在的 chunk

Nuxt 3 页面常见是按需加载。发版会生成新的资源文件名,但已打开的页面不会自动替换内存里的旧入口。如果用户长时间停留,再点导航,就会用旧入口里的路径去拿资源。这类问题不是接口挂了,也不是组件写错,而是发布策略和浏览器缓存之间的时间差。

我最后采用的处理链路

  1. 第一步:路由切换失败时先捕获,判断是否像动态 chunk 加载失败。
  2. 第二步:对疑似错误做一次短延迟重试,排除瞬时网络抖动。
  3. 第三步:重试仍失败,请求轻量版本接口,比较当前构建版本和线上最新版本。
  4. 第四步:确认版本变化后,用 location.replace 刷新到目标路由,并限制刷新次数。

版本探测和刷新兜底

版本探测可以很简单:构建时生成一个版本号,服务端接口返回它。前端在捕获到疑似 chunk 错误后再查询,不要每次路由都查,避免浪费。刷新也不是万能药:如果用户网络本来就差,盲目刷新可能更糟,所以我只在版本确实变化时兜底。

js
export default defineNuxtPlugin(({ $router }) => {
  $router.onError((err, to) => {
    const msg = String(err?.message || '');
    if (/chunk|import/i.test(msg)) {
      checkAppVersion().then((changed) => {
        if (changed) location.replace(to?.fullPath || '/');
      });
    }
  });
});

几个容易踩的坑

  • 不要把普通接口超时也当成 chunk 失效,错误判断要看加载失败特征。
  • 刷新后要能回到用户原本想去的页面,否则体验像丢导航。
  • 如果版本号接口也失败,宁可提示重试,也不要无限刷新。
  • 线上观察时保留原始错误信息,方便区分资源 404 和 JS 运行时报错。

“这类白屏修到最后,拼的不是某个神奇 API,而是把发布、缓存、路由错误和用户体验串起来。先捕获,再判断,最后温和刷新,比粗暴报错更贴近真实用户。”

Guestbook

留言

若这篇文章也曾停在你心上,留一行字吧,我会看的。

先确认一下邮箱

多这一步,是为了少些机器骚扰,也让我能更踏实地读每一条真人写下的字。验证码 10 分钟内有效;同一邮箱 60 秒内只能发一封。

本文留言

共 0 条已加载 0 条

这里还静悄悄的——愿意做第一个留下脚印的人吗?