HTML 本身不能做人脸检测，它只是标记语言，不具图像处理或摄像头访问能力；实际依赖 JavaScript 调用 getUserMedia + face-api.js 或 TensorFlow.js 等库，在 HTTPS/localhost 下经用户授权后加载同源模型并处理视频流。
HTML 本身不能做 Face Detection，它没有图像处理能力，也不具备访问摄像头或运行模型的权限。所有“HTML 人脸检测”实际都是靠 JavaScript 调用浏览器 API（如 MediaDevices.getUserMedia） + 第三方 JS 库（如 @tensorflow/tfjs、face-api.js）或后端 API 实现的。
为什么直接在 HTML 里写 <face-detect> 不行
HTML 是标记语言，只负责结构和语义，不执行逻辑。所谓“HTML 人脸检测”是常见误解，源于把整个前端流程（HTML 页面 + JS 脚本 + 摄像头流 + 模型推理）笼统称为“HTML 实现”。浏览器中真正干活的是 JavaScript，且必须满足以下条件：
- 页面通过 HTTPS 或
localhost提供服务（getUserMedia在非安全上下文被禁用） - 用户明确授予权限（摄像头访问需用户主动点击允许）
- 加载的 JS 模型需适配 Web 环境（如量化版 TensorFlow.js 模型，而非 Python 的
cv2.CascadeClassifier） - 模型加载耗时长，需处理
loading状态，否则detect调用会报model not loaded
face-api.js 在浏览器里跑人脸检测的最小可行步骤
face-api.js 封装了预训练模型（SSD Mobilenet V1），适合前端轻量部署。但它依赖 tf.js，且必须显式加载模型文件（不能只引用 CDN JS）：
- 引入 CDN：
<script src="https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@4.20.0/dist/tf.min.js"></script>和<script src="https://cdn.jsdelivr.net/npm/face-api.js@1.9.0/dist/face-api.min.js"></script> - 准备模型路径：从
face-api.js官方仓库下载weights/目录（含tiny_face_detector_model.weights.bin等），放到项目静态资源下，比如/models/ - 加载模型时指定路径：
await faceapi.nets.tinyFaceDetector.loadFromUri('/models')（不是loadFromUri('https://.../models')，路径必须与页面同源） - 检测前确保 canvas 已渲染且 video 元素有有效流：
video.readyState === 4，否则detectAllFaces返回空数组
用 TensorFlow.js 自定义模型时的兼容性陷阱
如果你用 Python 训练了自定义人脸检测模型并转成 tfjs 格式，注意三类常见失败点：
立即学习“前端免费学习笔记（深入）”；
- 输入尺寸硬编码：Web 模型必须接受动态分辨率（如
[null, null, 3]），不能固定为[640, 480, 3]，否则tf.loadGraphModel加载成功但predict报Invalid shape - 预处理差异：Python 端常用
cv2.resize+cv2.cvtColor，而 tf.js 需手动归一化（除以 255）、BGR→RGB 转换，漏掉任一环，检测框全偏移 - GPU 后端启用问题：Chrome 默认用 WebGL，但某些集成显卡会 fallback 到 CPU，导致 200ms/帧 → 2000ms/帧；可加
tf.setBackend('webgl')并监听tf.getBackend()确认
模型加载慢、摄像头权限被拒、canvas 尺寸与 video 不一致——这三个问题占实际调试时间的 80%。别急着调 minConfidence 或改 NMS 阈值，先用 console.log(video.videoWidth, canvas.width) 对齐尺寸，再看控制台有没有 Failed to load resource: net::ERR_BLOCKED_BY_CLIENT（广告拦截器屏蔽了模型文件）。
