1. 描述符JNI 里最容易栽跟头的命名规矩做 JNI 开发的人多多少少都遇到过这种场景Java 侧明明写好了 native 方法一运行却抛 UnsatisfiedLinkError或者报 NoSuchMethodError。你检查了方法名检查了头文件甚至重新编译了 so 库问题还在。这时候十有八九问题出在描述符上——你脑子里想的类名、方法签名和 JNI 真正认识的字符串不是同一个东西。JNI 描述符Descriptor是 Java Native Interface 里用来唯一标识类、方法、字段的一种字符串编码规范。它解决的核心问题是Java 类型系统和 C/C 类型系统之间没法直接对话需要一个中间语言把 Java 的类名和签名翻译成本地代码能精确匹配的文本。这就相当于两个人约定好的暗号暗号对得上两边才能接上头对不上编译器不报错但运行时就翻车。这篇内容适合所有刚开始接触 JNI、或者已经被 JNI 签名问题折磨过一轮的开发者。我会先把描述符的底层逻辑讲清楚再搭配 CLion 里配置 JNI 环境的完整实操最后把常见的报错——包括那句臭名昭著的error: a jni error has occurred, please check your installation and try again——逐条拆开告诉你根因在哪、怎么定位。全程是我自己踩坑后总结出来的经验不是照抄官方文档。需要先说清楚JNI 里谈论的描述符和热词里经常见到的Linux 文件描述符、USB HID 描述符、设备描述符请求失败完全是两码事。文件描述符是操作系统内核分配的一个整数值用来指代打开的文件、socket、设备等资源HID 描述符是 USB 设备向主机报告自身能力的结构化数据。而 JNI 描述符简单说就是一套包名类名 类型编码组成的纯文本命名规则。别被描述符三个字误导它们在各自领域的含义没有从属关系。2. 类描述符在本地代码里点名一个 Java 类2.1 类描述符的标准格式不是你想的那样很多新手第一次在 C/C 代码里调用 FindClass 时会下意识写这样的字符串jclass clazz (*env)-FindClass(env, java.lang.String);运行之后要么返回 NULL要么直接 JVM 崩溃。原因很简单JNI 的类描述符要求把包名里的点号.全部替换成斜杠/并且必须以分号;结尾。正确的写法是jclass clazz (*env)-FindClass(env, Ljava/lang/String;);注意这个字符串不是随便写的。L是对象类型的固定标记java/lang/String是类的全限定名包名类名点号变斜杠末尾的;是终止符。三者缺一不可。我刚开始接触 JNI 的时候最常犯的错就是漏掉末尾分号或者把点号落在里面。FindClass 不会给你任何编译期提示只会默默返回 NULL然后你在后面调用 NewObject 或 GetMethodID 时再踩一个 NullPointerException 或 JVM crash。为什么 JNI 不直接用java.lang.String这种自然写法因为 JVM 内部对类名有一套统一的二进制表示点号用于源码层面的包名分隔但在 VM 内部和 class 文件里类是使用斜杠形式的全限定名来索引的。JNI 作为连接 Java 和 Native 的桥梁必须沿用 VM 内部的约定而不是源码层面的书写习惯。2.2 数组类、内部类、基本类型各有各的写法类描述符除了普通对象还会碰到数组和内部类。数组类描述符以[开头后面跟元素类型的描述符[I表示int[][Ljava/lang/String;表示String[][[D表示double[][]这里有个容易搞混的细节[I后面没有分号因为I本身已经是基本类型描述符而[Ljava/lang/String;里里面嵌套的Ljava/lang/String;自带分号所以整个字符串以分号结尾。书写数组描述符时脑子里要时刻记住一层数组一个[对象元素必须L...;。内部类的情况稍微隐蔽一些。看这个 Java 类package com.example; public class Outer { public static class Inner { } }Inner的 JNI 类描述符是Lcom/example/Outer$Inner;中间的$符号是内部类在 JVM 层面与外部类的分隔符。不能写成Lcom/example/Outer/Inner;也不能写成Lcom/example/Outer.Inner;。我第一次在 Android 项目里 FindClass 内部类时就是按照包名习惯写成了斜杠结果运行时一直报 ClassNotFoundException 级别的错误排查了半天才发现是$的问题。还有个特别容易忽略的场景匿名内部类。它们被编译成Outer$1、Outer$2这样的类名在 JNI 里也要原样匹配。2.3 类描述符的经典踩坑JNI_OnLoad 与 FindClass 的时机写类描述符本身不难难的是在正确的时机调用 FindClass。常见的坑是在任意线程里直接调 FindClass 加载一个尚未初始化的类或者加载由自定义 ClassLoader 管理的类比如 Android 的动态加载插件。一个非常典型的例子是 Android 开发中在高德地图 SDK 等第三方库回调线程里调用 JNI 时报JNI detected error in application后面我会详细展开。这种问题的根因之一就是 FindClass 在线程关联的 ClassLoader 里找不到目标类返回了 NULL。解决方法包括在 JNI_OnLoad 里提前缓存全局引用或者通过 GetObjectClass / FindClass 拿到正确的 ClassLoader。注意FindClass 返回的是局部引用不能长期保存。如果需要在多个 native 调用之间复用类引用必须用 NewGlobalRef 转成全局引用并记得在库卸载时删除引用。3. 方法描述符比类名更容易出事的编码表3.1 类型编码对照一张表搞懂所有基础类型方法描述符描述的是参数类型列表 返回类型格式固定为(参数类型编码序列)返回类型编码中间没有空格、没有逗号。比如 Java 方法public native int add(int a, int b);它的方法描述符是(II)I括号内两个I表示两个 int 参数括号外的I表示返回 int。就这么简单。所有类型的编码对照如下Java 类型类型编码booleanZbyteBcharCshortSintIlongJfloatFdoubleDvoidV引用类型如 StringLjava/lang/String;数组如 int[][I对象数组如 String[][Ljava/lang/String;long为什么是J而不是L因为L已经留给了对象类型L...;。void为什么是V取的是 void 首字母。boolean 取Z是因为B被 byte 占了。这些编码都是 JVM 规范里写死的没有为什么只能记。3.2 手工推导方法签名实例演示我来演示几个真实的方法推导过程这部分值得仔细看因为工作中你会反复用到。示例一public native void setTitle(String title);参数是String对应的编码是Ljava/lang/String;返回值是 void编码是V。所以完整描述符是(Ljava/lang/String;)V示例二public native long getValue(int index, double[] data);参数列表编码为I[D也就是I[D返回值为J。完整描述符是(ID[J注意[D从结构上看是一个整体代表一个 double 数组参数不要把它拆开。书写顺序必须和参数声明顺序完全一致。示例三构造方法public class MyClass { public MyClass(String name, int id) { } }构造方法在 JNI 里属于特殊方法它的方法名固定是init描述符是(Ljava/lang/String;I)V用 GetMethodID 获取构造方法时方法名参数写init返回值永远标记为 void。这一点非常容易记混我见过有人把构造方法名写成类名结果 GetMethodID 一直返回 NULL。示例四重载方法public native void process(int value); public native void process(String value);这两个方法重载Java 侧可以靠参数类型区分。但在 JNI 里必须通过完整的方法描述符来区分。第一个的签名是(I)V第二个是(Ljava/lang/String;)V。只用方法名process去匹配JVM 根本不知道你想要哪个会直接匹配失败。3.3 泛型、数组与描述符的关系Java 泛型在编译期会被擦除type erasure所以 JNI 方法描述符里看不到泛型信息。例如public native void setList(ListString list);编译后的参数类型是java.util.List所以描述符是(Ljava/util/List;)V而不是带上String这种泛型标记的字符串。写描述符时不要画蛇添足。但数组不同数组是运行时类型会保留维度信息。比如public native int sum(int[] values);参数编码是[I不是I。漏掉数组开头的[是新手高频错误。因为 Java 侧int[]和int在 JNI 方法表里是完全不同的描述符写错之后不会编译报错而是在运行时找不到方法。3.4 用工具生成描述符比手写靠谱虽然我上面教了手推方法但实际开发中我更推荐用工具来生成描述符减少手写出错的概率。javap 命令JDK 自带的 javap 可以直接打印类的方法签名。对某个 class 文件执行javap -s -p 类名就会输出每个方法的描述符。这是最权威、最不会错的方式。IDE 插件IntelliJ IDEA 提供了Show JNI Signatures之类的功能CLion 配合插件也可以直接在代码里生成 JNI 方法声明。Android StudioAndroid Studio 的 JNI 相关插件同样可以自动生成方法定义和描述符。我的习惯是写完 native 方法后先用 javap 核对一遍描述符再写 C/C 侧的 GetMethodID / RegisterNatives。多花 30 秒能省下两小时的排错时间。4. CLion 里搭建 JNI 开发环境从零到跑通一个示例4.1 为什么我建议你用 CLion 而不是把 C 代码塞在 Android Studio 里CLion 对 C/C 的代码分析、调试、重构能力远强于 Android Studio 内置的编辑器尤其是跨平台桌面端 JNI 开发时——你在自己的电脑上跑一个 Java 程序加载一个本地 so 库CLion 可以像调试普通 C 程序一样打断点、看变量、检查内存。我一向的建议是在正式上 Android 之前先在本机用纯 Java CLion 把 JNI 逻辑调通。这样的好处是调试链路短、日志直观、没有 Android 那一层层套壳出问题时能更快定位到是不是描述符写错了。4.2 环境准备JDK、CMake、编译器的搭配先列出我本地环境作为参考JDK 1764 位版本JNI 头文件路径在$JAVA_HOME/includeCLion 2023.3 以上版本CMake 3.20Windows 上我用 MinGW-w64 或者 Visual Studio 工具链macOS 上直接用自带的 Clang 即可关键点是让 CLion 找到 JNI 头文件。JNI 的头文件有两处$JAVA_HOME/include/jni.h和$JAVA_HOME/include/平台目录/jni_md.h。在 Windows 下是$JAVA_HOME/include/win32/jni_md.hLinux 下是$JAVA_HOME/include/linux/jni_md.hmacOS 下是$JAVA_HOME/include/darwin/jni_md.h。4.3 CMakeLists.txt 配置重点看 include 路径一个最小可用的 CMakeLists.txt 长这样cmake_minimum_required(VERSION 3.20) project(jni_demo C CXX) set(CMAKE_CXX_STANDARD 17) # 设置 JAVA_HOME可以在系统环境变量里配置也可以在这里硬编码 set(JAVA_HOME $ENV{JAVA_HOME}) if(NOT JAVA_HOME) message(FATAL_ERROR JAVA_HOME 未设置请先配置 JDK 环境变量) endif() include_directories( ${JAVA_HOME}/include ${JAVA_HOME}/include/linux ${JAVA_HOME}/include/win32 ${JAVA_HOME}/include/darwin ) add_library(jni_demo SHARED src/native_lib.cpp ) # 让生成出来的库文件名直接是 libjni_demo.soJava 侧 System.loadLibrary(jni_demo) 对应这里的交叉平台 include 路径我直接并列写了三个虽然会有些冗余但对新手来说最省心编译器会自行选择存在的路径。想严格一点可以按平台判断不过小项目没必要纠结。4.4 完整示例Java 调用本地方法全程演示描述符的使用先写 Java 侧的类public class NativeMath { static { System.loadLibrary(jni_demo); } public native int add(int a, int b); public native String greeting(String name); public static void main(String[] args) { NativeMath math new NativeMath(); System.out.println(1 2 math.add(1, 2)); System.out.println(math.greeting(JNI)); } }然后用 javac 编译 Java 文件用javac -h . NativeMath.java生成 JNI 头文件。这个-h参数是 JDK 8 以后才有的会在当前目录生成一个NativeMath.h里面包含了根据 Java 方法自动生成的函数声明——注意这里面的函数名和签名里的描述符就是 JNI 层匹配的关键。生成的函数声明大概长这样JNIEXPORT jint JNICALL Java_NativeMath_add (JNIEnv *, jobject, jint, jint); JNIEXPORT jstring JNICALL Java_NativeMath_greeting (JNIEnv *, jobject, jstring);然后在 CLion 的src/native_lib.cpp里实现#include jni.h #include string extern C { JNIEXPORT jint JNICALL Java_NativeMath_add(JNIEnv *, jobject, jint a, jint b) { return a b; } JNIEXPORT jstring JNICALL Java_NativeMath_greeting(JNIEnv *env, jobject, jstring name) { const char *utf env-GetStringUTFChars(name, nullptr); std::string result std::string(Hello, ) utf !; env-ReleaseStringUTFChars(name, utf); return env-NewStringUTF(result.c_str()); } }在 CLion 里构建出libjni_demo.so或.dylib/.dll然后在 Java 侧运行时通过-Djava.library.path构建目录指定库路径java -Djava.library.pathcmake-build-debug NativeMath这里有个特别想说的小技巧如果你没让 CMake 输出固定文件名Linux 下生成的可能是libjni_demo.soJava 的loadLibrary(jni_demo)会自行加上lib前缀和.so后缀去找。如果你用System.load(/绝对路径/libjni_demo.so)加载则必须写全路径。两种方式别混用。5. 描述符错误引发的问题与排查实录5.1 报错error: a jni error has occurred, please check your installation and try again到底是什么意思这句话我在开发者社区里见过太多次了。它不是 JNI 的报错而是 JVM 启动时的一句通用错误提示通常出现在你用java -jar或者java -cp运行一个含 native 方法的类时。触发它的常见场景包括启动参数里指定的主类加载不了 native 方法库比如 so 路径写错System.loadLibrary抛出 UnsatisfiedLinkError但没有被代码捕获异常直接被 JVM 在启动阶段打印出来Java 版本与本地库编译时使用的 ABI 不匹配比如用 JDK 8 的 jni.h 头文件编译却跑在 JDK 17 上。如果你看到这句话第一件事不是去怀疑安装有问题而是去控制台看更早的 Caused by 部分。真正的根因一定在后面几行比如java.lang.UnsatisfiedLinkError: no jni_demo in java.library.path或者Cant load AMD 64-bit .dll on a IA 32-bit platform这类提示。5.2 排查 UnsatisfiedLinkError 时优先检查方法名还是描述符我的经验是先看方法描述符再看函数名。RegisterNatives方式注册时描述符写错会直接导致NoSuchMethodError或注册失败动态导出函数名方式javac -h 生成的Java_包名_类名_方法名下如果函数名写错JVM 会找不到符号报 UnsatisfiedLinkError但这和描述符无关。举个例子你在 Java 里声明public native void printMessage(String msg);在 C 里写成了JNIEXPORT void JNICALL Java_NativeMath_printMessage(JNIEnv *env, jobject thiz, jstring msg) { ... }如果你生成的函数名缺少了包名里的下划线转换、或类名大小写不完全一致运行时就报UnsatisfiedLinkError。注意 JNI 对类名里的下划线有特殊处理如果包名或类名里本来就带下划线_在函数名里要转成_1。例如类名Native_Math在 JNI 导出函数里是Java_Native_1Math_method。这个规则极其隐蔽是跨平台开发里很经典的坑。5.3 Android 侧经典报错JNI detected error in application很多人在 Android 集成高德地图 SDK 或其他带 so 的三方库时会看到类似日志A/libc: Fatal signal 6 (SIGABRT) JNI DETECTED ERROR IN APPLICATION: use of invalid jobject这句报错和描述符直接相关的场景通常是native 方法返回了一个错误的 jobject 类型。比如你 C 侧 return 的 jstring 实际是用 NewObject 创建的其他类型对象或者把一个 null 引用在 Java 层强制转型。JVM 在交付对象给 Java 层之前会做类型校验一旦发现引用类型与声明的返回描述符不匹配就直接 abort。排查这类问题重点做三件事检查 native 方法返回值声明和 C/C 函数返回类型是否一致检查 GetObjectClass / FindClass 拿到的类是否和预期一致打开 Android 的-Xcheck:jni选项在 debug 构建下默认开启它会把 JNI 层类型错误提前暴露在日志里而不是等到进程崩溃。5.4 我自己最常用的排错手段清单最后整理一份我每次都照着做的排查清单帮你快速定位描述符错误类问题症状首要检查位置常见根因FindClass 返回 NULL类描述符字符串漏分号、点号未转斜杠GetMethodID 返回 NULL方法描述符参数顺序写错、重载未区分签名UnsatisfiedLinkErrorJNI 导出函数名类名下划线未转_1NoSuchMethodError方法名/签名构造方法写了init或写错启动报 a jni error has occurredCaused by 部分库路径不对或架构不匹配Android: JNI DETECTED ERROR返回值 jobject 类型返回类型与描述符不匹配描述符对但依然找不到方法javap 核对泛型擦除后类型发生变化还有一个非常实用的小技巧在 Java 代码里临时加一个try { System.loadLibrary(...) } catch (Throwable t) { t.printStackTrace(); }很多时候能直接把 UnsatisfiedLinkError 的关键栈信息打出来省得你猜来猜去。6. 最后一个建议把描述符当成接口契约来对待JNI 描述符是个很小但极其关键的知识点。很多项目跑起来出问题不是业务逻辑复杂而是 Java 和 C/C 两侧对同一个方法的理解不一致。你在 Java 里写的是(int, String)在 C 侧却按(int, int)去解析 jobject崩溃几乎在所难免。我个人的做法是每次新增 native 方法都会把描述符写进代码注释里比如在 Java 方法上方直接注释// native signature: (Ljava/lang/String;I)Ljava/lang/String;。这样过了几个月再回头看不需要重新从 javap 里拉签名也不会因为重构改了参数类型而忘记同步 C 侧。另外建议你尽早养成用javap -s核对签名的习惯。哪怕你已经能熟练手写描述符工具校验依然是不可替代的保险。真正到了生产环境一个描述符写错导致的线上崩溃远比多敲一行命令要贵得多。如果你正准备开始写自己的 JNI 模块先把类描述符、方法描述符这两页纸的规则吃透再动手搭环境。基础打牢之后后面不管是 CLion 里的调试还是 Android 端集成三方库都会顺很多。
JNI描述符：类名与方法签名，彻底解决运行时错误
1. 描述符JNI 里最容易栽跟头的命名规矩做 JNI 开发的人多多少少都遇到过这种场景Java 侧明明写好了 native 方法一运行却抛 UnsatisfiedLinkError或者报 NoSuchMethodError。你检查了方法名检查了头文件甚至重新编译了 so 库问题还在。这时候十有八九问题出在描述符上——你脑子里想的类名、方法签名和 JNI 真正认识的字符串不是同一个东西。JNI 描述符Descriptor是 Java Native Interface 里用来唯一标识类、方法、字段的一种字符串编码规范。它解决的核心问题是Java 类型系统和 C/C 类型系统之间没法直接对话需要一个中间语言把 Java 的类名和签名翻译成本地代码能精确匹配的文本。这就相当于两个人约定好的暗号暗号对得上两边才能接上头对不上编译器不报错但运行时就翻车。这篇内容适合所有刚开始接触 JNI、或者已经被 JNI 签名问题折磨过一轮的开发者。我会先把描述符的底层逻辑讲清楚再搭配 CLion 里配置 JNI 环境的完整实操最后把常见的报错——包括那句臭名昭著的error: a jni error has occurred, please check your installation and try again——逐条拆开告诉你根因在哪、怎么定位。全程是我自己踩坑后总结出来的经验不是照抄官方文档。需要先说清楚JNI 里谈论的描述符和热词里经常见到的Linux 文件描述符、USB HID 描述符、设备描述符请求失败完全是两码事。文件描述符是操作系统内核分配的一个整数值用来指代打开的文件、socket、设备等资源HID 描述符是 USB 设备向主机报告自身能力的结构化数据。而 JNI 描述符简单说就是一套包名类名 类型编码组成的纯文本命名规则。别被描述符三个字误导它们在各自领域的含义没有从属关系。2. 类描述符在本地代码里点名一个 Java 类2.1 类描述符的标准格式不是你想的那样很多新手第一次在 C/C 代码里调用 FindClass 时会下意识写这样的字符串jclass clazz (*env)-FindClass(env, java.lang.String);运行之后要么返回 NULL要么直接 JVM 崩溃。原因很简单JNI 的类描述符要求把包名里的点号.全部替换成斜杠/并且必须以分号;结尾。正确的写法是jclass clazz (*env)-FindClass(env, Ljava/lang/String;);注意这个字符串不是随便写的。L是对象类型的固定标记java/lang/String是类的全限定名包名类名点号变斜杠末尾的;是终止符。三者缺一不可。我刚开始接触 JNI 的时候最常犯的错就是漏掉末尾分号或者把点号落在里面。FindClass 不会给你任何编译期提示只会默默返回 NULL然后你在后面调用 NewObject 或 GetMethodID 时再踩一个 NullPointerException 或 JVM crash。为什么 JNI 不直接用java.lang.String这种自然写法因为 JVM 内部对类名有一套统一的二进制表示点号用于源码层面的包名分隔但在 VM 内部和 class 文件里类是使用斜杠形式的全限定名来索引的。JNI 作为连接 Java 和 Native 的桥梁必须沿用 VM 内部的约定而不是源码层面的书写习惯。2.2 数组类、内部类、基本类型各有各的写法类描述符除了普通对象还会碰到数组和内部类。数组类描述符以[开头后面跟元素类型的描述符[I表示int[][Ljava/lang/String;表示String[][[D表示double[][]这里有个容易搞混的细节[I后面没有分号因为I本身已经是基本类型描述符而[Ljava/lang/String;里里面嵌套的Ljava/lang/String;自带分号所以整个字符串以分号结尾。书写数组描述符时脑子里要时刻记住一层数组一个[对象元素必须L...;。内部类的情况稍微隐蔽一些。看这个 Java 类package com.example; public class Outer { public static class Inner { } }Inner的 JNI 类描述符是Lcom/example/Outer$Inner;中间的$符号是内部类在 JVM 层面与外部类的分隔符。不能写成Lcom/example/Outer/Inner;也不能写成Lcom/example/Outer.Inner;。我第一次在 Android 项目里 FindClass 内部类时就是按照包名习惯写成了斜杠结果运行时一直报 ClassNotFoundException 级别的错误排查了半天才发现是$的问题。还有个特别容易忽略的场景匿名内部类。它们被编译成Outer$1、Outer$2这样的类名在 JNI 里也要原样匹配。2.3 类描述符的经典踩坑JNI_OnLoad 与 FindClass 的时机写类描述符本身不难难的是在正确的时机调用 FindClass。常见的坑是在任意线程里直接调 FindClass 加载一个尚未初始化的类或者加载由自定义 ClassLoader 管理的类比如 Android 的动态加载插件。一个非常典型的例子是 Android 开发中在高德地图 SDK 等第三方库回调线程里调用 JNI 时报JNI detected error in application后面我会详细展开。这种问题的根因之一就是 FindClass 在线程关联的 ClassLoader 里找不到目标类返回了 NULL。解决方法包括在 JNI_OnLoad 里提前缓存全局引用或者通过 GetObjectClass / FindClass 拿到正确的 ClassLoader。注意FindClass 返回的是局部引用不能长期保存。如果需要在多个 native 调用之间复用类引用必须用 NewGlobalRef 转成全局引用并记得在库卸载时删除引用。3. 方法描述符比类名更容易出事的编码表3.1 类型编码对照一张表搞懂所有基础类型方法描述符描述的是参数类型列表 返回类型格式固定为(参数类型编码序列)返回类型编码中间没有空格、没有逗号。比如 Java 方法public native int add(int a, int b);它的方法描述符是(II)I括号内两个I表示两个 int 参数括号外的I表示返回 int。就这么简单。所有类型的编码对照如下Java 类型类型编码booleanZbyteBcharCshortSintIlongJfloatFdoubleDvoidV引用类型如 StringLjava/lang/String;数组如 int[][I对象数组如 String[][Ljava/lang/String;long为什么是J而不是L因为L已经留给了对象类型L...;。void为什么是V取的是 void 首字母。boolean 取Z是因为B被 byte 占了。这些编码都是 JVM 规范里写死的没有为什么只能记。3.2 手工推导方法签名实例演示我来演示几个真实的方法推导过程这部分值得仔细看因为工作中你会反复用到。示例一public native void setTitle(String title);参数是String对应的编码是Ljava/lang/String;返回值是 void编码是V。所以完整描述符是(Ljava/lang/String;)V示例二public native long getValue(int index, double[] data);参数列表编码为I[D也就是I[D返回值为J。完整描述符是(ID[J注意[D从结构上看是一个整体代表一个 double 数组参数不要把它拆开。书写顺序必须和参数声明顺序完全一致。示例三构造方法public class MyClass { public MyClass(String name, int id) { } }构造方法在 JNI 里属于特殊方法它的方法名固定是init描述符是(Ljava/lang/String;I)V用 GetMethodID 获取构造方法时方法名参数写init返回值永远标记为 void。这一点非常容易记混我见过有人把构造方法名写成类名结果 GetMethodID 一直返回 NULL。示例四重载方法public native void process(int value); public native void process(String value);这两个方法重载Java 侧可以靠参数类型区分。但在 JNI 里必须通过完整的方法描述符来区分。第一个的签名是(I)V第二个是(Ljava/lang/String;)V。只用方法名process去匹配JVM 根本不知道你想要哪个会直接匹配失败。3.3 泛型、数组与描述符的关系Java 泛型在编译期会被擦除type erasure所以 JNI 方法描述符里看不到泛型信息。例如public native void setList(ListString list);编译后的参数类型是java.util.List所以描述符是(Ljava/util/List;)V而不是带上String这种泛型标记的字符串。写描述符时不要画蛇添足。但数组不同数组是运行时类型会保留维度信息。比如public native int sum(int[] values);参数编码是[I不是I。漏掉数组开头的[是新手高频错误。因为 Java 侧int[]和int在 JNI 方法表里是完全不同的描述符写错之后不会编译报错而是在运行时找不到方法。3.4 用工具生成描述符比手写靠谱虽然我上面教了手推方法但实际开发中我更推荐用工具来生成描述符减少手写出错的概率。javap 命令JDK 自带的 javap 可以直接打印类的方法签名。对某个 class 文件执行javap -s -p 类名就会输出每个方法的描述符。这是最权威、最不会错的方式。IDE 插件IntelliJ IDEA 提供了Show JNI Signatures之类的功能CLion 配合插件也可以直接在代码里生成 JNI 方法声明。Android StudioAndroid Studio 的 JNI 相关插件同样可以自动生成方法定义和描述符。我的习惯是写完 native 方法后先用 javap 核对一遍描述符再写 C/C 侧的 GetMethodID / RegisterNatives。多花 30 秒能省下两小时的排错时间。4. CLion 里搭建 JNI 开发环境从零到跑通一个示例4.1 为什么我建议你用 CLion 而不是把 C 代码塞在 Android Studio 里CLion 对 C/C 的代码分析、调试、重构能力远强于 Android Studio 内置的编辑器尤其是跨平台桌面端 JNI 开发时——你在自己的电脑上跑一个 Java 程序加载一个本地 so 库CLion 可以像调试普通 C 程序一样打断点、看变量、检查内存。我一向的建议是在正式上 Android 之前先在本机用纯 Java CLion 把 JNI 逻辑调通。这样的好处是调试链路短、日志直观、没有 Android 那一层层套壳出问题时能更快定位到是不是描述符写错了。4.2 环境准备JDK、CMake、编译器的搭配先列出我本地环境作为参考JDK 1764 位版本JNI 头文件路径在$JAVA_HOME/includeCLion 2023.3 以上版本CMake 3.20Windows 上我用 MinGW-w64 或者 Visual Studio 工具链macOS 上直接用自带的 Clang 即可关键点是让 CLion 找到 JNI 头文件。JNI 的头文件有两处$JAVA_HOME/include/jni.h和$JAVA_HOME/include/平台目录/jni_md.h。在 Windows 下是$JAVA_HOME/include/win32/jni_md.hLinux 下是$JAVA_HOME/include/linux/jni_md.hmacOS 下是$JAVA_HOME/include/darwin/jni_md.h。4.3 CMakeLists.txt 配置重点看 include 路径一个最小可用的 CMakeLists.txt 长这样cmake_minimum_required(VERSION 3.20) project(jni_demo C CXX) set(CMAKE_CXX_STANDARD 17) # 设置 JAVA_HOME可以在系统环境变量里配置也可以在这里硬编码 set(JAVA_HOME $ENV{JAVA_HOME}) if(NOT JAVA_HOME) message(FATAL_ERROR JAVA_HOME 未设置请先配置 JDK 环境变量) endif() include_directories( ${JAVA_HOME}/include ${JAVA_HOME}/include/linux ${JAVA_HOME}/include/win32 ${JAVA_HOME}/include/darwin ) add_library(jni_demo SHARED src/native_lib.cpp ) # 让生成出来的库文件名直接是 libjni_demo.soJava 侧 System.loadLibrary(jni_demo) 对应这里的交叉平台 include 路径我直接并列写了三个虽然会有些冗余但对新手来说最省心编译器会自行选择存在的路径。想严格一点可以按平台判断不过小项目没必要纠结。4.4 完整示例Java 调用本地方法全程演示描述符的使用先写 Java 侧的类public class NativeMath { static { System.loadLibrary(jni_demo); } public native int add(int a, int b); public native String greeting(String name); public static void main(String[] args) { NativeMath math new NativeMath(); System.out.println(1 2 math.add(1, 2)); System.out.println(math.greeting(JNI)); } }然后用 javac 编译 Java 文件用javac -h . NativeMath.java生成 JNI 头文件。这个-h参数是 JDK 8 以后才有的会在当前目录生成一个NativeMath.h里面包含了根据 Java 方法自动生成的函数声明——注意这里面的函数名和签名里的描述符就是 JNI 层匹配的关键。生成的函数声明大概长这样JNIEXPORT jint JNICALL Java_NativeMath_add (JNIEnv *, jobject, jint, jint); JNIEXPORT jstring JNICALL Java_NativeMath_greeting (JNIEnv *, jobject, jstring);然后在 CLion 的src/native_lib.cpp里实现#include jni.h #include string extern C { JNIEXPORT jint JNICALL Java_NativeMath_add(JNIEnv *, jobject, jint a, jint b) { return a b; } JNIEXPORT jstring JNICALL Java_NativeMath_greeting(JNIEnv *env, jobject, jstring name) { const char *utf env-GetStringUTFChars(name, nullptr); std::string result std::string(Hello, ) utf !; env-ReleaseStringUTFChars(name, utf); return env-NewStringUTF(result.c_str()); } }在 CLion 里构建出libjni_demo.so或.dylib/.dll然后在 Java 侧运行时通过-Djava.library.path构建目录指定库路径java -Djava.library.pathcmake-build-debug NativeMath这里有个特别想说的小技巧如果你没让 CMake 输出固定文件名Linux 下生成的可能是libjni_demo.soJava 的loadLibrary(jni_demo)会自行加上lib前缀和.so后缀去找。如果你用System.load(/绝对路径/libjni_demo.so)加载则必须写全路径。两种方式别混用。5. 描述符错误引发的问题与排查实录5.1 报错error: a jni error has occurred, please check your installation and try again到底是什么意思这句话我在开发者社区里见过太多次了。它不是 JNI 的报错而是 JVM 启动时的一句通用错误提示通常出现在你用java -jar或者java -cp运行一个含 native 方法的类时。触发它的常见场景包括启动参数里指定的主类加载不了 native 方法库比如 so 路径写错System.loadLibrary抛出 UnsatisfiedLinkError但没有被代码捕获异常直接被 JVM 在启动阶段打印出来Java 版本与本地库编译时使用的 ABI 不匹配比如用 JDK 8 的 jni.h 头文件编译却跑在 JDK 17 上。如果你看到这句话第一件事不是去怀疑安装有问题而是去控制台看更早的 Caused by 部分。真正的根因一定在后面几行比如java.lang.UnsatisfiedLinkError: no jni_demo in java.library.path或者Cant load AMD 64-bit .dll on a IA 32-bit platform这类提示。5.2 排查 UnsatisfiedLinkError 时优先检查方法名还是描述符我的经验是先看方法描述符再看函数名。RegisterNatives方式注册时描述符写错会直接导致NoSuchMethodError或注册失败动态导出函数名方式javac -h 生成的Java_包名_类名_方法名下如果函数名写错JVM 会找不到符号报 UnsatisfiedLinkError但这和描述符无关。举个例子你在 Java 里声明public native void printMessage(String msg);在 C 里写成了JNIEXPORT void JNICALL Java_NativeMath_printMessage(JNIEnv *env, jobject thiz, jstring msg) { ... }如果你生成的函数名缺少了包名里的下划线转换、或类名大小写不完全一致运行时就报UnsatisfiedLinkError。注意 JNI 对类名里的下划线有特殊处理如果包名或类名里本来就带下划线_在函数名里要转成_1。例如类名Native_Math在 JNI 导出函数里是Java_Native_1Math_method。这个规则极其隐蔽是跨平台开发里很经典的坑。5.3 Android 侧经典报错JNI detected error in application很多人在 Android 集成高德地图 SDK 或其他带 so 的三方库时会看到类似日志A/libc: Fatal signal 6 (SIGABRT) JNI DETECTED ERROR IN APPLICATION: use of invalid jobject这句报错和描述符直接相关的场景通常是native 方法返回了一个错误的 jobject 类型。比如你 C 侧 return 的 jstring 实际是用 NewObject 创建的其他类型对象或者把一个 null 引用在 Java 层强制转型。JVM 在交付对象给 Java 层之前会做类型校验一旦发现引用类型与声明的返回描述符不匹配就直接 abort。排查这类问题重点做三件事检查 native 方法返回值声明和 C/C 函数返回类型是否一致检查 GetObjectClass / FindClass 拿到的类是否和预期一致打开 Android 的-Xcheck:jni选项在 debug 构建下默认开启它会把 JNI 层类型错误提前暴露在日志里而不是等到进程崩溃。5.4 我自己最常用的排错手段清单最后整理一份我每次都照着做的排查清单帮你快速定位描述符错误类问题症状首要检查位置常见根因FindClass 返回 NULL类描述符字符串漏分号、点号未转斜杠GetMethodID 返回 NULL方法描述符参数顺序写错、重载未区分签名UnsatisfiedLinkErrorJNI 导出函数名类名下划线未转_1NoSuchMethodError方法名/签名构造方法写了init或写错启动报 a jni error has occurredCaused by 部分库路径不对或架构不匹配Android: JNI DETECTED ERROR返回值 jobject 类型返回类型与描述符不匹配描述符对但依然找不到方法javap 核对泛型擦除后类型发生变化还有一个非常实用的小技巧在 Java 代码里临时加一个try { System.loadLibrary(...) } catch (Throwable t) { t.printStackTrace(); }很多时候能直接把 UnsatisfiedLinkError 的关键栈信息打出来省得你猜来猜去。6. 最后一个建议把描述符当成接口契约来对待JNI 描述符是个很小但极其关键的知识点。很多项目跑起来出问题不是业务逻辑复杂而是 Java 和 C/C 两侧对同一个方法的理解不一致。你在 Java 里写的是(int, String)在 C 侧却按(int, int)去解析 jobject崩溃几乎在所难免。我个人的做法是每次新增 native 方法都会把描述符写进代码注释里比如在 Java 方法上方直接注释// native signature: (Ljava/lang/String;I)Ljava/lang/String;。这样过了几个月再回头看不需要重新从 javap 里拉签名也不会因为重构改了参数类型而忘记同步 C 侧。另外建议你尽早养成用javap -s核对签名的习惯。哪怕你已经能熟练手写描述符工具校验依然是不可替代的保险。真正到了生产环境一个描述符写错导致的线上崩溃远比多敲一行命令要贵得多。如果你正准备开始写自己的 JNI 模块先把类描述符、方法描述符这两页纸的规则吃透再动手搭环境。基础打牢之后后面不管是 CLion 里的调试还是 Android 端集成三方库都会顺很多。
