元数据
| id | vite-chunkloaderror | 收录 | 2026-08-29 |
|---|---|---|---|
| 问题域 | 构建与部署 | 主题分组 | 构建与部署 |
| 适用工具 | vite-deploynginx · 外部工具 | ||
症状
发布后部分用户白屏、刷新又偶尔恢复；控制台报 ChunkLoadError: Loading chunk N failed；动态 import 请求的带 hash 资源返回 404。
原因
版本错位：浏览器缓存的旧入口 HTML 仍引用旧版本 hash chunk，而新发布已删除旧资源 → 动态 import 404 → 模块加载失败 → 整页白屏。
解法
1. 发布顺序：先资源后入口（hash 静态资源先上线，入口 HTML 最后切换）
2. 旧资源保留过渡期（至少覆盖一个发布周期）
3. nginx SPA fallback 不能吞静态资源 404（try_files 先匹配真实文件，再回退 index.html）
4. CDN 与 Service Worker 遵循同一套版本一致性规则
验证证据
- 本地实测（2026-08-29）：vite 5.4.21 两次 build，chunk hash 变化（feature-DP5yDwy7.js → feature-PcJGFbac.js）；服务器只部署 v2 资源时旧 chunk HTTP 404（复现）；保留旧资源后新旧页面均 HTTP 200（解法成立）。
- 实测复现日志（2026-08-29）
来源与证据
素材来源：https://juejin.cn/post/7678324462626471946
验证证据：Evidence details kept locally (2026-08-29)