简介一套基于 face-api.js 的人脸采集实战源码包面向 Web 前端与 JavaScript 开发者用于在浏览器端快速搭建视频人脸采集环境解决摄像头调用、实时检测与数据保存等常见开发难题。项目先调用摄像头获取视频流再通过 face-api.js 完成逐帧人脸检测和 68 点特征定位并按清晰度与角度打分筛选出合格人脸图像存储覆盖从采集到输出的完整流程。压缩包共 28 个文件以 JS 逻辑文件为主配合 JSON 配置、HTML 页面与 LESS 样式同时内置 tiny_face_detector、ssd_mobilenetv1、face_landmark_68、face_recognition 等模型的 shard 权重文件总大小约 9.94MB。目前已有 257 人学习下载源码按模块划分包含构建与检查配置同时给出清晰的浏览器端机器学习模型加载路径适合二次开发。通过学习此项目开发者可以掌握基于 TensorFlow.js 与人脸模型的集成思路、视频帧异步处理技巧并在此基础上继续扩展人脸登录、安全验证、表情分析等功能。1. 人脸采集这个标题在解决什么问题做人脸登录或人脸考勤的前端经常被一个问题卡住模型都能跑通就是采不到能用的脸。不是没检测到就是拍糊了要不抓到了半张脸。标题里说的“人脸采集”不是单纯按一下快门而是基于 face-api.js 在浏览器里完成“打开摄像头、实时检测人脸、筛选合格帧、提取特征向量”这一整套动作。face-api.js 是 JavaScript 生态里最常用的浏览器端人脸检测识别库配合项目源码里的模型文件和页面能做成一个可直接演示的采集模块。我按一线工程的常见做法把实现路径、关键参数和排错方法讲清楚适合前端开发、全栈工程师和正在做毕业设计的同学。2. face-api.js 人脸采集的理论基础与模型选型2.1 浏览器里的人脸处理管线从摄像头帧到特征数组人脸采集不是把摄像头里的一帧原样保存那么简单。face-api.js 的典型调用链是const detections await faceapi .detectAllFaces(video, new faceapi.TinyFaceDetectorOptions()) .withFaceLandmarks() .withFaceDescriptors();detectAllFaces返回一个数组每个元素包含三个维度的数据detection里有边界框坐标和置信度landmarks是 68 个面部关键点descriptor是一个 128 维的 Float32Array。这三者正好对应“脸在哪、五官在哪、脸长什么样”。后端做人脸比对时真正参与计算的是 descriptor而不是图片像素本身。如果项目只做“预览 拍照”可以不用withFaceDescriptors但标题里既然出现了“采集”我建议把特征向量一并算出来。原因很简单照片可以重拍特征向量却是一张人脸在模型空间的稳定表示。保存它之后下次任何人脸比对都能直接复用不用重新跑模型。withFaceLandmarks除了画关键点还能用于判断头部的偏转角度和清晰度这在后面过滤废帧时非常有用。所以最小可用管线就是这三件套这也是人脸采集项目源码里最常见的初始化组合。从实现层面看faceapi.detectAllFaces每次调用都会把当前帧送入 TensorFlow.js 后端。face-api.js 底层默认优先使用 WebGL如果运行环境不支持 WebGL会退回 CPU 后端检测耗时会从几十毫秒涨到几百毫秒。排查“为什么卡”时先看浏览器 Console 有没有 backend 相关日志再考虑是否要换成体积更小的模型。2.2 模型文件部署本地静态资源方式与 CDN 方式的取舍face-api.js 的源码包可以通过 npm 安装但模型权重文件不会随包分发。项目源码里的 models 目录通常放的就是这些.json和.bin权重文件。加载方式有两种实际项目的取舍也不同。部署方式优点缺点适用场景本地静态目录离线可用、版本可控、局域网部署方便需要配置路径和 MIME 类型生产环境、内网采集CDN 引入零配置、适合快速演示外网依赖、可能有 CORS 限制demo、临时页面生产环境我更推荐本地静态目录因为模型文件版本必须和前端代码配套。一旦 CDN 更新了权重格式前端可能拿到维度不一致的 descriptor线上比对全部失败。常见做法是服务器根目录放一个models/文件夹然后await Promise.all([ faceapi.nets.tinyFaceDetector.loadFromUri(/models), faceapi.nets.faceLandmark68Net.loadFromUri(/models), faceapi.nets.faceRecognitionNet.loadFromUri(/models) ]);loadFromUri不是 npm 包里的相对路径而是从浏览器地址栏拼接出来的完整 URL。如果页面在http://localhost:8080下打开这句会请求http://localhost:8080/models/tiny_face_detector_model-weights_manifest.json。如果你是使用 HBuilder 搭建的纯静态工程注意不要双击index.html用file://协议打开否则模型文件会因跨域限制加载失败。正确做法是右键项目选择“运行 - 浏览器运行”或者在项目根目录执行python -m http.server 8080让浏览器通过 HTTP 访问页面。2.3 模型加载的初始化参数TinyFaceDetectorOptions 与输入分辨率模型加载完成后检测器的参数直接影响采集成功率。TinyFaceDetector 是 face-api.js 里为前端实时场景准备的轻量模型典型初始化方式const faceDetectorOptions new faceapi.TinyFaceDetectorOptions({ inputSize: 320, scoreThreshold: 0.5 });inputSize表示送入模型前的图像缩放边长。值越大保留的人脸细节越多检测越准但推理耗时增加值太小远处的人脸会出现漏检。我一般以 320 为起点如果摄像头离人较远调到 416如果追求 60fps可以降到 224但低于 160 会频繁漏检。scoreThreshold控制人脸置信度阈值默认 0.5。单人在摄像头前这种场景 0.5 足够复杂背景可以降到 0.3但要接受更多误检。另一个常用选择是 SSD MobileNet v1对应new faceapi.SsdMobilenetv1Options({ minConfidence: 0.5 })。它比 TinyFaceDetector 更稳但模型文件更大、首帧加载更慢实时采集场景一般不优先选它。face-api.js 还支持 MTCNN但需要加载三个阶段的级联权重速度更慢我在项目里基本不用。选 TinyFaceDetector 的理由是它在 WebGL 和 CPU 后端下都能保持可用和后端逻辑解耦适合做采集模块。3. 基于 face-api.js 实现人脸采集的最小可运行项目3.1 获取摄像头视频流getUserMedia 的浏览器兼容写法摄像头采集的第一步不是 face-api.js 提供的能力而是浏览器标准的navigator.mediaDevices.getUserMedia。页面里要有一个video元素承载视频流async function startCamera() { if (!navigator.mediaDevices?.getUserMedia) { throw new Error(当前环境不支持摄像头); } const stream await navigator.mediaDevices.getUserMedia({ video: { width: { ideal: 640 }, height: { ideal: 480 }, facingMode: user }, audio: false }); const video document.getElementById(video); video.srcObject stream; await video.play(); return stream; }width和height里的ideal表示期望值浏览器会自动选择最接近这个值的摄像头分辨率而不是强制必须使用某个值。facingMode: user对应前置摄像头后置摄像头可以传environment。参数设为audio: false可以避免同时申请麦克风权限减少权限弹窗对用户体验的干扰。这段代码需要页面运行在 HTTPS 或 localhost 下否则getUserMedia会直接抛错。video 元素建议加上muted和playsinline属性muted是为了规避浏览器自动播放策略playsinline是为了防止 iOS Safari 全屏播放视频流。采集页一般不需要真实播放声音所以这两个属性不会有副作用。3.2 实时人脸检测与自动采集的核心循环拿到视频流后需要在一个循环里持续检测人脸并判断当前帧是否值得采集。很多项目源码里的做法是let captureCount 0; async function captureLoop() { if (video.readyState 2 || video.videoWidth 0) { requestAnimationFrame(captureLoop); return; } const faces await faceapi .detectAllFaces(video, faceDetectorOptions) .withFaceLandmarks() .withFaceDescriptors(); if (faces.length 1) { const face faces[0]; if (isAngleOk(face) isSharpEnough(face)) { await uploadFace(face); captureCount 1; if (captureCount 5) { stopCamera(); } } } requestAnimationFrame(captureLoop); }这里使用detectAllFaces而不是detectSingleFace目的是判断镜头里是否只有一个人。如果faces.length不等于 1说明镜头里没人、有陌生路过的人或者有两个人同时入镜这几种情况都应拒绝采集。requestAnimationFrame会在每次浏览器重绘前回调但真正限制循环速度的是await faceapi.detectAllFaces的耗时。检测完成后才会安排下一帧相当于做了一层天然背压不需要额外加锁。采集到 5 张合格图片就停止摄像头这个数字来自“质量排序”的常见需求人脸姿态可能有轻微变化多采几张再交给后台选状态最好的一张成功率比单张采集高很多。在采集过程中页面上通常会叠加一个半透明面框提示用户正对屏幕面框的参考位置可以取video中心偏上一些因为人脸在画面下半部分时容易出现俯拍效果。3.3 采集质量相关的 3 个必调参数参数所在位置作用典型值调整方向inputSizeTinyFaceDetectorOptions模型输入分辨率320远距离调大至 416追求速度调小scoreThresholdTinyFaceDetectorOptions人脸置信度阈值0.5误检多时调高漏检多时调低采样间隔业务循环代码控制两次采集的间隔300 毫秒网络差时调大抓拍场景调小采集质量不能只靠模型参数业务侧参数同样重要。minFaceWidth和maxFaceWidth也是项目源码里经常出现的字段用来过滤离镜头过远或过近的人脸。人脸框宽度小于 80 像素时通常看不清大于 300 像素时可能已经贴脸表情变形都不是合格的人脸照片。可以在配置对象里集中管理const captureConfig { inputSize: 320, scoreThreshold: 0.5, minFaceWidth: 80, maxFaceWidth: 300, sampleInterval: 300, maxFrames: 5 };如果连续两帧的人脸框中心点位移太大说明人正在移动此时采集到的图片大概率模糊。“人脸静止判断”可以在业务代码里用两次detection.box.x和detection.box.y的差值实现。位移超过 5 像素就跳过这一帧等于给采集加了一个运动检测器。这些参数共同决定采集到的图片是否“优质”也是题目里“优质项目实战”这个表述最常落到的地方。4. 采集结果的后端持久化与人脸质量验证4.1 用 Canvas 导出人脸图片并生成 Blob检测到人脸后不能直接把整个 video 帧传给后台最好把人脸区域裁剪出来。裁剪时通常把检测框向外扩大一点保留额头和下巴边缘方便后端后续做活体判断或人工审核。function cropFace(video, face) { const box face.detection.box; const scale 1.2; const x Math.max(0, box.x - box.width * (scale - 1) / 2); const y Math.max(0, box.y - box.height * (scale - 1) / 2); const w Math.min(video.videoWidth - x, box.width * scale); const h Math.min(video.videoHeight - y, box.height * scale); const canvas document.createElement(canvas); canvas.width w; canvas.height h; const ctx canvas.getContext(2d); ctx.drawImage(video, x, y, w, h, 0, 0, w, h); return new Promise((resolve) { canvas.toBlob((blob) resolve({ blob, width: w, height: h }), image/jpeg, 0.92); }); }ctx.drawImage这里用了 9 参数形式前 4 个参数表示从原视频中截取的矩形后 4 个参数表示画到 canvas 上的位置和大小。因为人脸框可能落在视频边缘直接用box.x会得到负坐标所以必须用Math.max和Math.min做边界裁剪。scale 1.2表示把裁剪范围扩大 20%这样人脸周围留出一点余量特征比对时不容易被截断。canvas.toBlob是异步回调第三个参数是图片格式第四个参数是 JPEG 质量。0.92 是一个折中值0.9 以下在高压缩比下会出现明显的 JPEG 块0.95 以上体积增长明显但清晰度提升有限。Blob 比 Base64 更适合上传可以直接塞进 FormData也不需要手动处理 MIME 类型。4.2 清晰度与人脸角度过滤的落地做法人脸合格度不能只靠置信度判断。face-api.js 没有自带模糊检测接口但可以借助 Canvas 的像素数据实现一个轻量清晰度评分function sharpnessScore(canvas) { const context canvas.getContext(2d); const { data, width, height } context.getImageData(0, 0, canvas.width, canvas.height); let total 0; let count 0; for (let y 0; y height - 1; y 1) { for (let x 0; x width - 1; x 1) { const index (y * width x) * 4; const gray 0.299 * data[index] 0.587 * data[index 1] 0.114 * data[index 2]; const nextIndex ((y 1) * width x) * 4; const grayNext 0.299 * data[nextIndex] 0.587 * data[nextIndex 1] 0.114 * data[nextIndex 2]; total Math.abs(gray - grayNext); count 1; } } return total / count; }这个函数计算相邻像素的灰度梯度绝对值平均值值越大说明边缘越锐利。它没有引入额外算法库只用getImageData和一层循环对单人脸的裁剪图来说开销可控。校验项常用阈值说明清晰度2060低于 15 基本判定为虚焦左右眼连线角度不超过 8 度大于 10 度判定为歪头人脸框占比画面宽度的 20%60%过滤过远或过近的无效人脸头部的倾斜角度可以用landmarks里的眼睛坐标计算。getLeftEye()和getRightEye()返回的是 6 个关键点数组取第一个点作为眼角参考点function headAngle(face) { const leftEye face.landmarks.getLeftEye(); const rightEye face.landmarks.getRightEye(); const dx rightEye[0].x - leftEye[0].x; const dy rightEye[0].y - leftEye[0].y; return Math.atan2(dy, dx) * 180 / Math.PI; }Math.atan2返回值在 -180 到 180 度之间正脸时左右眼几乎处于同一条水平线角度接近 0。如果绝对值超过 8 度采集模块应该提示用户“请正对摄像头”而不是强行保存当前帧。4.3 特征向量入库与去重检索的前后端协作人脸照片和特征向量应当分开上传。照片放在对象存储或服务器磁盘descriptor 存入数据库作为比对索引。前端上传的代码async function uploadFace(face) { const { blob } await cropFace(video, face); const form new FormData(); form.append(image, blob, face_${Date.now()}.jpg); form.append(descriptor, JSON.stringify(Array.from(face.descriptor))); await fetch(/api/face, { method: POST, body: form }); }注意face.descriptor是 Float32Array直接JSON.stringify会得到一个带索引的对象而不是数组后端接收后无法直接使用。必须先用Array.from转成普通数组再交给 JSON 序列化。后端在 Node.js 环境下可以用原生的req.formData()解析app.post(/api/face, async (req, res) { const form await req.formData(); const descriptor JSON.parse(form.get(descriptor)); const nearest await FaceModel.findClosest(descriptor); if (nearest.distance 0.55) { return res.status(409).json({ duplicate: true }); } await FaceModel.insert(form.get(image), descriptor); res.json({ ok: true }); });这里的 0.55 是欧氏距离阈值。face-api.js 的 FaceMatcher 默认阈值是 0.6看起来方便但实际项目中会因为摄像头、光线和模型版本出现偏差。负责落地时建议先采集同一个人的 20 组数据计算这 20 个 descriptor 两两之间的距离把阈值设在这些距离的最大值附近才能降低重复采集概率。5. 项目源码实战中的报错排错与封装技巧5.1 常见报错模型加载 404、module 脚本 MIME 类型与 CORS模型加载 404 是项目源码里最常出现的问题。错误信息显示tiny_face_detector_model-weights_manifest.json找不到时先不要改代码用浏览器的 Network 面板看请求 URL。如果请求被指向了/src/models而不是服务器的/models说明loadFromUri的参数写错了。另一个高频报错是Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of text/html。这句话的意思是浏览器请求某个.js文件时服务器返回了index.html。多半是 Nginx 或 SPA 服务器把未匹配的请求全部 fallback 到了首页。处理办法是在 Nginx 里对location /models单独配置.bin返回application/octet-stream.json返回application/json不要走 index.html 转发规则。5.2 内存泄漏与连续采集的收尾人脸采集流程结束后必须释放摄像头资源否则浏览器的“摄像头”指示灯会一直亮着再次进入采集页面也会因为资源被占用而失败。标准写法function stopCamera(stream) { if (stream) { stream.getTracks().forEach((track) track.stop()); } const video document.getElementById(video); if (video) { video.srcObject null; } }stream.getTracks()会返回麦克风轨道和视频轨道这里只需要视频但统一stop()不会出错。采集循环里的requestAnimationFrame也要做状态判断不能在stopCamera之后继续执行。比较稳妥的做法是在循环开头检查一个isRunning标记停止时把标记置为 false再取消当前帧。5.3 把采集逻辑封装成可复用的采集控制类项目源码到了收尾阶段我会把采集逻辑封装成一个独立类避免散落在一堆页面函数里。最精简的形态class FaceCapture { constructor({ video, detectorOptions, onFace }) { this.video video; this.detectorOptions detectorOptions; this.onFace onFace; this.running false; } async loadModels(uri) { await Promise.all([ faceapi.nets.tinyFaceDetector.loadFromUri(uri), faceapi.nets.faceLandmark68Net.loadFromUri(uri), faceapi.nets.faceRecognitionNet.loadFromUri(uri) ]); } handleFrame async () { if (!this.running) return; const faces await faceapi .detectAllFaces(this.video, this.detectorOptions) .withFaceLandmarks() .withFaceDescriptors(); if (faces.length 1) { this.onFace?.(faces[0]); } requestAnimationFrame(this.handleFrame); } start() { this.running true; this.handleFrame(); } stop() { this.running false; } }使用这个类时onFace回调里只负责做质量判断和上传不掺入界面绘制逻辑方便在多个页面复用。封装完成后再加一个现实技巧把 descriptor 先通过IndexedDB暂存在本地等用户点击“完成采集”后批量上传这样摄像头预览不会因为单张图片上传被阻塞采集节奏也会更流畅。本文还有配套的精品资源点击获取