uni-app调用原生人脸插件必须通过uni.requireNativePlugin加载，否则App端不执行逻辑；插件名须与package.json中name字段完全一致；仅H5/小程序环境不支持，需条件编译隔离；Android/iOS需分别配置运行时权限与Info.plist描述；预览分辨率、动作超时、光照提示影响活体检测；base64图像需清洗前缀并匹配后端要求；建议初始化后预热SDK提升体验。
uni-app调用原生人脸插件必须走 uni.requireNativePlugin
不通过 uni.requireNativePlugin 加载的插件，在 App 端（iOS/Android）根本不会执行原生逻辑，只会静默失败或报 undefined。这是最常被忽略的前提——哪怕你把插件文件放对了路径、也配好了 manifest.json，没走这个 API 就等于没调用。
常见错误现象包括：faceplugin.detectLiveFace is not a function、控制台无任何日志、安卓端黑屏无预览、iOS 端直接卡在权限弹窗后无响应。
- 插件名必须与
nativePlugins/xxx/package.json中的name字段完全一致（区分大小写），例如"name": "bd-face-plugin"，调用时就得写uni.requireNativePlugin('bd-face-plugin') - 不能在
H5或小程序环境里测试该插件行为，uni.requireNativePlugin在非 App 环境返回undefined，需用条件编译隔离：#ifdef app-plus - 首次调用前建议加空值校验：
if (!facePlugin) { uni.showToast({ title: '插件未加载', icon: 'none' }); return; }
Android 和 iOS 权限配置不能只靠 manifest.json
仅在 manifest.json 勾选“相机”权限远远不够。Android 需运行时动态申请，iOS 需在 Info.plist 里补全描述字段，否则插件初始化就失败。
- Android：必须手动调用
uni.authorize({ scope: 'scope.camera' })，且需在uni.getSystemInfo返回platform === 'android'后再请求；部分厂商（如华为、小米）还需额外处理后台权限白名单 - iOS：除了
manifest.json的配置，必须在 Xcode 工程的Info.plist手动添加键NSCameraUsageDescription，值为中文说明（如“用于人脸识别验证”），否则 App 启动即崩溃或权限弹窗不出现 - 插件内部若涉及存储临时图片，Android 还需
WRITE_EXTERNAL_STORAGE（Android 10+ 推荐改用MediaStoreAPI，插件应适配 scoped storage）
活体检测失败的三大高频原因
调用 detectLiveFace 或类似方法后返回 face_not_detected、light_too_dark、pose_unqualified，通常不是算法问题，而是环境或参数配置不当。
- 前端预览分辨率过高：插件底层 SDK 对输入帧尺寸有硬性限制（如百度 SDK 要求 ≤ 1280×720），用
resolution="medium"或显式指定width/height属性 - 动作指令超时未匹配：传入的
actionType: 'blink'要求用户在timeout内完成眨眼，但默认timeout可能只有 3000ms；实测建议设为5000，并配合 UI 提示“请眨眼一次” - 光照/遮挡未做前端提示：插件返回质量分（如
qualityScore）但不主动弹窗。应在回调中判断res.data.quality 时，用uni.showToast提示“请确保光线充足、面部无遮挡”
插件返回的 base64 图像不能直接传给后端比对
很多开发者拿到 res.data.imageBase64 就直接发给后端，结果后端解码失败或特征提取异常——因为插件返回的 base64 前缀可能是 data:image/jpeg;base64,，也可能是纯二进制 base64 字符串，不同插件实现不一致。
- 先做标准化清洗：
const cleanBase64 = res.data.imageBase64.replace(/^data:image\/\w+;base64,/, '') - 确认后端期望格式：腾讯云要求 raw jpeg bytes，百度 AI 平台接受 base64（不含前缀）或 url；若后端用 OpenCV 解码，务必保证是完整 JPEG 格式，不能是 YUV/NV21 原始数据（某些插件会返回 raw data）
- 敏感操作建议本地脱敏：插件若支持
returnFeature: true，优先传特征值而非图像，避免生物信息明文传输
实际项目里最容易被跳过的，是插件初始化后的「预热」步骤——比如百度插件需先调用 initSDK 加载模型，虹软插件需 activeEngine 激活授权，这些操作耗时 300–800ms，放在页面 onShow 里同步触发，比等用户点“开始认证”再初始化，体验好得多。
