简介本资源为SeetaFace6人脸识别算法的Android DEMO工程面向需要在移动端集成人脸检测、关键点定位、人脸识别等能力的Android开发者尤其适合具备一定NDK与JNI基础的中高级工程师。工程同时提供arm64-v8a与armeabi-v7a两套so库可直接用于真机调试与二次开发。压缩包共565个文件约146.83MB包含276个hpp与87个h头文件、75个xml配置、60个so动态库以及少量java、gradle、mk等构建与源码文件覆盖算法头文件、模型资源与Android工程结构。目前已有751人学习下载。借助该工程读者可省去手动编译SeetaFace6的繁琐流程快速验证人脸检测、活体检测、质量评估、年龄性别估计及口罩检测等模型在Android端的实际效果并参考作者博文完成环境配置与排错适合作为移动端人脸识别项目的起步模板。1. 从一次编译翻车说起seetaface6 Android DEMO 到底该怎么装去年帮一个做门禁考勤的团队调 seetaface6 的 Android 端他们从别处拷来一份 DEMO 工程armeabi-v7a的 so 能跑切到arm64-v8a真机直接闪退logcat 里只有一行UnsatisfiedLinkError。折腾一下午才发现工程里只塞了 32 位的 so64 位目录是空的而现在的手机默认只加载 64 位库。这就是 seetaface6 Android DEMO 最典型的翻车姿势——不是代码写错是 so 库没配对。这份资源解决的就是这件事一个已经配好arm64-v8a和armeabi-v7a两套 so 库的 Android DEMO 工程拿到手不用自己去编译 C 源码、不用折腾 NDK 版本直接能跑人脸检测、关键点定位这些基础能力。适合两类人一是刚接触 android seetaface 集成、想先看效果再决定要不要深入的新手二是被 so 架构问题卡住、只想找个能跑通的参考工程的老手。下面按我实际装一遍的顺序把环境、导入、配置、验证和排错讲清楚。2. 装前把环境列清Android Studio、NDK 与 so 架构的版本取舍2.1 版本对照表别让工具链先把你绊倒seetaface6 的 Android DEMO 本质是一个带 JNI 层的普通 Android 工程so 库已经预编译好所以对 NDK 的依赖没有想象中那么重但版本选错照样出问题。我一般按下面这张表来配踩坑概率最低。组件推荐版本说明Android Studio2022.3 及以上老版本对abiFilters提示不友好Gradle Plugin7.4 左右太新会改jniLibs默认路径行为compileSdk33 或 34低于 30 部分 API 缺失minSdk21seetaface6 so 最低支持到 21NDK21.4.7075529仅当你要自己重编 so 时才需要JDK11JDK 17 偶发 Gradle 同步失败这里有个反直觉的点很多人以为 so 库工程必须装 NDK其实这份 DEMO 的 so 是现成的NDK 只在你想改 C 层、重新生成 so 时才用得上。新手阶段完全可以不装 NDK少一个变量少一份玄学。2.2 目录结构先看懂jniLibs 放哪、叫什么名导入工程前先确认 so 库的摆放位置。Android 工程加载 so 有两条路一是放在app/src/main/jniLibs/ABI/下二是放在app/libs/ABI/再在 Gradle 里指定sourceSets。这份 DEMO 用的是第一种标准做法。# 正确的目录结构ABI 目录名必须一字不差 app/src/main/jniLibs/ ├── arm64-v8a/ │ └── libseetaface_detector.so # 64 位库 └── armeabi-v7a/ └── libseetaface_detector.so # 32 位库目录名arm64-v8a和armeabi-v7a是 Android 规定的 ABI 标识写错一个字母Gradle 打包时不会报错但运行时会找不到库。so 文件名也要和 Java 层System.loadLibrary(seetaface_detector)里的字符串对应lib前缀和.so后缀由系统自动补你写中间那段就行。2.3 确认手机 ABI别拿 32 位库往 64 位机器上怼装之前花十秒确认目标设备的 ABI能省掉后面半小时的排查。用 adb 一条命令就能看# 查看已连接设备的 CPU 架构 adb shell getprop ro.product.cpu.abi # 输出示例arm64-v8a如果输出是arm64-v8a说明设备优先加载 64 位库工程里必须有对应的arm64-v8a目录否则就会走到UnsatisfiedLinkError。如果输出armeabi-v7a那 32 位库就够用。现在主流机型基本都是arm64-v8a所以这份同时带两套 so 的工程才省事——不用自己判断两个目录都放上系统按设备自动挑。3. 导入与配置Gradle 里 abiFilters 和 jniLibs 怎么写3.1 导入工程后先做三件事工程导入 Android Studio 后别急着点运行先按顺序确认三件事顺序错了会白等一次 Gradle 同步。第一步检查local.properties里的 SDK 路径是否指向你本机的 SDK路径带空格或中文会同步失败。第二步打开app/build.gradle确认ndk { abiFilters }里同时包含两个 ABI。第三步确认jniLibs目录没有被.gitignore之类的东西排除掉有时候从压缩包解压会丢文件。// app/build.gradle 关键片段 android { defaultConfig { ndk { // 同时保留两套 ABI系统按设备自动选择 abiFilters arm64-v8a, armeabi-v7a } } sourceSets { main { // 显式指定 jniLibs 路径避免默认路径被改后找不到 jniLibs.srcDirs [src/main/jniLibs] } } }abiFilters的作用是告诉 Gradle 只打包这两个架构的 so不写的话某些版本会把所有 ABI 都塞进去包体积翻倍。jniLibs.srcDirs是兜底万一你的工程结构不是标准布局这行能把它拉回来。这两处是 seetaface6 DEMO 配置里最容易漏的漏了不一定立刻报错但运行到加载库那一步就崩。3.2 加载 so 的 Java 层代码长什么样配置对了还得看 Java 层怎么加载。这份 DEMO 一般会在 Application 或某个工具类里做静态加载代码不长但位置有讲究。public class SeetaFaceEngine { static { // 名字对应 libseetaface_detector.so 去掉 lib 和 .so System.loadLibrary(seetaface_detector); } // native 方法声明具体实现在 so 里 public native long initDetector(String modelPath); public native int detect(long handle, byte[] imageData, int width, int height); }static块保证类第一次被引用时就加载 so加载失败会抛UnsatisfiedLinkError这个异常信息里通常带couldnt find libxxx.so看到它就直接去查 ABI 目录和文件名不用怀疑别的地方。native方法的方法名要和 so 里导出的符号一致这份 DEMO 已经对齐好了你改方法名就得同步改 C 层新手别动。3.3 模型文件放哪assets 还是外部存储seetaface6 的检测能力依赖模型文件DEMO 里通常把模型放在assets目录首次运行时拷贝到应用私有目录再传给 native 层。这一步不涉及 so但模型路径传错native 层会返回空句柄表现是检测一直失败但不崩。// 从 assets 拷贝模型到 filesDir再传给 native private String copyModel(String assetName) throws IOException { File outFile new File(getFilesDir(), assetName); if (!outFile.exists()) { try (InputStream is getAssets().open(assetName); OutputStream os new FileOutputStream(outFile)) { byte[] buf new byte[4096]; int len; while ((len is.read(buf)) 0) { os.write(buf, 0, len); } } } // native 层需要的是绝对路径 return outFile.getAbsolutePath(); }常见做法是只在文件不存在时拷贝避免每次启动都覆盖。返回的必须是绝对路径native 层不认assets://这种 URI。模型文件一般几十 MB别放错到会被清理的缓存目录。4. 避坑与排查so 加载失败的四种典型现象4.1 现象UnsatisfiedLinkError提示找不到库原因基本是 ABI 不匹配或目录名写错。先adb shell getprop ro.product.cpu.abi看设备架构再核对jniLibs下目录名是否完全一致。还有一种隐蔽情况工程里同时存在jniLibs和libs两个目录Gradle 只认配置的那个另一个里的 so 等于没放。解决方法是统一到jniLibs并在build.gradle里显式声明路径。4.2 现象能加载库但调用 native 方法直接崩多半是 so 和 Java 层方法签名对不上或者模型文件路径传了相对路径。用adb logcat | grep -i seeta过滤日志native 层崩溃前一般会打印模型加载失败的提示。确认模型已拷贝到filesDir且路径是绝对路径再检查 native 方法名有没有被混淆——release 包开了混淆但没保留 native 方法名也会崩。4.3 现象32 位能跑64 位闪退这是最典型的架构坑。原因是arm64-v8a目录缺失或里面的 so 是空文件。检查方法很简单解压 APK 看lib/arm64-v8a/下有没有对应的 so# 解压 APK 查看实际打包进去的 so unzip -l app-release.apk | grep lib/ # 正常应同时看到 lib/arm64-v8a/ 和 lib/armeabi-v7a/如果只有armeabi-v7a说明abiFilters没写全或 64 位目录没被识别。补上目录、确认abiFilters包含arm64-v8a重新打包即可。4.4 现象Gradle 同步报 jniLibs 相关错误常见于 Gradle Plugin 版本和sourceSets写法不匹配。新版插件对jniLibs.srcDirs的赋值方式有变化如果报Could not set unknown property改成jniLibs.srcDirs [src/main/jniLibs]这种直接赋值别用。另外路径里的反斜杠在 Windows 上要写成正斜杠或双反斜杠否则会被当转义符。4.5 现象装到真机提示 INSTALL_FAILED_NO_MATCHING_ABIS这个报错和 so 无关是 APK 里没有任何与设备匹配的 ABI。检查abiFilters是否把设备架构排除了或者打包时用了splits只出了单一架构的包。解决方法是确认abiFilters包含设备 ABI或者关掉 ABI splits 打全量包。5. 装完怎么验证跑通三步确认 so 真的生效了5.1 第一步确认 APK 里两套 so 都在打包完成后别急着装先解压 APK 核对。这一步能提前拦住 90% 的架构问题。# 列出 APK 内所有 so确认两个 ABI 目录都有内容 unzip -l app-debug.apk | grep \.so$ # 期望输出包含 # lib/arm64-v8a/libseetaface_detector.so # lib/armeabi-v7a/libseetaface_detector.so如果只看到一个回到第 3 章的abiFilters检查。两个都在再往下走。5.2 第二步真机安装后看加载日志装到真机打开应用用 logcat 盯加载过程。加载成功不会有明显提示加载失败会抛异常所以更稳的做法是在 Java 层加一行日志。static { try { System.loadLibrary(seetaface_detector); Log.i(SeetaFace, so loaded, abi Build.SUPPORTED_ABIS[0]); } catch (UnsatisfiedLinkError e) { Log.e(SeetaFace, so load failed, e); } }Build.SUPPORTED_ABIS[0]会打印设备首选 ABI和 APK 里的目录对一下就知道走的是哪套库。看到so loaded且 ABI 是arm64-v8a说明 64 位库生效了。5.3 第三步跑一次检测看返回结果最后用一张带人脸的图跑一次检测确认 native 层真的在工作。DEMO 里一般有现成的按钮点一下看有没有画出人脸框。如果框出来了整套环境就算通了。如果没框但没崩检查模型路径和图片格式——native 层通常要求传 RGB 或 BGR 的字节数组格式不对会返回 0 个结果。我自己的习惯是每次换机器或换 Android Studio 版本后都强制走一遍这三步解压看 so、logcat 看加载、跑图看结果。有一次偷懒跳过第一步结果 64 位目录里是个 0 字节的占位文件装到真机才崩又回头查了半天。从那以后这三步一步都不省。希望这份记录帮你少走一段弯路。本文还有配套的精品资源点击获取