face-api.js中TinyFaceDetector的Box构造函数错误排查

错误直接原因 #

这个错误的核心是TinyFaceDetector在高频扫描时返回了全为null的人脸边界框（Bounding Box），而后续依赖该框的withFaceLandmarks逻辑没有处理空值情况，直接将null参数传入了Box构造函数，触发类型校验错误。

深层原因分析 #

• 高频扫描的帧处理冲突：200ms间隔的检测请求，移动端浏览器可能还未完成前一帧的图像处理，导致当前帧的图像数据不完整（比如部分像素未加载），TinyFaceDetector无法识别出人脸，返回空的bbox。
• 轻量模型的稳定性局限：TinyFaceDetector为了轻量化牺牲了部分检测精度，在人脸快速移动、姿态变化或光线波动的场景下，更容易出现检测失败，返回无效的空结果。
• 边界情况未处理：代码中缺少对人脸检测结果有效性的校验，没有判断bbox参数是否合法，直接进入后续的关键点检测流程。

排查验证步骤 #

1. 日志定位：在detectFace调用后添加日志，打印每次返回的bbox数据，确认错误触发时确实是{"x": null, "y": null, "width": null, "height": null}，同时检查对应帧的画面是否存在人脸移出、黑屏等异常。
2. 空值拦截测试：临时添加判断逻辑，当bbox的任一参数为null时，跳过withFaceLandmarks的调用，观察错误是否消失。
3. 设备性能对比：在不同性能的移动端设备上测试，看错误出现频率是否和设备性能正相关，验证是否是帧处理不及时导致的。

优化方案（保留TinyFaceDetector的前提下） #

• 增加结果校验：在调用withFaceLandmarks前，先校验bbox的有效性：

  const detectionResult = await detectFace(/* 参数 */);
  if (detectionResult && detectionResult.box && detectionResult.box.x !== null && detectionResult.box.y !== null && detectionResult.box.width > 0 && detectionResult.box.height > 0) {
    // 执行withFaceLandmarks逻辑
  } else {
    // 处理检测失败的情况，比如跳过当前帧
  }
  

• 串行化帧处理：避免并发发起检测请求，确保上一次detectFace完全执行完成后，再调度下一次检测，比如用Promise链式调用替代固定间隔的定时器：

  async function scanLoop() {
    try {
      await detectAndProcessFrame();
    } catch (e) {
      // 捕获并处理错误
    }
    setTimeout(scanLoop, 200);
  }
  

• 调整模型参数：适当提高TinyFaceDetector的confidenceThreshold（比如从默认的0.5调到0.6），过滤低置信度的无效检测结果，减少空bbox的返回。

内容的提问来源于stack exchange，提问作者Chrissisbeast