uni-app 做 App，最容易在“认证”这一步卡住。表单能写、接口能调、页面能画，可一旦业务方说“要确认镜头前是个活人”，纯前端那套东西就立刻不够用了。我这两年接过的几个项目，最后都落到同一个组合上：uniapp 开发的 App 利用百度人脸实现认证功能。这套方案说白了就是把“取景、拍照、活体判断、人脸比对”四件事，拆到 App 端、自己的服务端、以及百度人脸服务三处去完成，App 端只负责最轻的活——把画面拍清楚、传上去、把结果展示出来。
这篇内容适合三类人看：第一类是已经在用 uniapp 做 App、被实名认证需求卡住的开发者；第二类是刚接触人脸识别接口、不确定该走 H5 方案还是原生采集的同学；第三类是要给项目做技术选型、需要评估成本和坑位的负责人。我不会只给你贴一段接口调用代码，而是把每一个参数为什么这么取、阈值为什么这么定、权限为什么这么申请，都拆开讲清楚。看完全篇，你应该能自己从零把这套认证链路搭起来，并且知道哪里最容易翻车。
1. 先把问题定义清楚：这套认证到底在认证什么
1.1 认证功能背后其实是三个独立的问题
很多人一上来就说“我要做人脸认证”，但“认证”这个词其实很含糊。拆开看，它至少包含三个彼此独立、可以分别实现的子问题。
第一个是活体判断：镜头前的是真人，还是一张打印的照片、一段录屏、一个手机里的翻拍？这个问题解决的是“防作弊”。第二个是身份比对：拍到的人脸，和系统里已经存档的那张脸，是不是同一个人？这个问题解决的是“是不是本人”。第三个是证件核验：如果业务要求更高，还需要把活体人脸和证件信息（姓名、证件号）做交叉校验，确认“这个人和这份证件对得上”。
这三件事的技术门槛完全不同。活体判断最依赖摄像头质量和算法，身份比对最依赖底库质量和阈值设定，证件核验则更多依赖权威数据源。我在做方案设计时，习惯先把这三件事列出来，然后问业务方一句：“你到底要防的是哪一类风险？”如果只是防止员工代打卡，活体 + 1:1 比对就够了；如果是要跑金融级的开户流程，那三个都得做，而且阈值要往上抬。
这个问题想不清楚，后面全是返工。我见过一个项目，需求方只说了“要人脸登录”，开发同学直接上了 1:N 人脸库搜索，结果底库里有几万人，搜索耗时高、误识率还高，最后发现其实只需要把当前登录账号的存档照片调出来做 1:1 比对，难度直接降了一个数量级。
1.2 为什么是百度人脸，而不是别的方案
人脸识别这个赛道可选项不少，百度人脸的优势在我的实际体感里主要落在三点上。
第一是文档和错误码足够细。这一点在做线上问题排查时太重要了。接口返回一个“未检测到人脸”，如果平台只给你这一句，你只能猜；百度这边会区分“未检测到人脸”“检测到多张人脸”“人脸质量不达标”，你在 App 端就能给出精准的用户提示，而不是干巴巴一句“认证失败，请重试”。
第二是活体检测可以直接在服务端做。这一点对 uniapp 项目特别关键。uniapp 打包出来的 App 底层是原生渲染层加 JS 逻辑，你要在端上集成一整套原生人脸 SDK，需要走离线打包和原生插件，接入成本不低。而百度提供了纯接口形态的在线活体检测：App 端只负责拍照并把图片传给你的服务端，服务端调接口拿到活体分，再决定是否继续比对。整个链路里，App 端不需要任何原生人脸 SDK。
第三是人脸库能力开箱即用。注册、更新、删除、分组、搜索这些接口都是现成的，你不需要自己维护特征向量，也不需要自己写相似度计算，底库管理直接用平台能力就行。
当然，代价也是有的。所有图片都要上传到云端处理，意味着网络质量直接决定认证成功率，也意味着你在做隐私合规说明时要把“人脸图像会传输到第三方服务”这件事写清楚。这一点后面第 5 章会展开。
1.3 链路分层：别把所有逻辑塞进 App
这是我踩过坑之后最想强调的一条设计原则：App 端只做采集和展示，所有敏感调用都放服务端。
原因很直接。调用百度人脸接口需要一个凭据，无论你是用 AK/SK 换 Access Token，还是用更复杂的签名方式，这个凭据一旦被打包进 App，就等于公开了。现在网上有大量自动化工具能直接从 apk 里把字符串扒出来，你的额度会在几天内被刷干净。我见过最惨的一个案例，AK/SK 硬编码在前端，一周时间跑掉了几十万次调用。
所以正确的分层是这样的：
- App 端（uniapp）：申请相机权限 → 打开取景框 → 引导用户正脸入框 → 拍照 → 压缩 → 把图片 base64 传给自己的服务端 → 展示结果。
- 服务端：持有 AK/SK → 换取并缓存 Access Token → 接收 App 传来的图片 → 调活体检测接口 → 调比对或搜索接口 → 返回结构化结果 → 记录流水日志。
- 百度人脸服务：完成活体判断、质量检查、特征提取与比对。
这个分层还有一个隐性好处：服务端可以做二次风控。比如同一个用户十分钟内请求了二十次认证，服务端可以直接拦截，App 端不用管这些逻辑。App 端越“薄”，后续升级越轻松——你改服务端的阈值策略，不需要重新发版。
2. 动手前的准备：账号开通、方案配置与工程配置
2.1 百度智能云控制台要建什么
正式写代码之前，控制台里有几样东西必须先建好，顺序错了会来回折腾。
第一步是创建应用。在人脸识别（或人脸实名认证）产品下新建一个应用，你会拿到三个关键值：API Key（简称 AK）、Secret Key（简称 SK），以及应用名称。AK/SK 只在创建时完整展示一次，记得当场保存到你的密码管理工具里，别只截个图丢在相册。
第二步是创建人脸库分组。人脸库接口里的group_id就是分组的标识。我的习惯是按业务线划分，比如staff_verify、user_realname，而不是所有业务共用一个默认分组。分开的好处是搜索范围小、响应快，而且某个业务要清库的时候不会误伤别人。分组名一旦定下来就别轻易改，改一次要迁移所有底库数据。
第三步是配置认证方案（如果你走 H5 活体方案的话）。人脸实名认证类产品通常需要你新建一个方案，在方案里勾选：是否做活体、活体等级、是否需要证件信息核验、比对源是什么。方案配好之后会生成一个方案 ID，服务端拿这个 ID 去换取前端可以打开的认证页地址。
注意：方案里的“活体等级”和后面接口里的
liveness_control是两套不同的开关。前者影响 H5 页面的交互流程，后者影响接口侧的判定强度。别把两者混为一谈，也不要两边都拉到最高，否则用户通过率会难看到你想哭。
2.2 鉴权：AK/SK、Access Token 与签名
百度人脸接口的鉴权走的是标准的 OAuth 2.0 客户端模式，流程分两步。
第一步，用 AK 和 SK 换 Access Token。请求方式是向鉴权地址发一个 POST，带上grant_type=client_credentials、client_id（你的 AK）、client_secret（你的 SK）。返回里会有access_token和expires_in，后者的单位是秒，通常是三十天。
第二步，把access_token拼在业务接口的 URL 查询参数上，比如.../rest/2.0/face/v3/detect?access_token=xxx，请求体里放业务参数。
这里有两个非常容易踩的点。
第一，Access Token 有获取频次限制。如果你每次用户请求都去换一次 Token，很快就会触发限流，接口开始报错。正确做法是在服务端做全局缓存：拿到 Token 之后记下过期时间，在过期前五到十分钟再刷新。整个服务实例共用一份，用 Redis 存也行，用进程内存 + 定时刷新也行，只要别每个请求都换。
第二，Token 失效的报错要单独处理。常见的错误码是 110（Token 无效）和 111（Token 过期）。虽然我们做了缓存，但线上总会出现各种意外——比如服务重启丢了内存缓存、比如多实例部署时某台机器的缓存时间算错了。所以业务接口的封装层里要写一个拦截逻辑：一旦收到这两个错误码，就强制刷新一次 Token 并重试一次原请求。这个重试必须是幂等的，别再嵌套重试。
至于更复杂的签名鉴权方式，一般是给有特殊安全要求的场景准备的，普通业务用 Access Token 就够了，没必要给自己加复杂度。
2.3 manifest.json 与权限声明
uniapp 项目里，manifest.json是打包配置的核心。人脸认证这块，需要重点确认这几项。
Android 侧，在app-plus.distribute.android.permissions里加上相机和网络权限。以下是我常用的一个最小集合：
"app-plus": { "distribute": { "android": { "permissions": [ "<uses-permission android:name=\"android.permission.CAMERA\"/>", "<uses-permission android:name=\"android.permission.INTERNET\"/>", "<uses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"/>", "<uses-permission android:name=\"android.permission.ACCESS_WIFI_STATE\"/>", "<uses-permission android:name=\"android.permission.WRITE_EXTERNAL_STORAGE\"/>", "<uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>" ] } } }存储权限在 Android 10 之后其实已经弱化了，很多机型不给也能通过缓存目录读写临时图片，但为了兼容老设备，我一般还是留着。如果你的 App 还用到麦克风（比如视频活体引导语音），记得把RECORD_AUDIO也加上，漏掉的话表现就是“相机正常、一说话就崩”，很难查。
iOS 侧要在app-plus.distribute.ios.privacyDescription里补上用途说明：
"ios": { "privacyDescription": { "NSCameraUsageDescription": "用于采集人脸照片完成身份认证", "NSPhotoLibraryUsageDescription": "用于选择已有照片进行人脸认证" } }iOS 这块有个硬性规则：凡是调用了相关权限 API，就必须在 plist 里申明用途，且文案要具体。写“需要相机权限”这种含糊描述，审核阶段有被拒的风险，改成“用于采集人脸照片完成身份认证”这种说明实际用途的表述更稳。
提示：
manifest.json里的权限只是“声明”，不代表用户会同意。Android 6.0 以后相机属于危险权限，必须在运行时再次申请，且用户可以选择拒绝。这一块在第 5 章详细讲。
2.4 要不要上 uts 原生插件
uniapp 从 3.x 开始支持 uts 插件，可以直接用 TypeScript 语法调用原生能力，打包时编译成原生代码。很多人一听到“人脸”两个字，第一反应就是“是不是得写原生插件”。
我的判断标准很简单：看你走的是接口方案还是 SDK 方案。
如果你走的是本文这套接口方案——App 端只拍照、传图片、等结果——那完全不需要 uts 插件，用 uniapp 自带的相机组件加上uni.request就够了。这也是我推荐这条路线的主要原因：接入成本低、发版灵活、不依赖原生编译环境。
如果你要集成原生的离线人脸 SDK（比如对联网有硬性限制的场景），那就必须走 uts 插件或原生插件 + 离线打包的路子。这条路的工作量大概是接口方案的三到五倍：你要写插件、调原生 API、处理生命周期、适配不同机型的前后置摄像头、还要在每次 uniapp 升级时验证插件兼容性。
所以我的建议是：能用接口方案就用接口方案，除非业务明确要求离线。很多需求方说“要离线”，其实只是担心网络不稳定，这种情况下做好重试和超时兜底，比上原生插件划算得多。
3. 核心原理：从一张照片到一条认证结论
3.1 活体检测怎么判断镜头前是不是真人
活体检测是这个链路里最“玄学”的一环，也是最容易被误解的。很多同学以为活体检测是在判断“这张脸长得像不像人”，其实不是，它判断的是这张图像在采集过程中有没有携带“真实三维人脸”才有的物理特征。
常见的攻击手段有三种：一是打印照片，拿一张纸质照片怼在镜头前；二是屏幕翻拍，用手机或平板播放一段人脸视频；三是面具或三维头模。这三种攻击方式在成像上会留下不同痕迹。
照片攻击的典型破绽是缺乏微动。真人的面部即使在静止状态，也会有呼吸带来的细微起伏、眼球的微动、皮肤局部的微小形变。这些变化在连续多帧里会体现为有规律的微小差异，而一张静止的照片，无论怎么拍，帧与帧之间的高频细节都是死的（除非拍摄者手在抖，但那种抖动是整体的、刚性的）。
屏幕翻拍的破绽主要在光学特性上。屏幕是自发光的，它的亮度分布、色域表现、摩尔纹、以及屏幕玻璃表面的反射，都和真实人脸在自然光或室内灯光下的漫反射不一样。算法会提取这些光影特征来判断。
理解了原理，你就能明白为什么活体检测对光照和环境这么敏感。逆光环境下人脸变成剪影，皮肤细节全丢，算法拿不到微动特征，误判概率就会上升。同理，在极暗环境里靠手机屏幕补光，人脸被一块小小的屏幕照着，反而更像“翻拍”。
这也是为什么我在 App 端做交互设计时，一定会加一句引导文案：“请到光线充足的地方，正脸对准取景框。”这句话不是客套，它能实打实地把通过率往上抬十几个百分点。
3.2 质量分：被大多数人忽略的一道门槛
接口调用里有个参数叫quality_control，取值通常是 NONE、LOW、NORMAL、HIGH 四档。很多示例代码直接写 NORMAL，然后就不管了。但这个参数背后的逻辑值得说一下。
质量分评估的是这张照片“适合不适合做比对”。它综合考虑了这些因素：人脸在画面中的占比是否足够大、是否在画面中央、是否模糊、光照是否均匀、是否被遮挡（口罩、墨镜、刘海）、姿态偏转角是否过大。
质量分不达标的图片，即使活体通过了，比对结果也可能不可靠。所以正确的处理顺序是：先卡质量，再判活体，最后做比对。三道关卡依次收紧，能显著降低误识率。
这里有个经验值可以参考。质量分门槛设得太低，等于没卡；设得太高，用户反复重拍，体验崩掉。我的做法是分场景设置：
| 场景 | quality_control | liveness_control | 说明 |
|---|---|---|---|
| 注册/建档 | HIGH | NORMAL | 底库照片质量必须高，否则后面全是坑 |
| 日常登录 | NORMAL | NORMAL | 平衡通过率和安全性 |
| 高风险操作 | HIGH | HIGH | 转账、改密等场景，宁可多试几次 |
建档那一步用 HIGH 是我的强烈建议。底库照片一旦质量不高，后面每一次比对都会受影响，而且你很难判断问题出在底库还是出在当次采集。花三秒钟让用户重拍一张清晰的，比后面花三天排查误识强太多。
3.3 1:1 比对与 1:N 搜索的区别与取舍
这两个词经常被混用，但它们完全是两回事。
1:1 比对（match）是把两张图片放一起，算一个相似度分数。它的输入是“本次采集的人脸”和“系统里已知的某张人脸”，输出是一个 0 到 100 的分数。整个过程中，你不需要人脸库，只需要事先存好这个人的一张参考照片。适合登录、二次验证这类“我知道你是谁，验证一下是不是本人”的场景。
1:N 搜索（search）是把一张图片丢进人脸库里，让系统告诉你库里最像的几个是谁。它的输入是“本次采集的人脸”加一个分组 ID 列表，输出是若干候选用户及其分数。适合“我不知道你是谁，你来认领身份”的场景，比如门禁、考勤。
1:N 的复杂度远高于 1:1。底库越大，搜索耗时越长，误识的概率也越高。假设单次比对的误识率是万分之一，那么在一万人的底库里做搜索，出现“认错人”的概率就上升到接近百分之几。这个数量级的变化在设计方案时必须考虑进去。
如果两个场景都需要，我的建议是分开做：先让人输入手机号或工号，定位到具体账号，再做 1:1 比对；只有在没有账号信息的前提下，才走 1:N 搜索，并且把分数阈值调高。
3.4 阈值怎么定：把误识率和通过率放在一起看
这是整套方案里最需要“拍板”的一个参数，也是最容易出问题的地方。
比对接口返回的分数，通常建议 80 分作为“同一人”的参考线，但这只是一个非常粗略的经验值，实际要看文档给出的各场景推荐区间。搜索接口支持传match_threshold参数，用来过滤候选结果。
阈值调高，误识率下降，但通过率也下降（本人被拒的概率上升）；阈值调低，通过率上升，但风险也上升。这两个指标是一对矛盾，没有“最优点”，只有“平衡点”。
我的做法是按业务风险等级分档：
- 低风险（比如普通 App 内部打卡）：阈值取推荐区间的下限，让本人尽量一次通过。
- 中风险（比如账号登录、信息查看）：取推荐区间的中位。
- 高风险（比如资金相关操作、关键资料修改）：取推荐区间上限，甚至在上限基础上再抬几个点。
同时一定要设计兜底路径。人脸认证永远会有一小部分真实用户无法通过——可能是光线太差、可能是面部有临时变化（受伤、过敏）、可能是手机摄像头故障。如果业务是“认证失败就无法使用”，那这部分用户会直接流失。所以必须准备人工审核、短信验证、证件上传等备选通道。
注意：不要把阈值写死在前端。所有阈值都放在服务端配置里，这样业务方想调整，你改个配置就能生效，不用重新打包发版。
4. 实操：从取流、压缩、调用到落库
4.1 服务端：Access Token 的获取与缓存
先解决服务端的基础设施。下面这段是 Node.js 环境下的实现，思路换成 Java、PHP、Python 都一样。
const AK = process.env.BAIDU_FACE_AK; const SK = process.env.BAIDU_FACE_SK; let tokenCache = { value: '', expireAt: 0 }; let refreshing = null; async function getAccessToken() { const now = Date.now(); // 提前 10 分钟刷新，避免边界时间失效 if (tokenCache.value && tokenCache.expireAt - now > 10 * 60 * 1000) { return tokenCache.value; } // 并发请求时只放一个请求出去，其余的复用同一个 Promise if (refreshing) return refreshing; refreshing = (async () => { const url = `https://aip.baidubce.com/oauth/2.0/token` + `?grant_type=client_credentials&client_id=${AK}&client_secret=${SK}`; const resp = await fetch(url, { method: 'POST' }); const data = await resp.json(); if (!data.access_token) { refreshing = null; throw new Error('token 获取失败: ' + JSON.stringify(data)); } tokenCache.value = data.access_token; tokenCache.expireAt = now + data.expires_in * 1000; refreshing = null; return tokenCache.value; })(); return refreshing; }这里有两个设计点值得说明。第一个是提前十分钟刷新。Token 的有效期是三十天，但服务端和百度的时间可能有秒级偏差，卡在过期瞬间刷新容易出问题，提前一点更保险。第二个是并发去重。用refreshing变量把并发的刷新请求合并成一个，避免服务重启后的瞬间流量把刷新接口打爆——这个坑我在一次大促前的压测里真实遇到过，重启后三百个请求同时去换 Token，结果触发了频次限制。
AK/SK 一定要从环境变量或配置中心读取，绝对不要写在代码里提交到仓库。这条不是洁癖，是保命线。
4.2 uniapp 端：相机取景与拍照
uniapp 提供了camera组件，在 App 端（vue 页面）和小程序端都能用。下面是一个可用的取景页结构。
<template> <view class="verify-page"> <camera class="cam" device-position="front" flash="off" resolution="high" @error="onCameraError" > <cover-view class="tip">请正脸对准圆形区域，保持光线充足</cover-view> <cover-view class="oval"></cover-view> </camera> <view class="footer"> <button class="btn" type="primary" @click="startVerify"> 开始认证 </button> <text class="sub">认证过程约 3 秒，请保持不动</text> </view> </view> </template>几个关键点。device-position="front"用前置摄像头，人脸认证场景几乎都用前置。resolution="high"建议开着，虽然图片更大，但清晰度直接影响质量分。cover-view是用来在相机上层绘制遮罩的内置组件，注意它只支持有限的样式，圆角、定位这些可以，复杂的效果做不了。
拍照逻辑：
methods: { startVerify() { const ctx = uni.createCameraContext(); // 给用户一点时间摆正姿势 uni.showLoading({ title: '采集中' }); setTimeout(() => { ctx.takePhoto({ quality: 'high', success: (res) => { uni.hideLoading(); this.handlePhoto(res.tempImagePath); }, fail: (err) => { uni.hideLoading(); console.error('拍照失败', err); uni.showToast({ title: '拍摄失败，请重试', icon: 'none' }); } }); }, 1200); }, onCameraError(e) { console.error('相机异常', e.detail); uni.showModal({ title: '无法使用相机', content: '请检查相机权限是否开启', showCancel: false }); } }那个 1200 毫秒的延时是有意为之。用户点下按钮的瞬间往往还在调整姿势，直接拍大概率会拍到模糊或半张脸。给一个短暂缓冲，通过率能明显提升。这个数值可以根据你的用户反馈调整，一千到一千五之间是我试出来比较舒服的区间。
如果camera组件在你的目标平台上表现异常（比如某些 Android 定制系统上预览黑屏），备选方案是用 5+ API 的plus.camera.captureImage，它调起的是系统相机，兼容性更好，但缺点是无法自定义取景框和引导层，体验会差一些。我的做法是优先用 camera 组件，在检测到异常机型时降级到系统相机。
4.3 图片压缩与 base64 处理
拍照拿到的临时图片动辄两三兆，直接转 base64 上传，体积会膨胀到四兆以上。百度人脸接口对图片有明确限制（base64 编码后通常不能超过 2M），而且上传时间越长，弱网下的失败率越高。所以压缩是必须的一步。
function compressImage(srcPath) { return new Promise((resolve) => { // #ifdef APP-PLUS plus.zip.compressImage({ src: srcPath, dst: srcPath.replace(/(\.\w+)$/, '_c.jpg'), quality: 70, // 压缩质量，0-100 width: '720px', // 限制宽度，高度按比例 overwrite: true, success: (e) => resolve(e.target), fail: (e) => { console.warn('压缩失败，使用原图', e); resolve(srcPath); } }); // #endif // #ifdef H5 || MP-WEIXIN resolve(srcPath); // #endif }); }压缩参数的取值逻辑说一下。quality: 70是在清晰度和体积之间比较平衡的点，我实测 1080P 的原图压到这个质量，通常落在 200 到 400KB，转成 base64 后大约 300 到 550KB，安全落在接口限制以内。宽度限制到 720px 是因为人脸比对并不需要超高分辨率——接口文档要求的最短边通常在 150px 以上、建议 300px 以上，720px 的宽度足够算法提取特征了，再高就是浪费带宽。
转 base64 的时候有一个必踩的坑：uni.getFileSystemManager或者plus.io读出来的 base64，很多情况下会带上data:image/jpeg;base64,这样的前缀。直接把这个字符串传给接口，会得到一个“图片格式错误”的报错，而且提示信息不会告诉你是因为前缀。一定要剥掉：
function readBase64(filePath) { return new Promise((resolve, reject) => { plus.io.resolveLocalFileSystemURL(filePath, (entry) => { entry.file((file) => { const reader = new plus.io.FileReader(); reader.onloadend = (e) => { // 关键：剥掉 data URI 前缀 const raw = e.target.result.split(',')[1] || e.target.result; resolve(raw); }; reader.onerror = reject; reader.readAsDataURL(file); }, reject); }, reject); }); }另外提醒一点，读文件和压缩都属于耗时操作，最好放在setTimeout或独立的异步流程里，别阻塞 UI。我在一个低端机上测过，一张三兆的图片读 base64 加上压缩，前后要接近一秒钟，如果不给 loading 提示，用户会以为按钮没反应，然后疯狂点击。
4.4 在线活体检测接口调用
服务端拿到 base64 之后，第一件事是调活体检测。这个接口的作用是判断图片里是不是真人，同时给出人脸质量、位置等信息。
async function faceVerify(base64Image) { const token = await getAccessToken(); const url = `https://aip.baidubce.com/rest/2.0/face/v3/faceverify?access_token=${token}`; const body = { image: base64Image, image_type: 'BASE64', face_field: 'quality,spoofing,age,gender,face_type', option: 'COMMON' }; const resp = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }); return await resp.json(); }返回结构里最重要的是这几个字段。error_code为 0 表示调用成功，非 0 就要走错误分支。result.face_liveness是活体分数，通常会附带一个thresholds数组，里面给出不同误识率档位对应的阈值。我的做法是不写死阈值，而是从返回值里的阈值列表按业务等级挑一个：低风险业务挑宽松档，高风险业务挑严格档。这样即使平台调整了算法，你的逻辑也不需要改。
face_field里加quality是为了拿到质量分。如果你发现质量分很低，直接返回让用户重拍比继续往下走更划算——因为质量差的图做比对，结果不可信。
提示：如果业务量比较大，建议在调用前先在服务端做一次粗略的图片校验：base64 长度是否在合理区间、解码后的头部字节是不是 JPEG 或 PNG。这类本地能拦的检查放在前面，可以省下不少无效调用。
4.5 人脸注册与搜索比对
活体通过之后，就进入业务逻辑分支。
场景一：建档注册。把这次采集的人脸写进人脸库，作为该用户的底库照片。
async function addFaceToLibrary(base64Image, userId) { const token = await getAccessToken(); const url = `https://aip.baidubce.com/rest/2.0/face/v3/faceset/user/add?access_token=${token}`; const body = { image: base64Image, image_type: 'BASE64', group_id: 'user_realname', user_id: userId, user_info: '业务侧标识，不要放敏感明文', quality_control: 'HIGH', liveness_control: 'NORMAL', action_type: 'REPLACE' }; const resp = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }); return await resp.json(); }action_type有两个值：APPEND是追加（一个人可以有多张脸），REPLACE是覆盖。实名认证场景我一般用REPLACE，保证一个人只保留一张最新的底库照片，避免多张照片之间互相干扰。user_id用你自己系统的用户主键，别用手机号或证件号这种敏感信息，因为它在返回日志里可能会被打印出来。
场景二：1:1 比对。用户已经登录，把本次采集的人脸与他档案里的那张照片做比对。
async function faceMatch(base64Image, registeredBase64) { const token = await getAccessToken(); const url = `https://aip.baidubce.com/rest/2.0/face/v3/match?access_token=${token}`; const body = [ { image: base64Image, image_type: 'BASE64', face_type: 'LIVE', quality_control: 'NORMAL', liveness_control: 'NORMAL' }, { image: registeredBase64, image_type: 'BASE64', face_type: 'IDCARD', quality_control: 'NORMAL', liveness_control: 'NONE' } ]; const resp = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }); return await resp.json(); }注意这里face_type的设置。现场采集的图是活体拍出来的，标LIVE；底库里那张如果是证件照或档案照，标IDCARD；不确定就标COMMON。liveness_control只在第一张上设NORMAL，第二张设NONE——因为底库照片本来就是从证件或档案里来的，对它做活体检测没有意义，反而可能因为它是翻拍件而判定失败。
返回里的score就是相似度分数。业务侧拿这个分数跟你配置的阈值比较，大于等于就判定通过。这里一定要把分数也记录下来，不要只记“通过/不通过”。线上出问题时，分数分布是排查的第一手材料：如果一批用户的分数集中在 60 到 75 之间，说明可能是阈值定高了，也可能是采集环境出了问题。
场景三：1:N 搜索。没有账号信息时的兜底方案。
const body = { image: base64Image, image_type: 'BASE64', group_id_list: 'staff_verify', quality_control: 'NORMAL', liveness_control: 'NORMAL', match_threshold: 85, // 调高阈值，降低误识 max_user_num: 3 // 最多返回 3 个候选 };搜索接口的地址是/rest/2.0/face/v3/search。返回的user_list是按分数降序排列的候选。match_threshold这个参数很重要，它的作用是先把低于阈值的候选过滤掉。如果不传，接口会用默认值（通常比较宽松），你会拿到一堆“其实不太像”的结果，业务侧还得再筛一遍。直接传一个偏高的值，让接口帮你筛，省事又省流。
4.6 前端交互与异常兜底
接口跑通只是开始，真正决定用户体验的是异常处理。人脸认证有个特点：失败是常态，不是例外。光线不对、姿势不对、镜头脏了、网络抖了，任何一项都能让认证失败。所以前端要把“失败”设计成流程的一部分，而不是意外。
我把失败分成三类，分别给不同的提示和动作：
第一类是可自助修复的。比如“未检测到人脸”“检测到多张人脸”“人脸模糊”“活体未通过”。这类提示要具体，并且给一个明确的动作指引：请正脸对准圆形区域、请确保画面中只有你一人、请到光线更亮的地方、请保持面部稳定。然后直接允许重试，不要让用户返回上一页重新进入。
第二类是需要切换方式的。比如连续三次活体失败、或者相机权限被拒绝。这时候要给出备选入口：换个环境再试、使用其他验证方式、联系客服人工审核。
第三类是系统级异常。比如接口返回未知错误、网络超时。这类不要暴露原始错误信息给用户，统一提示“服务暂时不可用，请稍后重试”，同时在后台记录完整错误码和请求 ID，方便排查。
还有一个细节我很在意：重试次数要有上限。我一般设三次。超过三次就锁定一段时间（比如十分钟），避免被自动化脚本反复试探。这个限制要放在服务端做，前端只负责展示剩余次数。
async function submitFace(base64) { try { const res = await uni.request({ url: `${BASE_URL}/api/face/verify`, method: 'POST', data: { image: base64 }, timeout: 15000, header: { 'content-type': 'application/json' } }); const data = res.data || {}; if (data.code === 0) { return { ok: true, data: data.result }; } return { ok: false, code: data.code, msg: data.message }; } catch (e) { return { ok: false, code: 'NETWORK', msg: '网络异常，请检查网络后重试' }; } }timeout: 15000这个值是我反复调整后定下来的。设得太短（比如 5 秒），弱网下大量请求被掐断；设得太长（比如 30 秒），用户干等着更难受。15 秒是个折中的数字，既给了上传和处理的余量，又不至于让人失去耐心。
5. 踩坑记录：权限、机型与网络
5.1 相机权限的申请、监听与兜底
权限这块是最容易出线上事故的地方，因为它在开发机上几乎不会出问题——开发时你早就同意了权限，用户不会。
Android 6.0 以后，相机是危险权限，需要运行时申请。uniapp 打包的 App 在启动相机组件时会自动触发系统权限弹窗，但这个行为是隐式的，你控制不了时机，也拿不到明确的拒绝回调。所以我更倾向于在进入认证页之前，主动申请一次：
function requestCameraPermission() { return new Promise((resolve) => { // #ifdef APP-PLUS if (plus.os.name !== 'Android') { return resolve(true); // iOS 由系统在首次调用时弹窗 } plus.android.requestPermissions( ['android.permission.CAMERA'], (result) => { const denied = result.deniedAlways || []; const deniedPresent = result.deniedPresent || []; if (denied.length > 0) { // 用户勾选了“不再询问”，必须去设置页手动开 uni.showModal({ title: '需要相机权限', content: '人脸认证需要访问相机，请在系统设置中开启权限', confirmText: '去设置', success: (r) => { if (r.confirm) { plus.runtime.openURL('app-settings:'); // iOS // Android 可用下面的方式打开应用详情页 } } }); resolve(false); } else if (deniedPresent.length > 0) { resolve(false); // 本次拒绝，下次还能再弹 } else { resolve(true); } }, (err) => { console.error('权限申请失败', err); resolve(false); } ); // #endif // #ifndef APP-PLUS resolve(true); // #endif }); }这里有个很多人问过的问题：uniapp 能不能实时监听系统权限弹窗的出现和消失？答案是：App 端拿不到系统弹窗的生命周期事件。你能依赖的只有两个东西——requestPermissions的回调结果，以及 App 的onShow生命周期。所以可行的做法是：弹窗返回后，如果结果是拒绝，就把 App 切到后台再切回前台的行为当作“用户可能去过设置页了”，在onShow里重新检查一次权限状态。这不是精确监听，但能覆盖大部分用户行为路径。
iOS 侧没有这么复杂，系统会在首次调用相机时自动弹窗，用户拒绝后，后续调用会直接失败。所以 iOS 的处理重点是：在相机报错回调里判断是否是权限问题，如果是，就引导用户去设置页。
plus.runtime.openURL('app-settings:')在 iOS 上能打开本应用的设置页。Android 各家系统不一样，通用的做法是打开应用详情页：
const main = plus.android.runtimeMainActivity(); const Intent = plus.android.importClass('android.content.Intent'); const Uri = plus.android.importClass('android.net.Uri'); const intent = new Intent('android.settings.APPLICATION_DETAILS_SETTINGS'); intent.setData(Uri.fromParts('package', main.getPackageName(), null)); main.startActivity(intent);注意：权限引导文案不要写得太生硬，也不要一上来就引导去设置页。先在页面上用友好的方式说明“为什么需要相机”，再弹系统权限，用户同意的概率会高很多。我做过对比，加了说明文案之后，权限同意率大概能提升两成左右。
5.2 机型和系统差异带来的兼容问题
这是 uniapp 做原生能力时绕不开的一块，人脸认证尤其明显，因为它重度依赖相机。
问题一：部分机型的相机预览画面被拉伸或变形。这通常是因为camera组件的宽高比和摄像头传感器的输出比例不匹配。解决办法是给容器设一个固定的宽高比，常见的是 3:4 或 9:16，让 container 去适配，而不是让摄像头去适配容器。如果还是不对，就需要考虑降级到系统相机。
问题二：前置摄像头拍出来的图片是镜像的。前置摄像头默认输出镜像图像，这本身不是问题（人照镜子也是镜像的），但如果你把这张镜像图和底库里的非镜像图做比对，分数可能会略有下降。大部分算法对镜像是有一定容忍度的，但如果你的通过率异常低，可以检查一下是不是这个原因。部分平台支持通过接口参数控制是否镜像，具体看文档。
问题三：低端机上camera组件打开慢。我测过几台千元机，从进入页面到画面出现要两三秒。这段时间如果不给提示，用户会以为页面卡住了。所以进入认证页后立刻显示一个“正在启动相机”的 loading，画面 ready 之后再隐藏。uniapp 的camera组件没有直接的 ready 事件，可以用一个短延时加首帧检测的方式近似实现。
问题四：刘海屏、挖孔屏的遮挡。取景框顶部容易被状态栏或刘海挡住，导致用户的脸被切掉一部分。解决办法是取景区域整体下移，或者用safe-area-inset-top这类安全区适配。这个细节不做，质量分会莫名其妙地低。
5.3 弱网下的超时与重试设计
人脸认证涉及一次图片上传加两次接口调用（活体 + 比对），总耗时由网络决定。在弱网环境（比如地下车库、电梯口、老小区）下，超时是家常便饭。
我的处理策略分三层。
第一层是压缩前置。前面说过，把图片压到 300 到 500KB，传输时间能砍掉一大半。这一步投入产出比最高。
第二层是分段超时。不要给整个请求设一个笼统的超时，而是给上传和处理分别设。上传设 10 秒，服务端调用百度接口设 5 秒。这样如果上传本身就卡住了，能立刻失败，不用等到 15 秒。
第三层是自动重试，但要有条件。只对“网络类错误”自动重试一次，且重试必须有幂等保护。我一般会在请求里带一个客户端生成的requestId，服务端遇到相同requestId就直接返回上次的结果，避免重复注册或重复扣费。
async function submitWithRetry(base64, retry = 1) { const requestId = `${Date.now()}_${Math.random().toString(36).slice(2)}`; const result = await submitFace(base64, requestId); if (!result.ok && result.code === 'NETWORK' && retry > 0) { await new Promise((r) => setTimeout(r, 800)); return submitWithRetry(base64, retry - 1); } return result; }那个 800 毫秒的等待也是有讲究的。网络抖动通常是瞬时的，立刻重试大概率还是失败，等一下再试成功率更高。但也不能等太久，用户会觉得卡死。
6. 常见报错速查与几条压箱底的经验
6.1 错误码速查表
下面这张表是我这两年排查问题时攒下来的，覆盖了绝大部分线上遇到的情况。具体含义请以平台最新文档为准，这里给的是我实际遇到过的对应关系和处理方式。
| 错误码 | 含义 | 常见原因 | 处理方式 |
|---|---|---|---|
| 110 | Access Token 无效 | 缓存失效、手动改过配置 | 强制刷新 Token 后重试一次 |
| 111 | Access Token 过期 | 缓存过期时间计算错误 | 同上，并检查缓存逻辑 |
| 100 | 参数错误 | 参数名拼错、类型不对 | 对照文档逐项核对请求体 |
| 216101 | 缺少必要参数 | body 字段漏传 | 检查 image、image_type 等必填项 |
| 216201 | 图片格式错误 | base64 带了 data URI 前缀 | 剥掉data:image/...;base64, |
| 216202 | 图片体积超限 | 未压缩或压缩不够 | 压到 500KB 以内再传 |
| 216630 | 识别错误 | 图片内容异常 | 记录日志，让用户重拍 |
| 216631 | 未检测到人脸 | 人脸不在框内、光线太暗 | 提示对准取景框、改善光照 |
| 216632 | 检测到多张人脸 | 背景有人、海报上有人脸 | 提示确保画面中只有一人 |
| 216634 | 人脸质量不达标 | 模糊、遮挡、角度偏 | 提示保持稳定并正对镜头 |
| 222207 | 未找到匹配的用户 | 底库中无该用户 | 转入建档流程 |
| 216401 | 用户已存在 | 重复调用注册接口 | 改用 REPLACE 或 update 接口 |
| 223120 | 活体检测未通过 | 疑似照片或翻拍 | 提示真人操作，并限制重试次数 |
| 17 / 18 | 请求量限流 | 并发过高或未做缓存 | 加缓存、加队列、必要时提额 |
| 216500 | 未知错误 | 服务端异常 | 记录完整返回体，上报排查 |
排查经验上，我建议在服务端把完整的原始返回值落一份日志，包括请求参数（图片只记长度和哈希，不要记内容）、返回码、错误信息、耗时。线上出问题时，光看一个错误码是不够的，你需要看到完整的上下文。但同时要注意，日志里绝对不能明文存人脸图片和敏感信息，只记哈希值就够了。
6.2 文档里不会写的经验
经验一：底库照片的质量决定了整个系统的天花板。这句话我反复强调。很多项目初期为了快速上线，建档时用quality_control: NORMAL甚至LOW，结果后面每次比对都要跟一张糊图比，通过率怎么调都上不去。建档这一步就该用 HIGH，宁可让用户多拍两次，也别把垃圾照片存进底库。
经验二：活体检测要跟重试策略绑定。活体失败如果允许无限重试，攻击者可以不停地试探，总有蒙对的时候。我在服务端做的策略是：同一用户同一设备，十分钟内活体失败超过五次就锁定，需要走人工通道解封。这个逻辑放在服务端，前端拦不住绕过。
经验三：单帧活体不如多帧。接口方案默认是单张图片做活体判断，安全性天然弱于视频活体。如果你的业务风险较高（比如涉及资金），建议走 H5 视频活体方案，让用户在页面上做一个随机动作（眨眼、转头），连续采样多帧，防翻拍能力强得多。代价是接入多一个 H5 页面，用web-view承载，交互体验会稍微割裂一些。
经验四：用 web-view 承载 H5 认证页时，返回逻辑要特别处理。这是我最近才踩的坑。web-view页面的返回行为和普通页面不一样，用户在认证页按物理返回键，可能直接退出了整个流程，也可能什么都没发生。稳妥的做法是在web-view外层包一个自己的页面，监听onBackPress，在返回前先跟 H5 页面通信确认当前状态：如果认证正在进行中，就提示“认证尚未完成，确认退出吗”；如果已经完成，就直接跳转到结果页。这部分需要 H5 页面配合抛出状态消息，双方约定好消息格式。
经验五：把“失败原因”翻译成人话。接口返回的 216634，用户看不懂，客服也看不懂。所以我在服务端做了一层映射：把错误码转成用户能理解的中文提示，同时给客服侧输出一份更详细的说明文档。这个映射表是要持续维护的，每次遇到新错误码就补一条。看起来是小事，但能省掉大量客服工单。
经验六：留一个“降级开关”。再稳定的第三方服务也可能出现波动。我在配置里留了一个开关，一旦人脸服务整体不可用，就自动切换到备选验证方式（短信验证码或人工审核），保证业务不中断。这个开关平时是关着的，但真出事的时候能救命。
经验七：定期核对调用量和账单。按调用次数计费的接口，最怕的是被刷。建议做一个简单的告警：当日调用量超过往日均值的三倍就发通知。前面提到的 AK/SK 泄露问题，如果有这个告警，损失能控制在很小范围内。
我个人在实际项目里最大的体会是，人脸认证这件事技术难度不高，工程难度不低。接口文档看半天就能调通，但要让它在几百种机型、各种网络环境、各种用户行为下都稳定工作，需要的是持续打磨：权限引导加一句文案、压缩参数调一档、重试逻辑加一个幂等键、错误提示换一个说法。这些细节堆起来，才是决定这套认证功能好不好用的东西。
另外一个建议是，从第一天就把日志和指标埋好。每次认证记录：设备型号、系统版本、采集耗时、接口耗时、活体分、质量分、比对分、最终结果。等你的通过率从 70% 提到 90% 的时候，你会发现这些数据比任何经验判断都可靠——你能清楚地看到是哪一类机型拖了后腿，是哪一档分数区间的用户被误拒了。这套数据体系建起来之后，后续任何调整都是有据可依的，而不是拍脑袋改阈值。
