GraalVM Native Image CLI 选项完全指南:从类路径配置到构建优化与诊断

GraalVM Native Image CLI 选项完全指南:从类路径配置到构建优化与诊断

【免费下载链接】graal GraalVM compiles applications into native executables that start instantly, scale fast, and use fewer compute resources 🚀 【免费下载链接】graal 项目地址: https://gitcode.com/gh_mirrors/gr/graal

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 帮助文本是最准确的排查方式。

【免费下载链接】graal GraalVM compiles applications into native executables that start instantly, scale fast, and use fewer compute resources 🚀 【免费下载链接】graal 项目地址: https://gitcode.com/gh_mirrors/gr/graal

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值