纯血鸿蒙没有 AOSP，Android 的 .aar 拖进去直接编译失败：人脸 SDK 鸿蒙版接入全记录
先说结论
- HarmonyOS NEXT 必须用百度人脸实名认证方案 6.x 鸿蒙专版（.har 格式），Android 的 .aar 和 .so 直接搬会编译/运行双失败。
- 授权文件是 idl-license.face-harmony（不是 face-android），连同密钥、配置文件一起放
rawfile目录，签名信息必须在build-profile.json5里配对。 - 模拟器会掩盖 ABI 问题——so 库缺失往往在真机上才炸
UnsatisfiedLinkError，调试期务必以真机为准。
一、为什么 Android 版 SDK 不能直接搬
HarmonyOS NEXT 从系统层面去掉了 AOSP 兼容层，不装安卓虚拟机，应用只能用 ArkTS/ArkUI 加 Native（NAPI）的方式开发。手里的 Android 依赖、.jar、甚至部分 .so，都别指望拖进工程就能跑。
百度单独做了鸿蒙适配：人脸实名认证 APP 方案 6.x 明确支持 HarmonyOS NEXT，给的是 .har（Harmony Ability Package）格式的鸿蒙包，不是 Android 的 .aar。两种拿法，取决于你要做端云完整方案还是仅服务端接入。
| 接入方式 | SDK 文件 | 说明 |
|---|---|---|
| 方案集成 | facesolutionlib-1.0.0.har | 端云通讯模块 |
faceplatformlib-2.0.1.har | 人脸能力模块 | |
liantianSharedLibrary-1.0.1.har | 风控能力模块 | |
| 服务端接入 | lib_Enhance.har | 百度人脸SDK，含人脸能力+风控能力 |
提醒：具体拿哪个包、几个文件，取决于你要做"端云完整实名认证方案"还是"仅服务端接入"，以控制台下载的示例工程为准，别只看文档目录。
二、接入前准备（10 分钟）
- 百度智能云控制台创建应用，开通人脸实名认证相关服务，拿到应用的 API Key / Secret Key。
- 从控制台下载鸿蒙（HarmonyOS NEXT）示例工程和 SDK 资源。
- 准备一台 HarmonyOS NEXT 真机（模拟器只能做 UI 调试）。
三、四步接入
步骤 1：引入 .har 依赖
把 SDK 的 .har 文件放进工程，在 oh-package.json5 里声明依赖（以你实际下载的包名为准）：
{
"name": "my_face_app",
"version": "1.0.0",
"dependencies": {
"facesolutionlib": "file:./libs/facesolutionlib-1.0.0.har",
"faceplatformlib": "file:./libs/faceplatformlib-2.0.1.har",
"liantianSharedLibrary": "file:./libs/liantianSharedLibrary-1.0.1.har"
}
}
步骤 2：授权文件进 rawfile
从控制台创建应用后，下载四类配置文件，全部放到工程 resources/rawfile/ 目录：
| 文件 | 作用 |
|---|---|
idl-license.face-harmony | 人脸授权文件（鸿蒙版后缀是 face-harmony） |
idl-key.face-android | 大数据风控密钥文件 |
local_config.json | 本地配置 |
quality_config.json | 质量控制配置（姿态角、光照、模糊度、遮挡阈值） |
坑位预告：授权文件放错目录或在构建时被过滤，SDK 初始化不会立刻报错，通常是第一次采集时才返回授权校验失败，排查起来很费时间。
步骤 3：签名配置
在 build-profile.json5 中配置宿主应用的签名信息（signingConfigs / material），签名包名必须与你在控制台创建应用时申请授权使用的包名一致。签名不匹配 = 授权校验不过，这是最容易排查又最容易被忽略的一条。
步骤 4：权限声明 + 初始化 + 采集
在 module.json5 声明相机权限：
"requestPermissions": [
{
"name": "ohos.permission.CAMERA",
"reason": "用于人脸采集与实名认证",
"usedScene": { "abilities": ["EntryAbility"] }
}
]
ArkTS 侧初始化与采集的调用方式（示意，接口命名以控制台下载的官方示例工程为准）：
// 1. 初始化（应用启动时或进入实名认证页面前）
FaceManager.init(context, callback);
// 2. 配置采集参数：活体模式、动作个数、质量控制
let config = {
livenessType: 'action', // action / silent / zijin(炫瞳)
actionsNum: 2, // 动作活体：眨眼、张嘴、转头等
isOpenMultiFrame: true
};
// 3. 启动采集页面，拿到加密后的图片流
FaceManager.startFaceCollect(config, (result) => {
// result 内含加密图片、设备指纹等，用于端云互验
});
// 4. 与服务端配合：云端调用人脸实名认证(V4)接口完成核验
说明：活体有三种：静默活体、炫瞳活体、动作活体（眨眼/张嘴/左右转头/抬头低头/点头摇头等 8 个动作可配顺序），动作活体完全在本地离线跑。采集到的图片端侧直接加密（支持 AES 与国密），云端解密后再核验，黑产想绕过采集端直接打云端接口这条路基本堵死。
四、真机踩坑清单（按我遇到的概率排）
| 现象 | 根因 | 解决 |
|---|---|---|
真机运行报 UnsatisfiedLinkError | SDK 的 so 库没覆盖目标 ABI，或被打包过滤 | 确认 arm64-v8a 目录下库文件齐全；鸿蒙真机几乎都是 arm64，x86 模拟器反而不触发此错 |
| 初始化/采集时授权校验失败 | 授权文件没进 rawfile，或签名包名和控制台申请时不一致 | 核对 idl-license.face-harmony 位置 + build-profile.json5 签名 material |
| 拿 Android 授权文件（face-android）直接放鸿蒙工程 | 后缀对应平台，鸿蒙必须 face-harmony | 去控制台按鸿蒙平台重新下载授权文件 |
| 模拟器演示一切正常，产品验收时真机崩 | 模拟器 x86 指令集掩盖 ABI 缺失 | 规范化：每个里程碑都跑一遍真机回归 |
| 风控提示"风险设备"拒绝采集 | 调试机开启开发者模式/模拟器/root 环境触发风控 | DevEco 真机调试属于正常开发路径；正式测试用非调试状态设备 |
五、端云配合：不只是"采一张图"
接入之前我也以为人脸 SDK 就是"拍照→传云端→返回结果"。翻完鸿蒙这套方案的文档，端侧要干的活比想象的多：
- 端云互验加密：SDK 输出加密图片（AES/国密），云端解密核验。想绕过 App 直接打云端接口？走不通。
- 风控设备指纹：SDK 采集设备环境信息随请求上传，云端识别风险设备。脚本攻击、ROM 注入、视频劫持、虚拟机批量、病毒侵入——这些手段云端能拦住。
- 云端核验链：人脸质量检测 → 活体检测 → 人脸实名认证，串行执行，任一步不过即终止，省掉一堆无效请求。实名认证推荐阈值 80（误识率万分之一量级），按业务精度自己调。
总之：端侧采集、加密、风控，云端解密、比对、核验，少一个都不行。联调服务端时别只盯着返回值调阈值，端侧的采集参数（质量控制配置）也要一起排。
相关文章专栏
专栏一：