1. 从一次 UnsatisfiedLinkError 说起:JNI 到底在约定什么
第一次被要求把一段加密逻辑从 Java 挪到 native 层,我以为在代码开发工具里把 NDK 勾上就完事,结果 CMake 找不到工具链、javah 出来的函数名和包名对不上,装到真机上一跑就是 UnsatisfiedLinkError。JNI 不是一门新语言,它是一套命名与调用约定:Java 侧用 System.loadLibrary 加载 so,native 侧用固定格式的函数名,或者一张运行时映射表,把自己挂到 Java 方法上。前者叫静态注册,靠 javah 生成的头文件把 Java 方法名直接写进 so 的符号表;后者叫动态注册,靠 JNI_OnLoad 里调 RegisterNatives 在加载时完成绑定。静态注册上手快、符号暴露;动态注册配置麻烦、改名成本低、逆向成本高。下面按 Android Studio 加 NDK、CMake 这条工具链,把两条路各走一遍,再讲我踩过的坑。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具链先搭对:三个组件、一个模板、一份 CMakeLists
2.1 NDK、CMake、Command-line Tools 各管什么
装 JNI 环境的第一步不是写代码,是把代码开发工具里的三个组件对齐。路径在 Android Studio 的设置里:
text复制Preferences → Appearance & Behavior → System Settings → Android SDK → SDK Tools
必装的三项是 NDK (Side by side)、CMake、Android SDK Command-line Tools。它们各管一段,缺一个就会在某个阶段卡住:
- NDK (Side by side):真正提供
jni.h、jni_md.h和 clang 交叉编译工具链的组件。它不在 SDK 里预装,勾选后单独下载到 SDK 目录下的 ndk 子目录。没有它,CMake 在配置阶段就会报找不到 toolchain。 - CMake:Android Gradle Plugin 用它读取 CMakeLists.txt,生成 ninja 构建脚本,再去调 NDK 里的 clang。SDK Tools 里装的这份 CMake 是构建专用二进制,不是系统里那个同名命令,两者混用会出现版本对不上的怪问题。
- Android SDK Command-line Tools:提供 adb、sdkmanager、avdmanager 这些命令入口,很多构建脚本和调试流程依赖它。旧版 JDK 里的 javah 也依赖 JDK 环境,后面生成头文件会用到。
三个组件装完,建议先做一次 Gradle sync,让 Android Studio 把 NDK 路径写进本地配置。我习惯在这一步就打开 Build 窗口看有没有 toolchain 相关的 warning,有的话先解决再写代码,否则后面所有报错都会指向同一个根因。
提示:NDK 版本和 AGP 版本之间有兼容关系,版本跨得太大时 sync 阶段就会失败。真遇到这种情况,先降 NDK 版本,不要急着改 CMakeLists。
2.2 建工程时选 Native C++ 模板
新建模块时选 Native C++ 模板,不要选纯 Java 模板。两者的差别很实际:Native C++ 模板会自动生成 src/main/cpp 目录、一份 CMakeLists.txt、一个 native-lib.cpp 示例,并在 MainActivity 里写好 loadLibrary 调用;Java 模板什么都不会生成,cpp 目录、CMake 配置、Gradle 里的 externalNativeBuild 都得手动补。
模板生成后,模块的 build.gradle 里会有这样一段:
gradle复制android {
defaultConfig {
externalNativeBuild {
cmake {
// 路径相对模块目录,不是项目根目录
path "src/main/cpp/CMakeLists.txt"
}
}
}
}
这里的 path 指向模块内的 CMakeLists.txt。很多翻车是因为把项目根目录的相对路径写了进去,Gradle 会报找不到 CMakeLists。判断方法很简单:看报错里的路径是不是从模块目录开始算的。
模板还会生成一份默认的 CMakeLists,里面通常已经有一行 add_library。我一般会把示例的 native-lib.cpp 删掉,换成自己的源文件,然后同步改 add_library 里的源文件名,三处名字保持一致再往下走。
2.3 CMakeLists 三行骨架与库名对应
JNI 模块的 CMakeLists 可以很简单,骨架就三行:
cmake复制cmake_minimum_required(VERSION 3.18.1)
# 第一个参数是库名,去掉 lib 前缀和 .so 后缀,就是 loadLibrary 里要写的名字
add_library(encrypt SHARED encrypt.c)
add_library 的三个参数含义要拆开看:
- 第一个参数
encrypt是逻辑库名。构建产物是libencrypt.so,但 Java 侧System.loadLibrary("encrypt")写的是去掉lib前缀和.so后缀的名字。这三处必须严格一致,大小写也算。 - 第二个参数
SHARED表示生成动态库。写成STATIC会得到.a静态库,loadLibrary根本加载不了。 - 第三个参数是源文件列表。多个源文件用空格分隔,比如
encrypt.c utils.c。源文件扩展名会决定编译方式:.c按 C 编译,.cpp按 C++ 编译,这个差别在讲符号改编时会要人命。
CMakeLists 改完点 sync,Android Studio 会重新配置一次。配置成功的话,Build 窗口里能看到 ninja 生成的记录;失败的话通常会停在 “Configuring incomplete”,往上翻能找到具体是哪一行。
3. 静态注册:javah 头文件、包名映射与 C 函数落地
3.1 Java 侧声明与 so 加载
静态注册的第一步是在 Java 类里声明 native 方法,并加载 so:
java复制package com.example.jnidemo;
public class EncryptUtils {
static {
// 名字必须和 CMakeLists 里 add_library 的第一个参数一致
System.loadLibrary("encrypt");
}
// 静态 native 方法,C 侧第二个参数是 jclass
public static native int s1(int v1, int v2);
// 字符串处理示例
public static native String s3(String origin);
}
几个细节值得说明。System.loadLibrary 放在 static 块里,意味着类第一次被使用时才触发加载,加载失败会抛 ExceptionInInitializerError,真正的错误原因藏在 cause 里,看日志要往下翻一层。方法声明必须是 native 且没有方法体,返回值用 Java 类型而不是 C 类型。另外这里声明的是 static 方法,C 侧对应函数的第二个参数是 jclass;如果写成普通实例方法,第二个参数就变成 jobject,指向调用该方法的对象。这个参数类型搞错,编译期不会报,运行期参数错位,属于典型的玄学崩溃。
3.2 javah 与包名到函数名的映射规则
声明完方法,在模块的 java 目录下执行:
bash复制cd app/src/main/java
javah com.example.jnidemo.EncryptUtils
它会在当前目录生成 com_example_jnidemo_EncryptUtils.h,内容大致是:
c复制/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
JNIEXPORT jint JNICALL Java_com_example_jnidemo_EncryptUtils_s1
(JNIEnv *, jclass, jint, jint);
JNIEXPORT jstring JNICALL Java_com_example_jnidemo_EncryptUtils_s3
(JNIEnv *, jclass, jstring);
函数名的拼法是有规则的,按段拆开看:
| Java 侧 | 头文件里 |
|---|---|
包名 com.example.jnidemo |
com_example_jnidemo,点全部换成下划线 |
类名 EncryptUtils |
原样接在后面 |
方法名 s1 |
原样接在后面 |
static native |
第二个参数是 jclass |
普通 native |
第二个参数是 jobject |
生成的 .h 我会剪切到 src/main/cpp 目录,和 encrypt.c 放在一起,编译时直接 include 相对路径即可。头文件里那句“DO NOT EDIT”要当真,手改函数名是最常见的翻车来源,后面排查章节会细说。
高版本 JDK 里 javah 已经不再随包提供,常见做法是改用 javac 的 -h 参数直接生成头文件:
bash复制# -h 指定头文件输出目录,-d 指定 class 输出目录
javac -h cpp -d out app/src/main/java/com/example/jnidemo/EncryptUtils.java
两种方式的产物等价,函数命名规则完全一样,选一种固定在项目脚本里就行,不要今天用 javah 明天用 javac,否则生成的头文件版本会混。
3.3 C 侧实现:基础类型、字符串与资源释放
实现文件 encrypt.c:
c复制#include <string.h>
#include <jni.h>
JNIEXPORT jint JNICALL Java_com_example_jnidemo_EncryptUtils_s1(
JNIEnv* env, jclass clazz, jint v1, jint v2) {
return v1 + v2; // 整数加法,jint 就是 Java 的 int
}
JNIEXPORT jstring JNICALL Java_com_example_jnidemo_EncryptUtils_s3(
JNIEnv* env, jclass clazz, jstring origin) {
// 把 Java 字符串转成 C 字符串,第三个参数 0 表示不关心是否返回副本
const char* str = (*env)->GetStringUTFChars(env, origin, 0);
if (str == NULL) {
return NULL; // 内存不足时这里会返回 NULL,必须判空
}
// 截取第 0、2、4 位,数组开 4 个元素,最后一个由编译器填 '\0'
char result[4] = {str[0], str[2], str[4]};
// 释放 GetStringUTFChars 拿到的内存,否则每调一次漏一块
(*env)->ReleaseStringUTFChars(env, origin, str);
// 用截取结果构造新的 Java 字符串返回
return (*env)->NewStringUTF(env, result);
}
这段代码里每个参数都要说清楚。JNIEnv* 是 JNI 函数表的入口,所有 JNI 调用都通过它;jclass 对应 Java 侧调用这个 native 方法的类本身,可以拿它做反射;jint、jstring 是 Java 类型在 C 侧的映射,jstring 不是 char*,不能直接当字符串用。
字符串处理是静态注册里最容易漏的一环。GetStringUTFChars 会返回一个指向字符序列的指针,第三次参数传 0 表示不关心底层是否复制,传 JNI_TRUE 则强制拷贝。不管哪一种,用完都要调 ReleaseStringUTFChars,否则内存会持续上涨。result[4] = {str[0], str[2], str[4]} 只写了三个初始化值,第四个元素被编译器初始化为 \0,这个隐式补零恰好满足了 NewStringUTF 对零结尾字符串的要求——但它是运气,不是设计,后面讲坑时会说这里为什么脆。
4. 代码开发工具侧的动态注册:JNI_OnLoad 与一张映射表
4.1 Java 侧只留一个 native 声明
动态注册的 Java 侧和静态注册长得几乎一样,区别只在 so 名字和实现方式:
java复制package com.example.jnidemo;
public class DynamicUtils {
static {
// 这个库名对应另一份 CMakeLists 里的 add_library
System.loadLibrary("dynamic");
}
public static native int add(int v1, int v2);
}
Java 侧不需要为每个方法准备一个独立命名的 C 函数,方法名、参数都只出现在这张 Java 声明里,so 里靠一张映射表把名字和函数指针连起来。这也是动态注册之所以能降低符号暴露面的原因:导出符号表里不会出现 Java_com_example_jnidemo_DynamicUtils_add 这种一眼就能反推方法名的符号。
4.2 JNINativeMethod 三元组与方法签名
C 侧先写真正干活的函数,再写映射表:
c复制#include <jni.h>
// 真正干活的函数,名字随意,不参与 JNI 符号命名
jint native_add(JNIEnv* env, jobject obj, jint a, jint b) {
return a + b;
}
// 三元组:Java 方法名、方法签名、C 函数指针
static JNINativeMethod methods[] = {
{"add", "(II)I", (void*)native_add}
};
JNINativeMethod 的三个字段各有约束。第一个是 Java 侧的方法名,必须和 DynamicUtils 里声明的 add 完全一致,大小写敏感。第二个是方法签名,Java 在编译期丢弃了参数类型信息,JNI 只能靠签名字符串来校验绑定关系。(II)I 的含义是:括号里两个 I 表示两个 int 入参,括号后的 I 表示返回 int。V 表示 void,L...; 表示对象类型。第三个字段是函数指针,类型必须和签名匹配,强制转换成 void* 是 JNI 接口的规定写法,不是随便转。
签名写错的时候编译能过,运行期注册会失败,而且失败信息往往只有一句笼统的返回码,这是动态注册最难受的地方。我习惯在写映射表之前先把签名用 javap 核对一遍,具体命令放在最后一章。
4.3 JNI_OnLoad 的返回值和错误分支
注册入口是一个固定名字的导出函数:
c复制JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* reserved) {
JNIEnv* env;
// 第三个参数是请求的 JNI 版本,失败时 env 不可用
if ((*vm)->GetEnv(vm, (void**)&env, JNI_VERSION_1_6) != JNI_OK) {
return JNI_ERR;
}
// 类名用斜杠分隔,不能用点,这是 JNI 的类描述符规则
jclass clazz = (*env)->FindClass(env, "com/example/jnidemo/DynamicUtils");
if (clazz == NULL) {
return JNI_ERR;
}
// 第四个参数是映射表长度,必须和 methods 数组的实际条目数一致
if ((*env)->RegisterNatives(env, clazz, methods, 1) != JNI_OK) {
return JNI_ERR;
}
return JNI_VERSION_1_6;
}
这里每一步都有失败的可能,也都能静默地把问题推到加载阶段。GetEnv 拿不到 env 时返回 JNI_ERR,System.loadLibrary 会直接抛异常,cause 里能看到 JNI_OnLoad returned -1 之类的信息。FindClass 找不到类时返回 NULL,常见原因是类名用了点号而不是斜杠,或者这个类还没被任何类加载器加载过。RegisterNatives 返回非 JNI_OK 时,说明映射表里至少有一项对不上,方法名、签名、数量三者要逐项核。
最后一个返回值必须是 JNI_VERSION_1_6,它告诉虚拟机这个库需要的 JNI 版本。返回别的值、或者忘记 return,加载会失败。这个错误没有编译期提示,只能靠日志。
注意:动态注册只是把符号名从导出表里拿掉了,类描述符字符串
com/example/jnidemo/DynamicUtils和方法名add仍然以明文形式存在于 so 里。字符串扫描一样能找到线索,它降低的是逆向成本,不是消除暴露。
5. 避坑与排查:五个真机翻车现场
5.1 UnsatisfiedLinkError:库名和 add_library 对不上
现象:真机一跑就崩,日志是 java.lang.UnsatisfiedLinkError: dalvik.system.PathClassLoader[DexPathList...] couldn't find "libencrypt.so",或者 No implementation found for int com.example.jnidemo.EncryptUtils.s1(int, int)。
原因:前者是 so 根本没打进 APK,或者 System.loadLibrary 里的名字和 add_library 的第一个参数不一致;后者是 so 加载成功了,但符号表里找不到对应函数。两种报错长得很像,排查方向完全不同。库名不一致最常见的情况是大小写写错、加了 lib 前缀、或者模块里有多个 CMakeLists 只改了其中一个。
解决:把三处名字写在一起对照——add_library 的第一个参数、System.loadLibrary 的字符串、构建产物里的 libxxx.so 文件名。三处一致后再跑。如果是符号找不到,去下一节核对函数名。
5.2 函数名对不上:包名、类名、下划线的连锁反应
现象:No implementation found for int com.example.jnidemo.EncryptUtils.s1(int, int),日志里明确给出了 Java 侧期望的完整方法签名。
原因:头文件里生成的函数名和运行时类全名不一致。常见触发点是改了包名或类名之后没有重新生成头文件,或者头文件是手工复制过来改了其中一段。包名里的点要全部换成下划线,只要漏换一个,整段函数名就对不上。另外,如果包名或类名里本身含有下划线、或者含有非 ASCII 字符,映射规则会更复杂,这种命名我一般直接避开。
解决:不要手改函数名。改完包名或类名,重新执行一次 javah 或 javac -h,把头文件覆盖过去,然后对着日志里的期望签名逐段比对。日志里的方法签名其实已经把类全名、方法名、参数类型都写出来了,它是最好的校对依据。
5.3 源文件叫 .cpp:C++ 名字改编把符号改没了
现象:代码、库名、包名全对,nm 看 so 的导出表里也有一堆符号,但就是找不到 Java_com_example_jnidemo_EncryptUtils_s1,运行时依然是 No implementation found。
原因:源文件扩展名是 .cpp,CMake 按 C++ 编译,JNIEXPORT 的函数名被 C++ 的名字改编机制处理成了 _Z... 开头的符号,Java 侧按 C 的名字去查,自然查不到。这个问题在 Native C++ 模板下特别容易发生,因为模板默认给的就是 cpp。
解决:要么把文件改回 .c,要么在 C++ 里用 extern "C" 把函数声明包起来,禁用名字改编:
c复制#ifdef __cplusplus
extern "C" {
#endif
JNIEXPORT jint JNICALL Java_com_example_jnidemo_EncryptUtils_s1(
JNIEnv* env, jclass clazz, jint v1, jint v2) {
return v1 + v2;
}
#ifdef __cplusplus
}
#endif
5.4 字符串截取:数组没留结尾、GetStringUTFChars 没释放
现象:返回的字符串偶发乱码、内容比预期长,或者长跑之后 native 内存持续上涨,最终触发 OOM。
原因:char result[4] = {str[0], str[2], str[4]} 这种写法依赖编译器把第四个元素补成 \0,一旦数组长度或初始化列表改一改,结尾就不再有保证;如果入参字符串长度不足 5 位,str[4] 直接读到越界内存。另一个来源是 GetStringUTFChars 拿到的指针没有配对调用 ReleaseStringUTFChars,每调一次漏一块。
解决:先用 strlen 判断源字符串长度,不够长就返回空串或者抛出明确错误;固定长度数组至少留一位给 \0,或者用 strncpy 配合显式补零;ReleaseStringUTFChars 放在构造返回字符串之前,用中间变量把截取结果先存下来。
c复制size_t len = strlen(str);
char result[4] = {0}; // 全部清零,结尾天然安全
if (len >= 5) {
result[0] = str[0];
result[1] = str[2];
result[2] = str[4];
}
(*env)->ReleaseStringUTFChars(env, origin, str);
5.5 动态注册的静默失败:类名斜杠、签名、返回版本
现象:System.loadLibrary("dynamic") 抛 ExceptionInInitializerError,cause 里是 UnsatisfiedLinkError,然后是一句 JNI_OnLoad returned -1。
原因:三个高频点——FindClass 的参数写成了点号分隔的类名而不是斜杠;映射表里的签名写错,比如把 (II)I 写成 (I)I;RegisterNatives 的第四个参数和数组条目数不一致。还有一个隐蔽点:JNI_OnLoad 末尾返回了 JNI_ERR 或者返回了别的版本号,虚拟机直接判定加载失败。
解决:在这个入口里加日志,把每一步的返回值打出来,定位到具体是哪一步返回了非 OK。类名一律用斜杠描述符;签名用 javap 核对;映射表数量用 sizeof(methods)/sizeof(methods[0]) 而不是手写数字,少一个数的问题就没了。
6. 进阶:用 javap -s 对齐签名,用导出表判断暴露面
动态注册的签名我最怕手写,后来固定成一个流程:先把 Java 类编译出来,用 javap 直接读虚拟机视角的签名,再往映射表里抄。
bash复制# 在编译产物的 classes 目录下执行,-s 输出签名,-p 包含私有成员
javap -s -p com.example.jnidemo.DynamicUtils
输出里每个方法下面会有一行 descriptor:,那就是 JNI 需要的签名字符串,(II)I 会原样出现在里面。手写签名和 javap 输出对照一遍,比运行期看一句笼统的 JNI_ERR 省时间得多。对象类型、数组类型的签名比较复杂,更不应该凭记忆写。
静态注册和动态注册怎么选,我一般按三个维度判断:
| 维度 | 静态注册 | 动态注册 |
|---|---|---|
| 入口 | javah 或 javac -h 生成的头文件 | JNI_OnLoad 里调 RegisterNatives |
| so 导出表 | 有 Java_com_... 形式的完整符号 |
通常只剩 JNI_OnLoad |
| 改包名或类名的成本 | 必须重新生成头文件,否则运行期找不到 | 只改类描述符字符串 |
| 出错时机 | 调用时报 No implementation found | 加载时报 JNI_OnLoad returned -1 |
| 方法数量多时 | 头文件函数成倍增长 | 一张映射表集中管理 |
导出表怎么查:构建出的 so 在 build/intermediates 下面,用 nm -D libencrypt.so 或者把 so 拖进常见的逆向分析工具看导出符号列表。静态注册的 so 里能直接看到一堆 Java_com_example_jnidemo_EncryptUtils_s1 这样的名字,方法名一目了然;动态注册的 so 里主要看到 JNI_OnLoad,方法名要靠扫字符串才能找到。这就是加固时选动态注册的实际理由,不是它更“高级”,而是它把方法名从结构化的符号表里挪到了非结构化的字符串里。
但别把它当万能药。so 里的类描述符、方法名字符串仍然是明文,只要有人做字符串扫描,照样能定位。真正要收紧暴露面,除了注册方式,还得配合符号裁剪和字符串处理,这部分超出一次教程的范围,我只提醒一句:先确认你的威胁模型,再决定要不要为动态注册付出那份额外的配置成本。
从那以后我每次新建 native 模块,都强制先把库名、包名、签名这三样写在便签上贴在屏幕边,编完先用 nm 看一眼导出符号,再上真机。这套笨办法救过我很多次,希望帮到你。
