uni-app中微信小程序人脸识别API调用失败的常见原因有哪些？

Question

在uni-app中调用微信小程序人脸识别API（`wx.startFacialRecognitionVerify`/`wx.startFacialRecognitionVerifyWithUpload`）失败，常见原因包括：① **未开通人脸核身服务**——需在微信支付商户平台开通并完成企业认证；② **appid未绑定或权限不足**——需在微信公众平台“接口权限”中确认已授权“人脸识别”能力；③ **调用环境非真机或非微信原生环境**——uni-app的H5/APP端不支持，仅支持微信小程序平台（`mp-weixin`），且必须在iOS 12+/Android 7.0+真机运行；④ **用户未授权摄像头**——需提前调用`uni.authorize({scope: 'scope.camera'})`并处理拒绝逻辑；⑤ **参数错误**——如`encrytedData`、`iv`、`reqId`格式不符，或`name`、`idCardNumber`未脱敏/未Base64编码；⑥ **签名验证失败**——后端验签时`sign`生成方式与微信规则不一致（需使用RSA-SHA256）。建议通过`wx.getSystemInfoSync().SDKVersion`校验基础库版本≥2.21.0，并结合`wx.onFaceDetectResult`监听过程态。

Answer 1

```html

一、环境准入层：运行平台与基础能力校验

人脸识别API是微信原生高权限能力，wx.startFacialRecognitionVerify仅在 mp-weixin 编译目标下生效，H5/APP/快应用等端完全不可用。需通过 uni.getSystemInfoSync().platform === 'ios' || 'android' + wx.getSystemInfoSync().SDKVersion 双重断言（≥2.21.0）。真机调试是硬性前提——开发者工具模拟器返回 errCode: -1 且无错误详情。

二、资质授权层：商户侧与公众号侧双通道开通

• 微信支付商户平台：进入「产品中心 → 人脸核身」，完成企业对公账户认证、营业执照上传、法人身份证核验；开通后获取 facial_verify_id（非AppID）
• 微信公众平台：登录「开发管理 → 接口权限」，确认「人脸识别」接口已勾选并提交审核（需提供业务场景说明及合规承诺函）

未完成任一环节均导致调用时返回 errCode: 880001（服务未开通）或 errCode: 880002（权限不足）。

三、前端授权与生命周期管控

摄像头权限必须显式申请且不可静默获取：
uni.authorize({ scope: 'scope.camera' }) 需在调用人脸识别前独立触发，并监听 uni.onAuthComplete。若用户拒绝，需引导至系统设置页（uni.openSetting），否则后续调用直接失败且不抛出明确错误码。

四、参数构造层：六要素强校验规范

字段	格式要求	常见错误
reqId	32位小写十六进制字符串（UUIDv4）	含大写字母或短于32位
name/idCardNumber	UTF-8编码后Base64（非URL安全Base64）	前端直接传明文或使用btoa错误编码
encryptedData/iv	微信服务端下发的AES-128-CBC密文（需后端解密）	前端误用本地生成的mock数据

五、签名验证层：RSA-SHA256全链路一致性

后端验签必须严格遵循微信文档：
① 拼接原始字符串：reqId + encryptedData + iv + name + idCardNumber（顺序不可变）
② 使用商户私钥（PKCS#8 PEM格式）进行 RSA-SHA256 签名
③ 前端传入的 sign 字段必须为 Base64 编码后的签名值
任意环节偏差将导致 errCode: 880005（签名无效）。

六、过程态监控：从黑盒调用到可追踪诊断

graph LR
A[调用 wx.startFacialRecognitionVerify] --> B{是否进入采集界面？}
B -->|否| C[检查环境/权限/参数]
B -->|是| D[wx.onFaceDetectResult 监听]
D --> E[status=1：检测中]
D --> F[status=2：比对成功]
D --> G[status=3：失败/超时]
G --> H[捕获 errCode & errMsg]

七、典型错误码速查表与根因映射

• errCode: -1 → 环境非真机或基础库版本过低
• errCode: 880001 → 商户平台未开通人脸核身服务
• errCode: 880004 → reqId 重复或格式非法
• errCode: 880006 → name/idCardNumber 未Base64编码或含非法字符
• errCode: 880007 → 后端验签失败（RSA密钥不匹配或摘要算法错误）

八、生产级健壮性增强实践

建议封装 FaceVerifyService 类，内置：
✅ 自动降级逻辑（当 wx.canIUse('startFacialRecognitionVerify') 返回 false 时启用OCR+活体视频替代方案）
✅ 参数预校验中间件（正则校验身份证号、Unicode转义处理姓名）
✅ 全链路埋点（从 authorize 开始记录 timestamp、SDKVersion、errCode、耗时）
✅ 错误归因看板（聚合 errCode 分布，关联设备型号/OS版本/网络类型）

九、合规性红线：GDPR与《个人信息保护法》落地要点

调用人脸识别前必须：
• 弹窗展示《人脸信息处理告知书》并获取单独明示同意（不可捆绑在用户协议中）
• 存储的 encryptedData 和 iv 必须加密落库，密钥由KMS托管
• 用户撤回授权后，立即销毁本地缓存的生物特征临时凭证
• 每次调用需记录操作日志（时间、用户ID、reqId、操作人IP）并保留6个月

十、跨端兼容演进路径：面向未来的架构设计

当前 uni-app 仅支持微信小程序，但可通过以下方式构建扩展性：
① 定义抽象接口 IBiometricService（含 verify()、getStatus() 方法）
② 实现微信专有适配器 WechatFaceAdapter 与支付宝适配器 AlipayFaceAdapter
③ 在 uni-app conditional compilation 中动态注入适配器实例
④ 后续接入鸿蒙 ArkTS 时仅需新增 HMSFaceAdapter，核心业务逻辑零修改

```