更新记录

1.2.0（2026-10-16） 下载此版本

• 模型与 face-api.js 不再随插件分发：改为纯离线方案，需宿主自行下载并放到项目根 /static/face-models/ 下（见 readme「准备模型文件」）
• 组件读取路径写死为项目根 static：/static/face-models/face-api/face-api.min.js 与 /static/face-models/models/
• 插件 static/ 仅保留组件 UI 图片（icon/引导图/结果图），宿主工程不再「零配置」
• assetBase 语义收窄为「模型资源根路径」（不再影响组件图片），默认读取项目根 /static/face-models/

1.1.0（2026-10-12） 下载此版本

• 架构重写：从「web-view 内嵌 H5」改为 renderjs，检测逻辑在组件的 webview 层直接运行
• 不再需要独立的 H5 工程与构建产物（已移除 hybrid/），项目结构回归纯 uni-app
• 模型、图片、face-api.js 浏览器版统一内置到插件 static/，宿主工程零配置
• 新增 assetBase 属性，可显式指定资源根路径
• 新增 back 事件（结果页返回 / 倒计时结束）
• 移除 h5BaseUrl 属性（renderjs 版无需 H5 部署地址）
• 平台支持：App(app-vue) 与 H5；不支持小程序、nvue、uni-app x

1.0.4（2026-10-10） 下载此版本

• 修复插件市场下载包不完整的问题：移除包内与根目录重名的模型说明文件（hybrid/html/livedetect/models/readme.md），规避市场端重打包时误将 models 目录当作插件根目录的异常
• 该文件仅为模型介绍文档，face-api.js 运行时不加载它，插件功能无任何变化

平台兼容性

uni-app(5.0)

uni-app x(5.0)

Rui-faceVerify 人脸检测、人脸识别、活体检测与人证比对

一款面向 uni-app 的人脸活体检测 + 人证核身组件：先通过摄像头引导用户完成指定动作，判定操作者为「真人」；再可选地将抓拍人像连同姓名、身份证号提交给业务方自己的核验接口，完成「人证一致」比对。

检测算法基于 face-api.js，借助 renderjs 在组件所在的 webview 层直接运行——不依赖任何原生 SDK、不内嵌 web-view，全流程在设备端本地离线推理，人脸画面不经过任何第三方。

插件自身的 UI 图片随插件内置；face-api.js 与模型不随插件分发，需按下文「准备模型文件」放到项目根 static/。

功能介绍

动作活体检测

• 支持 张嘴、眨眼、左转头、右转头、点头 5 种动作
• 动作序列自由配置（actions），按顺序逐个引导，全部通过才算活体通过
• 内置光线、距离、正对屏幕等实时提示；动作切换时抛出 action 事件，便于自定义语音或文案

两种认证模式

人证比对（接口零硬编码）

• 插件不内置任何服务器地址，比对接口由业务方通过 verifyApi 自行配置
• 活体通过后向该接口发起 POST（application/json）：{ realName, idCard, faceImage }
• 约定式契约：返回 { success: true | false } 即判定通过 / 不通过
• 支持 token 鉴权（请求头 Authorization: Bearer <token>）
• 提供 test 测试模式：不调用真实接口，本地模拟成功，便于快速联调

结果与回调

• 无论哪种模式，均回传抓拍人像（data:image/png;base64,...），业务方可自行入库或二次核验
• 通过 result / success / fail / action / error / back 事件回传全流程状态
• 结果页提供 5 秒自动返回倒计时，也可手动返回

接入与技术特性

• 引入即用：uni_modules + easycom，模板中直接写 <Rui-faceVerify/>，无需 import 与注册
• 无原生依赖：renderjs 在 webview 层运行，不需要任何原生插件
• 本地离线：模型加载与推理均在设备端完成
• 可调可换：动作阈值与页面文案集中在 common/faceConfig.js，可按业务调整
• 隐私友好：页面展示的姓名、身份证号自动脱敏

支持的平台

准备模型文件（必读）

本插件不自带任何模型文件，采用纯离线方案：face-api.js 浏览器版与模型均由宿主工程自行放置。

请下载配套示例工程，把其根目录下的 static/face-models/ 整个目录拷贝到你的项目根目录 static/ 下，并保持如下目录结构（插件代码读取路径已写死，目录与文件名均不可修改）：

static/
└── face-models/
    ├── face-api/
    │   └── face-api.min.js
    └── models/
        ├── tiny_face_detector_model-weights_manifest.json
        ├── tiny_face_detector_model-shard1
        ├── face_landmark_68_model-weights_manifest.json
        └── face_landmark_68_model-shard1

注意：模型放在项目根 static/，不是插件 uni_modules/Rui-faceVerify/static/。若模型必须放在其他位置，可通过 assetBase 属性显式指定根路径。

快速开始

组件位于 uni_modules 下，无需 import、无需注册，直接在模板中使用：

<template>
    <Rui-faceVerify
        :visible="visible"
        mode="identity"
        :actions="[1, 2]"
        name="测试用户"
        idcard="000000000000000000"
        verify-api="https://your-domain.com/verify"
        @success="onSuccess"
        @fail="onFail"
        @action="onAction"
        @back="onBack"
    />
</template>

<script>
export default {
    data() {
        return { visible: true }
    },
    methods: {
        onSuccess(e) {
            console.log('认证通过', e.picture)
            this.visible = false
        },
        onFail(e) {
            console.log('认证失败', e.state)
        },
        onAction(e) {
            // 活体动作切换，可用于自定义语音/文案
            console.log('当前动作', e.description)
        },
        onBack() {
            // 结果页点击“返回”或倒计时结束
            this.visible = false
        }
    }
}
</script>

也可以按 URL 参数方式使用（见工程内 pages/face/index.vue）：

/pages/face/index?mode=identity&actions=1,2&name=测试用户&idcard=000000000000000000&verifyApi=https://your-domain.com/verify

Props

Events

结果字段说明：

人证比对接口约定

identity 模式会在活体通过后，向你配置的 verifyApi 发起 POST（application/json） 请求：

{
    "realName": "测试用户",
    "idCard": "000000000000000000",
    "faceImage": "data:image/png;base64,..."
}

接口需返回：

{ "success": true }

约定规则：

• HTTP 200 且 success 为布尔值 才算有效响应
• success: true → 认证通过；success: false → 认证失败
• 非 200、超时、网络异常，或缺少布尔 success 字段，一律视为失败，并在结果页给出明确提示

注意事项

1. 模型文件：插件不带任何模型，必须把 face-api.js 与模型按「准备模型文件」放到项目根 /static/face-models/，否则认证时会提示「加载 face-api.js 失败」或「加载人脸模型失败」。
2. 平台限制：本组件依赖 renderjs，仅支持 App(app-vue) 与 H5，不支持小程序、nvue 与 uni-app x。
3. 摄像头权限：App 端打包需勾选相机权限（组件已声明用途说明）；H5 端需在 HTTPS 环境下才能调起摄像头。
4. 跨域：H5 平台由浏览器直接发起比对请求，你的接口必须放行 CORS（含 OPTIONS 预检）；若使用 token，还需允许 Authorization、Content-Type 请求头。App 端无此限制。
5. 语音播报：动作提示音使用 webview 的 speechSynthesis，部分设备 WebView 不支持；可通过监听 @action 自行播报。
6. faceImage 格式：为 data:image/png;base64, 前缀的完整 data URL，如你的后端需要纯 base64，请自行截取逗号后的内容。
7. 人脸数据合规：抓拍人像属敏感个人信息，请务必在自身隐私政策中说明用途与留存策略。

目录结构

uni_modules/Rui-faceVerify
├── components/Rui-faceVerify/Rui-faceVerify.vue   # 组件入口（UI + 状态机 + renderjs 检测）
├── common/faceConfig.js                           # 动作/阈值/文案/脱敏/参数归一化
├── static/
│   └── face/                                      # 组件 UI 图片（icon/引导图/结果图，随插件内置）
├── package.json
├── readme.md
└── changelog.md

模型与 face-api.js 不在此目录，需放到宿主项目根 static/face-models/，见「准备模型文件」。

更新日志

见 changelog.md