更新记录

1.0.0（2026-11-09）

• 首个版本，仅支持 Android（minSdk 24）
• 组件 <zy-face-liveness>：相机预览、人脸框绘制、实时检测、相机录入、抓拍、前后摄像头切换、缩放模式
• 能力：多人检测、1:N 人脸库检索、1:1 比对、RGB 活体、动作活体（眨眼/张嘴/摇头/抬头）、年龄区间/性别/人种、口罩、睁闭眼、表情、人脸质量
• 人脸库持久化到应用目录（特征库 + 名单表分离，名单表由插件自建，支持分页与重命名）

平台兼容性

uni-app(4.72)

uni-app x(4.72)

其他

zy-face-liveness 离线人脸识别 / 活体检测

Android 平台 UTS 插件（uni-app / uni-app x），基于开源引擎方案，全程离线，不依赖任何云服务。

• 支持平台：App-Android（uni-app Vue2/Vue3、uni-app x）
• 最低系统：Android 7.0（API 24）

示例页面

组件用法要点：uts 组件不要 import、也不要写 components 注册，直接用插件 id 作为标签名（<zy-face-liveness>）， 由编译器自动解析到 uni_modules/zy-face-liveness/utssdk/app-android/index.vue。 若用 import Xxx from '@/uni_modules/.../index.vue'，该文件会被 vue-loader 当普通 vue 文件解析， 报 Module parse failed: Unexpected token（<script lang="uts"> 的类型标注无法识别）。

组件依赖 NVLoad / NVLoaded 生命周期，只能用在 nvue 页面（参考 zy-uvccamera 的用法）。

一、快速开始

import { init, detect, compare, register, search, count, listUsers, remove, release } from '@/uni_modules/zy-face-liveness'

// 1) 初始化（首次会解压模型，耗时数秒，必须在页面加载完成之后调用）
init({
  packName: 'Pikachu',
  thresholds: 0.48,      // 1:N 阈值，越大越严格
  maxDetectFaceNum: 5,   // 单帧最多人脸数
  success: (res) => {
    console.log('引擎就绪', res.version)
  },
  fail: (err) => {
    console.error('初始化失败', err.errCode, err.errMsg)
  }
})

1. 识别一张图片的人脸信息

detect({
  image: '/storage/emulated/0/DCIM/a.jpg',  // 本地路径 / file:// / content:// / http(s) / base64
  flags: {
    rgbLiveness: true,   // 默认 true
    quality: true,
    mask: true,
    eyeState: true,
    actions: true,
    attribute: true,
    emotion: true
  },
  success: (res) => {
    console.log('人脸数', res.faceNum)
    const face = res.faces[0]
    console.log('位置', face.rect, '角度', face.angle)
    console.log('活体', face.liveness, '质量', face.quality, '口罩', face.mask)
    console.log('年龄区间', face.ageBracket, '性别', face.gender, '人种', face.race)
    console.log('左眼睁', face.leftEyeOpen, '表情', face.emotion)
    console.log('动作', face.actions) // { blink, jawOpen, shake, headRaise, normal }
  }
})

2. 判断两张图片是否同一人

compare({
  image1: '/sdcard/a.jpg',
  image2: '/sdcard/b.jpg',
  thresholds: 0.48,
  success: (res) => {
    console.log('相似度', res.similarity, res.percentage + '%', '是否同一人', res.same)
  },
  fail: (err) => {
    // 9280005 表示某张图没检测到人脸
  }
})

3. 录入人脸库 + 检索

// 录入（可批量，多张一起提交）
register({
  images: ['/sdcard/a.jpg', '/sdcard/b.jpg'],
  names: ['张三', '李四'],
  success: (res) => {
    res.items.forEach(item => {
      console.log(item.success, item.id, item.name, item.message)
    })
  }
})

// 从人脸库找人
search({
  image: '/sdcard/c.jpg',
  topK: 3,
  success: (res) => {
    if (res.matched) {
      console.log('命中', res.items[0].id, res.items[0].name, res.items[0].similarity)
    }
  }
})

// 名单管理
count({ success: (res) => console.log('人脸库总数', res.count) })
listUsers({ page: 1, pageSize: 20, success: (res) => console.log(res.total, res.users) })
remove({ ids: [3, 4], success: (res) => console.log(res.removed) })

4. 页面卸载时释放

onUnload(() => {
  release({})
})

二、相机组件

<template>
  <view style="flex:1">
    <zy-face-liveness
      ref="faceRef"
      style="width:100%;height:500px;"
      :front="true"
      :auto-start="true"
      :detect-flags="flags"
      @onEvent="onFaceEvent"></zy-face-liveness>

    <button @tap="startRegister">录入当前人脸</button>
  </view>
</template>

<script>
export default {
  data() {
    return {
      // 初始开关（JSON 字符串），也可运行时用 setDetectFlags 修改
      flags: '{"rgbLiveness":true,"recognize":true,"attribute":true}'
    }
  },
  methods: {
    onFaceEvent(e) {
      const detail = e.detail
      // type: loaded / started / stopped / detect / recognize / register / capture / error / flags / scaleType / switchCamera
      if (detail.type === 'detect') {
        const data = JSON.parse(detail.dataJson)
        // data.faceNum / data.faces[]
      }
      if (detail.type === 'recognize') {
        const data = JSON.parse(detail.dataJson)
        console.log('命中', data.faces[0].name)
      }
      if (detail.type === 'register') {
        const data = JSON.parse(detail.dataJson)
        console.log('录入', data.success, data.id, data.name, data.path)
      }
      if (detail.type === 'error') {
        console.warn('相机/引擎错误', detail.code, detail.msg)
      }
    },
    startRegister() {
      this.$refs.faceRef.registerFace({ name: '张三', needBase64: false })
    }
  }
}
</script>

组件 props

组件方法

组件事件 onEvent(e)

e.detail = { type, code, msg, dataJson }，dataJson 需自行 JSON.parse。

三、module API

所有函数统一 { success, fail, complete } 回调，失败为 UniError（errSubject = 'zy-face-liveness'）。

init 参数

FaceInfo 字段

四、错误码

五、性能与最佳实践

1. 只开需要的开关：quality / mask / eyeState / actions / attribute / emotion 每开一项都会增加单帧耗时； 相机实时识别默认只开 rgbLiveness，需要属性时再开。recognize: true 会额外做特征提取 + 检索，最耗性能。
2. 动作活体：不要只看单帧 actions，建议统计 2~3 秒内连续帧（如 blink 命中 ≥1 且 liveness > 0.5 的帧数占比）。
3. RGB 活体：建议连续采集多帧，活体帧数 > 非活体帧数时判定为真人（单帧容易误判）。
4. 注册质量：录入图不要戴口罩 / 墨镜，人脸尽量正对、光线均匀；detect 先看 quality > 0.5 再注册。
5. init 时机：首次 init 会解压模型（Pikachu 约 17MB），务必在页面可交互后再调用并给 loading。

六、存储与已知限制

• 特征库：Android/data/<包名>/files/zy_face_liveness/face_feature.db（由引擎持久化）
• 名单表：Android/data/<包名>/files/zy_face_liveness/face_names.db（插件自建，id → name）
• 卸载应用或清除数据会丢失人脸库，请按需导出备份
• 若通过其他途径（直接操作引擎）增删特征，名单表不会同步；以 count() 返回的特征数为准
• cameraId / physicalCameraId（多摄指定）当前版本预留未生效，仅支持前后摄像头切换
• 仅支持 Android