前端发版后页面白屏:一次入口 chunk 被改名的复盘
前端发版后页面白屏:一次入口 chunk 被改名的复盘
现象
一次小范围前端修复上线后,登录页背景正常、资源请求全部返回 200,但页面中央的登录卡片没有出现。浏览器控制台没有 404,也没有明显的语法错误,只有应用根节点为空。
这类现象很容易被误判为接口故障或缓存没刷新。实际排查时,先看两个事实:
1. 所有 JavaScript、CSS 请求都是 200;
2. 页面 DOM 已加载,但 `#app` 内部没有任何内容。
当“资源成功”与“页面空白”同时出现时,问题通常不在网络,而在模块图或运行时初始化。
根因
该项目使用 Vite 构建。发布目录里有两个关键文件:
• `index.html` 引用入口 chunk,例如 `index-y2sUVFaj.sms7.js`;
• 某个懒加载页面 chunk 内部又通过相对路径 import 同一个入口 chunk。
为了绕开 `Cache-Control: max-age=31536000, immutable`,我把入口 chunk 复制成新文件名,并让 `index.html` 指向新文件。表面上只是一个 URL 变化,实际却把同一个模块变成了两个不同的模块实例:
• 浏览器加载 `index-...fix.js`,创建了一份 Vue 运行时;
• 懒加载页面仍 import `index-...sms7.js`,又创建了第二份 Vue 运行时。
两份运行时各自维护自己的组件注册表、响应式系统和当前实例。登录组件在第一份运行时里注册,却在第二份运行时的上下文里渲染,最终表现为组件树无法挂载,根节点保持空白。
为什么普通刷新和清缓存无效
因为问题不是旧缓存,而是同一页面内同时存在两个模块实例。即使所有请求都命中最新文件,只要入口 chunk 与懒加载 chunk 对同一个模块使用了不同 URL,模块图就会分裂。清缓存、换浏览器、无痕模式都不会改变这个结果。
正确的缓存处理方式
方案一:全量重新构建
修改源码后重新构建,让构建工具重新计算所有 chunk 的 hash,并同步更新 `index.html` 与模块间的 import。代价是需要完整构建,但一致性最好。
方案二:只给懒加载 chunk 加版本查询参数
如果只想替换一个懒加载页面,可以保留入口 chunk 文件名,只修改入口 chunk 中对目标懒加载文件的引用:
import("./DashboardView-DRaqW2yi.sms7.js?v=1116")
这样目标文件会以新 URL 加载,而它内部对入口 chunk 的相对 import 仍解析回原文件名,模块实例不会分裂。入口文件本身不需要改名。
不要做的事
不要单独重命名入口 chunk。入口 chunk 被多处引用,改名后必须保证所有引用方都同步指向新名字;只改 `index.html` 一定会留下旧引用。
快速诊断清单
出现“资源 200 但页面空白”时,可以按以下顺序检查:
1. 打开开发者工具 Network,确认入口 chunk 与懒加载 chunk 是否都成功加载;
2. 在 Console 执行 `document.querySelector('#app').innerHTML.length`,确认是否为空;
3. 检查入口 chunk 与懒加载 chunk 是否引用了同一个模块的不同 URL;
4. 搜索构建产物中的旧文件名,确认没有残留引用;
5. 对比 `index.html`、入口 chunk、懒加载 chunk 三者的引用关系。
回滚与验证
本次处理采用最小回滚:
• 将 `index.html` 的引用恢复为原入口文件名;
• 将入口 chunk 内对懒加载页面的引用恢复为原文件名;
• 删除临时复制出来的文件;
• 重新加载页面,确认登录卡片恢复显示;
• 再按业务路径逐页打开,确认没有其他模块图分裂。
验证时不能只看首页是否出现内容,还要进入实际业务页,确认懒加载模块、状态管理和路由都正常。模块图分裂有时只影响某一条路由,首页正常并不代表修复完整。
经验总结
1. 带内容哈希的静态资源适合长期缓存,但发布流程必须保证引用关系一致。
2. 入口 chunk 是模块图的根,不适合为了绕过缓存而单独改名。
3. “请求全部 200”只能证明网络层成功,不能证明模块图完整。
4. 遇到白屏先判断是资源缺失、运行时异常,还是模块实例分裂,再决定回滚或重建。
5. 小范围热修可以给懒加载资源加查询参数,但入口文件应保持稳定。
前端发布的风险往往不在代码本身,而在构建产物之间的隐式引用。把引用关系当作发布契约来检查,能避免很多“看起来已经上线、实际却没有渲染”的问题。
- 点赞
- 收藏
- 关注作者
评论(0)