更新记录

1.0（2026-11-03）

V1.0可实时检测是否有人脸

平台兼容性

其他

人脸检测 Demo 使用说明

1. Demo 简介

本 Demo 是一个基于 Uni-app + UTS + CameraX + ML Kit 的 Android 离线人脸检测示例。

主要功能：

• 调用设备摄像头进行实时人脸检测，默认优先使用前置摄像头。
• 不在页面显示相机预览，只在后台分析相机画面。
• 根据检测结果回调“检测到人脸”或“未检测到人脸”状态。
• 检测到双眼、鼻子和嘴巴等关键特征完整后，提示保持约 1 秒并自动抓拍。
• 在页面中显示最近一次抓拍图片和最近事件时间。
• 支持手动停止检测，页面隐藏、退出或 Activity 销毁时释放相机资源。
• 检测在本机完成，不依赖后端服务；抓拍图片仅在页面内临时显示，不主动保存到相册或本地文件。

本 Demo 仅支持 Android App，不支持 H5、微信小程序和 iOS。

2. 运行环境要求

• HBuilderX：建议使用支持 Vue 3 和 UTS 插件的较新版本。
• Android 设备：Android 8.0（API 26）及以上。
• 设备需要具有可用摄像头，建议使用真机测试。
• 首次编译需要联网下载 CameraX、ML Kit 等 Maven 依赖。
• 手机需要开启“开发者选项”和“USB 调试”，并通过 USB 连接电脑。

主要依赖版本：

androidx.camera:camera-camera2:1.3.4
androidx.camera:camera-lifecycle:1.3.4
com.google.mlkit:face-detection:16.1.7

3. 在 HBuilderX 中运行 Demo

3.1 导入项目

1. 解压 Demo 压缩包。
2. 打开 HBuilderX。
3. 选择“文件 → 导入 → 从本地目录导入”。
4. 选择包含 manifest.json 的 Demo 根目录。
5. 等待 HBuilderX 完成项目加载。

3.2 制作并运行自定义基座

项目包含 face-detector UTS 原生插件，不能直接使用不含该插件的标准基座。

1. 将 Android 手机连接到电脑，确认 HBuilderX 能识别设备。
2. 选择“运行 → 运行到手机或模拟器 → 制作自定义调试基座”。
3. 等待自定义基座制作完成。
4. 选择“运行 → 运行到手机或模拟器 → 运行到 Android App 基座”。
5. 选择刚制作的自定义调试基座，等待应用安装并启动。

如果 HBuilderX 在运行时自动提示制作自定义基座，按提示执行即可。

修改 UTS 插件代码、原生依赖或 Android 权限后，需要重新制作自定义调试基座。仅修改 Vue 页面通常不需要重新制作。

3.3 打包独立 APK

如需脱离 HBuilderX 单独安装和演示：

1. 在 HBuilderX 中选择“发行 → 原生 App-云打包”。
2. 选择 Android 平台并配置证书。
3. 完成云打包后，将生成的 APK 安装到 Android 设备。

unpackage/debug/android_debug.apk 属于调试基座，不建议作为正式发布安装包。

4. 页面操作说明

1. 打开应用后，点击“开始检测”。
2. 首次使用时，在系统弹窗中允许应用使用相机。
3. 将面部对准前置摄像头，保证光线充足并完整露出双眼、鼻子和嘴巴。
4. 页面会根据检测过程显示以下状态：

5. 点击“停止检测”可结束分析并释放相机资源。

本 Demo 在一次连续检测到完整五官并完成抓拍后，会保留该抓拍状态；如需重新检测，可停止后再次开始。

5. 在其他 Uni-app 项目中使用插件

5.1 复制插件

将以下目录完整复制到目标项目根目录：

uni_modules/face-detector

复制后的结构：

目标项目
├─ uni_modules
│  └─ face-detector
│     ├─ package.json
│     └─ utssdk
│        ├─ interface.uts
│        └─ app-android
│           ├─ AndroidManifest.xml
│           ├─ config.json
│           └─ index.uts
├─ pages
└─ manifest.json

5.2 配置 Android 要求

确认目标项目的 Android minSdkVersion 不低于 26，并配置相机权限：

<uses-permission android:name="android.permission.CAMERA" />

插件已包含相机权限和 Maven 依赖配置，正常通过 Uni Modules 方式集成时无需重复添加依赖。

5.3 调用插件

<script>
import { startFaceDetect, stopFaceDetect } from '@/uni_modules/face-detector'

export default {
  methods: {
    startDetection() {
      startFaceDetect((event) => {
        console.log('事件类型：', event.type)
        console.log('提示信息：', event.message)
        console.log('时间戳：', event.timestamp)

        if (event.imageBase64) {
          console.log('已收到抓拍图片')
        }
      })
    },

    stopDetection() {
      stopFaceDetect()
    }
  },

  onUnload() {
    stopFaceDetect()
  }
}
</script>

集成后需要重新制作自定义调试基座或重新打包。

6. 回调接口说明

开始检测

startFaceDetect(callback)

重复调用时，如果检测已经运行，不会重复启动摄像头。

停止检测

stopFaceDetect()

停止分析、注销回调并释放相机、检测器和线程资源。

回调参数

图片格式示例：

data:image/jpeg;base64,/9j/4AAQSkZJRg...

可直接赋值给 Uni-app 的 <image> 组件 src 属性进行显示。

7. 常见问题

7.1 提示“未授予相机权限”或“用户拒绝了相机权限”

打开手机“设置 → 应用管理 → 当前应用 → 权限”，允许相机权限后重新启动检测。

7.2 提示摄像头启动或绑定失败

• 确认设备摄像头可正常使用。
• 关闭正在占用摄像头的其他应用。
• 重新连接设备并重启 Demo。
• 使用模拟器时，确认已为模拟器配置可用摄像头。

7.3 一直提示未检测到人脸

• 增加环境亮度，避免逆光。
• 将面部正对摄像头并保持适当距离。
• 完整露出双眼、鼻子和嘴巴，避免口罩或手部遮挡。

7.4 插件编译失败或调用方法不存在

• 确认 face-detector 位于项目根目录的 uni_modules 下。
• 确认使用支持 UTS 的 HBuilderX 版本。
• 清理项目缓存后重新运行。
• 重新制作自定义调试基座，不要继续使用旧基座。

7.5 首次构建下载依赖失败

检查电脑网络、代理和 Maven 仓库访问情况，然后重新编译。依赖下载完成后，人脸检测功能本身不需要连接后端服务。