当前位置：首页 > 文章列表 > 文章 > 前端 > Vite 前端发布后白屏怎么处理：JS 404、CDN 旧缓存和回滚路径

Vite 前端发布后白屏怎么处理：JS 404、CDN 旧缓存和回滚路径

来源：17golang原创 2026-07-09 11:08:00 0浏览收藏

前端发布上线后，不少用户刷新页面直接看到空白屏幕，控制台里弹出 GET /assets/index-8f3d2a.js 404 类报错，很多人第一反应会误判成后端接口异常。但对 Vite、React、Vue 这类文件名带哈希后缀产物的项目来说，最常见的诱因都是 index.html、JS/CSS 产物版本和 CDN 缓存不同步：用户手里的是旧版 HTML，浏览器拿着旧 HTML 里的旧资源地址发起请求，对应的旧 chunk 早就在线上被清掉了，自然加载不到有效代码，页面直接白屏。

要点速览

发布后白屏先打开浏览器控制台和 Network 面板排查，重点找 JS 404、ChunkLoadError、Failed to fetch dynamically imported module。
如果 HTML 引用的文件在对象存储或静态资源服务里不存在，优先按缓存版本不一致的方向排查。
紧急止血的优先顺序是回滚 index.html、清理 CDN 缓存、恢复已删除的旧产物，不要上来就改业务代码重发。
长期优化方案是保留最近几次的构建产物，HTML 配置短缓存，带哈希后缀的静态文件配置长缓存。

触发信号：白屏常常从 JS 404 开始

这类故障的第一现场一般在浏览器端，而不是后端的日志系统里。用户反馈页面打不开，客服收到的截图只能看到空白页面；值班同学打开开发者工具后，能在 Console 或 Network 面板里看到某个 JS 文件返回 404，或是动态导入的模块加载失败。

Vite 前端发布后白屏时浏览器控制台出现 JS 404 并命中 CDN 旧缓存

先把几个典型的故障信号对齐清楚：

信号	说明	优先动作
`index-xxxx.js 404`	HTML 引用了不存在的构建产物	检查发布产物是否被误清理
`ChunkLoadError`	异步 chunk 加载失败	确认旧 chunk 文件是否还在服务端留存
只有部分用户白屏	CDN、浏览器或灰度版本命中了不同缓存	对比响应头和 CDN 命中节点信息
强刷后页面恢复正常	本地缓存或 CDN 缓存被强制刷新	继续排查整体缓存策略配置

快速判断：先确认 HTML 和产物是不是同一版

不要一上来就重发新版本。先把线上正在生效的 HTML 内容拉下来，看它到底引用了哪些资源，再去静态资源存放位置确认对应文件是否真实存在。

curl -s https://example.com/ | grep -o 'assets/[^"]*\\.js'
curl -I https://static.example.com/assets/index-8f3d2a.js

如果第一条命令能看到旧资源的文件名，第二条请求却返回 404，基本可以判定是 HTML、CDN 或构建产物清理策略出了问题。这里先别急着修改业务代码，因为组件逻辑根本没有机会运行，页面已经卡在资源加载阶段。

还要查看资源的响应头。Cache-Control、Age、ETag、CDN 命中标记都能说明用户拿到的是哪个缓存层的内容。如果 index.html 被设置成长时间缓存，白屏出现的概率会明显升高。

处理步骤：先恢复页面，再清缓存

紧急止血的目标很明确：让用户拿到一套互相匹配的 HTML 和静态资源。只要页面能重新渲染，接口、样式这类小问题可以后续慢慢处理。

推荐按这个顺序处理：

回滚 index.html 到上一个可用版本，让它重新引用对应版本的旧产物。
确认旧 JS/CSS 文件仍在对象存储或静态资源服务里正常留存。
清理 index.html 的 CDN 缓存，必要时清理入口页所在的公开路径。
用无缓存的隐私窗口访问首页，确认 Network 面板里的 JS/CSS 请求都是 200 状态。
如果旧产物已经被删除，先从构建制品库或发布记录恢复对应文件，再清理 CDN 缓存。

很多团队会把静态文件全部覆盖到同一个路径，再顺手清理旧文件。这个操作看起来节省存储空间，实际上风险很高。带哈希的文件名本来就是为了支持长期缓存，旧版本 HTML 在一段时间内仍可能被用户或 CDN 命中，旧 chunk 文件至少要保留几个发布批次的量。

回滚路径：HTML 和静态产物要分开看

前端发布的回滚不只是“把代码退回去”。真正影响用户访问的是入口 HTML 和静态产物。两者可以分开处理：HTML 应该配置短缓存、支持快速回滚；带哈希的 JS/CSS 可以配置长缓存，但不能发布完就立刻删除旧版本文件。

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

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

如果入口页路径不止一个，比如 /、/admin/、/mobile/，回滚时要逐个确认覆盖。只回滚一个入口，另一个入口还引用失效的 chunk，用户仍然会反馈白屏。

告警确认：别等客服截图才知道白屏

前端白屏应该能被自动监控发现。最基础的做法是把资源加载失败、路由初始化失败、首屏渲染超时这类事件上报到监控平台。发布后 5 到 10 分钟内，如果 JS 404 或 ChunkLoadError 指标突然升高，就应该自动提醒值班人员处理。

监听 window.addEventListener('error', ...)，捕获 script 和 link 标签的资源加载失败事件。
监听 unhandledrejection，记录动态导入模块加载失败的异常。
上报信息包含资源 URL、页面 URL、发布版本、用户浏览器信息和 CDN 命中信息。
发布后自动访问首页和关键路由，检查 JS/CSS 资源的响应状态码。

window.addEventListener('error', function (event) {
  var target = event.target;
  if (target && (target.tagName === 'SCRIPT' || target.tagName === 'LINK')) {
    reportAssetError({
      url: target.src || target.href,
      page: location.href,
      release: window.__APP_VERSION__ || 'unknown'
    });
  }
}, true);

这里的上报函数可以直接接入团队已有的前端监控服务，不需要单独搭建一套系统。关键是别只记录“白屏了”这个结果，要把资源 URL 和发布版本信息带上，否则排查时还得从用户截图里猜问题原因。

复盘项：把构建产物保留策略写进发布流程

故障恢复后，最该补全的是发布流程规则，而不是要求值班同学记住“下次操作小心点”。下面几项可以直接加入发布检查环节：

最近 5 到 10 次构建产物全部保留，不自动删除仍可能被引用的哈希后缀文件。
index.html 设置短缓存或协商缓存，避免用户长期命中旧入口文件。
发布顺序先上传新静态资源，再切换 HTML 版本，回滚时按反向顺序操作。
CDN 刷新范围要明确，入口页和静态资源不要合并成一个刷新动作。
发布后自动探测首页、登录页、核心业务路由和所有异步 chunk 文件。

如果项目用了灰度发布机制，还要确认灰度环境和全量环境的静态资源前缀是否一致。灰度 HTML 引用全量资源，或者全量 HTML 引用灰度资源，都会产生一批很难复现的白屏问题。

常见问题

Vite 白屏一定是 CDN 缓存问题吗？

不一定。接口鉴权失败、运行时语法报错、环境变量缺失也会导致白屏。但如果控制台明确打印 JS 或 CSS 404 报错，就应该先按资源版本不一致的方向排查。

为什么强刷能恢复，普通刷新不行？

强刷会绕过一部分浏览器缓存，并重新向 CDN 发起资源请求。普通刷新可能仍然命中本地留存的旧 HTML 或旧 chunk，所以表现会不一致。

带 hash 的 JS 文件需要每次都清 CDN 吗？

通常不需要。带 hash 的文件内容变更后文件名也会同步变化，更适合配置长缓存。真正需要谨慎处理的是入口 HTML 和没有 hash 后缀的公共文件。

旧构建产物要保留多久？

可以按团队发布频率定。一天多次发布的项目，至少保留最近 5 到 10 个批次；低频发布项目可以保留更久，重点是覆盖 CDN 和浏览器缓存可能的最长存活时间。

小结

Vite 前端发布后白屏，先别急着重发代码。打开控制台看有没有 JS 404 报错，再确认 index.html 引用的资源是否还在线上正常留存，是最快的排查路径。足够稳定的发布流程，要做到入口 HTML 可快速回滚、CDN 缓存可控刷新、旧 hash 产物按批次留存、发布后有自动探测和资源错误告警。