1. 从一次 so 加载失败说起:Android JNI 工程到底怎么串
第一次在 Android 工程里接 JNI,最容易被“代码开发工具”坑到的不是 C 语法,而是 so 到底从哪里加载。Android Studio 把 NDK、CMake、javah 和 System.loadLibrary 串成一条链,任何一环名字对不上,运行时就直接给你脸色看。这条路线适合已经能在 Java 层写业务、但一碰 native 就不知道先配环境还是先写方法的同学;也适合想把静态注册换成动态注册、让方法名别在 so 里排得太整齐的熟手。下面按“先搭工具链,再跑静态注册,最后用 JNI_OnLoad 收口”的顺序走,每一步都落到可复制执行的命令和代码。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具链:Android Studio 里把 NDK、CMake、javah 串成一条线
JNI 工程里真正让人翻车的,往往不是 JNIEnv 指针,而是工具链的命名没有闭环。Java 侧 System.loadLibrary("encrypt") 要的短名、CMake 里 add_library(encrypt ...) 的 target 名、源文件名和 javah 生成的头文件名,这四样东西只要有一处对不上,编译期可能风平浪静,运行期直接报库加载失败。先把工具链当成一条生产线来搭,后面写 C 代码才有意义。
2.1 装齐三件套:NDK、CMake、命令行工具
Android Studio 的入口在设置里,路径是固定的:
bash复制# Android Studio 设置路径
# Preferences → Appearance & Behavior → System Settings → Android SDK → SDK Tools
# 必装组件:NDK (Side by side)、CMake、Android SDK Command-line Tools
这段不是让你在终端执行,而是把 SDK Tools 面板里的勾选顺序记牢。NDK (Side by side) 提供编译 C 代码需要的头文件和工具链;CMake 负责读取 CMakeLists.txt 并把 encrypt.c 编成共享库;Android SDK Command-line Tools 让构建过程能拿到命令行工具。三者缺一个,后面要么找不到 jni.h,要么 CMake 配置直接失败。
| 组件 | 在 JNI 工程里的作用 | 漏装后的典型表现 |
|---|---|---|
| NDK (Side by side) | 提供 jni.h、C 编译器和平台库 |
C 文件里 #include <jni.h> 直接标红 |
| CMake | 读取 CMakeLists.txt,生成 so |
工程不知道 encrypt.c 要编进哪个库 |
| Android SDK Command-line Tools | 支撑命令行构建与工具调用 | 构建链路缺命令,配置阶段就卡住 |
建工程时选 Native C++ 模板,不要选普通 Java 模板。模板会替你生成一段 Gradle 配置:
groovy复制externalNativeBuild {
cmake {
path "src/main/cpp/CMakeLists.txt"
}
}
这里的 path 指向 src/main/cpp/CMakeLists.txt,意思是构建系统从这个入口读取 native 构建规则。路径不要随手改成别的目录,除非你同步把 CMakeLists.txt 挪过去;否则 Gradle 找不到构建脚本,后面所有 so 都不会产出。
2.2 从 Java native 声明到 javah 头文件:包名和路径先对齐
先写 Java 侧的声明。类名、包名、native 方法名和 System.loadLibrary 的库名要一起定下来:
java复制// EncryptUtils.java
package com.nb.s3jni;
public class EncryptUtils {
static {
System.loadLibrary("encrypt"); // 加载 so 库
}
// 基础类型示例
public static native int s1(int v1, int v2);
// 字符串处理示例
public static native String s3(String origin);
}
static 代码块在类初始化时执行,System.loadLibrary("encrypt") 里的 encrypt 是库的短名,不带 lib 前缀,也不带 .so 后缀。两个 native 方法都是 static,所以之后 C 函数第二个参数会是 jclass,不是 jobject;这一点在生成头文件时会直接体现出来,写 C 实现时不要凭感觉换成 jobject。
接下来生成头文件。材料里的做法是先进入 Java 源码目录,再对完整包名加类名执行 javah:
bash复制cd app/src/main/java
javah com.nb.s3jni.EncryptUtils
cd 到 app/src/main/java 是为了让 javah 能按包路径找到 com/nb/s3jni/EncryptUtils.java。命令里用的是点号分隔的完整类名 com.nb.s3jni.EncryptUtils,不是文件路径。执行成功后会在当前目录生成 com_nb_s3jni_EncryptUtils.h,内容大致如下:
c复制/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
JNIEXPORT jint JNICALL Java_com_nb_s3jni_EncryptUtils_s1
(JNIEnv *, jclass, jint, jint);
JNIEXPORT jstring JNICALL Java_com_nb_s3jni_EncryptUtils_s3
(JNIEnv *, jclass, jstring);
头文件里的函数名不是随便起的,Java_ 后面依次拼包名、类名和方法名,下划线是分隔符。s1 的签名是 (JNIEnv *, jclass, jint, jint),对应 Java 侧两个 int 参数;s3 的签名是 (JNIEnv *, jclass, jstring),对应 Java 的 String。C 实现如果把这个名字拼错,编译能过,运行时会找不到 native 方法,最后表现成调用失败或链接错误。所以 javah 生成的头文件不要手改,直接拿它当函数名对照表。
2.3 让 CMake target 和 System.loadLibrary 对上:add_library 的命名闭环
CMake 侧只做一件核心事:把 encrypt.c 编成一个名为 encrypt 的共享库。材料里的配置很短:
cmake复制cmake_minimum_required(VERSION 3.18.1)
add_library(encrypt SHARED encrypt.c) # 指定源文件
cmake_minimum_required(VERSION 3.18.1) 约束 CMake 的最低版本;add_library(encrypt SHARED encrypt.c) 里的第一个参数 encrypt 是 target 名,也是最终库的短名,必须和 System.loadLibrary("encrypt") 里的字符串一致。SHARED 表示生成动态共享库,JNI 运行时要加载的就是它;encrypt.c 是源文件,文件不存在或路径写错时,CMake 配置阶段就会失败。
这里最容易出现的误用是“target 叫 encrypt,加载时写 encryptlib”,或者“Java 里加载 dynamic,CMake 还在编 encrypt”。静态注册阶段先用 encrypt 跑通,等切到动态注册时再建一个 dynamic target,不要在一个 target 里来回改名字。库名、target 名、源文件名三者保持可追溯,后面排查时才能一眼看出是哪一环断了。
3. 静态注册实战:用 javah 生成的签名把 s1 和 s3 跑通
静态注册是 JNI 的基线:Java 方法名直接映射到 C 函数名,函数名由 javah 按包名、类名和方法名拼出来。它不灵活,但足够直观,适合先把“Java 声明—头文件—C 实现—CMake 编库—Java 调用”这条链路跑通。把 s1 的整数加法和 s3 的字符串截取都跑出来,再切动态注册,心里才有对照组。
3.1 先定返回类型和参数:s1 用基础类型,s3 用字符串
Java 侧声明保持和头文件一致:
java复制// EncryptUtils.java
package com.nb.s3jni;
public class EncryptUtils {
static {
System.loadLibrary("encrypt");
}
public static native int s1(int v1, int v2);
public static native String s3(String origin);
}
s1 返回 int,参数是两个 int,所以 C 侧对应 jint 返回值和两个 jint 参数。s3 返回 String,参数是 String,C 侧对应 jstring 返回值和 jstring 参数。这里不要用 int 直接替换 jint 的语义,jint 是 JNI 对 Java int 的类型映射;在材料给出的实现里,返回值和参数都按 jint、jstring 写,和 javah 头文件严格对齐。
方法声明为 static 还有一个直接后果:C 函数第二个参数是 jclass,表示调用该静态方法的类;如果声明成实例方法,第二个参数才会是 jobject。这不是风格问题,而是签名的一部分。把 jclass 写成 jobject 可能编译能过,但和头文件不一致,静态注册的符号匹配就会出问题。
3.2 C 侧实现:整数加法和字符串截取
C 文件实现两个函数,函数名直接照抄 javah 头文件:
c复制// encrypt.c
#include <string.h>
#include <jni.h>
JNIEXPORT jint JNICALL Java_com_nb_s3jni_EncryptUtils_s1(
JNIEnv* env, jclass clazz, jint v1, jint v2) {
return v1 + v2; // 整数加法
}
JNIEXPORT jstring JNICALL Java_com_nb_s3jni_EncryptUtils_s3(
JNIEnv* env, jclass clazz, jstring origin) {
// Java字符串转C字符串
const char* str = (*env)->GetStringUTFChars(env, origin, 0);
// 字符截取:第0/2/4位
char result[4] = {str[0], str[2], str[4]};
// 释放资源并返回新字符串
(*env)->ReleaseStringUTFChars(env, origin, str);
return (*env)->NewStringUTF(env, result);
}
Java_com_nb_s3jni_EncryptUtils_s1 里的 s1 和 Java 方法名完全一致,参数顺序是 JNIEnv*、jclass、两个 jint。函数体只做 v1 + v2,返回类型 jint 和 Java 的 int 对齐。
s3 的重点在字符串生命周期。GetStringUTFChars(env, origin, 0) 把 Java 字符串转成 C 侧可读的 UTF 字符指针,第三个参数 0 表示不强制要求拷贝;拿到指针后,char result[4] = {str[0], str[2], str[4]}; 取原字符串第 0、2、4 位,数组长度 4,最后一个位置由编译器补 \0。ReleaseStringUTFChars(env, origin, str) 必须在 NewStringUTF 之前调用,因为 str 指向的资源要先释放,NewStringUTF 再用 result 生成新的 Java 字符串。顺序反了或者忘记释放,短期可能看不出来,跑久了解放资源就会变成玄学崩溃。
注意:
char result[4] = {str[0], str[2], str[4]};默认输入至少有 5 个字符。如果传入"abc"这类短字符串,str[4]已经越界,C 侧不会替你兜底。实战里要么先判长度,要么换成安全截取,不要拿这段代码直接接用户输入。
3.3 编译并调用:把 Java 侧入口当验收点
CMake 把 encrypt.c 编进 encrypt 库之后,Java 侧加载库并调用两个方法,就是最小验收:
java复制// 在已有 Java 入口里调用,前提是 EncryptUtils 已触发类初始化
int sum = EncryptUtils.s1(1, 2);
String out = EncryptUtils.s3("abcdef");
EncryptUtils.s1(1, 2) 走的是静态注册的 Java_com_nb_s3jni_EncryptUtils_s1,返回 3。EncryptUtils.s3("abcdef") 取第 0、2、4 位,期望结果是 "ace"。调用前不需要手动再写 System.loadLibrary,类里的静态代码块已经做了;但要注意,调用必须发生在 EncryptUtils 类初始化之后,否则 native 方法还没有和库绑定。
验收时先看 s1,因为它只涉及基础类型,失败点少;再看 s3,因为它暴露字符串资源管理问题。如果 s1 能过、s3 崩溃,问题基本落在 GetStringUTFChars、ReleaseStringUTFChars 或数组下标上,而不是 CMake target 名。把这两个方法拆开验证,排错时能少绕很多路。
4. 动态注册实战:JNI_OnLoad 里用 RegisterNatives 收口方法映射
静态注册把 Java 方法名直接写进 so 的导出符号里,方法一多,符号表就很整齐;动态注册则把映射收进 JNI_OnLoad,用 RegisterNatives 在运行时登记。它不是“更高级所以必须用”,而是当你想集中管理映射、避免方法名直接暴露时,多一个更可控的选择。先跑通 add(int, int),再谈迁移。
4.1 先写 Java 侧壳:DynamicUtils 和库名 dynamic
Java 侧单独建一个类,库名也单独起,避免和静态注册的 encrypt 混在一起:
java复制// DynamicUtils.java
public class DynamicUtils {
static { System.loadLibrary("dynamic"); }
public static native int add(int v1, int v2);
}
System.loadLibrary("dynamic") 对应的 CMake target 也必须是 dynamic,源文件可以是另一个 dynamic.c。add 是静态 native 方法,Java 侧只声明,不写实现。这里把库名和类名分开,是为了让静态注册和动态注册各自有清晰的边界:encrypt 管 s1/s3,dynamic 管 add。如果两个库混在一个 target 里,后面排查 JNI_OnLoad 是否执行会很麻烦。
4.2 JNINativeMethod 的签名怎么读:(II)I 对应 add(int,int)
C 侧先写实际功能函数,再写映射表:
c复制#include <jni.h>
// 实际功能函数
jint native_add(JNIEnv* env, jobject obj, jint a, jint b) {
return a + b;
}
// 方法映射表
static JNINativeMethod methods[] = {
{"add", "(II)I", (void*)native_add}
};
native_add 是真正干活的函数,返回 jint,参数是 JNIEnv*、jobject、两个 jint。这里第二个参数写成 jobject,是因为映射表登记的是 Java 侧的 add,而 add 在 Java 里是静态方法;但材料给出的实际功能函数签名用了 jobject obj,这在实际运行时通常不会影响 int 加法,因为函数体没有使用 obj。如果要严格贴合静态方法的语义,也可以把它写成 jclass,但映射表里的函数指针类型最终由 RegisterNatives 按签名调用,关键还是参数个数和类型顺序。
JNINativeMethod 的三个字段分别是 Java 方法名、方法签名和 C 函数指针。{"add", "(II)I", (void*)native_add} 里,add 对应 Java 的 add;(II)I 是 JNI 签名,括号内两个 I 表示两个 int 参数,括号外 I 表示返回 int;(void*)native_add 把函数地址转成 void* 塞进映射表。签名写错,RegisterNatives 会失败,Java 侧调用就会落到“找不到实现”的状态。
4.3 JNI_OnLoad 返回 JNI_VERSION_1_6,FindClass 用斜杠路径
动态注册的入口是 JNI_OnLoad,库被加载时由 JVM 调用:
c复制JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* reserved) {
JNIEnv* env;
if ((*vm)->GetEnv(vm, (void**)&env, JNI_VERSION_1_6) != JNI_OK)
return JNI_ERR;
// 注册类方法
jclass clazz = (*env)->FindClass(env, "com/nb/s3jni/DynamicUtils");
(*env)->RegisterNatives(env, clazz, methods, 1);
return JNI_VERSION_1_6;
}
GetEnv(vm, (void**)&env, JNI_VERSION_1_6) 取当前线程的 JNIEnv,第三个参数是要求的 JNI 版本;返回不是 JNI_OK 就直接 JNI_ERR,不要继续往下走。FindClass 的类名必须用斜杠:com/nb/s3jni/DynamicUtils,不是 com.nb.s3jni.DynamicUtils。RegisterNatives(env, clazz, methods, 1) 的最后一个参数是映射表条目数,这里只有 add 一个方法,所以是 1。函数最后返回 JNI_VERSION_1_6,和 GetEnv 请求的版本保持一致。
动态注册的价值在这里体现得很直接:Java 方法名 add 不需要作为 Java_com_nb_s3jni_DynamicUtils_add 这样的符号出现在 so 里,映射关系集中在 methods[],改方法时只动一张表。它不会让代码自动安全,但会让 so 的符号表少一点“按图索骥”的便利,分析成本会上去。迁移时先确认 JNI_OnLoad 真的执行、FindClass 返回非空、RegisterNatives 返回成功,再看 add 的返回值。
5. 用代码开发工具排查:JNI 工程最常见的五类翻车现场
JNI 的报错经常只给一个很粗的现象:库加载失败、方法找不到、进程崩了。真正要定位,还是回到工具链的名字、签名和资源释放。下面五类是我在静态注册和动态注册之间来回切时最常遇到的翻车现场,按“现象 → 原因 → 解决”拆开写,尽量让下一次少猜一点。
5.1 现象:一运行就提示库加载失败,代码还没进 native
现象是 Java 侧刚触发 System.loadLibrary 就失败,C 代码完全没有机会执行。原因通常不是 C 语法,而是 System.loadLibrary("encrypt") 的短名和 CMake add_library(encrypt SHARED encrypt.c) 的 target 名不一致;也可能是 encrypt.c 根本没被加进 target,构建产物里没有对应的 so。解决顺序是先看 Java 侧加载名,再看 CMake target 名,最后看源文件是否在 target 里。两边都叫 encrypt,源文件写对,才有继续排查的价值。
5.2 现象:javah 生成了头文件,但 C 函数名和 Java 方法对不上
现象是编译阶段找不到符号,或者运行时 native 方法没有被绑定。原因常见于 javah 命令执行目录不对、包名写错、类名拼错,或者头文件生成后又被手动改了函数名。javah com.nb.s3jni.EncryptUtils 必须在 app/src/main/java 下执行,生成的函数名应该是 Java_com_nb_s3jni_EncryptUtils_s1 和 Java_com_nb_s3jni_EncryptUtils_s3。解决方式是回到 Java 源码目录重新生成头文件,C 文件里的函数名直接照抄头文件,不要凭记忆补下划线。
5.3 现象:字符串方法偶发崩溃,日志指到 native
现象是 s1 正常,s3 偶尔崩,或者跑一段时间后资源异常。原因有三个常见点:GetStringUTFChars 之后没有配对 ReleaseStringUTFChars;char result[4] 固定取 str[0]、str[2]、str[4],输入长度不足 5 就越界;释放顺序和 NewStringUTF 使用顺序混在一起。解决时先把字符串长度判断补上,保证取下标前输入足够长;再把 ReleaseStringUTFChars 放在 NewStringUTF 之前,保证 str 释放后不再被使用。不要因为“偶发”就归因于玄学,字符串资源问题往往是确定性的越界或泄漏。
5.4 现象:JNI_OnLoad 返回了版本,但 add 调用还是失败
现象是库能加载,JNI_OnLoad 也返回了 JNI_VERSION_1_6,但 add 调用没有落到 native_add。原因常见于 FindClass 写成点号路径 com.nb.s3jni.DynamicUtils,而 JNI 要求斜杠 com/nb/s3jni/DynamicUtils;也可能是 RegisterNatives 的映射表签名写成 (II)V 之类和 Java 方法不匹配,或者映射条目数量传错。解决时逐项对照:类名斜杠、{"add", "(II)I", (void*)native_add}、RegisterNatives(env, clazz, methods, 1) 的条目数。JNI_OnLoad 返回值正确不代表注册一定成功,RegisterNatives 的返回值也要看。
5.5 现象:静态注册能跑,切到动态注册后 so 里还能看到旧符号
现象是 s1/s3 还能调用,add 却走了旧库,或者 so 里仍然能看到静态注册的函数名。原因往往是动态注册没有单独建 dynamic target,旧的 encrypt.c 还留在同一个 CMake target 里;或者 Java 侧还在 System.loadLibrary("encrypt"),没有切到 dynamic。解决方式是让动态注册走独立的 add_library(dynamic SHARED dynamic.c) 和 System.loadLibrary("dynamic"),静态注册的 encrypt 保持不动;改完后重新构建,确认加载的是新库,而不是旧产物。库名混用是迁移阶段最常见的“看起来改了,其实没改”。
6. 把 JNI 工作流固化成习惯:一次编译、一次加载、一次注册的验证顺序
我现在验收 JNI 工程,不看“能不能跑”,先看名字和签名是否闭环。下面这张表是我常用的顺序,每次切静态注册或动态注册都走一遍:
| 检查点 | 看什么 | 失败时先改哪 |
|---|---|---|
| Java native 声明 | 方法名、参数类型、返回类型 | 先改 Java 声明,再重新 javah |
| javah 头文件 | Java_ 后包名、类名、方法名 |
回到 app/src/main/java 重新生成 |
| CMake target | add_library 第一个参数 |
和 System.loadLibrary 短名对齐 |
| 库加载 | System.loadLibrary("encrypt") 或 "dynamic" |
先确认 target 名,再看源文件 |
| 动态注册 | FindClass 斜杠路径、(II)I 签名、条目数 |
对照 methods[] 和 Java 方法 |
| 字符串资源 | GetStringUTFChars 与 ReleaseStringUTFChars 成对 |
释放放在 NewStringUTF 之前 |
bash复制# 我的 JNI 验收顺序
# 1. 确认 Java native 声明与 javah 头文件一致
# 2. 确认 CMake add_library 的 target 与 System.loadLibrary 短名一致
# 3. 先跑静态注册 s1/s3,再切动态注册 add
# 4. 检查 GetStringUTFChars 与 ReleaseStringUTFChars 成对
这段清单不替你写代码,但能挡住大部分“编译过了、运行挂了”的问题。先验头文件,再验 target,再验加载,最后验注册;静态注册和动态注册分开跑,不要让两个库名互相污染。静态注册的 s1 是基础类型的最小闭环,s3 是字符串资源的最小闭环;动态注册的 add 是映射表的最小闭环。三个都过,再谈方法变多、库变多。
从那以后我每次接 JNI 工程,都强制按“先头文件、再 target、再加载、最后注册”走一遍,不再靠运气。希望帮到你。
