最近用UniApp接人脸核身踩了几个坑记下来给后面做类似需求的朋友省点时间。一、uni.checkFaceID别盲用不少教程上来就说用uni.checkFaceID判断设备是否支持人脸实际跑一遍就会发现这东西在App端不太靠谱。iOS上它走的是系统FaceID封装有几个前置条件用户得在系统设置里开过人脸识别设备刚重启完或者权限还没初始化调用就返回false不是代码问题。Android更坑一些。targetSdkVersion大于等于29的时候回调可能直接丢失。查了半天发现是底层兼容性问题跟业务代码没关系。如果你们的App需要稳定支持Android建议直接用uni.checkIsSupportSoterAuthentication配合uni.startSoterAuthentication。这套方案微信支付和小程序都在用跨端兼容性有保证。二、白屏问题排查顺序调用uni.startFacialRecognitionVerify白屏排查这三个地方基本能解决权限配置iOS在manifest.json里必须配NSFaceIDUsageDescription描述不能空否则启动就崩。Android在manifest里勾选人脸识别模块摄像头权限会自动加。改完配置重新打自定义基座标准基座不支持人脸相关能力。调用时机别在onLoad或者onShow里直接调。原生控件渲染需要时间页面刚加载完就调容易白屏。用按钮触发或者setTimeout延迟200ms再调。页面元素冲突人脸识别页面是原生控件调用之前确认没有全屏弹窗、遮罩层或者自定义导航栏盖在上面。有的话先关掉再调。三、Android 9以上设备容易忽略的点Android 9API 28开始系统废弃了旧指纹API换成BiometricPrompt。UniApp对这套新API的适配有点滞后部分Android 10、11设备上调uni.checkFaceID直接返回false但系统设置里明明已经录了指纹或面容。两种处理方式改用封装了BiometricPrompt兼容逻辑的原生插件比如市面上几家主流人脸SDK都有对应的UniApp插件版在Android端补android.permission.USE_BIOMETRIC权限虽然UniApp底层不一定完全认但部分ROM会因此放开限制建议真机调试的时候iOS和Android主流机型都跑一遍小米13、华为Mate系列这类设备容易出问题。四、前端别碰验签逻辑前端拿到certifyId或者result之后直接传给后端接口不要在代码里做任何解析操作。javascript// 正确做法uni.startFacialRecognitionVerify({// ...success(res){// 直接传后端别自己解api.verifyFace({certifyId:res.certifyId}).then((){// 后端返回通过才算通过});}});人脸SDK返回的resultJSON多数是base64编码再加了一层加密前端解不了。后端必须调厂商的查询接口用certifyId去换真实的认证结果。前端判断认证通过的唯一依据是后端接口返回passed: true不认前端回调里的任何布尔值。五、自定义基座绕不开UniApp标准基座不支持原生能力扩展。人脸识别涉及摄像头、活体检测、加密传输纯JS搞不定。必须用HBuilderX打自定义调试基座把第三方人脸SDK的原生模块加进去。调用之前先检查插件有没有注册成功javascriptconst facePlugin uni.requireNativePlugin(‘com.example.face’);if (!facePlugin) {console.error(‘人脸插件未加载请确认自定义基座已重新编译’);return;}真机调试选「运行到自定义基座」选「运行到手机」的话uni.requireNativePlugin直接返回undefined。 **六、几个容易被卡住的细节** - challenge参数由服务端生成比如UUID前端不能写固定值否则有重放攻击风险 - iOS的NSFaceIDUsageDescription配置项描述必须写中文且不能为空 - 调生物识别之前先用uni.checkIsSoterEnrolledInDevice确认用户已经录了指纹或面容没录的话直接弹窗提示“未录入”体验很差 - SOTER认证成功后返回的resultJSON里有signature和signedChallenge后端要校验签名并比对challenge前端不需要处理 **总结** - 人脸核身接入的坑集中在权限配置、Android兼容和验签闭环三个地方。前端调用代码量不大但每一步漏了都可能静默失败。 - 建议先用官方demo把SOTER方案跑通确认设备兼容和权限流程都没问题之后再集成第三方SDK。一步到位容易卡在基座打包和权限配置的交叉问题上排查起来比较耗时。 - 官方demo和方案获取详情a hrefhttps://www.faceplusplus.com.cn/faceid-solution/ relnofollow target_blank旷视FaceID实人核验技术方案/a