uni.startSoterAuthentication是uni-app唯一跨平台可用的官方生物认证接口，它底层调用iOS的LAContext和Android的BiometricPrompt，必须传动态challenge、设双模式requestAuthModes、配齐原生权限与SDK模块，resultJSON需由服务端验签。
uni.startSoterAuthentication 是唯一跨平台可用的官方接口
别折腾 uni.checkFingerPrint 或 uni.checkFaceID 单独调用——它们只是能力探测，不触发验证，且 Android 上行为极不稳定。真正能弹出系统级生物认证弹窗、返回可验签凭证的，只有 uni.startSoterAuthentication。它底层调 iOS 的 LAContext 和 Android 的 BiometricPrompt，不是模拟，是真走系统通道。
注意：这个 API 在 H5 和小程序里也能调，但 App 端（app-plus）才真正生效；H5 永远 fallback 到密码输入，小程序则受限于微信容器能力（iOS 微信不支持指纹，只走 Face ID）。
- 必须传
challenge，且每次调用都要生成新值（比如Date.now() + Math.random().toString(36).substr(2, 9)），写死会导致后端验签失败 -
authContent在 iOS 上强制显示，文案必须明确（如“请验证面容以完成支付”）；Android 部分厂商会忽略，但留空在 iOS 会直接无提示卡住 -
requestAuthModes建议始终设为['fingerPrint', 'facial']双模式——单写fingerPrint在 iPhone 用户只配了 Face ID 时会被无视，部分国产 Android 机型（如 EMUI 10.1）甚至会因该字段缺失直接报错
权限和配置漏一项，API 就静默失效
不是报错，而是调用后没反应、没弹窗、回调都不触发——这是最坑的。根本原因是原生层没准备好，JS 层完全感知不到。
iOS 必须同时满足三件事：
- Xcode 中开启
Face ID/Lockdown ModeCapability -
manifest.json的NSFaceIDUsageDescription字段不能为空字符串或纯空格（否则启动即崩溃） - App SDK 配置里勾选「FaceID」模块（HBuilderX → manifest.json → App SDK 配置 → iOS 模块配置）
Android 更容易踩坑：
-
manifest.json里手动加权限：<uses-permission android:name="android.permission.USE_FINGERPRINT"></uses-permission>（即使 targetSdkVersion ≥ 30，uni-app 当前版本仍依赖它初始化） - Android 9+ 建议额外加
android.permission.AUTHENTICATE_ACCOUNTS，否则某些 ROM（如 MIUI 12.5）会拒绝调起 BiometricPrompt - OAuth 模块必须在 manifest.json → App 模块配置 → OAuth 中勾选「指纹识别」和「人脸识别」两项——只勾一个，部分 Android 设备（尤其华为 EMUI 12）会初始化失败
success 回调里的 resultJSON 不是 token，是待验签的加密凭证
拿到 { success: true, resultJSON: "xxx" } 后直接存进 uni.setStorageSync 或拼进 URL 跳转，等于把密钥明文暴露给历史记录和系统最近任务栏。这不是前端能自行解析的数据，是给后端做联合验签用的。
-
resultJSON是 base64 编码的 JSON 字符串，服务端需先atob()再JSON.parse() - 关键字段包括：
rawData（签名原文）、signature（签名值）、signedChallenge（必须和服务端下发的challenge完全一致） - 前端必须同时上传设备标识（如
uni.getSystemInfoSync().model）和认证类型（fingerPrint或facial），后端才能决定调 Apple 的attestation接口还是 Google 的BiometricPrompt.CryptoObject解析逻辑 - 绝对不要在 fail 回调里自动重试——用户连续取消 2 次，iOS 会锁死生物认证 60 秒，Android 部分机型也会触发系统级限频
真机调试必须用自定义基座，云打包前务必验证
标准基座或云打包生成的 App，大概率不带完整生物识别 SDK 支持。很多开发者本地调试正常，一上测试环境就黑屏或无响应，根源在此。
自定义基座构建流程中，要确认：
- Android 插件路径是否为
nativePlugins/android/xxx/，iOS 是否为nativePlugins/ios/xxx/（大小写敏感，文件名必须和uni.requireNativePlugin('xxx')完全一致） - Android 插件的
plugin.xml是否声明了androidx.biometric:biometric:1.2.0+依赖（低于 1.1.0 版本在 Android 12+ 无法触发活体检测） - iOS 插件是否包含
tencentcloudfaceid.framework或LocalAuthentication.framework的显式链接（仅靠 Capability 开启不够）
最容易被忽略的是：用户点 × 关闭弹窗后，500ms 内再次调用 uni.startSoterAuthentication 会直接进入 fail，errMsg 是 cancel，且无法恢复——必须等间隔超时，或引导用户手动点击重试按钮。
