JNI开发里最绕不过去的环节就是生成头文件。我刚入门那会儿每次在Java类里加一个native方法都要重新手动敲一遍javah命令先切到编译输出目录确认class文件位置再照着老笔记把包名、类名、输出目录一项项填进去常常因为少写了一个classpath参数或者包名大小写敲错白折腾半天。后来在IDEA里配置了一次External Tools把javah做成了一键外部工具右键点一下头文件自动生成到指定目录这个流程才算彻底顺了。这篇文章就把javah命令的完整用法和IDEA一键配置的具体做法都写清楚适合正在做JNI开发、或者初次接触JNI头文件生成流程的Java开发者参考。1. 先弄懂javah生成的到底是什么文件JNI开发里一个带native方法的Java类无法直接和C/C库对接。Java那一侧只声明方法名、参数和返回值C那一侧则是一大堆jni.h里的类型和JNIEnv操作两边名字对不上、类型也对不上。javah的作用就是读入编译后的class文件自动生成一个C/C的头文件把双方的“翻译规则”固化下来。你用native方法名去C函数里找对应看这个.h文件就能一目了然。1.1 一个JNI调用的完整生命周期先理清JNI调用在项目里到底是怎么一环扣一环的。一个典型的流程是在Java类里声明native方法并加载动态库。用javac编译出class文件。用javah读入class生成对应的C/C头文件。在C/C工程里引入这个头文件实现JNIEXPORT函数。编译C/C代码生成动态库Linux是so、macOS是dylib、Windows是dll。Java程序运行时通过System.loadLibrary加载动态库JVM在库中查找JNIEXPORT声明的函数符号并完成调用。javah就是中间那个翻译器。它本身不编译C代码也不负责动态库调用只负责把Java方法签名映射成C函数原型。你只要在Java类里改了方法名、参数类型或返回值类型就必须要重新生成头文件否则C函数签名和Java侧对不上运行时会出现UnsatisfiedLinkError。1.2 HelloWorld级别的最小范例用一个最简单的类来演示包名定为com.example.jni类名叫HelloJNIpackage com.example.jni; public class HelloJNI { static { System.loadLibrary(hello_jni); } public native String hello(String name); public native int add(int a, int b); }这个类声明了两个native方法hello接收一个String返回一个Stringadd接收两个int返回一个int。对javah来说这两个方法就是生成头文件的核心依据。注意一点javah面向的是编译后的class文件而不是.java源文件。如果你只有.java没有编译出.classjavah会直接报“找不到类”。1.3 生成的头文件有三个必须看懂的片段假设我们已经在命令行生成好头文件内容大致是/* DO NOT EDIT THIS FILE - it is machine generated */ #include jni.h /* Header for class com_example_jni_HelloJNI */ #ifndef _Included_com_example_jni_HelloJNI #define _Included_com_example_jni_HelloJNI #ifdef __cplusplus extern C { #endif /* * Class: com_example_jni_HelloJNI * Method: hello * Signature: (Ljava/lang/String;)Ljava/lang/String; */ JNIEXPORT jstring JNICALL Java_com_example_jni_HelloJNI_hello (JNIEnv *, jobject, jstring); /* * Class: com_example_jni_HelloJNI * Method: add * Signature: (II)I */ JNIEXPORT jint JNICALL Java_com_example_jni_HelloJNI_add (JNIEnv *, jobject, jint, jint); #ifdef __cplusplus } #endif #endif头文件里有三块内容必须看懂。第一是函数命名规则Java_包名_类名_方法名包名里的点全部替换成下划线。第二是JNI类型映射Java的String映射为jstringint映射为jintJVM在调用时会自动做类型转换。第三是Signature注释它记录了Java方法的完整签名比如(Ljava/lang/String;)Ljava/lang/String;表示方法接收一个String返回一个String。Signature在方法重载时会直接体现在函数名里后面避坑章节会细说。映射关系可以简单记成一张表Java类型JNI类型说明intjint32位有符号整数booleanjbooleanunsigned charlongjlong64位有符号整数floatjfloat32位浮点doublejdouble64位浮点Stringjstring引用类型需用JNI函数转换Objectjobject引用类型int[]jintArray数组对象2. javah命令的参数逐个拆解javah在JDK 8里是一个独立命令位于JDK的bin目录下。它的完整Help输出是这样的用法: javah [options] classes 其中, [options] 包括: -o file 输出文件 (只能使用 -o 或 -d 之一) -d dir 输出目录 -v -verbose 启用 verbose 输出 -h --help -? 显示此消息 -version 输出版本信息 -jni 生成 JNI 样式的 header (默认) -force 始终写入输出文件 -classpath path 从中加载类的路径 -cp path 从中加载类的路径 -bootclasspath path 从中加载引导程序的路径 -encoding encoding 指定编码2.1 每个参数的实际用途-classpath和-cp是同一个意思用于指定类路径。javah不是直接扫.java文件而是需要从类路径里加载class文件来分析native方法所以这里必须能让它找到编译后的类。对带包名的类类路径要指向包目录的上一级比如com.example.jni.HelloJNI所在的class文件在out目录下classpath就要写out目录不能写到out/com/example/jni那一层。-d指定输出目录生成的.h文件会放在该目录下。默认情况下javah当前目录作为输出目录。文件名很有特点它把包名也拼进了文件名比如com_example_jni_HelloJNI.h而不是像javac那样按包名建目录。这一点经常让第一次用的人找不到文件。-o和-d是互斥的只能选一个。有些人习惯把多个类的头文件合并到一个文件里就用-o指定一个文件比如javah -o all_headers.h A B C。如果同时写-o和-djavah会直接报参数冲突。-force的作用是始终写入输出文件。默认情况下如果目标文件已存在某些JDK版本会根据文件时间戳决定是否重写加-force可以强制覆盖在脚本批量生成场景里比较稳妥。-encoding用于指定读取class文件或处理中文字符串时的编码建议固定为UTF-8否则遇到中文方法名注释或中文字面量会出现乱码。2.2 两个反直觉的参数陷阱javah里面的-h是帮助参数这个和很多人的直觉相反。在JDK 8时代你想给javah传“头文件输出目录”是不存在的输出目录用的是-d。到了JDK 10以后用javac -h替代-h反而变成了指定输出目录新同学如果两套命令行混着看很容易把参数记串。-v-verbose会打印javah加载类和写入文件的详细过程排查类路径问题时很有用。我一般遇到“找不到类”的情况会先加-v跑一次看它实际到哪个目录加载类比瞎猜强得多。2.3 多类生成和批量处理技巧javah支持一次传入多个类每两个类名之间用空格分隔比如javah -classpath ./out -d ./jni com.example.jni.HelloJNI com.example.jni.OtherNative它会为每个类生成一个独立的.h文件。在Linux/macOS的shell里也可以用通配符把一批类名带进来但Windows的cmd不支持这种写法需要列全。真正的大项目一般不用手敲javah而是用Maven/Gradle插件或自己写脚本把classpath从构建系统里读出来再循环调用javah。IDE的一键化配置本质上也是帮你把这串命令固定下来。3. 命令行方式生成头文件的标准流程在配置IDEA之前建议先把命令行流程完整跑一遍。这样你能知道IDEA一键配置背后的每个参数在干嘛出问题也好排查。3.1 准备一个带native方法的类我用上面的HelloJNI类作为演示。新建一个目录结构如下的项目demo/ ├── com/example/jni/HelloJNI.java └── out/在demo目录下编译javac -encoding UTF-8 -d ./out com/example/jni/HelloJNI.java注意-d参数把class文件输出到out目录。编译后out目录下会出现com/example/jni/HelloJNI.class。3.2 先编译再javah的完整命令在demo目录下执行javah -classpath ./out -d ./jni com.example.jni.HelloJNI执行完之后jni目录下会生成com_example_jni_HelloJNI.h。这里有两个容易出错的细节第一如果当前目录还包含其他路径classpath一定要明确不要指望javah自动去当前目录找。javah没有任何自动扫描功能它只认classpath参数指定的路径。第二类名参数要写全限定名也就是com.example.jni.HelloJNI而不是HelloJNI也不是com/example/jni/HelloJNI.class。很多人在这里把路径分隔符写成了斜杠javah不认。如果类里依赖了第三方库javah在加载类时需要把依赖也放入classpath否则会报“无法访问某个类的符号”。比如javah -classpath ./out:./libs/foo.jar -d ./jni com.example.jni.HelloJNIWindows下classpath的分隔符是分号不是冒号。3.3 C端如何消费这份头文件生成的头文件不会自己实现功能还需要一个C文件来写真正的方法体。创建hello.cpp#include jni.h #include com_example_jni_HelloJNI.h #include string JNIEXPORT jstring JNICALL Java_com_example_jni_HelloJNI_hello (JNIEnv *env, jobject thiz, jstring name) { const char *rawName env-GetStringUTFChars(name, nullptr); std::string result Hello, std::string(rawName) !; env-ReleaseStringUTFChars(name, rawName); return env-NewStringUTF(result.c_str()); } JNIEXPORT jint JNICALL Java_com_example_jni_HelloJNI_add (JNIEnv *env, jobject thiz, jint a, jint b) { return a b; }编译成动态库之前需要告诉编译器jni.h在哪里。以macOS为例JDK的include目录通常需要加两个g -shared -fPIC -o libhello_jni.dylib \ -I $JAVA_HOME/include \ -I $JAVA_HOME/include/darwin \ hello.cppLinux下把darwin换成linux。Windows生成dll时命令稍有差别但原理一样。编译好动态库后Java侧运行时需要指定库路径java -Djava.library.path./build -cp ./out com.example.jni.HelloJNI一个简单的Main类加个main方法调用add能输出正确结果就说明从javah到C的整条链路走通了。4. IDEA一键生成External Tools配置实战命令行流程熟悉之后可以把它固化到IDEA里。所谓的“一键编译头文件”本质上就是把上面的javah命令改成IDEA的外部工具配置让用户不用切终端、不用手抄包名。4.1 为什么不用插件而用External Tools做JNI头文件生成确实有专门插件但我的建议是优先用External Tools。原因有三点一是插件版本不一定跟随你的IDEA版本更新遇到新版本经常出现不兼容二是External Tools只是存储一条命令不引入额外依赖换电脑后重新配置也很快三是它的参数可以随时改扩展到javac -h方案也容易。对一条核心命令来说插件带来的便利远不如它多出的不确定性。4.2 一步步配置javah外部工具打开IDEA的设置面板进入Tools - External Tools。不同版本的IDEA菜单位置略有差异但关键字就是External Tools。点击加号新建一个工具填写以下内容配置项填写内容NameJNI头文件 (javah)Program$JDKPath$/bin/javahArguments-classpath $OutputPath$ -d $OutputPath$ $FileClass$Working directory$ProjectFileDir$打开“Open console for tool output”这样生成过程的日志会出现在IDEA底部的控制台报错时能直接看到。解释一下这里用到的IDEA宏变量$JDKPath$会替换成IDEA当前使用的JDK路径不用手动写死JDK位置。$OutputPath$是模块的编译输出目录通常是out/production/模块名。javah需要在这个目录里找到.class头文件也输出到这个目录。$FileClass$是当前选中Java类的全限定名。比如选中了HelloJNI.java它就是com.example.jni.HelloJNI。这个变量是External Tools里专门为Java类提供的用起来非常方便。$ProjectFileDir$是当前项目根目录。配置完成后使用姿势是这样的先Build - Build Project确保class文件已经生成。在Project窗口选中HelloJNI.java。右键 - External Tools - JNI头文件 (javah)。去out目录找com_example_jni_HelloJNI.h。注意如果项目还没编译$OutputPath$下面没有classjavah会报“找不到类”。这种情况不是配置有问题是漏掉了编译步骤。如果你在IDEA里开了自动编译选中类文件直接右键一般也可以但为了稳妥建议还是手动执行一次Build。4.3 第三方依赖和多模块场景下的classpath补全上面的配置对无依赖的单模块项目完全够用。但项目一复杂问题就来了如果HelloJNI里用到了第三方库的类javah加载类时也需要这些库。你可以把Arguments改成-classpath $OutputPath$$PathSeparator$$ProjectClasspath$ -d $OutputPath$ $FileClass$其中$PathSeparator$会自动匹配Windows的分号或Unix的冒号$ProjectClasspath$则是IDEA整理的当前项目完整类路径。这个写法比手写依赖路径要省心。多模块项目里如果当前类依赖另一个模块的类但IDEA没有把依赖模块加入当前模块的依赖列表javah依然会报“无法访问”。正确做法是先在Project Structure里把模块依赖关系配好再用$ProjectClasspath$或者$Classpath$宏。我实际用下来宏变量在多模块下偶尔会漏掉某些输出路径遇到这种情况最简单的兜底方案是手动把缺失路径拼进-classpath用$PathSeparator$连接。4.4 配置好之后的使用姿势与验证配置完成后验证方法很简单。选中HelloJNI.java右键执行外部工具控制台会输出类似Loading class com.example.jni.HelloJNI... Creating com_example_jni_HelloJNI.h打开输出目录检查头文件里的方法签名是否和Java一致。如果一致说明这一键配置已经生效。之后每次新增或修改native方法只需要重新右键执行一次头文件就会覆盖更新。整个过程不用切终端不用记命令这也是IDEA External Tools最大的价值。5. JDK 10后javah移除怎么用javac -h继续“一键”很多开发者发现自己的JDK里没有javah命令执行时报“command not found”。这不是配置写错而是JDK版本已经走到了10或更高。5.1 javah为什么会被干掉JDK 9里javah被标记为废弃JDK 10正式移除。移除的原因不复杂javac本身就掌握着Java源码的全部类型信息生成JNI头文件这种能力直接挪进javac反而更合理。单独维护一个命令行工具既要维护class文件解析逻辑又要同步类型系统变化代价不划算。Oracle在移除前给出的替代方案就是javac -h参数新的命令行方式直接从.java源文件生成头文件连先javac再javah的中间步骤都省掉了。5.2 javac -h的用法和参数差异先看命令行写法javac -encoding UTF-8 -h ./jni -d ./classes com/example/jni/HelloJNI.java这里-h后面跟的是头文件输出目录javac会一边编译一边生成头文件。如果你只需要头文件连-d都可以不写javac默认会把class输出到源文件相同目录。加上-d则把class放到指定目录避免污染源码目录。javac -h和javah在参数上有一个很坑的差异javah的-h表示帮助javac -h的-h表示头文件输出目录。我见过不少人把javah的帮助需求套到javac上结果参数被吃了或者直接报错。另一个差异是输入对象不同javah吃class文件javac -h吃.java源文件。这意味着IDEA配置的宏变量也要改不能直接把老配置复制过去。5.3 在IDEA中配置javac -h方案在External Tools里再新建一个工具配置项填写内容NameJNI头文件 (javac -h)Program$JDKPath$/bin/javacArguments-h $OutputPath$ -classpath $OutputPath$ $FilePath$Working directory$ProjectFileDir$这里把$FileClass$换成了$FilePath$因为javac需要的是源文件路径而不是类名。同样先Build再右键选中HelloJNI.java执行该工具头文件会生成到$OutputPath$下和javah方案输出位置一致。有一个细节值得留意javac -h在处理带依赖的项目时classpath同样要补全。如果类依赖了第三方库建议把Arguments里加上$ProjectClasspath$-h $OutputPath$ -classpath $OutputPath$$PathSeparator$$ProjectClasspath$ $FilePath$5.4 两个方案的适用场景对照对比项javah方案javac -h方案适用JDKJDK 8 / 9JDK 10及以上输入对象class文件java源文件是否依赖编译产物必须先Buildjavac会自动把依赖源码一并编译输出目录参数-d-hIDEA中的类变量$FileClass$$FilePath$依赖处理复杂依赖需补classpath复杂依赖需补classpath如果你还在用JDK 8用javah方案顺手如果已经升级到JDK 11或更高直接用javac -h方案。两个方案可以不冲突地同时配置成两个External Tools需要哪个用哪个。6. 我踩过的坑JNI头文件生成避坑清单最后把这几年在JNI头文件生成上踩过的坑集中列一下每一条都是真实遇到过的问题按出现频率排序。6.1 类路径相关的三个典型报错第一个是“错误: 找不到类 com.example.jni.HelloJNI”。原因是classpath没指向class文件所在目录或者类已经被删掉了。解决方式是确认编译输出目录里确实有com/example/jni/HelloJNI.class再把该目录写进-classpath。第二个是“错误: 无法访问HelloJNI找不到X类的类文件”。这说明目标类本身能找到但它引用的其他类不在classpath里。第三方依赖项目里特别常见。解决方式是把依赖的jar包或依赖模块的输出目录加进classpath用$ProjectClasspath$最省事。第三个是“javah: 错误: 不应该为接口生成JNI头文件”。对接口使用javah会报这个错因为接口里的方法没有实现JNI规范也不要求为接口生成头文件。如果你确实需要在接口里定义native方法然后实现生成逻辑会复杂很多多数情况下建议直接在实现类上生成。6.2 方法重载和特殊字符的命名规则头文件里的函数名不是简单拼接重载方法会在函数名后面追加签名。比如类里有public native int add(int a, int b); public native int add(double a, double b);javah生成的两个函数分别是Java_com_example_jni_HelloJNI_add__II Java_com_example_jni_HelloJNI_add__DD后面那两个字母II表示int,intDD表示double,double。如果你在C里实现时只写了最前面的Java_com_example_jni_HelloJNI_addJVM找不到重载对应的函数符号运行时会报UnsatisfiedLinkError。还有一类坑是类和方法的特殊字符。Java中允许方法名包含下划线比如hello_world但JNI命名规范要求下划线转义成_1所以生成结果是Java_com_example_jni_HelloJNI_hello_1world。如果直接按直觉写hello_world也是找不到符号。6.3 静态方法与实例方法的参数差异静态native方法生成的函数原型里第二个参数是jclass而不是jobject。看个例子public static native void init();对应头文件JNIEXPORT void JNICALL Java_com_example_jni_HelloJNI_init (JNIEnv *, jclass);实例方法的第二参数是jobject表示当前对象this静态方法的第二参数是jclass代表类对象。实现C函数时混用这两个参数类型轻则编译告警重则逻辑拿错对象导致崩溃。很多老手在不写头文件、手撸JNI函数名时最容易漏掉这个。6.4 生成后的头文件千万别手动改头文件第一行就写着“DO NOT EDIT THIS FILE”这真不是客套话。javah或javac -h生成的头文件是Java方法签名和C函数原型的权威对应关系手动增删参数或改函数名会造成Java侧与C侧签名不一致。表现为编译通过但运行时UnsatisfiedLinkError或者明明加载了动态库却一直报找不到符号。正确的做法是修改Java代码里的native方法声明后重新右键执行一次外部工具同步头文件再同步修改C实现。不要既改Java又手改头文件两边一旦脱节排查起来非常痛苦。我早期就因为这习惯经常半天定位不到一个“诡异”的加载错误后来才明白根因不过是头文件和Java声明没同步。JNI头文件生成是整个JNI链路里最容易机械化、也最应该机械化的一步。无论是JDK 8时代的javah还是JDK 10之后的javac -h只要把这套命令在IDEA里配成External Tools后续每次修改native方法都能右键搞定。记住一个原则任何生成器产出的文件都不应该手工编辑你的修改对象永远是Java源码和C实现头文件只是连接两者的自动桥梁。
JNI开发里最绕不过去的环节就是生成头文件。我刚入门那会儿每次在Java类里加一个native方法都要重新手动敲一遍javah命令先切到编译输出目录确认class文件位置再照着老笔记把包名、类名、输出目录一项项填进去常常因为少写了一个classpath参数或者包名大小写敲错白折腾半天。后来在IDEA里配置了一次External Tools把javah做成了一键外部工具右键点一下头文件自动生成到指定目录这个流程才算彻底顺了。这篇文章就把javah命令的完整用法和IDEA一键配置的具体做法都写清楚适合正在做JNI开发、或者初次接触JNI头文件生成流程的Java开发者参考。1. 先弄懂javah生成的到底是什么文件JNI开发里一个带native方法的Java类无法直接和C/C库对接。Java那一侧只声明方法名、参数和返回值C那一侧则是一大堆jni.h里的类型和JNIEnv操作两边名字对不上、类型也对不上。javah的作用就是读入编译后的class文件自动生成一个C/C的头文件把双方的“翻译规则”固化下来。你用native方法名去C函数里找对应看这个.h文件就能一目了然。1.1 一个JNI调用的完整生命周期先理清JNI调用在项目里到底是怎么一环扣一环的。一个典型的流程是在Java类里声明native方法并加载动态库。用javac编译出class文件。用javah读入class生成对应的C/C头文件。在C/C工程里引入这个头文件实现JNIEXPORT函数。编译C/C代码生成动态库Linux是so、macOS是dylib、Windows是dll。Java程序运行时通过System.loadLibrary加载动态库JVM在库中查找JNIEXPORT声明的函数符号并完成调用。javah就是中间那个翻译器。它本身不编译C代码也不负责动态库调用只负责把Java方法签名映射成C函数原型。你只要在Java类里改了方法名、参数类型或返回值类型就必须要重新生成头文件否则C函数签名和Java侧对不上运行时会出现UnsatisfiedLinkError。1.2 HelloWorld级别的最小范例用一个最简单的类来演示包名定为com.example.jni类名叫HelloJNIpackage com.example.jni; public class HelloJNI { static { System.loadLibrary(hello_jni); } public native String hello(String name); public native int add(int a, int b); }这个类声明了两个native方法hello接收一个String返回一个Stringadd接收两个int返回一个int。对javah来说这两个方法就是生成头文件的核心依据。注意一点javah面向的是编译后的class文件而不是.java源文件。如果你只有.java没有编译出.classjavah会直接报“找不到类”。1.3 生成的头文件有三个必须看懂的片段假设我们已经在命令行生成好头文件内容大致是/* DO NOT EDIT THIS FILE - it is machine generated */ #include jni.h /* Header for class com_example_jni_HelloJNI */ #ifndef _Included_com_example_jni_HelloJNI #define _Included_com_example_jni_HelloJNI #ifdef __cplusplus extern C { #endif /* * Class: com_example_jni_HelloJNI * Method: hello * Signature: (Ljava/lang/String;)Ljava/lang/String; */ JNIEXPORT jstring JNICALL Java_com_example_jni_HelloJNI_hello (JNIEnv *, jobject, jstring); /* * Class: com_example_jni_HelloJNI * Method: add * Signature: (II)I */ JNIEXPORT jint JNICALL Java_com_example_jni_HelloJNI_add (JNIEnv *, jobject, jint, jint); #ifdef __cplusplus } #endif #endif头文件里有三块内容必须看懂。第一是函数命名规则Java_包名_类名_方法名包名里的点全部替换成下划线。第二是JNI类型映射Java的String映射为jstringint映射为jintJVM在调用时会自动做类型转换。第三是Signature注释它记录了Java方法的完整签名比如(Ljava/lang/String;)Ljava/lang/String;表示方法接收一个String返回一个String。Signature在方法重载时会直接体现在函数名里后面避坑章节会细说。映射关系可以简单记成一张表Java类型JNI类型说明intjint32位有符号整数booleanjbooleanunsigned charlongjlong64位有符号整数floatjfloat32位浮点doublejdouble64位浮点Stringjstring引用类型需用JNI函数转换Objectjobject引用类型int[]jintArray数组对象2. javah命令的参数逐个拆解javah在JDK 8里是一个独立命令位于JDK的bin目录下。它的完整Help输出是这样的用法: javah [options] classes 其中, [options] 包括: -o file 输出文件 (只能使用 -o 或 -d 之一) -d dir 输出目录 -v -verbose 启用 verbose 输出 -h --help -? 显示此消息 -version 输出版本信息 -jni 生成 JNI 样式的 header (默认) -force 始终写入输出文件 -classpath path 从中加载类的路径 -cp path 从中加载类的路径 -bootclasspath path 从中加载引导程序的路径 -encoding encoding 指定编码2.1 每个参数的实际用途-classpath和-cp是同一个意思用于指定类路径。javah不是直接扫.java文件而是需要从类路径里加载class文件来分析native方法所以这里必须能让它找到编译后的类。对带包名的类类路径要指向包目录的上一级比如com.example.jni.HelloJNI所在的class文件在out目录下classpath就要写out目录不能写到out/com/example/jni那一层。-d指定输出目录生成的.h文件会放在该目录下。默认情况下javah当前目录作为输出目录。文件名很有特点它把包名也拼进了文件名比如com_example_jni_HelloJNI.h而不是像javac那样按包名建目录。这一点经常让第一次用的人找不到文件。-o和-d是互斥的只能选一个。有些人习惯把多个类的头文件合并到一个文件里就用-o指定一个文件比如javah -o all_headers.h A B C。如果同时写-o和-djavah会直接报参数冲突。-force的作用是始终写入输出文件。默认情况下如果目标文件已存在某些JDK版本会根据文件时间戳决定是否重写加-force可以强制覆盖在脚本批量生成场景里比较稳妥。-encoding用于指定读取class文件或处理中文字符串时的编码建议固定为UTF-8否则遇到中文方法名注释或中文字面量会出现乱码。2.2 两个反直觉的参数陷阱javah里面的-h是帮助参数这个和很多人的直觉相反。在JDK 8时代你想给javah传“头文件输出目录”是不存在的输出目录用的是-d。到了JDK 10以后用javac -h替代-h反而变成了指定输出目录新同学如果两套命令行混着看很容易把参数记串。-v-verbose会打印javah加载类和写入文件的详细过程排查类路径问题时很有用。我一般遇到“找不到类”的情况会先加-v跑一次看它实际到哪个目录加载类比瞎猜强得多。2.3 多类生成和批量处理技巧javah支持一次传入多个类每两个类名之间用空格分隔比如javah -classpath ./out -d ./jni com.example.jni.HelloJNI com.example.jni.OtherNative它会为每个类生成一个独立的.h文件。在Linux/macOS的shell里也可以用通配符把一批类名带进来但Windows的cmd不支持这种写法需要列全。真正的大项目一般不用手敲javah而是用Maven/Gradle插件或自己写脚本把classpath从构建系统里读出来再循环调用javah。IDE的一键化配置本质上也是帮你把这串命令固定下来。3. 命令行方式生成头文件的标准流程在配置IDEA之前建议先把命令行流程完整跑一遍。这样你能知道IDEA一键配置背后的每个参数在干嘛出问题也好排查。3.1 准备一个带native方法的类我用上面的HelloJNI类作为演示。新建一个目录结构如下的项目demo/ ├── com/example/jni/HelloJNI.java └── out/在demo目录下编译javac -encoding UTF-8 -d ./out com/example/jni/HelloJNI.java注意-d参数把class文件输出到out目录。编译后out目录下会出现com/example/jni/HelloJNI.class。3.2 先编译再javah的完整命令在demo目录下执行javah -classpath ./out -d ./jni com.example.jni.HelloJNI执行完之后jni目录下会生成com_example_jni_HelloJNI.h。这里有两个容易出错的细节第一如果当前目录还包含其他路径classpath一定要明确不要指望javah自动去当前目录找。javah没有任何自动扫描功能它只认classpath参数指定的路径。第二类名参数要写全限定名也就是com.example.jni.HelloJNI而不是HelloJNI也不是com/example/jni/HelloJNI.class。很多人在这里把路径分隔符写成了斜杠javah不认。如果类里依赖了第三方库javah在加载类时需要把依赖也放入classpath否则会报“无法访问某个类的符号”。比如javah -classpath ./out:./libs/foo.jar -d ./jni com.example.jni.HelloJNIWindows下classpath的分隔符是分号不是冒号。3.3 C端如何消费这份头文件生成的头文件不会自己实现功能还需要一个C文件来写真正的方法体。创建hello.cpp#include jni.h #include com_example_jni_HelloJNI.h #include string JNIEXPORT jstring JNICALL Java_com_example_jni_HelloJNI_hello (JNIEnv *env, jobject thiz, jstring name) { const char *rawName env-GetStringUTFChars(name, nullptr); std::string result Hello, std::string(rawName) !; env-ReleaseStringUTFChars(name, rawName); return env-NewStringUTF(result.c_str()); } JNIEXPORT jint JNICALL Java_com_example_jni_HelloJNI_add (JNIEnv *env, jobject thiz, jint a, jint b) { return a b; }编译成动态库之前需要告诉编译器jni.h在哪里。以macOS为例JDK的include目录通常需要加两个g -shared -fPIC -o libhello_jni.dylib \ -I $JAVA_HOME/include \ -I $JAVA_HOME/include/darwin \ hello.cppLinux下把darwin换成linux。Windows生成dll时命令稍有差别但原理一样。编译好动态库后Java侧运行时需要指定库路径java -Djava.library.path./build -cp ./out com.example.jni.HelloJNI一个简单的Main类加个main方法调用add能输出正确结果就说明从javah到C的整条链路走通了。4. IDEA一键生成External Tools配置实战命令行流程熟悉之后可以把它固化到IDEA里。所谓的“一键编译头文件”本质上就是把上面的javah命令改成IDEA的外部工具配置让用户不用切终端、不用手抄包名。4.1 为什么不用插件而用External Tools做JNI头文件生成确实有专门插件但我的建议是优先用External Tools。原因有三点一是插件版本不一定跟随你的IDEA版本更新遇到新版本经常出现不兼容二是External Tools只是存储一条命令不引入额外依赖换电脑后重新配置也很快三是它的参数可以随时改扩展到javac -h方案也容易。对一条核心命令来说插件带来的便利远不如它多出的不确定性。4.2 一步步配置javah外部工具打开IDEA的设置面板进入Tools - External Tools。不同版本的IDEA菜单位置略有差异但关键字就是External Tools。点击加号新建一个工具填写以下内容配置项填写内容NameJNI头文件 (javah)Program$JDKPath$/bin/javahArguments-classpath $OutputPath$ -d $OutputPath$ $FileClass$Working directory$ProjectFileDir$打开“Open console for tool output”这样生成过程的日志会出现在IDEA底部的控制台报错时能直接看到。解释一下这里用到的IDEA宏变量$JDKPath$会替换成IDEA当前使用的JDK路径不用手动写死JDK位置。$OutputPath$是模块的编译输出目录通常是out/production/模块名。javah需要在这个目录里找到.class头文件也输出到这个目录。$FileClass$是当前选中Java类的全限定名。比如选中了HelloJNI.java它就是com.example.jni.HelloJNI。这个变量是External Tools里专门为Java类提供的用起来非常方便。$ProjectFileDir$是当前项目根目录。配置完成后使用姿势是这样的先Build - Build Project确保class文件已经生成。在Project窗口选中HelloJNI.java。右键 - External Tools - JNI头文件 (javah)。去out目录找com_example_jni_HelloJNI.h。注意如果项目还没编译$OutputPath$下面没有classjavah会报“找不到类”。这种情况不是配置有问题是漏掉了编译步骤。如果你在IDEA里开了自动编译选中类文件直接右键一般也可以但为了稳妥建议还是手动执行一次Build。4.3 第三方依赖和多模块场景下的classpath补全上面的配置对无依赖的单模块项目完全够用。但项目一复杂问题就来了如果HelloJNI里用到了第三方库的类javah加载类时也需要这些库。你可以把Arguments改成-classpath $OutputPath$$PathSeparator$$ProjectClasspath$ -d $OutputPath$ $FileClass$其中$PathSeparator$会自动匹配Windows的分号或Unix的冒号$ProjectClasspath$则是IDEA整理的当前项目完整类路径。这个写法比手写依赖路径要省心。多模块项目里如果当前类依赖另一个模块的类但IDEA没有把依赖模块加入当前模块的依赖列表javah依然会报“无法访问”。正确做法是先在Project Structure里把模块依赖关系配好再用$ProjectClasspath$或者$Classpath$宏。我实际用下来宏变量在多模块下偶尔会漏掉某些输出路径遇到这种情况最简单的兜底方案是手动把缺失路径拼进-classpath用$PathSeparator$连接。4.4 配置好之后的使用姿势与验证配置完成后验证方法很简单。选中HelloJNI.java右键执行外部工具控制台会输出类似Loading class com.example.jni.HelloJNI... Creating com_example_jni_HelloJNI.h打开输出目录检查头文件里的方法签名是否和Java一致。如果一致说明这一键配置已经生效。之后每次新增或修改native方法只需要重新右键执行一次头文件就会覆盖更新。整个过程不用切终端不用记命令这也是IDEA External Tools最大的价值。5. JDK 10后javah移除怎么用javac -h继续“一键”很多开发者发现自己的JDK里没有javah命令执行时报“command not found”。这不是配置写错而是JDK版本已经走到了10或更高。5.1 javah为什么会被干掉JDK 9里javah被标记为废弃JDK 10正式移除。移除的原因不复杂javac本身就掌握着Java源码的全部类型信息生成JNI头文件这种能力直接挪进javac反而更合理。单独维护一个命令行工具既要维护class文件解析逻辑又要同步类型系统变化代价不划算。Oracle在移除前给出的替代方案就是javac -h参数新的命令行方式直接从.java源文件生成头文件连先javac再javah的中间步骤都省掉了。5.2 javac -h的用法和参数差异先看命令行写法javac -encoding UTF-8 -h ./jni -d ./classes com/example/jni/HelloJNI.java这里-h后面跟的是头文件输出目录javac会一边编译一边生成头文件。如果你只需要头文件连-d都可以不写javac默认会把class输出到源文件相同目录。加上-d则把class放到指定目录避免污染源码目录。javac -h和javah在参数上有一个很坑的差异javah的-h表示帮助javac -h的-h表示头文件输出目录。我见过不少人把javah的帮助需求套到javac上结果参数被吃了或者直接报错。另一个差异是输入对象不同javah吃class文件javac -h吃.java源文件。这意味着IDEA配置的宏变量也要改不能直接把老配置复制过去。5.3 在IDEA中配置javac -h方案在External Tools里再新建一个工具配置项填写内容NameJNI头文件 (javac -h)Program$JDKPath$/bin/javacArguments-h $OutputPath$ -classpath $OutputPath$ $FilePath$Working directory$ProjectFileDir$这里把$FileClass$换成了$FilePath$因为javac需要的是源文件路径而不是类名。同样先Build再右键选中HelloJNI.java执行该工具头文件会生成到$OutputPath$下和javah方案输出位置一致。有一个细节值得留意javac -h在处理带依赖的项目时classpath同样要补全。如果类依赖了第三方库建议把Arguments里加上$ProjectClasspath$-h $OutputPath$ -classpath $OutputPath$$PathSeparator$$ProjectClasspath$ $FilePath$5.4 两个方案的适用场景对照对比项javah方案javac -h方案适用JDKJDK 8 / 9JDK 10及以上输入对象class文件java源文件是否依赖编译产物必须先Buildjavac会自动把依赖源码一并编译输出目录参数-d-hIDEA中的类变量$FileClass$$FilePath$依赖处理复杂依赖需补classpath复杂依赖需补classpath如果你还在用JDK 8用javah方案顺手如果已经升级到JDK 11或更高直接用javac -h方案。两个方案可以不冲突地同时配置成两个External Tools需要哪个用哪个。6. 我踩过的坑JNI头文件生成避坑清单最后把这几年在JNI头文件生成上踩过的坑集中列一下每一条都是真实遇到过的问题按出现频率排序。6.1 类路径相关的三个典型报错第一个是“错误: 找不到类 com.example.jni.HelloJNI”。原因是classpath没指向class文件所在目录或者类已经被删掉了。解决方式是确认编译输出目录里确实有com/example/jni/HelloJNI.class再把该目录写进-classpath。第二个是“错误: 无法访问HelloJNI找不到X类的类文件”。这说明目标类本身能找到但它引用的其他类不在classpath里。第三方依赖项目里特别常见。解决方式是把依赖的jar包或依赖模块的输出目录加进classpath用$ProjectClasspath$最省事。第三个是“javah: 错误: 不应该为接口生成JNI头文件”。对接口使用javah会报这个错因为接口里的方法没有实现JNI规范也不要求为接口生成头文件。如果你确实需要在接口里定义native方法然后实现生成逻辑会复杂很多多数情况下建议直接在实现类上生成。6.2 方法重载和特殊字符的命名规则头文件里的函数名不是简单拼接重载方法会在函数名后面追加签名。比如类里有public native int add(int a, int b); public native int add(double a, double b);javah生成的两个函数分别是Java_com_example_jni_HelloJNI_add__II Java_com_example_jni_HelloJNI_add__DD后面那两个字母II表示int,intDD表示double,double。如果你在C里实现时只写了最前面的Java_com_example_jni_HelloJNI_addJVM找不到重载对应的函数符号运行时会报UnsatisfiedLinkError。还有一类坑是类和方法的特殊字符。Java中允许方法名包含下划线比如hello_world但JNI命名规范要求下划线转义成_1所以生成结果是Java_com_example_jni_HelloJNI_hello_1world。如果直接按直觉写hello_world也是找不到符号。6.3 静态方法与实例方法的参数差异静态native方法生成的函数原型里第二个参数是jclass而不是jobject。看个例子public static native void init();对应头文件JNIEXPORT void JNICALL Java_com_example_jni_HelloJNI_init (JNIEnv *, jclass);实例方法的第二参数是jobject表示当前对象this静态方法的第二参数是jclass代表类对象。实现C函数时混用这两个参数类型轻则编译告警重则逻辑拿错对象导致崩溃。很多老手在不写头文件、手撸JNI函数名时最容易漏掉这个。6.4 生成后的头文件千万别手动改头文件第一行就写着“DO NOT EDIT THIS FILE”这真不是客套话。javah或javac -h生成的头文件是Java方法签名和C函数原型的权威对应关系手动增删参数或改函数名会造成Java侧与C侧签名不一致。表现为编译通过但运行时UnsatisfiedLinkError或者明明加载了动态库却一直报找不到符号。正确的做法是修改Java代码里的native方法声明后重新右键执行一次外部工具同步头文件再同步修改C实现。不要既改Java又手改头文件两边一旦脱节排查起来非常痛苦。我早期就因为这习惯经常半天定位不到一个“诡异”的加载错误后来才明白根因不过是头文件和Java声明没同步。JNI头文件生成是整个JNI链路里最容易机械化、也最应该机械化的一步。无论是JDK 8时代的javah还是JDK 10之后的javac -h只要把这套命令在IDEA里配成External Tools后续每次修改native方法都能右键搞定。记住一个原则任何生成器产出的文件都不应该手工编辑你的修改对象永远是Java源码和C实现头文件只是连接两者的自动桥梁。
