白屏问题诊断
从 document/静态资源、JavaScript 启动错误、root mount/render、CSS 可见性、路由数据与主线程阻塞分层定位页面白屏，并用 Console、Network、Elements 和 Performance 建立证据链。
#debug
#growing
#frontend
#browser
[!info] related notes
白屏问题诊断
先定义白屏是哪一类
- HTML 文档本身没成功返回；
- HTML 有了，但 JS/CSS 资源失败；
- JS 启动时抛异常；
- 应用没 mount；
- DOM 已存在但 CSS 让它不可见；
- 路由/数据 pending 或错误态没有 UI；
- 主线程被长期阻塞，看起来像白屏。
不要把这些问题统一叫“打包坏了”。
第一步：Document 是否成功
Network 先看主 document：
- status；
- response body；
- redirect；
- Content-Type。
如果 document 都失败，不必先看 React/Vue。
第二步：关键资源是否加载
检查：
- entry JS；
- CSS；
- dynamic chunks；
- module import；
- asset path / base URL。
典型错误：404、MIME type、CSP、chunk version mismatch。
第三步：Console 是否有启动异常
如果资源都 200，Console 查第一条真正异常：
- module load error；
- uncaught exception；
- hydration/mount error；
- config/env undefined。
不要被后续级联报错淹没。
第四步：Elements 判断“没渲染”还是“看不见”
检查 root：
- 是否为空；
- 是否已有 DOM；
- display/visibility/opacity；
- 尺寸是否为 0；
- 内容是否被 overlay 遮住。
DOM 存在就说明方向已经从“应用没运行”转到 layout/style/rendering。
第五步：路由与数据状态
SPA 常见：
- route guard 一直 pending；
- lazy chunk 失败；
- API error 没有 fallback；
- loading boundary 没 UI；
- auth redirect loop。
Network 与 Router/state log 联动确认。
第六步：Performance 看是否只是迟迟没画出来
如果主线程有数秒 Long Task，页面可能不是逻辑白屏，而是 render 被阻塞。
这时进入 长任务调试。
诊断矩阵
| 证据 | 优先方向 |
|---|---|
| document 失败 | server/CDN/routing |
| entry chunk 404 | build/deploy/base path |
| Console 首条异常 | app bootstrap/runtime |
| root 空 | mount/render/router |
| DOM 有但不可见 | CSS/layout/overlay |
| API/route pending | data/auth/router |
| 主线程长任务 | performance |
迁移检查
场景：生产环境部署后首页白屏，刷新 Network 看到 HTML 200，但一个 hashed JS chunk 404。
闭卷回答：
- 为什么不用先查组件代码？
- 应该检查 build artifact、HTML 引用、CDN cache/deploy 的哪些边界？
- 如果 chunk 200，但 Console 报 runtime exception，排查方向怎样变化？
- 如果 DOM 已存在但不可见，又该切到哪个面板？
Digital Biome