GraalVM Native Image 构建输出（Build Output）完全解读：从构建阶段到机器可读报告

• 编译器
• JIT编译
• 语言运行时
• 高性能计算
• 内存管理

GraalVM Native Image 在构建原生可执行文件时，会在终端输出一份结构化的构建日志。本指南以 GraalVM 官方文档 BuildOutput.md 为核心，逐段解读这份日志的每个字段——从 8 个构建阶段、安全报告、优化建议、资源统计、构建产物，到机器可读的 JSON 输出与 PGO 性能剖析文件格式，并结合仓库中的源码（如 ProgressReporter.java 与 SubstrateOptions.java）验证其实现。读完本文，你将能够看懂任何一次 native-image 构建日志，并能利用-H:BuildOutputJSONFile与构建报告把构建过程接入 CI/CD 监控与调优工作流。

文中所展示的示例输出为构建一个HelloWorld类对应的原生可执行文件（helloworld）时的完整日志，下文将逐行拆解。

================================================================================ GraalVM Native Image: Generating 'helloworld' (executable)... ================================================================================ [1/8] Initializing... (4.4s @ 0.29GiB) Builder configuration: - Java version: 26+13, vendor version: Oracle GraalVM 26-dev+13.1 - Graal compiler: optimization level: 2, target machine: x86-64-v3, PGO: ML-inferred - C compiler: gcc (linux, x86_64, 13.3.0) - Assertions: enabled, system assertions: enabled - 1 user-specific feature(s): - com.oracle.svm.thirdparty.gson.GsonFeature Image configuration: - Garbage collector: Serial GC (max heap size: 80% of RAM) - Assertions: disabled (class-specific config may apply), system assertions: disabled -------------------------------------------------------------------------------- Build resources: - 30.00GiB of memory (48.0% of system memory, capped at 30GiB) - 32 thread(s) (88.9% of 36 available processor(s), determined at start) [2/8] Performing analysis... [*******] (3.7s @ 0.58GiB) 2,140 types, 1,939 fields, and 8,997 methods found reachable 775 types, 35 fields, and 244 methods registered for reflection 49 types, 35 fields, and 48 methods registered for JNI access 52 resource accesses registered with 107B total size 4 native libraries: dl, pthread, rt, z [3/8] Building universe... (0.9s @ 0.74GiB) [4/8] Parsing methods... [*] (1.6s @ 0.72GiB) [5/8] Inlining methods... [***] (0.5s @ 0.66GiB) [6/8] Compiling methods... [***] (9.9s @ 0.81GiB) [7/8] Laying out methods... [*] (1.1s @ 0.67GiB) [8/8] Creating image... [**] (2.5s @ 0.90GiB) 2.86MiB (21.13%) for code area: 4,078 compilation units 3.56MiB (26.33%) for image heap: 63,478 objects and 1 resource 6.01MiB (44.40%) for debug info generated in 0.4s 7.11MiB (52.55%) for other data 13.53MiB in total image size, 6.88MiB in total file size -------------------------------------------------------------------------------- Top 10 origins of code area: Top 10 object types in image heap: 342.94KiB java.base/java.util 820.99KiB byte[] for string data 289.94KiB java.base/java.lang 750.97KiB byte[] for code metadata 270.50KiB o.g.n.~e/c.o.svm.core.code 347.48KiB java.base/java.lang.String 189.67KiB o.g.n.~e/c.o.s.genscavenge 217.34KiB o.g.n.~e/c.o.s.c.h.Dyna~anion 129.09KiB java.base/j.util.concurrent 209.51KiB java.base/java.lang.Class 83.00KiB o.g.n.~e/c.o.s.c.j.functions 184.75KiB java.base/j.u.HashMap$Node 81.76KiB java.base/java.util.stream 115.53KiB java.base/char[] 76.73KiB o.g.n.~e/com.oracle.svm.core 107.66KiB java.base/j.i.u.SoftR~nceKey 60.32KiB o.g.n.~e/c.o.svm.core.thread 105.09KiB java.base/java.lang.Object[] 58.18KiB o.g.n.~e/c.o.svm.graal.stubs 88.63KiB java.base/j.u.c.Concu~p$Node 1.25MiB for 119 more packages 700.05KiB for 585 more object types Use '--emit build-report' to create a report with more details. -------------------------------------------------------------------------------- Security report: - Binary includes Java deserialization. - CycloneDX SBOM with 5 component(s) is embedded in binary (406B). 6 type(s) could not be associated to a component. - Advanced obfuscation not enabled; enable with '-H:AdvancedObfuscation=""' (experimental support). -------------------------------------------------------------------------------- Recommendations: G1GC: Use the G1 GC ('--gc=G1') for improved latency and throughput. PGO: Use Profile-Guided Optimizations ('--pgo') for improved throughput. FUTR: Use '--future-defaults=all' to prepare for future releases. HEAP: Set max heap for improved and more predictable memory usage. CPU: Enable more CPU features with '-march=native' for improved performance. -------------------------------------------------------------------------------- 1.3s (4.8% of total time) in 88 GCs | Peak RSS: 2.14GiB | CPU load: 18.03 -------------------------------------------------------------------------------- Build artifacts: /home/janedoe/helloworld/gdb-debughelpers.py (debug_info, 80.60KiB) /home/janedoe/helloworld/helloworld (executable, 6.88MiB) /home/janedoe/helloworld/helloworld.debug (debug_info, 6.66MiB) /home/janedoe/helloworld/sources (debug_info, 37.61MiB) ================================================================================ Finished generating 'helloworld' in 25.5s.

Build Stages（构建阶段）

构建过程被划分为 8 个编号阶段，从[1/8]到[8/8]，每个阶段行尾的括号依次展示该阶段耗时与构建进程的堆内存占用（例如(4.4s @ 0.29GiB)表示耗时 4.4 秒、峰值堆约 0.29 GiB）。进度指示器（如[*******]）用于可视化各阶段的迭代进度。

Initializing（初始化）

本阶段完成 Native Image 构建进程的初始化，并初始化Feature（构建期钩子，可用于注册反射、资源、JNI 等元数据）。此阶段还会打印出Builder configuration（构建器配置）与Image configuration（镜像配置）两大块信息，具体字段如下。

Native Image Kind（镜像类型）

默认情况下 Native Image 生成的是可执行文件（executables），但也可以生成 原生共享库（通过--shared）与 静态可执行文件。示例中Generating 'helloworld' (executable)即标明本次生成的是可执行文件。

Java Version Info（Java 版本信息）

显示 Native Image 构建进程自身的 Java 与 vendor 版本，例如Java version: 26+13, vendor version: Oracle GraalVM 26-dev+13.1。这两个值同样会被写入生成的原生二进制内的java.vm.version与java.vendor.version属性中。如果构建遇到问题需要上报，请附上版本与 vendor 信息。

Graal Compiler（Graal 编译器）

展示 Graal 编译器选用的优化级别与目标机器类型：

• 优化级别可用-O控制，默认值为2，开启激进优化；-Ob为快速构建模式，可显著加快编译阶段（适合开发期）；-Os以体积为目标进行优化。
• 目标机器类型用-march选择，AMD64 默认x86-64-v3，AArch64 默认armv8-a。更激进的用法见下文 CPU 建议。

在 Oracle GraalVM 上，该行还会附带 Profile-Guided Optimization (PGO) 状态：

• off：未使用 PGO；
• instrument：生成的可执行文件/共享库已插桩以收集 PGO 数据（--pgo-instrument）；
• user-provided：PGO 已启用并使用用户提供的剖析文件（例如--pgo default.iprof）；
• ML-inferred：使用机器学习（ML）模型静态推断控制流分裂分支的 profile（示例输出中的PGO: ML-inferred即为此模式）。

C Compiler（C 编译器）

显示构建过程使用的 C 编译器可执行文件、厂商、目标架构与版本，例如gcc (linux, x86_64, 13.3.0)。Native Image 在链接阶段需要依赖系统 C 工具链。

Assertions in the Builder（构建器中的断言）

指明 Native Image Builder 进程是否启用了 Java 断言与系统断言。启用断言有助于 GraalVM 团队定位和调试 Builder 自身的问题（示例中为Assertions: enabled, system assertions: enabled）。

User-Specific Features（用户特定 Feature）

列出所有由用户提供或显式启用、或由框架隐式代为注册的Feature。GraalVM Native Image 内部的 Feature 不在此列。示例中展示了com.oracle.svm.thirdparty.gson.GsonFeature，即由 Gson 库自动注册的构建期 Feature。

Garbage Collector（垃圾收集器）

指明生成的可执行文件中使用的 GC：

• Serial GC：默认 GC，面向低内存占用与较小 Java 堆场景优化；
• G1 GC（GraalVM Community Edition 不可用）：多线程 GC，通过减少 stop-the-world 停顿来改善延迟并保持高吞吐；
• Epsilon GC：不执行任何垃圾回收，面向运行时间极短、分配内存极少的应用。

更多细节见 Memory Management（内存管理）。示例中显示Serial GC (max heap size: 80% of RAM)。

Maximum Heap Size（最大堆大小）

默认情况下，堆大小被限制为系统内存的某个百分比，允许 GC 按自身策略自由分配内存。可在运行可执行文件时通过-Xmx限制最大堆（例如./myapp -Xmx64m），以获得更低且更可预测的内存占用，某些情况下还能改善延迟；也可以在构建时用-R:MaxHeapSize预配置最大堆大小。

Assertions in the Generated Image（生成镜像中的断言）

显示生成镜像中配置的 hosted Java 断言默认值：

• 构建期初始化的类始终使用这些默认值；
• 使用-H:-StrictRuntimeJavaOptions构建时，运行时初始化的镜像类也使用构建期选项，而运行时加载的类无条件禁用断言；
• 使用-H:+StrictRuntimeJavaOptions构建时，运行时初始化的镜像类与运行时加载的类，其断言状态由运行时-ea、-da、-esa、-dsa选项决定。

启用断言有助于发现并调试内置到镜像中的 Java 代码问题。

Experimental Options（实验性选项）

列出所有生效的实验性选项，包括其来源以及可用的 API 选项替代方案（若存在）。实验性选项应避免在生产环境中使用，它们可能在任何版本中变化；如果某项实验特性对你至关重要，请提交 issue 推动其转正。

Picked upNATIVE_IMAGE_OPTIONS

列出通过NATIVE_IMAGE_OPTIONS环境变量拾取的额外构建选项。该变量与JAVA_TOOL_OPTIONS类似，其值会以前缀形式附加到native-image命令行选项之前；不允许通过该环境变量传递参数文件。它面向用户、构建环境或工具注入额外构建选项而设计。在源码中，其常量定义于 SubstrateOptions.java（NATIVE_IMAGE_OPTIONS_ENV_VAR = "NATIVE_IMAGE_OPTIONS"）。

Build Resources（构建资源）

展示构建进程的内存限制与线程数（示例：30.00GiB of memory (48.0% of system memory, capped at 30GiB)与32 thread(s)）。几点关键说明：

• 该内存限制指的是Java 堆上限，实际内存消耗可能更高；请结合构建末尾的 peak RSS 判断真实内存占用。实际消耗也可能低于限制，因为 GC 只会按需提交内存。
• 默认内存策略：在容器或 CI 环境（$CI环境变量设为true）中使用dedicated 模式（使用系统内存的 85%，但不超过 30GiB）；否则使用shared 模式（尽量利用可用内存，避免对开发者机器造成内存压力）。若系统可用内存不足 8GiB，则回退到 dedicated 模式。构建时机器缓慢可考虑释放内存（如关闭不用的应用）。
• 可用-J-XX:MaxRAMPercentage=60.0或-J-Xmx16g设置相对/绝对内存上限；-J-Xms9g可保证一个最小限制（若已知构建至少需要这么多内存）。
• 默认使用所有可用处理器以最大化速度，但不超过 32 个线程；可用--parallelism=4显式指定线程数。减少线程数可降低系统负载与内存消耗（代价是构建变慢）。

Performing Analysis（执行分析）

本阶段执行 points-to analysis（指针分析），进度指示器可视化分析迭代次数。迭代次数异常庞大通常意味着分析存在问题，很可能是配置错误或某个 Feature 行为异常。本阶段还会打印以下统计：

• Reachable Types, Fields, and Methods（可达类型/字段/方法）：静态分析发现的可达类型（原始类型、类、接口、数组）、字段与方法数量。该指标反映应用规模大小，非常适合在合并代码改动、增删或升级依赖前后对比，以量化改动对二进制大小的影响。可达元素越多，原生二进制通常越大。示例：2,140 types, 1,939 fields, and 8,997 methods found reachable。
• Reflection Registrations（反射注册数）：注册给反射使用的类型、字段与方法数量。数量过大会带来明显的反射开销、拖慢构建并增大二进制体积（反射元数据见下文 Reflection Metadata）。
• JNI Access Registrations（JNI 注册数）：注册给 JNI 访问的类型、字段与方法数量。
• Foreign Access Registrations（外呼/内呼注册数）：为 foreign function access（外部函数访问，FFM API） 注册的 downcall 与 upcall 数量。
• Runtime Compiled Methods（运行时编译方法数）：标记为运行时编译的方法数量。仅当可执行文件内置运行时编译能力（例如构建 Truffle 语言）时才显示。这些方法会对应堆中的 graph encodings。

Building Universe（构建 Universe）

构建包含所有类型、字段与方法的 universe，该 universe 随后用于生成原生二进制。

Parsing Methods（解析方法）

Graal 编译器解析所有可达方法，进度指示器以递增的时间间隔周期性打印。

Inlining Methods（内联方法）

执行平凡方法内联，进度指示器可视化内联迭代次数。

Compiling Methods（编译方法）

Graal 编译器将所有可达方法编译为机器码，进度指示器同样以递增间隔周期性打印。这也是-Ob快速构建模式重点加速的阶段。

Laying Out Methods（布局方法）

对已编译的方法进行布局。

Creating Image（创建镜像）

生成并写出原生二进制，调试信息（若请求）也在本阶段生成。该阶段会给出镜像体积的构成明细（如下），其中：

• 总镜像大小（total image size）：在链接之前计算，为代码区 + 镜像堆 + 调试信息（若请求并嵌入二进制）+ 其他数据之和；
• 总文件大小（total file size）：链接后镜像在磁盘上的实际大小。通常略小于镜像大小，因为链接期还有额外优化。示例中13.53MiB in total image size, 6.88MiB in total file size。

Code Area（代码区）

包含 Graal 编译器为所有可达方法生成的机器码。因此，减少可达方法数量即可缩减代码区大小。

Origins of Code Area（代码区来源）

为帮助用户理解机器码来源，输出会给出 Top 10 来源分解。一个 origin 是一组 Java 来源的集合，可以是 JAR 文件、包名或类名。例如java.base/java.util来自 JDK 基础模块；svm.jar、org.graalvm.nativeimage.base模块等 origin 包含 Native Image 运行时内部源码。基于该分解重新审视应用依赖可有效缩减代码区与整个可执行文件体积。注意：部分库/框架对 Native Image 的适配程度优于其他，新版本库的代码足迹可能改善也可能恶化。

Image Heap（镜像堆）

包含可达对象，如静态应用数据、元数据，以及用途各异的byte[]。示例中3.56MiB (26.33%) for image heap: 63,478 objects and 1 resource。输出右侧还会列出 Top 10 对象类型。镜像堆中的byte[]又细分为以下几类：

General Heap Data Stored inbyte[]

所有既不用于java.lang.String、也不属于 code metadata、reflection metadata 或 graph encodings 的byte[]对象总大小，因此也可能包含来自应用代码的byte[]。

Embedded Resources Stored inbyte[]

用于在原生二进制内存储资源（例如通过Class.getResource()访问的文件）的byte[]总大小，资源数量显示在堆（Image Heap）小节中。所有资源及其模块、名称、来源、大小等附加信息均收录在 构建报告 中；也可用-H:+GenerateEmbeddedResourcesFile以 JSON 格式输出，该 JSON 文件符合 embedded-resources-schema-v1.1.0.json 定义的 schema。

Code Metadata Stored inbyte[]

用于 代码区 元数据的byte[]总大小。因此减少可达方法数同样能缩减这部分元数据。

Reflection Metadata Stored inbyte[]

用于反射元数据（类型、字段、方法、构造器数据）的byte[]总大小。要减少反射元数据，应减少 注册给反射的元素数量。

Graph Encodings Stored inbyte[]

用于图编码的byte[]总大小，这些编码来自 运行时编译方法。因此减少这类方法即可缩减对应图编码体积。

Heap Alignment（堆对齐）

为所选 GC 对齐堆而预留的额外空间，也可能包含 GC 特有的数据结构。其大小只能通过更换垃圾收集器来影响。

Debug Info（调试信息）

生成的调试信息总大小（若启用）。示例：6.01MiB (44.40%) for debug info generated in 0.4s。

Other Data（其他数据）

二进制中既不属于代码区、也不属于堆、也不属于调试信息的数据量。这类数据通常包含 Native Image 的内部信息，不应占据主导地位（示例：7.11MiB (52.55%)）。

Security Report（安全报告）

本节在 GraalVM Community Edition 中不可用。

• Deserialization（反序列化）：指明原生可执行文件是否包含 Java 反序列化能力。若未包含，则攻击面更小，无法被基于 Java 反序列化的攻击利用。
• Software Bill of Material (SBOM)：指明是否组装了 SBOM 及其存储方式。存储格式包括：embed（嵌入二进制）、classpath（保存到类路径）、export（作为 JSON 构建产物输出）。SBOM 默认启用，默认embed；嵌入时显示其大小，组件数始终显示；可用--enable-sbom=false关闭。示例：CycloneDX SBOM with 5 component(s) is embedded in binary (406B)。未关联类型（unassociated types）：当某些类型（类、接口、注解）无法关联到 SBOM 组件时会显示；若这些类型存在漏洞，SBOM 扫描将无法检出。解决办法是在项目 POM 的 properties 或MANIFEST.MF中以标准格式声明正确的 GAV 坐标（Group ID、Artifact ID、Version）。当启用hashes选项时，会为 JAR 输入与 GraalVM 内部组件计算哈希；目录不计算。若启用hashes但部分组件无法计算哈希，会显示无哈希组件数量，可用以下命令列出它们：

jq '.components[] | select(.hashes == null)' /path/to/app.sbom.json

可通过 构建报告 查看已包含组件、其依赖与未关联类型；更多信息见 Native Image 中的软件物料清单（SBOM）。

• Advanced Obfuscation（高级混淆）：指明是否应用了高级混淆。混淆作用于应用代码与第三方依赖，但不作用于 JDK 与 Substrate VM 代码。被混淆的元素包括：模块/包/类名、方法名与源文件名（栈跟踪中可见）、字段名（堆转储中可见）。不被混淆的元素包括：受可达性元数据注册影响的名称、-H:Preserve保留代码中的名称、包含加载资源类的模块与包名、注解/lambda/代理的名称。可用-H:AdvancedObfuscation=export-mapping导出原始名到混淆名的映射文件，配合native-image-utils deobfuscate命令还原栈跟踪；构建报告 提供混淆统计（如类名与方法名的混淆百分比）。更多信息见 Native Image 中的高级混淆。提示：Native Image 通过移除 class 文件、激进优化与消除死代码来天然混淆二进制，高级混淆特性额外混淆符号名。
• Backwards-Edge Control-Flow Integrity (CFI)：可通过实验性-H:CFI=HW选项强制启用 CFI。目前仅适用于 Graal 为 Linux AArch64 编译的代码，利用指针认证码（PAC）保证函数返回地址的完整性。
• Software Control-Flow Integrity (CFI)：可通过实验性-H:CFI=SW_NONATIVE选项在软件层面强制启用 CFI。目前仅适用于 Graal 为 Linux AMD64 编译的代码，用于校验间接分支与方法返回的目标。

Recommendations（建议）

构建输出可能包含以下一条或多条建议，帮助你更好地使用 Native Image。

• FUTR: Use the Correct Semantics and Prepare for Future Releases：使用--future-defaults=all启用所有计划在未来 GraalVM 版本中成为默认值的特性。该选项通常不会影响程序行为，但能保证程序符合正确的执行语义，并抵御未来版本中的意外变化。
• AWT: Missing Reachability Metadata for Abstract Window Toolkit：分析发现镜像中包含了java.awt为应用收集此类元数据，否则应用很可能无法正常工作。若你的应用并非桌面应用（例如不直接使用 Swing/AWT），应重新评估 AWT 依赖是否真的必要。
• HOME: Setjava.homeWhen Running the Binary：分析检测到System.getProperty("java.home")的使用。为确保其返回有效值，运行二进制时传入-Djava.home=<path>；否则该调用将返回null。
• CPU: Enable More CPU Features for Improved Performance：构建进程发现你的 CPU 支持比当前启用更多的特性（如 AES、LSE）。若应用部署在相同或支持相同 CPU 特性的机器上，可考虑在构建时使用-march=native，让 Graal 编译器使用全部可用 CPU 特性，从而显著提升性能。可用-march=list列出所有可显式定位的机器类型。
• G1GC: Use G1 Garbage Collector for Improved Latency and Throughput：你的平台支持 G1 GC，可考虑构建时使用--gc=G1改善延迟与吞吐。更多信息见 Memory Management。追求最佳峰值性能时，还可结合 Profile-Guided Optimization。
• HEAP: Specify a Maximum Heap Size：参见上文 Maximum Heap Size 小节。
• PGO: Use Profile-Guided Optimization for Improved Throughput：考虑使用 PGO 优化应用的吞吐。它让 Graal 编译器在 AOT 编译时利用剖析信息（类似 JIT 运行时的效果）。步骤如下：
  1. 使用--pgo-instrument构建应用；
  2. 以代表性负载运行插桩应用，生成.iprof格式剖析文件；
  3. 重新构建并传入剖析信息：--pgo=<your>.iprof，生成优化版本。 参考指南：使用 Profile-Guided Optimization 优化原生可执行文件。追求最佳峰值性能时也可考虑 G1 垃圾收集器。
• QBM: Use Quick Build Mode for Faster Builds：开发期可考虑-Ob快速构建模式加速构建。它减少 Graal 编译器执行的优化数量，缩短 编译阶段 耗时；不仅对开发有用，还可能使生成的可执行文件更小。但请注意，由于优化减少，可执行文件的峰值吞吐可能较低。
• INIT: Use the Strict Image Heap Configuration：开始使用--strict-image-heap以精简配置并为未来 GraalVM 版本做准备（该版本将默认启用此模式）。该模式只要求存储在镜像堆中的类标记--initialize-at-build-time，从而有效减少构建期初始化所需的配置条目数量。迁移建议：从零开始引入构建期初始化，优先选择单个类（而非整个包）进行构建期初始化；迁移前务必把框架依赖升级到最新版本（它们可能也需要迁移）。注意：自 GraalVM for JDK 22 起，Native Image 默认启用--strict-image-heap。

Resource Usage Statistics（资源使用统计）

• Garbage Collections（垃圾回收）：所有 GC 花费的总时间、GC 总时间占进程总时间的百分比以及 GC 总次数。示例1.3s (4.8% of total time) in 88 GCs。大量 GC 或高 GC 耗时通常意味着系统处于内存压力之下；增加可用内存可缩短原生二进制构建时间。
• Peak RSS：操作系统报告的峰值常驻内存集大小。该值表示构建进程的最大内存消耗。可将其与 构建资源 中报告的内存限制对比：若余量充足且 GC 统计 无异常，可将系统总内存降至接近 peak RSS 的水平以降低运维成本。示例：Peak RSS: 2.14GiB。
• CPU load：进程使用的 CPU 时间除以进程总时间。示例CPU load: 18.03。增加 CPU 核数可缩短构建时间。

Build Artifacts（构建产物）

列出所有构建产物，包括生成的原生二进制，也可能包含附加库、C 头文件或调试信息。部分产物必须与原生二进制保持在同一位置，因为运行时需要它们。例如使用 AWT 的应用，构建过程还会输出 JDK 中的库与 shim 以提供兼容的 AWT 支持，这些库需与二进制一起复制分发。示例产物：

• gdb-debughelpers.py（debug_info，80.60KiB）—— GDB 调试辅助脚本；
• helloworld（executable，6.88MiB）—— 最终可执行文件；
• helloworld.debug（debug_info，6.66MiB）—— 调试信息文件；
• sources（debug_info，37.61MiB）—— 源码引用信息。

可使用-H:+GenerateBuildArtifactsFile让构建器以 JSON 格式输出机器可读的产物清单。该 JSON 文件符合 build-artifacts-schema-v0.9.0.json 定义的 schema（该 schema 包含每种产物类型的说明以及它们是否在运行时必需）。该选项在源码中定义为 SubstrateOptions.java 中的GenerateBuildArtifactsFile，默认产物文件名为build-artifacts.json。

Machine-Readable Build Output（机器可读构建输出）

native-image构建器的人类可读输出会随新版本演进，不应被工具解析。如需机器可读输出，请使用-H:BuildOutputJSONFile=<file.json>选项，让构建器以 JSON 格式输出构建信息，可用于构建监控工具。该 JSON 文件符合 build-output-schema-v0.9.4.json 定义的 schema；仅当构建成功时才生成该 JSON 文件。

在源码层面，该选项同样定义于 SubstrateOptions.java，类型为HostedOptionKey<AccumulatingLocatableMultiOptionValue.Paths>（可多次累积指定多个输出路径）；其在构建成功后的产物导出流程中，由 ProgressReporter.java 的createAdditionalArtifactsOnSuccess方法调用reportBuildOutput，将构建输出 JSON 以BUILD_INFO类型产物写入指定路径。

从 schema 文件 build-output-schema-v0.9.4.json 可以看出，JSON 输出包含四大顶层必填字段：

• general_info：构建过程的一般信息，含镜像文件名name、graalvm_version（已弃用，推荐用vendor_version/java_version代替）、java_version、vendor_version、graal_compiler（含optimization_level、march与 Oracle GraalVM 专属的pgo模式枚举instrument/user-provided/ML-inferred）、c_compiler、garbage_collector；
• analysis_results：分析结果，含types/fields/methods三组，每组又包含total（已弃用）、reachable、reflection、jni（未设置时为-1），方法组额外包含foreign_downcalls与foreign_upcalls；
• image_details：镜像统计，含total_bytes、code_area（bytes与compilation_units）、image_heap等；
• resource_usage：资源使用统计。

下面是一个在 CI/CD 构建管道中检查可达方法数是否超标的实际示例：

native-image -H:BuildOutputJSONFile=build.json HelloWorld # ... cat build.json | python3 -c "import json,sys;c = json.load(sys.stdin)['analysis_results']['methods']['reachable']; assert c < 12000, f'Too many reachable methods: {c}'" Traceback (most recent call last): File "<string>", line 1, in <module> AssertionError: Too many reachable methods: 12128

此例中可达方法数为 12128，超出了 12000 的阈值，管道因此失败退出——这正是把构建质量门槛纳入自动化流水线的典型用法。

Colorful Build Output（彩色构建输出）

默认情况下，当检测到合适的终端时，native-image构建器会为构建输出着色以提升可读性，同时遵循NO_COLOR、CI与TERM环境变量来检测颜色支持。如需显式控制，可用--color选项设置为always、never或auto（默认值）。

Related Documentation（相关文档）

• 构建原生共享库
• 构建静态链接或基本静态链接的原生可执行文件
• Feature（构建期钩子 SDK 文档）
• 与原生代码的互操作
• Native Image 中的 Java Native Interface (JNI)
• 内存管理
• Native Image 构建概览
• Native Image 构建配置

• 编译器
• JIT编译
• 语言运行时
• 高性能计算
• 内存管理