1. 功能库搬到 Android:先把 libredwg 的 so 与 JNI 边界分开
把 libredwg 这类功能库搬到 Android,麻烦不在写业务代码,而在 Android 交叉编译后的 .so 如何被 NDK、CMake 和 JNI 一层层认出来。很多人把 libredwg.so 丢进 jniLibs 就以为结束,结果 CMake 能过、安装能过,一调 native 方法就报 UnsatisfiedLinkError。这个流程适合已经能跑 Android 工程、准备接第三方 C 功能库的人:先定 ABI 目录,再写 CMake 导入,最后用 JNI 桥接层隔开 Java 调用,顺序反了就会反复返工。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 功能库的 ABI 产物布局:NDK 交叉编译后先定 jniLibs 目录
功能库接进 Android 工程,第一件事不是打开 Android Studio,而是看 NDK 交叉编译产物放在哪里。CMake 里那句 ${ANDROID_ABI} 不是装饰,它要求每个 ABI 都有一个独立目录,目录名还必须和构建时传进来的 ABI 完全一致。目录定错,后面写再漂亮的 JNI 代码也救不回来。
我一般先把产物按下面这种结构摆好,再做 CMake 导入:
bash复制# 目录名必须等于 CMake 拿到的 ANDROID_ABI
app/src/main/jniLibs/arm64-v8a/libredwg.so
app/src/main/jniLibs/armeabi-v7a/libredwg.so
# 注意:不要把所有 ABI 的 so 混在 jniLibs 根目录
这里的关键不是文件名好看,而是让 Gradle 打包 APK 时能按 ABI 取到对应的 libredwg.so。jniLibs 是 Android 工程里放预编译原生库的常规位置,CMake 只负责链接,不负责替你搬文件;如果 CMake 指向一个工程外部的路径,构建阶段可能能过,但 APK 里未必会带这个 so,运行时就会变成“明明编译成功,一加载就找不到库”。
2.1 CMake 的 IMPORTED 目标不是“复制文件”
add_library(redwg SHARED IMPORTED) 的含义是告诉 CMake:有一个已经编译好的共享库,不要从源码重新编,只把路径登记成目标。它和 add_library(dwg_jni SHARED src/main/cpp/dwg_jni.c) 是两回事,后者才会真正编译 JNI 桥接层。
所以 IMPORTED_LOCATION 必须指向真实存在的文件,而且要尽量和 APK 打包路径保持一致。示例里用的是:
cmake复制${CMAKE_SOURCE_DIR}/../jniLibs/${ANDROID_ABI}/libredwg.so
如果 CMakeLists.txt 在 src/main/cpp 下,CMAKE_SOURCE_DIR 就是 src/main/cpp,../jniLibs 正好回到 src/main/jniLibs。这个相对关系一旦被移动,比如把 CMakeLists.txt 换到别的目录,路径就会整体偏移,CMake 配置阶段不一定立刻报错,链接或运行阶段才翻车。
2.2 ABI 目录和 CMake 变量要一对一
${ANDROID_ABI} 在单 ABI 构建时是一个值,在多 ABI 构建时会分别取值。配置一次就能处理多个 ABI,前提是每个值都能在 jniLibs 下找到同名目录。常见做法是只保留实际要发布的 ABI,不要为了“看起来全”把没有产物的目录也留着;CMake 不会因为某个 ABI 目录为空就自动跳过,它只会按路径去找文件。
如果工程只需要 64 位,就不要让构建脚本同时产出 32 位任务;如果确实要双 ABI,就要保证 libredwg.so 两份都来自对应的 NDK 交叉编译,而不是把 64 位产物复制到 32 位目录里凑数。ABI 混装是后面 dlopen 报位数错误的根源。
2.3 产物检查先看三件事
交叉编译完成后,我一般先做三项确认:文件名是否是 libredwg.so,所在目录名是否等于目标 ABI,ELF 位宽和依赖库是否来自目标工具链。文件名错一个字母,IMPORTED_LOCATION 就会指向空路径;目录名写成 arm64 而不是 arm64-v8a,CMake 按 ${ANDROID_ABI} 拼出来就是另一个位置;依赖库如果还链着主机上的库,Android 运行时同样加载不起来。
这一步不需要写业务代码,但它是整个功能库集成里最值得慢下来的地方。先让产物布局稳定,再进 Android Studio 配 CMake,后面排查问题时才有唯一的对照基准。
3. 功能库的 CMake 与 JNI 接线:一份配置把 libredwg、log 和桥接层接起来
真正的接线分两层:CMake 把预编译的 libredwg.so 和 JNI 桥接层 dwg_jni.c 编到同一个 dwg_jni 动态库里;Java 侧只加载 dwg_jni,不直接加载 libredwg。这样 Java 看到的是一个桥接库,libredwg 的符号和头文件都收在 native 层,边界清楚,后面换版本也只需要动桥接层。
3.1 一份可复用的 CMakeLists.txt
下面这份配置来自实际工程结构,CMakeLists.txt 放在 src/main/cpp 下,预编译库放在 src/main/jniLibs/${ANDROID_ABI} 下:
cmake复制cmake_minimum_required(VERSION 3.18.1)
project("dwgreader")
# 导入交叉编译好的 libredwg.so
add_library(redwg SHARED IMPORTED)
set_target_properties(redwg PROPERTIES
IMPORTED_LOCATION ${CMAKE_SOURCE_DIR}/../jniLibs/${ANDROID_ABI}/libredwg.so
)
# 编译 JNI 桥接层
add_library(dwg_jni SHARED
src/main/cpp/dwg_jni.c
)
# 链接 Libredwg 动态库和 Android 内置的 log 库
target_link_libraries(dwg_jni
redwg
log
)
find_library(log-lib log)
target_link_libraries(dwg_jni ${log-lib})
这份配置在 Android Studio 2022.3+ 和 AGP 7.4+ 环境下实测通过。cmake_minimum_required 写 3.18.1 是为了避免工程里 CMake 版本过低导致 IMPORTED 目标属性行为不一致;project("dwgreader") 只是工程名,和 Java 包名不需要一致;add_library(redwg SHARED IMPORTED) 声明的是预编译库,不会触发源码编译;IMPORTED_LOCATION 里的 ${ANDROID_ABI} 让 CMake 在构建不同 ABI 变体时自动选择对应目录下的 so 文件,配置一次就能处理多个 ABI 构建任务。
target_link_libraries(dwg_jni redwg log) 里的 redwg 是上面声明的导入目标,log 是 Android NDK 提供的日志库。后面又用 find_library(log-lib log) 查了一次日志库,再链接 ${log-lib},这是 CMake 里更通用的查找写法。两种写法同时出现不会改变最终链接意图,实际工程保留一种即可;示例保留两种,是为了说明 log 既可以直接按库名链接,也可以先查找再链接。真正要盯的是 dwg_jni 是否同时拿到了 redwg 和日志库,不然 JNI 层一写 __android_log_print 就会在链接阶段报未定义符号。
3.2 最小 JNI 桥接层:先验证 loadLibrary,再接 libredwg
dwg_jni.c 一开始不要急着写解析 DWG 的业务函数,先做一个最小桥接层,确认 System.loadLibrary("dwg_jni") 能走到 JNI_OnLoad,并且日志库已经链上。下面这段只验证加载链路,不涉及 libredwg 的具体接口:
c复制#include <jni.h>
#include <android/log.h>
#define LOG_TAG "dwg_jni"
#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
// 动态库被加载时先打一条日志,确认 JNI 层已经进来
JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) {
(void)vm;
(void)reserved;
LOGI("dwg_jni loaded");
return JNI_VERSION_1_6;
}
JNI_OnLoad 是 JNI 规范里的入口,返回 JNI_VERSION_1_6 表示桥接层声明的 JNI 版本。LOG_TAG 用 dwg_jni 而不是 libredwg,是为了在日志里区分“桥接库已经加载”和“功能库内部打印”。如果这条日志没出现,先查 System.loadLibrary 有没有执行,再查 APK 里有没有 libdwg_jni.so,不要一上来就怀疑 libredwg。
接着补一个最小的 Java 入口和一个返回字符串的 native 方法,用来验证 JNI 函数名是否对得上:
java复制package com.example.dwgreader;
public final class NativeDwg {
static {
// 只加载桥接库,libredwg 由 dwg_jni 在 native 侧链接
System.loadLibrary("dwg_jni");
}
public static native String version();
}
对应 C 函数名要按 Java_包名_类名_方法名 生成。包名里的点换成下划线,类名和方法名保持原样:
c复制JNIEXPORT jstring JNICALL Java_com_example_dwgreader_NativeDwg_version
(JNIEnv *env, jclass clazz) {
(void)clazz;
// 先返回桥接层标识,确认 Java 到 native 的调用链通了
return (*env)->NewStringUTF(env, "dwg_jni");
}
这段代码的重点不是返回值,而是函数名。com.example.dwgreader.NativeDwg.version() 对应的就是 Java_com_example_dwgreader_NativeDwg_version。包名、类名、方法名任何一处改动,C 函数名都要跟着改;如果 Java 侧调 version() 时报 No implementation found,先对这三个名字,不要先怀疑 CMake 链接。
3.3 业务边界放在桥接层,不让 Java 直接碰 libredwg 句柄
桥接层跑通以后,再把 libredwg 的打开、解析、关闭收进 native 层。Java 侧最好只暴露 open、parse、close 这类动作,句柄用 long 或内部对象持有,不把 libredwg 的结构体指针直接传到 Java。这样做的原因很实际:功能库的版本一变,结构体布局和错误码都可能变,Java 层如果直接依赖这些细节,后面升级会变成全工程改。
桥接层内部要做两件事:一是把 Java 传入的路径、缓冲区、回调参数做合法性检查,二是把 libredwg 返回的错误码翻译成 Java 能识别的结果。具体解析函数按 libredwg 暴露的头文件接,桥接层只负责搬运句柄、检查空指针和记录日志。CMake 里 dwg_jni 已经链接了 redwg,所以桥接层可以直接引用功能库符号;但 Java 侧看到的仍然只有 dwg_jni,加载顺序和符号可见性都更可控。
4. 功能库集成避坑:五个高频现象对应的排查路径
功能库集成最容易出现“构建成功、运行失败”的假象。下面五个现象都来自同一条链路:ABI 目录、CMake 导入、JNI 命名、动态库加载。排查时按“现象 → 原因 → 解决”走,不要跳步。
4.1 现象:dlopen failed: library "libredwg.so" not found
原因通常有两个:IMPORTED_LOCATION 拼出来的路径不存在,或者 so 只被 CMake 引用、没有被放进 APK。示例路径是 ${CMAKE_SOURCE_DIR}/../jniLibs/${ANDROID_ABI}/libredwg.so,只要 CMakeLists.txt 的位置变了,../jniLibs 就会指到别处;另一种情况是文件放在工程外,CMake 链接时能找到,但 Gradle 打包时没带进去。
解决时先看 jniLibs/${ANDROID_ABI}/libredwg.so 是否真实存在,再确认 IMPORTED_LOCATION 和它指向同一个文件。不要把 so 放在 build 目录里当唯一来源,构建清理一次就可能消失。改完路径后做一次 clean,再安装 APK,避免旧包里的 so 干扰判断。
4.2 现象:UnsatisfiedLinkError: No implementation found for ...
这个报错通常不是 libredwg 没链接,而是 JNI 函数名没对上。Java 包名、类名、方法名和 C 函数名必须严格对应,com.example.dwgreader.NativeDwg.version() 对应 Java_com_example_dwgreader_NativeDwg_version。如果方法有重载,或者类被混淆,名字还会进一步变化。
解决时先把 Java 侧声明的 native 方法抄下来,逐段对 C 函数名。包名里的点全部换成下划线,类名和方法名不要改大小写。验证阶段先保留 version() 这种无参方法,确认调用链通了,再逐步加带路径、带缓冲区的业务方法。不要一上来就接复杂参数,否则报错会混在一起。
4.3 现象:dlopen failed: "... is 32-bit instead of 64-bit"
原因是 ABI 目录和 so 位数不一致,常见于把 64 位产物复制进 armeabi-v7a,或者把 32 位产物放进 arm64-v8a。${ANDROID_ABI} 只会按目录名取文件,不会检查 ELF 头;目录名对了、文件位数错了,CMake 可能照样链接,运行时才被系统拒绝。
解决时按 ABI 重新出产物,每个目录只放对应工具链编译的 libredwg.so。如果工程只发 64 位,就删掉 32 位构建任务;如果要双 ABI,就保证两份 so 都来自各自的 NDK 交叉编译。不要用“先放进去试试”的方式混装,这类问题在日志里看起来像加载失败,实际根因在产物目录。
4.4 现象:CMake 配置能过,链接阶段报找不到 redwg
原因是 IMPORTED_LOCATION 指向的文件不存在,或者 add_library(redwg SHARED IMPORTED) 之后没有正确设置目标属性。CMake 对导入目标的检查方式和普通源文件目标不同,路径写错时不一定在配置第一行就报,常常拖到链接阶段才暴露。
解决时先把 IMPORTED_LOCATION 的值打印出来,确认展开后的绝对路径;再确认 CMAKE_SOURCE_DIR 是不是 src/main/cpp。如果 CMakeLists 被移动到别的目录,../jniLibs 的相对层级就要重新算。不要把 IMPORTED_LOCATION 写成目录,它要的是具体文件路径,文件名必须带 libredwg.so。
4.5 现象:Java 侧加载库没有日志,也没有明显异常
原因是 System.loadLibrary("dwg_jni") 没有执行,或者日志标签被过滤。loadLibrary 的参数是库名,不带 lib 前缀和 .so 后缀;写成 libdwg_jni.so 反而找不到。另一个常见情况是静态代码块放在没有被调用的类里,类没初始化,加载动作自然不会发生。
解决时先确认 System.loadLibrary("dwg_jni") 在静态块里,并且这个类在调用 native 方法前已经被使用。再检查 JNI_OnLoad 里的 LOG_TAG 是否和日志过滤条件一致。如果日志仍然没有,先看 APK 里有没有 libdwg_jni.so,再看 CMake 是否把 dwg_jni.c 编进了目标。加载链路要一段一段验,不要同时改 CMake、Java 和 C 代码。
5. 验证与进阶:把功能库加载链路做成可回归检查
功能库接好后,我习惯把验证拆成一张固定检查表,每次换 so 或改 CMake 都走一遍,避免靠记忆判断。
| 检查点 | 看什么 | 通过标准 |
|---|---|---|
| ABI 目录 | jniLibs/${ANDROID_ABI}/libredwg.so 是否存在 |
每个目标 ABI 都有独立目录和对应产物 |
| CMake 导入 | IMPORTED_LOCATION 展开后的绝对路径 |
指向真实文件,不是目录,不依赖构建缓存 |
| 桥接库 | libdwg_jni.so 是否由 dwg_jni.c 编出 |
System.loadLibrary("dwg_jni") 能走到 JNI_OnLoad |
| JNI 命名 | Java_包名_类名_方法名 |
Java 调用 native 方法不报 No implementation found |
| 运行日志 | dwg_jni loaded 是否出现 |
出现后再接 libredwg 业务符号 |
进阶阶段,我会把 version() 保留成桥接层的自检方法,后面接 libredwg 的打开和解析时,先确认 version() 正常,再逐步替换内部实现。这样出问题时能快速判断是加载链路坏了,还是功能库业务调用坏了。从那以后我每次接功能库,都强制先走一遍“目录、CMake、JNI 名、加载日志”四步,再谈业务解析。希望帮到你。
