GraalVM Native Image CLI 选项完全指南:从类路径配置到构建优化与诊断
GraalVM Native Image 的 native-image 命令行工具将 JVM 应用提前编译(AOT)为独立的原生可执行文件。本文以官方 CLI 选项参考为核心,系统梳理类路径与模块、类初始化策略、可达性元数据、静态链接、性能优化、监控与诊断等全部常用选项,并结合本仓库(GraalVM 主仓库,substratevm 为 SubstrateVM 实现所在)的源码逐项印证每个选项的底层实现与适用场景,帮助你快速定位构建问题、写出可复用的构建命令。
类路径与模块:让构建器找到你的类
native-image 构建器本身运行在 JVM 之上,需要通过类路径(classpath)或模块路径(module path)发现应用类。
如果 native-image 找不到你的类,显式指定类路径:
native-image -cp <path1>:<path2> <class>
-cp与 JVM 的-classpath语义一致,多个路径用冒号(Linux/macOS)或分号(Windows)分隔;<class>是包含main方法的全限定类名(如com.example.App);- 在 Gradle/Maven 生态中,该参数通常由构建插件自动生成,手工排查时可用
-cp覆盖。
如果使用 Java 模块系统(JPMS):
native-image -p <module-path> --add-modules <module-name> <class>
-p指定模块路径,--add-modules声明需要解析的根模块;- 底层通过
ImageClassLoader(位于substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/ImageClassLoader.java附近)统一加载类路径与模块路径中的类型,构建时的类加载器与运行时镜像中的类空间一一对应。
构建失败排查:类初始化、内存与构建器 JVM 标志
Native Image 构建期最常见的失败是类初始化时机错误:静态初始化块在构建期执行时依赖了运行时才存在的条件(如读取环境变量、启动服务)。SubstrateVM 中由 ClassInitializationSupport(见 ClassInitializationSupport.java)统一决策每个类在构建期初始化(BUILD_TIME)还是延迟到运行期(RUN_TIME),并通过 --initialize-at-build-time / --initialize-at-run-time 覆盖默认策略。
如果某个类在构建期被初始化但必须延迟:
native-image --initialize-at-run-time=com.example.LazyClass <class>
如果某个类必须在构建期完成初始化(例如其静态状态需要被固化进镜像堆):
native-image --initialize-at-build-time=com.example.EagerClass <class>
两点实践提示:
- 两个选项都支持
包名与类名两种粒度,包名写法如--initialize-at-run-time=com.example; - 从源码看,选项内部使用
InitializationValueBuildTime/InitializationValueRunTime值转换器解析,并对非法配置(如把 JDK 内部类强制改为 run-time 初始化)直接抛出UserError中止构建,避免生成错误镜像。
如果某个类型必须在构建期被完整定义(例如作为 --link-at-build-time 的链接根,将未找到的类在构建期就报错而非运行期):
native-image --link-at-build-time <class>
如果构建进程内存不足(默认构建器堆通常较小):
native-image -J-Xmx8g <class>
如果需要设置构建期系统属性(会随镜像固化,运行期默认继承):
native-image -Dkey=value <class>
如果需要向承载构建器的 JVM 传递任意标志:
native-image -J<flag> <class>
-J 前缀等价于把后续参数原样转发给构建 JVM,常用于调优构建器本身的 GC 或调试参数。
缺失可达性元数据:从"运行期神秘报错"到"构建期精确报错"
Native Image 通过静态分析确定哪些元素可达,反射(reflection)、JNI、代理(proxy)、资源(resource)、序列化(serialization)等动态特性必须通过可达性元数据(reachability metadata,即 reflect-config.json、resource-config.json 等)显式注册。
如果希望缺失注册时获得精确报错(GraalVM JDK 23+):
native-image --exact-reachability-metadata <class>
如果只想对特定类路径条目启用精确元数据处理:
native-image --exact-reachability-metadata-path=<path> <class>
该选项在源码中的定义位于 SubstrateOptions.java,对应内部选项 ThrowMissingRegistrationErrors 与 ThrowMissingRegistrationErrorsPaths。官方帮助文本 ExactReachabilityMetadataHelp.txt 给出了关键行为:
- 启用后,当某元素缺少元数据注册时,二进制会在对应反射/资源/JNI/序列化访问点快速失败,抛出
java.lang.Error的子类,并精确说明缺的是哪个元素; - 可将作用域缩小到单个包:
--exact-reachability-metadata=pkg; - 选项可以携带参数出现在命令行、模块路径上 jar 中的
native-image.properties、或类路径 jar 中的native-image.properties三个位置,作用域规则不同:不带参数时只能出现在命令行或模块路径的 properties 中; - 官方明确提示该模式将在未来版本成为默认行为,建议尽早采用以平滑迁移。
配套的还有 MissingRegistrationReportingMode 运行期选项(Throw/Exit/Warn),控制缺失注册错误的报告方式。
输出与二进制类型:改名、共享库与静态链接
重命名输出二进制:
native-image -o myapp <class>
对应源码中的 -o 选项(见 SubstrateOptions.java),默认输出名与入口类名一致。
构建共享库(供 C/C++ 等通过头文件调用):
native-image --shared <class>
对应 SharedLibrary 选项,构建产物为 .so/.dylib/.dll 并附带导出符号表。
构建完全静态链接的可执行文件:
native-image --static --libc=musl <class>
静态链接但保留动态 libc:
native-image --static-nolibc <class>
从 SubstrateOptions.java 的源码校验逻辑可以确认重要限制:
--static仅在 Linux 上受支持,其他平台直接报invalidOptionValue错误;- 完全静态链接必须配合 musl libc(
--libc=musl),否则构建器会提示 "Building static executable images is only supported with musl libc"; --libc可选值为glibc(默认)、musl、bionic;- 完全静态还需要静态版的 zlib。
性能与优化:迭代速度、运行性能与体积的三向权衡
最快构建时间(开发迭代):
native-image -Ob <class>
-Ob 关闭大部分优化与额外分析,构建最快,适合 CI 冒烟或本地快速验证,但生成的二进制运行性能较低。
最佳运行性能:
native-image -O3 <class>
-O3 全量优化,适合发布构建;-O2 为默认级别,-O1 介于两者之间。
针对二进制体积优化:
native-image -Os <class>
-Os 在保持可接受性能的前提下压缩镜像体积,适合容器分发等体积敏感场景。
更换垃圾回收器:
native-image --gc=epsilon <class> # 无 GC,追求吞吐
native-image --gc=serial <class> # 默认
Native Image 还提供 G1(--gc=G1)与 Z(--gc=Z,适合大堆低延迟)等选择,不同 GC 的取舍可查阅仓库中 GC 实现目录 com.oracle.svm.core.genscavenge、com.oracle.svm.core.g1。
针对当前机器 CPU 特性优化:
native-image -march=native <class>
追求跨机器最大兼容性:
native-image -march=compatibility <class>
-march 控制目标 CPU 指令集;注意源码中 NativeImageOptions.java 标记了旧的 -march 相关历史选项已废弃并建议改用 -march=native。
限制构建并行度(降低构建期 CPU 与内存峰值):
native-image --parallelism=4 <class>
默认并行度取决于机器核数,构建器会按此参数调度分析、编译等阶段的线程池。
调试与诊断:符号、详细日志与构建报告
在二进制中嵌入调试符号:
native-image -g <class>
-g 生成 DWARF 调试信息,配合 GDB 调试原生二进制;配套的 -g1 提供精简符号。仓库 debug 目录包含 GDB Python 辅助脚本,可参考 gdbpy 中的集成方式。
详细构建输出:
native-image --verbose <class>
打印构建各阶段(分析、编译、链接)的详细日志,用于观察耗时分布。
检查类初始化与替换(substitution):
native-image --diagnostics-mode <class>
输出类初始化顺序、替换类等内部诊断信息。
生成详细的 HTML 构建报告:
native-image --emit build-report <class>
# 或: --emit build-report=report.html
构建报告包含镜像内容、包大小、类初始化状态、可达性元数据使用情况等,是分析镜像构成的利器。--emit 还可配合 analysis、embedded-resources 等选项输出多种产物。
追踪某个类的实例化(定位镜像堆中对象的来源):
native-image --trace-object-instantiation=com.example.MyClass <class>
对应源码中的 TraceObjectInstantiation 选项(见 SubstrateOptions.java),会为指定类打印每个实例的创建栈,常用于排查意外被固化进镜像堆的对象。
网络支持:用可达性元数据注册 URL 协议处理器
如果生成的二进制需要 HTTP/HTTPS 等 JDK URL 协议处理器,需要通过反射元数据注册对应的 Handler 类,例如在 reflect-config.json 中:
{
"reflection": [
{
"type": "sun.net.www.protocol.http.Handler",
"methods": [{"name": "<init>", "parameterTypes": []}]
},
{
"type": "sun.net.www.protocol.https.Handler",
"methods": [{"name": "<init>", "parameterTypes": []}]
}
]
}
源码证据(见 SubstrateOptions.java):--enable-http、--enable-https、--enable-url-protocols 三个选项已被标记为 deprecated,官方 deprecation 消息明确建议"Use reachability metadata instead"(改用可达性元数据)。file: 与 resource: 等默认协议不需要额外注册。因此新代码应直接采用上述 JSON 元数据方式。
监控与可观测性:堆转储、JFR 与线程转储
需要运行期监控能力(堆转储、JFR 事件、线程转储):
native-image --enable-monitoring=heapdump,jfr,threaddump <class>
该选项定义于 VMInspectionOptions.java,内部支持 heapdump、jfr、threaddump 等监控器名称,默认值为 jfr。启用后二进制可通过 jcmd(对应 com.oracle.svm.jdwp.bridge 等桥接组件)或 HTTP 端点触发堆转储、录制 JFR 事件流、导出线程转储。注意监控功能会引入少量运行期开销,仅按需启用对应项。
安全与合规:安全服务类
需要全部安全服务(如完整 TLS/SSL 提供方集合):
native-image --enable-all-security-services <class>
注意源码中该选项同样被标记为 deprecated(见 SubstrateOptions.java),deprecation 注释为 "Add all security service classes to the generated image."。原因是全量打包安全服务会显著增大镜像体积,更推荐通过可达性元数据按需注册实际使用的安全提供方,保持镜像精简。
交叉编译与平台:目标平台与自定义 C 编译器
为不同 OS/架构交叉编译:
native-image --target=linux-aarch64 <class>
--target(见 SubstrateOptions.java)指定目标三元组,例如 linux-aarch64、darwin-aarch64 等,构建器会调用对应平台的交叉工具链(需要预先安装)。
指定自定义 C 编译器:
native-image --native-compiler-path=/usr/bin/gcc <class>
Native Image 构建产物由 Graal 编译器生成 C 源码后交给本机工具链链接,该选项直接指定使用的编译器可执行文件路径,便于使用自定义工具链或交叉编译器。
信息与发现:查询构建环境与可用能力
列出可用 CPU 特性:
native-image --list-cpu-features
输出当前 JVM 宿主机器可用的 CPU 特性集合,用于判断 -march=native 会启用哪些指令集。
列出可观察模块:
native-image --list-modules
列出构建器视角下可观察到的 Java 模块,排查模块路径配置问题。
查看本机工具链与构建设置:
native-image --native-image-info
输出 native-image 版本、JVM 信息、工具链(编译器、链接器)路径与版本等,是提交 bug 报告或排查环境问题时的第一手信息,对应源码中的 native-image-info API 选项(见 SubstrateOptions.java)。
快速参考:常用选项一览
| 场景 | 命令片段 |
|---|---|
| 指定类路径 | -cp <path1>:<path2> <class> |
| 使用模块 | -p <module-path> --add-modules <module> <class> |
| 类延迟到运行期初始化 | --initialize-at-run-time=com.example.LazyClass |
| 类在构建期初始化 | --initialize-at-build-time=com.example.EagerClass |
| 构建期完整链接类型 | --link-at-build-time <class> |
| 构建器堆扩容 | -J-Xmx8g |
| 缺失元数据精确报错 | --exact-reachability-metadata / --exact-reachability-metadata-path=<path> |
| 重命名产物 | -o myapp |
| 共享库 | --shared |
| 完全静态(仅 Linux + musl) | --static --libc=musl |
| 静态但保留动态 libc | --static-nolibc |
| 最快构建 | -Ob |
| 最佳运行性能 | -O3 |
| 体积优先 | -Os |
| 换 GC | --gc=epsilon / --gc=serial / --gc=G1 / --gc=Z |
| 本机 CPU 特性 | -march=native |
| 跨机器兼容 | -march=compatibility |
| 限制构建并行度 | --parallelism=4 |
| 调试符号 | -g |
| 详细日志 | --verbose |
| 类初始化诊断 | --diagnostics-mode |
| HTML 构建报告 | --emit build-report |
| 追踪对象实例化 | --trace-object-instantiation=com.example.MyClass |
| 运行期监控 | --enable-monitoring=heapdump,jfr,threaddump |
| 全部安全服务 | --enable-all-security-services(已弃用) |
| 交叉编译 | --target=linux-aarch64 |
| 自定义 C 编译器 | --native-compiler-path=/usr/bin/gcc |
| 查询 CPU 特性 | --list-cpu-features |
| 查询可观察模块 | --list-modules |
| 工具链与构建信息 | --native-image-info |
结语
native-image 的 CLI 选项体系围绕"构建期(build-time)"与"运行期(run-time)"两个世界展开:类路径/模块决定构建器如何发现代码,类初始化策略决定静态状态何时固化,可达性元数据决定动态特性如何被静态分析感知,优化级别决定镜像性能与体积的平衡,诊断选项则让构建黑盒变得可观测。本文所有选项均可通过 native-image --help、native-image --help-extra 进一步查阅,其权威定义与校验逻辑统一收敛在 SubstrateVM 的 SubstrateOptions.java 与 VMInspectionOptions.java 等源码文件中,遇到选项行为不符预期时,直接阅读对应 @APIOption 定义与 doc-files 帮助文本是最准确的排查方式。
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



