更新记录

1.0.0（2026-11-12）

• 首个版本：基于虹软 ArcFace 5.0 增值版 SDK 的离线人脸识别插件（注册 / 检索 / 比对均在本机完成）
• 激活与引擎：requestPermissions / getDeviceFinger / activeOnline / activeOffline / isActivated / customFaceDataPath / init(options)（path 指定人脸库目录）
• 图片能力：getImageFace / imageFaceRegister / batchRegister / faceCompare（1:N）
• 1:1 比对：faceCompare11（两张图片）/ faceCompareWithUser（图片 vs 库内人员）/ compareFeature（特征）， 统一返回 similar / pass / threshold
• 人脸库：增删查清 + 本地持久化（特征与注册头像落盘，init 自动回灌）
• nvue 相机组件 <zy-ArcFacePro>：CameraX 预览、人脸框、活体、1:N 识别、相机内注册、前后摄像头切换
• demo：pages/arcfacepro/arcfacepro.vue（API）、pages/arcfacepro/arcfacepro-camera.nvue（组件）

平台兼容性

uni-app(4.72)

uni-app x(4.72)

其他

zy-ArcFacePro

安卓虹软 ArcFace 5.0（增值版）离线人脸识别 UTS 插件：本地注册、本地检索、本地比对，全程无需联网推理。

特性

• 激活：在线激活（activeKey + appId + sdkKey）、离线激活（.dat 授权文件）、设备指纹、激活状态查询
• 人脸库（本地持久化）：图片注册、批量注册、删除、清空、按 id 查询、全部查询、数量统计
• 图片能力：单图人脸信息（年龄 / 性别 / 口罩 / 活体 / 3D 角度 / 人脸框）、单图注册、1:N 比对
• 1:1 比对：两张图片比对、图片与库内指定人员比对、两个特征直接比对（均返回相似度 + 是否达标）
• 相机组件：CameraX 预览 + 实时人脸框 + 活体检测 + 1:N 识别 + 相机内注册 + 自定义提示文案 + 前后摄像头切换
• 无需联网识别：推理全部在本机完成，特征与人脸头像只保存在应用私有目录

平台支持

• minSdkVersion：21
• 架构：armeabi-v7a、arm64-v8a
• 依赖：config.json 已声明全部三方依赖与仓库，无需手动配置

安装

1. 把 zy-ArcFacePro 整个目录放入项目的 uni_modules/；
2. 由于插件带原生 so 与三方 SDK，标准基座无法使用，必须打自定义基座或云打包；
3. config.json 已声明三方依赖（CameraX 等）与所需权限（相机 / 网络 / 手机状态 / 媒体读取）， 无需额外配置。

体积提示：人脸 SDK 约 173MB（每个 ABI 的 libarcsoft_face.so 约 105MB，模型已编译进 so）， 插件目录本身不含二进制，构建时自动拉取；打出的 apk 会显著变大， 只需单架构时可在打包时只勾选 arm64-v8a。

权限说明：targetSdkVersion >= 33 时不再申请 READ_EXTERNAL_STORAGE（系统会直接抛 IllegalArgumentException），requestPermissions 会按 targetSdkVersion 自动改用 READ_MEDIA_*。

激活流程

1. 调用 requestPermissions 拿到所需运行时权限；
2. 调用 getDeviceFinger 拿到设备指纹；
3. 到 虹软开放平台 创建应用，用设备指纹 + 包名申请 appId / sdkKey / activeKey；
4. 调用 activeOnline({ appId, sdkKey, activeKey }) 激活（同一 activeKey 有激活次数限制，成功后可不再调用）；
5. 调用 init({ path }) 初始化引擎（组件内也会自动初始化；path 可选，用于指定人脸库目录）。

Module API

所有方法都是 (options?, callback) 风格，回调 res = { code, message, data }，code === 0 表示成功。

url 支持：本地绝对路径、file://、content://（相册选择）、http(s)://、base64（可带 data:image/jpeg;base64, 前缀）。

数据结构

type ArcFaceImageFaceInfo = {
  age: number        // -1 未知
  gender: number     // 1 男 / 0 女 / -1 未知（虹软原始值）
  mask: number       // 1 佩戴口罩 / 0 未佩戴 / -1 未知
  liveness: number   // 1 真人 / 0 非真人 / -1 未知
  face3D: { yaw: number, roll: number, pitch: number }
  face: { top: number, bottom: number, left: number, right: number, width: number, height: number }
}

type ArcFaceRegisterFaceInfo = {
  userId: string
  userName: string
  faceId: number      // 特征在引擎内的 id
  imagePath: string   // 注册头像本地路径
  registerTime: number
  featureData: string // 特征 Base64
  imageBase64?: string
}

示例

import {
  requestPermissions, getDeviceFinger, activeOnline, init,
  getImageFace, imageFaceRegister, faceCompare, getAllFace, getFaceCount
} from '@/uni_modules/zy-ArcFacePro'

requestPermissions((res) => console.log('权限', res.code, res.data.grantedList))

getDeviceFinger((res) => {
  if (res.code === 0) console.log('设备指纹', res.data.info)
})

activeOnline({ appId: 'xxx', sdkKey: 'yyy', activeKey: 'zzz' }, (res) => {
  if (res.code !== 0) return uni.showToast({ title: res.message, icon: 'none' })
  init({}, (r) => console.log('引擎版本', r.data.version, '人脸库', r.data.count))
  // 需要自定义人脸库目录时：init({ path: '/sdcard/xxx/faceDB' }, (r) => {})
})

// 图片注册
imageFaceRegister({ url: '/sdcard/face/zhangsan.jpg', id: '1001', name: '张三' }, (res) => {
  console.log(res.code, res.data.user)
})

// 1:N 比对
faceCompare({ url: '/sdcard/face/test.jpg', similar: 0.85 }, (res) => {
  if (res.code === 0) console.log('命中', res.data.user.userName, res.data.similar)
})

1:1 比对

三种用法共用一套返回语义：比对流程本身成功就返回 code === 0，是否同一人由 data.pass 决定 （等价于 data.similar >= data.threshold）。只有取图失败、未检出人脸、提特征失败才返回错误码 （-102 未发现人脸、-10002 文件不存在、-10003 url 有误、-106 id 未注册）。

import { faceCompare11, faceCompareWithUser, compareFeature } from '@/uni_modules/zy-ArcFacePro'

// 两张图片各取面积最大的人脸比对
faceCompare11({ url: '/sdcard/a.jpg', url2: '/sdcard/b.jpg', similar: 0.85 }, (res) => {
  if (res.code !== 0) return console.log('比对失败', res.message)
  console.log('相似度', res.data.similar, res.data.pass ? '同一人' : '不是同一人')
})

// 现场照片 vs 工号对应的人（只比这一条记录，不走 1:N 检索，结果与人脸库规模无关）
faceCompareWithUser({ url: '/sdcard/live.jpg', id: '1001', similar: 0.85 }, (res) => {
  if (res.code === 0 && res.data.pass) console.log('核验通过', res.data.user.userName)
})

// 特征对特征（特征来自注册记录 / onFaceResult / 服务端下发）
compareFeature({ feature1: featureA, feature2: featureB, similar: 0.85 }, (res) => {
  console.log(res.data.similar, res.data.pass)
})

相机组件

只在 nvue 页面 中可用（page.nvue），标签即插件 id（SFC 模板中大小写敏感，须与插件 id 完全一致）：

<zy-ArcFacePro
  ref="camera"
  class="camera"
  :config="config"
  :auto-start="true"
  @onInitResult="onInitResult"
  @onFaceResult="onFaceResult"
  @onError="onError"></zy-ArcFacePro>

属性

config.camera：

config.video：

方法

所有方法最后一个参数为 callback(res)，res = { code, message, data }。

事件

onFaceResult.detail：trackId status code message userId userName faceId imagePath registerTime similar faceSize featureData imageBase64 compareImageBase64 registerImageBase64 failFaceImageBase64 failImageBase64。

组件示例

<template>
  <view style="flex:1;">
    <zy-ArcFacePro ref="camera" style="width:750rpx;height:800rpx;" :config="config"
      @onInitResult="onInitResult" @onFaceResult="onFaceResult"></zy-ArcFacePro>
    <button @click="registerFace">注册当前人脸</button>
  </view>
</template>

<script>
export default {
  data() {
    return {
      config: {
        camera: { facing: 1, size: [1280, 720] },
        video: { similar: 0.8, liveness: true, isKeepMaxFace: true, drawFaceBorder: true }
      }
    }
  },
  methods: {
    onInitResult(e) { console.log('初始化', e.detail.status) },
    onFaceResult(e) {
      const d = e.detail
      console.log(d.status ? '识别成功 ' + d.userName : '未匹配 code=' + d.code)
    },
    registerFace() {
      this.$refs.camera.register({ id: '1001', name: '张三' }, (res) => {
        console.log('注册', res.code, res.message)
      })
    }
  }
}
</script>

状态码

注意事项

1. 人脸库持久化：虹软 SDK 的特征库只在内存，插件把特征（Base64）与注册头像持久化到 Android/data/<包名>/files/Pictures/faceDB（faces.json + registerFaces/），每次 init 自动回灌； 需要换目录用 init({ path })（等价于 init 之前调 customFaceDataPath）， 引擎初始化之后再传不同目录会返回 -1（特征已回灌内存，换目录须释放引擎或重启应用）。
2. 激活与 init 的关系：未激活时 init 可能返回虹软错误码，识别也会失败；请先激活。
3. 引擎单例：整个进程只有一个引擎实例（module API 与组件共用），调用已在内部串行化； 组件未初始化时会自动 init。
4. 性能：默认以 1280×720 作为分析分辨率，图片解码最大边 1280；偏远/低端机可把 config.camera.size 降到 [640,480]。
5. 识别频次：默认 isOutRecognize=true（同一张脸只回调一次，移出画面后才再次识别）； 需要定频刷新时置为 false 并调整 continueTime。
6. 性别取值是虹软原始值（1 男 / 0 女），与部分文档描述的 0/1 相反，业务侧按此判断。