face-detector-lite

基于 TensorFlow.js 与 BlazeFace 的轻量级浏览器人脸检测库，默认内置模型与依赖，适用于现代 Web 项目与 Vue 3。


在线体验

- 演示站点：https://doudou-start.github.io/face-detector/
- CDN 加载：
- jsDelivr：https://cdn.jsdelivr.net/npm/face-detector-lite/dist/face-detector.standalone.min.js
- unpkg：https://unpkg.com/face-detector-lite/dist/face-detector.standalone.min.js
- npm 安装：npm install face-detector-lite

功能亮点

- 纯前端运行：无需后端服务，支持完全离线环境。
- 即开即用：包内自带 TF.js、BlazeFace 与模型文件，无需额外下载。
- 接口简洁：链式事件、易理解的配置项，兼容 TypeScript。
- Vue 支持：提供现成的 Vue 3 组件与插件包装。

快速开始

$3

``html


`

$3

`html

`

$3

`bash
npm install face-detector-lite
`
`js
import FaceDetector from 'face-detector-lite';

const detector = new FaceDetector({
showVideo: true,
// libUrls: { tf: '/node_modules/face-detector-lite/libs/tf.min.js', blazeface: '/node_modules/face-detector-lite/libs/blazeface.js' },
// modelUrl: '/node_modules/face-detector-lite/models/blazeface/model.json'
});

await detector.initialize();
detector.startDetection();
`
> 默认 offlineOnly = true。若希望自动回落到 CDN，可显式设置 offlineOnly: false。

Vue 3 集成


`js
import { FaceDetectorView } from 'face-detector-lite/vue';
// 或 import FaceDetectorPlugin from 'face-detector-lite/vue';
// app.use(FaceDetectorPlugin);
`
`vue

`

> 组件默认会隐藏视频 (show-video=false)、渲染一个占位容器 (render-container=true)，并在挂载完成后自动开始检测 (start-on-mounted=true)。

如需自定义行为，可传入对应属性：

`vue
:show-video="true"
:render-container="false"
:start-on-mounted="false"
:interval="150"
:camera="{ facingMode: 'environment', width: 1280, height: 720 }"
@initialized="onReady"
@detected="onDetected"
@no-face="onNoFace"
@error="onError"
/>
`

API 概览

$3

`js
new FaceDetector(options?)
`
常用配置
- showVideo：是否渲染摄像头画面，默认 false。
- videoContainer：自定义视频容器，可为选择器或 DOM 实例。
- interval：检测间隔（毫秒），默认 100。
- modelUrl：自定义模型地址，默认加载内置模型。
- libUrls：自定义 TF.js / BlazeFace 资源路径。
- offlineOnly：是否禁止访问 CDN，默认 true。
- camera：摄像头参数 { facingMode, width, height }。

实例方法
- initialize()：初始化摄像头与模型。
- startDetection() / stopDetection()：开始或停止检测。
- detectFace()：执行一次检测，返回是否识别到人脸。
- destroy()：释放摄像头与模型资源。

事件链式调用
- onInitialized(fn)、onFaceDetected(fn)、onNoFace(fn)、onError(fn)。

运行模式说明


- npm / Bundler：默认使用包内 libs/ 与 models/ 资源；可改写 libUrls、modelUrl 指向自托管路径。
- CDN 版本：dist/face-detector.standalone.min.js 已自带所有依赖，直接插入