uni.checkFaceID仅检测生物识别能力，不进行身份认证；需分别配置iOS的FaceID模块与NSFaceIDUsageDescription、Android的USE_FINGERPRINT权限；H5/小程序恒返回false，必须做平台校验与降级；Android 9+需用原生插件兼容BiometricPrompt。
uni-app 里做 App 端指纹或人脸解锁，不能只调 uni.checkFaceID 就完事——iOS 和 Android 行为不一致、权限配置缺一不可、H5/小程序恒返回 false，真机调试前漏掉任一环节，调用就静默失败或报 unauthorized。
uni.checkFaceID 在 iOS 和 Android 上的权限差异
iOS 要求在 manifest.json → App SDK 配置 → iOS 模块配置中勾选「FaceID」，且必须填写 NSFaceIDUsageDescription（值不能为空字符串，否则 App 启动即崩溃）；Android 则要求 targetSdkVersion ≥ 23，并在权限配置里手动添加 android.permission.USE_FINGERPRINT——注意：Android 9+ 已废弃该权限，但 uni-app 当前版本（截至 2026 年 4 月）仍依赖它触发底层识别流程。
常见错误现象：
- 未勾选 iOS FaceID 模块 → Xcode 编译通过，但运行时调用
uni.checkFaceID直接返回false，无任何提示 -
NSFaceIDUsageDescription值为空或仅空格 → iOS App 启动闪退，Xcode 控制台报NSFaceIDUsageDescription is missing - Android 端没加
USE_FINGERPRINT权限 →uni.checkFaceID返回unauthorized，且不会弹系统授权框
调用前必须做的平台判断与降级逻辑
uni.checkFaceID 在 H5 和小程序端永远返回 false，不能靠条件编译“绕过”——如果业务逻辑里写了 #ifdef APP-PLUS 就直接走生物识别，而没写 fallback（比如密码/手势），上线后 H5 用户会卡死在登录页。
实操建议：
- 始终用
uni.getSystemInfoSync().platform === 'app'做二次校验，比仅依赖条件编译更可靠 - 调用
uni.checkFaceID后，必须检查返回值是否为true；若否，立即触发备用方案（如跳转 PIN 码输入页） - 不要在
onLoad里直接调用，建议放在用户点击「指纹登录」按钮后执行，避免冷启动时权限弹窗被系统拦截
实际解锁流程：从检测到鉴权的两步分离
uni.checkFaceID 只负责检测设备是否支持并已授权生物识别，它不参与身份核验——真正的“解锁”需后端比对用户绑定的生物特征模板。也就是说，前端调用的是设备能力，后端才是认证主体。
典型流程：
- 第一步：调用
uni.checkFaceID，成功后调用uni.startSmsVerification或自定义接口获取临时 token（用于防重放） - 第二步：调用原生插件（如腾讯云人脸核身插件）或服务端 API 提交活体检测结果 + 加密后的设备特征，由后端完成 1:1 比对
- 关键点：前端绝不能把用户生物特征数据（如 face token）明文传给后端，应使用插件封装的加密通道或服务端下发的 AES 密钥临时加密
容易踩的坑：uni.checkFaceID 成功 ≠ 用户身份已确认，它只是打开设备识别能力的钥匙，不是开门的锁。
Android 9+ 设备上指纹失效的兼容处理
Android 9（API 28）起，USE_FINGERPRINT 权限被标记为 deprecated，系统改用 BiometricPrompt API。uni-app 当前未自动适配新 API，导致部分 Android 10+ 设备调用 uni.checkFaceID 返回 false，即使系统设置里已开启指纹。
应对方式：
- 优先改用原生插件方案（如
TencentFacePlugin或百度 AI 插件），它们已封装BiometricPrompt兼容逻辑 - 若坚持用
uni.checkFaceID，需在 Android 端补充android.permission.USE_BIOMETRIC（虽然 uni-app 不认它，但某些 ROM 会因此放开限制） - 务必在测试机列表中加入 Android 12/13 的主流机型（如小米 13、华为 Mate 50），不能只测模拟器
最常被忽略的一点：很多团队只在 iOS 上完整走通流程，却默认 Android “应该也行”，结果上线后大量中高端 Android 用户反馈指纹图标灰掉——这不是代码 bug，是权限链断裂。
