结论：唯一稳定可用的生物认证接口是uni.startSoterAuthentication；它跨平台调用iOS LAContext和Android BiometricPrompt，需严格配置权限、双模式requestAuthModes、服务端生成challenge、校验resultJSON签名，且调用前必须完成设备支持、用户授权、生物信息录入三重判断。
直接上结论：别用 uni.checkFaceID 或 uni.checkFingerPrint 做登录入口，它们只探测能力、不触发认证，且在 Android 上大概率静默失败；真正能稳定弹窗、返回可验签凭证的，只有 uni.startSoterAuthentication。
为什么 uni.checkFaceID 在 Android 上总返回 false 或 unauthorized
这不是代码问题，是权限和配置没到位：uni.checkFaceID 在 Android 端实际依赖 android.permission.USE_FINGERPRINT —— 即使你 targetSdkVersion ≥ 33，uni-app 当前版本（2026 年中）仍强制检查这个已废弃的权限。不加，直接返回 unauthorized；加了但 manifest.json 没正确声明，或没勾选 OAuth 的“指纹识别”和“人脸识别”，就静默返回 false。
实操建议：
- 在
manifest.json→ App 模块配置 → OAuth（登录鉴权）中，必须同时勾选「指纹识别」和「人脸识别」——即使只用指纹，缺人脸选项会导致部分 Android 10+ 设备初始化失败 - Android 权限配置里手动添加字符串：
android.permission.USE_FINGERPRINT（不是 XML 标签） - iOS 端别漏填
NSFaceIDUsageDescription，值不能为空或纯空格，否则 App 启动即闪退 - 真机调试必须用「自定义基座」，云打包或标准基座不带生物识别 SDK，调用必失败
uni.startSoterAuthentication 调用前必须做的三件事
漏掉任一环节，就会黑屏、无弹窗、或成功回调但后端验签失败：
- 先调
uni.checkIsSoterEnrolledInDevice({ checkAuthMode: 'fingerPrint' })确认用户真录了指纹（iOS 面容同理，checkAuthMode: 'facial'） -
challenge参数必须是服务端生成的随机字符串（如 UUID），前端拼接或固定值会导致重放攻击，后端无法验签 -
manifest.json中 Android 权限必须包含android.permission.USE_FINGERPRINT，iOS 必须勾选 FaceID 模块并填好NSFaceIDUsageDescription
requestAuthModes 设成 ['fingerPrint', 'facial'] 是刚需
单写 ['fingerPrint'] 在 iPhone 用户只配了 Face ID 时会被系统忽略；部分国产 Android 机型（如 EMUI 10.1）甚至会因该字段缺失直接报错。双模式兜底才是真实可用的做法。
注意点：
- iOS 上
authContent是必显文案，留空会导致弹窗无提示，用户不知道要干什么 - Android 部分厂商会忽略
authContent，但不影响流程 -
success回调里的resultJSON是 base64 编码的 JSON 字符串，需服务端atob(resultJSON)后再JSON.parse，里面含signedChallenge，必须和服务端传入的challenge完全一致才可信 - 不要在
fail回调里自动重试——用户连续失败 3 次后，iOS 会锁死生物认证 60 秒
success 回调不等于登录成功
uni.startSoterAuthentication 的 success 只表示设备本地校验通过，返回的是加密凭证（resultJSON 字段），不是 token，也不是用户 ID。前端如果直接把 resultJSON 当作 token 发给后端，99% 会 401。
后端必须做可信验签：
- iOS：需解析
attestation+signature，向 Apple 服务验证凭证有效性 - Android：需处理
BiometricPrompt.CryptoObject输出，结合设备标识（如uni.getSystemInfoSync().model）做平台级校验 - 前端必须传给后端三要素：
resultJSON、authMode（fingerPrint或facial）、设备唯一标识（推荐用plus.device.getInfo().uuid）
最容易被忽略的是：H5 和小程序端 uni.startSoterAuthentication 会 fallback 到密码输入或直接失败，必须用 uni.getSystemInfoSync().platform === 'app' 做二次校验，不能只靠条件编译。
