命令行选项

以下类别提供了用于配置 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 社区版中不可用。）
--enable-url-protocols：列出要启用的逗号分隔的 URL 协议
--features：一个逗号分隔的完全限定的 Feature 实现类列表
--force-fallback：强制构建一个回退原生可执行文件
--gc=<value>：选择要使用的 Native Image 垃圾收集器实现。<value> 的允许选项为：G1 用于 G1 垃圾收集器（GraalVM 社区版中不可用）；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 编译代码的 Profile-guided 优化收集的数据（如果未指定任何内容，则从 default.iprof 读取）。每个文件必须包含一个以 JSON 格式序列化、可选地用 gzip 压缩的 PGOProfiles 对象。（GraalVM 社区版中不可用。）
--pgo-instrument：对 AOT 编译代码进行检测，以收集用于 Profile-guided 优化的数据到 default.iprof 文件中。（GraalVM 社区版中不可用。）
--pgo-sampling：通过对 AOT 编译代码进行采样来执行分析，以收集用于 Profile-guided 优化的数据。（GraalVM 社区版中不可用。）
--shared：构建一个共享库
--silent：静默构建输出
--static：构建一个静态链接的可执行文件（需要 libc 和 zlib 静态库）
--static-nolibc：使用 libc 动态链接构建静态链接的可执行文件
--target：为 native-image 选择编译目标（以 <OS>-<architecture> 格式）。它默认为主机的 OS-体系结构对。
--trace-class-initialization：提供一个逗号分隔的完全限定的类名列表，这些类名用于跟踪类初始化
--trace-object-instantiation：提供一个逗号分隔的完全限定的类名列表，这些类名用于跟踪对象实例化
-O<level>：控制代码优化，其中可用变体为：b - 优化以获得最快的构建时间，s - 优化以获得最小的尺寸，0 - 不进行优化，1 - 基本优化，2 - 积极优化，3 - 所有优化以获得最佳性能（在使用 Profile-Guided 优化时自动启用）
-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。使用 -march=compatibility 以获得最佳兼容性，或者使用 -march=native 以获得最佳性能（如果原生可执行文件部署在同一台机器或具有相同 CPU 特性的机器上）。要列出所有可用的机器类型，请使用 -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 代替基于 Oracle Linux 8 GraalVM 基础镜像的默认 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_dbg.nib，基于给定的 app.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> 以将 <package> 打开到 <target-module>，无论模块声明如何。
--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 社区版中不可用。

图形转储 #

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: 在运行时转储编译图形。