🛡️ FaceGuard - 轻量级人脸识别采集工具

FaceGuard 是一个基于 face-api.js 封装的 JavaScript 类，旨在帮助开发者快速集成人脸识别与图像采集功能到 Web 应用中。

只需几行代码，即可实现：

• 自动加载 AI 模型
• 打开摄像头并预览
• 实时人脸检测
• 高置信度自动采集
• 用户操作引导（如“请向前移动”）
• 返回 Base64 图像用于上传

💡 适用于：人脸登录、实名认证、考勤打卡、身份核验等场景。

🚀 快速开始

1. 安装依赖

npm install face-guard

face-api.js 需要预训练模型文件。建议将模型放在项目的 public/models/ 目录下：
public/
 └── models/
      ├── tiny_face_detector_model-weights_manifest.json
      ├── face_landmark_68_model-weights_manifest.json
      └── face_recognition_model-weights_manifest.json

🔗 模型下载地址： 👉 https://github.com/justadudewhohacks/face-api.js/tree/master/weights 下载整个weights文件夹 放置public/models/下即可 🔗 备用下载地址： 👉 https://github.com/gaoxiaozhu/faceApi_model.git 直接克隆models放置在public/models/下即可

### 2. 引入 FaceGuard

```javascript
import FaceGuard from 'face-guard';

HTML 结构

<video id="video" width="720" height="560" autoplay muted></video>
<div id="feedback" style="margin: 10px 0; color: #d32f2f; font-size: 16px;"></div>
<button id="stopBtn">停止采集</button>

JavaScript 使用

import  FaceGuard  from 'face-guard';

// 创建实例
const faceGuard = new FaceGuard({
  modelPath: '/models', // 模型路径
  // 人脸识别成功回调
  onFaceDetected(imageBase64) {
    console.log('✅ 人脸采集成功！', imageBase64);
    // 可上传到服务器
    fetch('/api/verify-face', {
      method: 'POST',
      body: JSON.stringify({ image: imageBase64 }),
      headers: { 'Content-Type': 'application/json' }
    });
  },

  // 用户操作反馈（可用于 UI 提示）
  onFeedback(message) {
    document.getElementById('feedback').textContent = message;
  },

  // 错误处理
  onError(error) {
    console.error('❌ FaceGuard 错误:', error);
    alert('无法访问摄像头，请检查权限或重试');
  }
});

// 启动识别
const video = document.getElementById('video');
await faceGuard.start(video);

// 停止识别（例如用户点击“重新采集”）
document.getElementById('stopBtn').addEventListener('click', () => {
  faceGuard.stop();
});

📚 API 参考

new FaceGuard(options)

| 参数名 | 类型 | 默认值 | 描述 | | --- | --- | --- | --- | | modelPath | string | '/models' | 模型文件路径 | | onFaceDetected | function | - | 人脸识别成功回调，返回 Base64 图像 | | onFeedback | function | - | 用户操作反馈回调 | | onError | function | - | 错误处理回调 |

# faceGuard.start(videoElement)
启动人脸识别与图像采集，参数为视频元素。

# faceGuard.stop()
停止人脸识别与图像采集。

工作流程

[启动] → 加载模型 → 请求摄像头权限 → 显示视频预览 → 每 100ms 检测一次人脸 → 无人脸 → “未检测到人脸” → 置信度低 → “请向前/向左移动” → 置信度 > 0.9 → 自动采集图像 → 调用 onFaceDetected → 停止

⚠️ 注意事项 必须调用 stop() 在组件销毁或页面跳转时务必调用 faceGuard.stop()，否则摄像头将持续开启，造成资源浪费

// Vue 示例
onUnmounted(() => {
  faceGuard.stop();
});

// React 示例
useEffect(() => {
  return () => faceGuard.stop();
}, []);