在省市级心理普查项目中，前端开发团队有时会收到基层学校关于页面无法正常显示的反馈，表现往往是屏幕一片空白，除了浏览器默认框架外没有任何业务内容。
当研发人员在公司网络环境下尝试复现时，页面通常能够正常加载。缺乏完善的前端白屏监控体系，技术团队难以了解远端设备上的真实渲染情况。
本文将探讨如何在现代心理测评前端架构中，引入轻量的探测机制，实现对白屏等异常情况的及时捕捉与定位。
导致白屏的主要因素
在采用 Vue 或 React 等现代框架的单页应用（SPA）中，页面初始状态往往是一个空的 <div id="app"></div>，实际的 DOM 元素依赖 JavaScript 文件（如 app.js）动态渲染。
导致最终用户看到白屏的原因主要包括两方面：
- 静态资源加载失败：在网络条件较差的环境下，关键的
app.js文件下载超时或失败，导致 HTML 结构无法被后续逻辑填充。 - 运行时异常（JS Error）：虽然 JavaScript 文件加载成功，但在执行特定业务逻辑时发生了未捕获的错误。在 SPA 架构中，一个未妥善处理的异常可能导致整个组件树的渲染流程中断，进而导致页面白屏。
基于 MutationObserver 的骨架屏侦测
为了在用户反馈前主动发现白屏问题，可以在 HTML 的初始结构中植入一段轻量且无外部依赖的原生 JavaScript 监控脚本。
在橙星云前端基建团队的实践中，我们采用了基于 MutationObserver API 的监控方案，用于监听根节点 <div id="app"></div> 的变化。
监控脚本会设定一个时间阈值（例如 5 秒）。当页面开始加载时计时器启动，如果 Vue/React 框架在指定时间内成功挂载，并在 #app 内部生成了足够数量的子 DOM 节点（或者替换了默认的骨架屏），探针会察觉到这一变化并取消计时器。
若超过阈值时间后，#app 内部仍未发生预期的结构变化，监控脚本便判定页面出现白屏异常，随后向监控服务端发送一条包含关键上下文信息的报警日志，例如：{"type": "WHITE_SCREEN", "url": "...", "ua": "...", "network": "3G"}
异常堆栈的捕获与 SourceMap 还原
除了知道“发生了白屏”，研发团队更需要了解问题的具体成因。
全局注册 window.onerror 和监听 unhandledrejection 事件是收集前端异常的基础手段。当发生导致渲染崩溃的错误时，监控脚本会将错误堆栈（Error Stack）一并上报。
然而，线上环境运行的通常是经过 Webpack 或 Vite 压缩混淆后的代码。直接上报的报错信息往往难以解读，例如：TypeError: a.b is undefined at app.js:1:2048。
为了能够定位到具体的源代码位置，团队可以在 CI/CD 构建流水线中引入 SourceMap 管理机制。每次发版时，构建系统会将包含源码映射关系的 SourceMap 文件安全地上传至内部监控服务器，而不暴露给外网。当监控服务器收到线上报错坐标 app.js:1:2048 时，可利用 SourceMap 自动进行反向解析，准确提示出发生异常的源文件路径、具体行号及相关变量，从而大幅降低故障排查的成本。
在复杂多变的网络和设备环境下，前端的稳定性监控至关重要。通过结合 MutationObserver 对 DOM 挂载状态的监测、全局异常捕获以及 SourceMap 的精确解析，技术团队能够更加主动地发现和定位线上异常，提升系统的整体健壮性。