更新记录

5.0.1（2026-07-03）

修复部分已知问题

5.0.0（2026-07-03）

• 首个 UTS 版本上架（人脸 2.0 的 5.0 升级版），当前版本支持 Android（iOS 后期陆续上线，已购免费升级）
• 百度官方人脸能力：离线采集 + 活体，采集过程不联网
• 4 种采集模式，运行时可切：collect(静默) / action(动作) / color(炫瞳) / action_color(动作+炫瞳)
• 静默模式带「防伪校验」开关：关 = 抓到合格好脸秒出图（打卡提速）；开 = 走百度真实静默活体
• 动作活体：动作池可配（眨眼/张嘴/左转/右转/抬头/低头）+ 动作个数随机抽 N
• 出图方式可选：face 裁脸特写 / full 整帧原图 / both 双图；质量档 宽松/正常/严格
• API：initFace / startFace / releaseFace，回调返回人脸图 base64
• 附赠 nvue 内嵌预览采集组件 <fsyang-face-view>（前后摄/循环采集，打卡考勤场景）

平台兼容性

uni-app(4.71)

uni-app x(4.71)

fsyang-face 离线人脸采集 / 活体检测（UTS · Android）

离线人脸采集 + 活体检测 UTS 原生插件（百度官方人脸能力）：炫瞳 / 动作 / 静默活体 + 静默秒拍提速档，识别过程纯离线（不联网），一行 API 拉起采集，回调返回人脸图 base64（裁脸 / 原图 / 双图可选）。另附赠可嵌入页面的 nvue 预览采集组件，适合考勤打卡机场景。

⚠️ 平台支持：Android（vue2 / vue3 / nvue 均可用）。真机调试需自定义调试基座 / 云打包（标准基座不含原生库）。

能力一览

• 防伪校验开关（仅静默模式）：关 = 抓到合格好脸立即出图（提速秒拍，适合打卡）；开 = 走百度真实静默活体（更严）。
• 出图方式：face 裁脸特写 / full 整帧原图 / both 双图同回。
• 质量档：0 宽松 / 1 正常 / 2 严格。
• 活体界面为百度官方成熟 UI（含动作引导动画、遮挡红字提示），无需自己写界面。

快速接入

import { initFace, startFace, releaseFace } from '@/uni_modules/fsyang-face'

// 1. 全局初始化一次(建议 App onLaunch)
initFace({}, (res) => {
  // res.success === true 且 res.code === 1000 表示离线授权成功
})

// 2. 先申请相机权限(百度采集页不自申请),再拉起采集
plus.android.requestPermissions(['android.permission.CAMERA'], (r) => {
  if (r.granted && r.granted.length > 0) {
    startFace({
      mode: 'collect',        // collect | action | color | action_color
      qualityLevel: 2,        // 0 宽松 / 1 正常 / 2 严格
      cropMode: 'both',       // face 裁脸 / full 原图 / both 双图
      antiSpoof: false,       // 仅静默模式生效:false 秒拍提速 / true 真实活体
      actions: ['eye', 'mouth', 'headLeft', 'headRight'], // 动作池(动作模式)
      actionNum: 2            // 从动作池随机抽 N 个;0 = 全部
    }, (res) => {
      if (res.success) {
        const face = res.imageBase64   // 裁脸特写 JPEG base64
        const full = res.fullBase64    // 整帧原图 JPEG base64
      }
    })
  }
})

API

initFace(options, callback)

回调 FaceInitResult：code(1000=成功) / success / message。

startFace(options, callback)

回调 FaceCollectResult：code(0=成功) / success / message / imageBase64(裁脸) / fullBase64(原图)。

releaseFace()

释放 SDK 资源。

内嵌预览采集组件 <fsyang-face-view>（nvue）

不想全屏拉起百度活体页？在 nvue 页面直接嵌入预览组件，界面完全自己排——适合打卡机、门禁一体机等常驻采集场景（自动检测「脸全在框内 + 无遮挡 + 距离合适 + 清晰」后自动拍照，可循环连续采集，摄像头不重启）。

<fsyang-face-view
  ref="cam"
  style="width:750rpx;height:900rpx;"
  :facing="'front'"     :quality="1"
  :cropMode="'both'"    :showFrame="true"   :frameRatio="0.7"
  @ready="onReady" @status="onStatus" @captured="onCaptured" @error="onError"
/>

方法（this.$refs.cam.xxx()）：startDetect() 开始一次采集 / stopDetect() 停止 / switchCamera() 切换前后摄。 事件：@ready 相机就绪 / @status 实时引导提示（把脸移入框内、XX有遮挡…）/ @captured 出图（face/full base64 + 文件路径）/ @error。

重要：license 如何申请（接入自己的 App 必读）

授权为「在线激活式」离线授权：首次联网激活一次，之后纯离线运行。license 与你 App 的包名 + 签名证书 MD5 绑定，三步拿到：

1. 登录百度智能云控制台 → 人脸识别 → 人脸实名认证 → 项目管理 → 新建项目并配置方案；
2. 创建/关联应用时登记你 App 的包名 + 签名 MD5，即可获取授权文件：idl-license.face-android、idl-key.face-android（及 local_config.json、quality_config.json）；
3. 用你的授权文件替换插件 utssdk/app-android/assets/ 下同名文件，initFace 传入你的 licenseKey，init 返回 1000 即激活成功。

官方步骤与错误码详见百度文档：Android 方案集成指南（第 5 节「SDK 集成与授权」）。

💰 费用说明：本插件使用的离线采集 / 活体检测能力无需向百度付费，license 在百度控制台自助申请即可；若你的业务还需要百度在线增值服务（如实名认证权威库核验、云端比对等），其费用以百度官方定价为准，与本插件无关。插件内置 license 仅供跑 demo 参考。

常见激活错误对照：1006 签名 MD5 与控制台不一致 / 1008 包名不一致 / 1004 licenseKey 不匹配 / 1012 授权文件名或路径不对。

依赖与权限

• 原生依赖已随插件自带，导入即用（需自定义基座 / 云打包）
• 权限：相机（必需）、网络（仅首次授权激活）
• minSdkVersion 21（Android 5.0+）；abi：armeabi-v7a + arm64-v8a（不支持 x86 模拟器，请用 ARM 真机）

注意事项

• 本插件仅含 Android 端实现；工程如同时打包其他平台，请用条件编译 #ifdef APP-ANDROID 包裹插件调用。
• 炫瞳模式在夜间 / 戴眼镜时易因镜片反光中断超时，建议此场景改用动作活体或保证光线充足。
• 采集行为默认读 utssdk/app-android/assets/local_config.json（超时、声音等），mode 等参数运行时覆盖。
• 人脸图像仅在本机生成并回调给宿主 App，插件不采集不上传任何业务数据。