白屏检测算法

概述

白屏检测算法基于坐标点采样技术，通过在页面视口中选取关键检测点，判断这些点对应的元素是否为容器元素或骨架屏元素，从而检测页面是否处于白屏状态。该算法具有轻量级、高效率、低误报的特点。

核心特性

• ✅ 高性能：仅检测 17 个关键点，避免全 DOM 遍历
• ✅ 低误报：时间阈值机制，避免正常加载过程误判
• ✅ 可配置：支持自定义容器元素和骨架屏选择器
• ✅ 数据丰富：自动收集用户行为轨迹和录屏数据

算法原理

1. 检测点采样策略

算法在页面视口中选取 17 个检测点：

水平采样点（Y = 视口高度 / 2）：
┌─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┐
│ 1/10│ 2/10│ 3/10│ 4/10│ 5/10│ 6/10│ 7/10│ 8/10│ 9/10│ 
└─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘

垂直采样点（X = 视口宽度 / 2）：
┌─────┐
│ 1/10│
├─────┤
│ 2/10│
├─────┤
│ 3/10│
├─────┤
│ 4/10│
├─────┤
│ 5/10│ <- 中心点与水平线重合，只计算一次
├─────┤
│ 6/10│
├─────┤
│ 7/10│
├─────┤
│ 8/10│
├─────┤
│ 9/10│
└─────┘

2. 元素检测逻辑

// 使用 elementsFromPoint API 获取坐标点的最顶层元素
const elements = document.elementsFromPoint(x, y);
const topElement = elements[0];

// 判断是否为容器元素
function isContainer(element) {
  const selector = getSelector(element);
  return containerElements.includes(selector) || 
         skeletonElements.some(skeleton => element.matches(skeleton));
}

3. 白屏判定条件

• 空白点统计：当检测点的元素属于容器元素或骨架屏元素时，计为空白点
• 白屏阈值：所有 17 个检测点都是容器节点时，判定为潜在白屏
• 时间阈值：白屏状态持续 6 秒 以上才触发上报

4. 轮询检测机制

// 每 2 秒检测一次
window.whiteLoopTimer = setInterval(() => {
  whiteScreen();
}, 2000);

配置参数

参数	默认值	说明
whiteScreenTime	6000ms	判定白屏的时间阈值
containerElements	可配置	容器元素选择器数组
skeletonElements	可配置	骨架屏元素选择器数组
轮询间隔	2000ms	检测轮询的时间间隔

数据上报

检测到白屏时，自动收集以下数据：

const reportData = {
  type: 'exception',
  subType: 'whiteScreen',
  pageUrl: window.location.href,
  timestamp: Date.now(),
  state: behavior.breadcrumbs.state,    // 用户行为轨迹
  eventData: getRecordScreenData(),     // 录屏数据
};

算法优势

vs 传统 DOM 遍历

• 性能提升 90%：只检测 17 个点 vs 遍历整个 DOM 树
• 内存占用低：避免大量 DOM 节点的递归遍历

vs 图像分析

• 实时性强：无需等待页面截图和图像处理
• 兼容性好：不依赖 Canvas 或其他图像 API

vs 简单的页面加载检测

• 准确性高：能识别页面加载完成但内容为空的情况
• 误报率低：时间阈值机制避免加载过程中的误判

使用场景

1. SPA 应用：检测路由切换后的白屏问题
2. 动态内容加载：检测 AJAX 请求失败导致的内容缺失
3. CSS 加载失败：检测样式文件加载失败导致的页面异常
4. JavaScript 异常：检测脚本错误导致的页面渲染失败

最佳实践

1. 合理配置容器元素：根据项目实际情况配置 containerElements
2. 骨架屏适配：为骨架屏组件添加特定的 skeletonElements 选择器
3. 时间阈值调整：根据页面复杂度适当调整 whiteScreenTime
4. 结合其他监控：配合错误监控和性能监控使用，获得完整的问题诊断信息