命令行选项

配置 Native Image 的选项分为以下几类

构建选项：运行 native-image --help 以获取有关构建选项的帮助。
额外构建选项：运行 native-image --help-extra 以获取有关额外构建选项的帮助。
专家构建选项：运行 native-image --expert-options 以获取有关专家选项的帮助。

根据 GraalVM 版本，native-image 构建器的选项可能有所不同。

Native Image 选项也可以分为托管选项或运行时选项。

托管选项：用于配置构建过程，例如，影响原生二进制文件中包含的内容以及其构建方式。这些选项使用前缀 -H:。
运行时选项：用于在构建原生二进制文件时提供初始值，使用前缀 -R:。在运行时，默认前缀是 -XX:（这是应用程序特定的，并非 Native Image 强制要求）。

有关如何定义和使用这些选项的更多信息，请阅读 com.oracle.svm.core.option 包文档。

构建选项 #

运行 native-image --help 以获取有关构建选项的帮助。

-cp, -classpath, --class-path <class search path of directories and ZIP/JAR files>：以 :（Windows 上为 ;）分隔的目录、JAR 归档和 ZIP 归档列表，用于搜索类文件
-p <module path>, --module-path <module path>：以 :（Windows 上为 ;）分隔的目录列表。每个目录都是一个模块目录。
--add-modules <module name>[,<module name>...]：除了初始模块外，还要添加要解析的根模块。<module name> 也可以是 ALL-DEFAULT、ALL-SYSTEM、ALL-MODULE-PATH。
-D<name>=<value>：设置系统属性
-J<flag>：将选项直接传递给运行 native-image 构建器的 JVM
--diagnostics-mode：启用诊断输出：类初始化、替换等。
--enable-preview：允许类依赖于此版本的预览功能
--enable-native-access <module name>[,<module name>...]：启用允许执行受限原生操作的模块。<module name> 也可以是 ALL-UNNAMED
--verbose：启用详细输出
--version：打印产品版本并退出
--help：打印此帮助信息
--help-extra：打印非标准选项的帮助
--auto-fallback：如果可能，构建一个独立的可执行文件
--color：彩色构建输出（always、never 或 auto）
--configure-reflection-metadata：启用未调用方法的反射对象的运行时实例化
--emit：作为构建结果发出额外数据。使用 build-report 发出详细的构建报告，例如：--emit build-report 或 --emit build-report=report.html
--enable-all-security-services：将所有安全服务类添加到生成的原生可执行文件
--enable-http：在原生可执行文件中启用 HTTP 支持
--enable-https：在原生可执行文件中启用 HTTPS 支持
--enable-monitoring：启用监控功能，允许在运行时检查 VM。逗号分隔的列表可以包含 heapdump、jfr、jvmstat、jmxserver（实验性）、jmxclient（实验性）、threaddump 或 all（已弃用行为：如果未提供参数，则默认为 all）。例如：--enable-monitoring=heapdump,jfr。
--enable-sbom：将软件物料清单（SBOM）嵌入到可执行文件或共享库中，以进行被动检查。逗号分隔的列表可以包含 cyclonedx、strict（如果未提供参数，则默认为 cyclonedx）或 export，用于将 SBOM 保存到原生可执行文件的输出目录。可选的 strict 标志会在任何类无法与 SBOM 中的库匹配时中止构建。例如：--enable-sbom=cyclonedx,strict。（GraalVM Community Edition 中不可用。）
--enable-url-protocols：列出要启用的逗号分隔的 URL 协议
--exact-reachability-metadata：启用对反射、资源、JNI 和序列化的精确且用户友好的处理
--exact-reachability-metadata-path：从给定类路径或模块路径条目中的所有类型触发对反射、资源、JNI 和序列化的精确处理
--features：逗号分隔的完全限定 Feature 实现类列表
--force-fallback：强制构建一个回退原生可执行文件
--gc=<value>：选择 Native Image 垃圾回收器实现。<value> 允许的选项有：G1 用于 G1 垃圾回收器（GraalVM Community Edition 中不可用）；epsilon 用于 Epsilon 垃圾回收器；serial 用于串行垃圾回收器（默认）。
--initialize-at-build-time：在原生可执行文件生成期间初始化的包和类（以及隐式地所有其超类）的逗号分隔列表。空字符串表示所有包。
--initialize-at-run-time：必须在运行时而非生成期间初始化的包和类（以及隐式地所有其子类）的逗号分隔列表。当前不支持空字符串。
--install-exit-handlers：提供 java.lang.Terminator 退出处理器
--libc：选择要使用的 libc 实现。可用的实现有 glibc、musl、bionic。
--link-at-build-time：要求类型在原生可执行文件构建时完全定义。如果不带参数使用，则选项范围内所有类都必须完全定义。
--link-at-build-time-paths：要求给定类或模块路径条目中的所有类型在原生可执行文件构建时完全定义
--list-cpu-features：显示目标平台特定的 CPU 特性并退出
--list-modules：列出可观察模块并退出
--native-compiler-options：提供用于查询代码编译的自定义 C 编译器选项
--native-compiler-path：提供用于查询代码编译和链接的自定义 C 编译器路径
--native-image-info：显示原生工具链信息和可执行文件的构建设置
--no-fallback：构建一个独立的原生可执行文件或报告失败
--parallelism：指定在原生可执行文件生成期间并发使用的最大线程数
--pgo：提供一个逗号分隔的文件列表，从中读取为 AOT 编译代码的配置文件引导优化收集的数据（如果未指定，则从 default.iprof 读取）。每个文件必须包含一个以 JSON 格式序列化（可选地由 gzip 压缩）的 PGOProfiles 对象。（GraalVM Community Edition 中不可用。）
--pgo-instrument：检测 AOT 编译的代码，将配置文件引导优化的数据收集到 default.iprof 文件中。（GraalVM Community Edition 中不可用。）
--pgo-sampling：通过对 AOT 编译代码进行采样来执行分析，以收集用于配置文件引导优化的数据。（GraalVM Community Edition 中不可用。）
--shared：构建共享库
--silent：静默构建输出
--static：构建静态链接的可执行文件（需要 libc 和 zlib 静态库）
--static-nolibc：构建静态链接的可执行文件，其中 libc 动态链接
--target：选择 native-image 的编译目标（采用 <OS>-<architecture> 格式）。默认为主机的操作系统-架构对。
--trace-object-instantiation：提供一个逗号分隔的完全限定类名列表，用于跟踪对象实例化
-O<level>：控制代码优化，可用变体有：b - 优化以实现最快的构建时间，s - 优化以减小大小，0 - 无优化，1 - 基本优化，2 - 激进优化，3 - 所有优化以实现最佳性能（通过配置文件引导优化 (PGO) 自动启用）
-da, -da[:[packagename]|:[classname], disableassertions[:[packagename]|:[classname]：在运行时以指定粒度禁用断言
-dsa, -disablesystemassertions：在运行时禁用所有系统类中的断言
-ea, -ea[:[packagename]|:[classname], enableassertions[:[packagename]|:[classname]：在运行时以指定粒度启用断言
-esa, -enablesystemassertions：在运行时启用所有系统类中的断言
-g：生成调试信息
-march：为特定机器类型生成指令。在 AMD64 上默认为 x86-64-v3，在 AArch64 上默认为 armv8-a。如果原生可执行文件部署在同一台机器或具有相同 CPU 特性的机器上，请使用 -march=compatibility 以获得最佳兼容性，或使用 -march=native 以获得最佳性能。要列出所有可用的机器类型，请使用 -march=list。
-o：要生成的输出文件的名称

额外构建选项 #

运行 native-image --help-extra 以获取有关附加选项的帮助。

--exclude-config：排除类路径/模块路径模式和资源模式的空格分隔对的配置。例如：--exclude-config foo.jar META-INF\/native-image\/.*.properties 将忽略所有名为 foo.jar 的 JAR 文件中 META-INF/native-image 下的所有属性文件。
--expert-options：列出专家图像构建选项
--expert-options-all：列出所有专家图像构建选项（风险自负）。标有 Extra help available 的选项包含可以使用 --expert-options-detail 显示的帮助。
--expert-options-detail：显示逗号分隔的选项名称列表的所有可用帮助。传递 * 以显示所有包含该内容的选项的额外帮助。
--configurations-path <search path of option-configuration directories>：一个分隔的目录列表，这些目录将被视为选项配置目录。
--debug-attach[=<port or host:port (* can be used as host meaning bind to all interfaces)>]：在原生可执行文件生成期间附加到调试器（默认端口为 8000）
--diagnostics-mode：启用将图像构建信息记录到诊断目录。
--dry-run：输出用于构建的命令行
--bundle-create[=new-bundle.nib]：除了图像构建外，创建一个原生图像捆绑文件 (*.nibfile)，允许稍后再次重新构建该图像。如果传递了捆绑文件，则将使用给定名称创建捆绑包。否则，捆绑文件名称将从图像名称派生。请注意，这两个捆绑选项都可以通过 dry-run 和 container 进行扩展。
- dry-run：仅执行捆绑操作，而不进行任何实际的原生可执行文件构建
- container：设置容器镜像并在该容器内执行原生可执行文件生成。需要安装 Podman 或无根 Docker。如果可用，Podman 是首选，无根 Docker 是备用方案。将其中一个指定为 =<container-tool> 会强制使用特定工具。
- dockerfile=<Dockerfile>：使用用户提供的 Dockerfile，而不是基于适用于 GraalVM 的 Oracle Linux 8 基础镜像的默认 Dockerfile
--bundle-apply=some-bundle.nib[,dry-run][,container[=<container-tool>][,dockerfile=<Dockerfile>]]：将从给定捆绑文件构建图像，使用与最初传递给 Native Image 以创建捆绑包的完全相同的参数和文件。请注意，如果在 --bundle-apply 之后额外传递 --bundle-create，则将根据给定捆绑参数以及之后传递的任何附加参数写入新捆绑包。例如：native-image --bundle-apply=app.nib --bundle-create=app_dbg.nib -g 会基于给定 app.nib 捆绑包创建一个新的捆绑包 app_dbg.nib。两个捆绑包相同，只是新的捆绑包也使用了 -g 选项。
-E<env-var-key>[=<env-var-value>]：允许 Native Image 在原生可执行文件生成期间访问给定环境变量。如果未提供可选的 <env-var-value>，则环境变量的值将取自调用 Native Image 的环境。
-V<key>=<value>：为 native-image.properties 文件中的占位符提供值
--add-exports：值 <module>/<package>=<target-module>(,<target-module>) 会更新 <module> 以将 <package> 导出到 <target-module>，无论模块声明如何。<target-module> 可以是 ALL-UNNAMED 以导出到所有未命名模块
--add-opens：值 <module>/<package>=<target-module>(,<target-module>) 会更新 <module> 以向 <target-module> 开放 <package>，无论模块声明如何
--add-reads：值 <module>=<target-module>(,<target-module>) 会更新 <module> 以读取 <target-module>，无论模块声明如何。<target-module> 可以是 ALL-UNNAMED 以读取所有未命名模块

有用选项列表 #

有些专家级选项用户可能会觉得有用或需要。例如，用于转储 native-image 构建器图形的选项，或者在构建过程中打印各种统计信息。

构建输出和构建报告 #

Native Image 提供信息丰富的构建输出，包括构建过程中的各种统计信息。可以使用 -H:BuildOutputJSONFile 选项请求 JSON 格式的机器可读构建输出，然后由监控工具处理。JSON 文件根据 build-output-schema-v0.9.3.json 中定义的 JSON 模式进行验证。可以使用 --emit build-report 选项请求包含附加信息的综合报告。

注意：--emit build-report 选项在 GraalVM Community Edition 中不可用。

图形转储 #

Native Image 重用了 GraalVM 调试环境中用于图形转储、日志记录、计数器以及所有其他功能的选项。这些 GraalVM 选项既可以作为托管选项（如果您想转储 native-image 构建器的图形），也可以作为运行时选项（如果您想在运行时动态编译期间转储图形）使用。

正常工作的 Graal 编译器选项包括 Dump、DumpOnError、Log、MethodFilter，以及为转储处理器指定文件名和端口的选项。例如

-H:Dump= -H:MethodFilter=ClassName.MethodName：转储 native-image 构建器的编译器图形。
-XX:Dump= -XX:MethodFilter=ClassName.MethodName：在运行时转储编译图形。

系统属性 #

您可以使用 -D<system.property>=<value> 选项语法在图像构建时定义系统属性。它为 native-image 工具设置系统属性，但该属性不会包含在生成的运行时可执行文件中。但是，JDK 系统属性会包含在生成的运行时可执行文件中并在运行时可见。

例如

-D<system.property>=<value> 将仅在构建时可见。如果原生可执行文件中访问此系统属性，它将返回 null。
-Djava.version=24 将在构建时和原生可执行文件中都可见，因为该值默认会复制到二进制文件中。

以下系统属性会自动复制到生成的运行时可执行文件中

名称	描述
file.separator	文件分隔符
file.encoding	默认语言环境的字符编码
java.version	Java 运行时环境版本
java.version.date	发布的通用可用 (GA) 日期
java.class.version	Java 类格式版本号
java.runtime.version	Java 运行时环境版本
java.specification.name	Java 运行时环境规范名称
java.specification.vendor	Java 运行时环境规范供应商
java.specification.version	Java 虚拟机规范版本
java.vm.specification.name	Java 虚拟机规范名称
java.vm.specification.vendor	Java 虚拟机实现供应商
java.vm.specification.version	Java 虚拟机规范版本
line.separator	行分隔符
native.encoding	指定主机环境的字符编码
org.graalvm.nativeimage.kind	指定图像是作为共享库还是可执行文件构建
path.separator	路径分隔符
stdout.encoding	指定 `System.out` 和 `System.err` 的编码
sun.jnu.encoding	指定解析通过命令行传递的值时的编码