唯一稳定可用的面容ID解锁入口是uni.startSoterAuthentication;它跨平台调用iOS LAContext和Android BiometricPrompt,需严格满足三重前提:设备支持、用户已录入、服务端动态生成challenge,且iOS必须完成FaceID模块勾选、NSFaceIDUsageDescription非空、Xcode开启Face ID Capability。

uni.checkFaceID 只检测能力,不触发解锁
调用 uni.checkFaceID 后返回 {available: true},不代表能立刻“解锁”——它只告诉你设备支持且用户已授权 Face ID / Touch ID,但不唤起系统认证弹窗,也不返回任何可用于校验的凭证。真正在 App 端完成面容 ID 解锁,必须走认证流程,而非探测流程。
真正能解锁的只有 uni.startSoterAuthentication
这是 uni-app 当前(2026 年)唯一稳定、跨平台、可生产使用的面容 ID 解锁入口。它底层调 iOS 的 LAContext,能正确弹出系统级面容识别 UI,并返回带签名的 result 字符串,服务端可用该字符串验签并确认身份。
调用前必须满足三个硬性条件:
-
uni.checkIsSupportSoterAuthentication返回res.supportMode包含'facial'(说明系统支持面容) -
uni.checkIsSoterEnrolledInDevice({ checkAuthMode: 'facial' })返回isEnrolled: true(说明用户真录了面容) -
challenge参数必须由服务端动态生成(如 UUID),前端拼接或固定值会导致后端验签失败
示例关键调用:
uni.startSoterAuthentication({
requestAuthModes: ['facial'],
challenge: 'server-generated-uuid-here',
authContent: '请验证面容以继续'
})
iOS 配置漏一项,就完全静默失效
不是报错,而是点击无反应、不弹窗、success/fail 回调都不触发——这是最常被忽略的坑。
必须同时完成以下三件事:
- manifest.json → App SDK 配置 → iOS 模块配置中勾选「FaceID」
- manifest.json 的
NSFaceIDUsageDescription值不能为空字符串或纯空格(否则 App 启动即闪退) - Xcode 工程需开启 Face ID Capability(entitlements 文件里要有
com.apple.developer.authentication-services)
缺任意一项,uni.startSoterAuthentication 在 iOS 上就等于没写。
Android 和 H5/小程序根本不能走面容 ID 流程
Android 设备即使有前置摄像头,uni.startSoterAuthentication 传 ['facial'] 也大概率 fallback 到指纹,或直接返回不支持;H5 和所有小程序端调用该 API 恒 fallback(H5 弹密码框,小程序受限于容器能力,iOS 微信甚至不支持面容)。别在条件编译里写 #ifdef APP-PLUS 就默认能用面容——必须用 uni.getSystemInfoSync().platform === 'ios' 再次校验,且仅对 iOS 用户展示“面容登录”按钮。
最后提醒:真机调试务必用「自定义基座」,标准基座或云打包不带完整生物识别 SDK,调用必静默失败。厂商适配不是代码问题,是原生层没准备好,JS 层感知不到。


















