java-add-graalvm-native-image-support

GraalVM Native Image 支持

为 Java 项目添加 GraalVM Native Image 的唯一事实来源，不受框架限制。采用迭代方式：配置、构建、查看错误、修复、重新构建，直到原生构建成功且可执行文件运行正常。

详细内容位于 references/；仅加载项目所需的内容：

主题	文件
Maven / Gradle 原生插件设置	references/build-tools.md
可达性元数据和追踪 Agent	references/reachability-metadata.md
常见构建/运行时错误及修复方法	references/troubleshooting.md
Spring Boot（AOT、-Pnative、nativeCompile、build-image）	references/spring-boot.md
Quarkus	quarkus-native-and-container skill（移交）；简要说明见 references/quarkus.md
Micronaut	references/micronaut.md

第 1 步：分析项目

1. 构建工具：pom.xml（Maven）或 build.gradle / build.gradle.kts（Gradle）。如果存在，优先使用包装器（./mvnw、./gradlew）。
2. 根据依赖项/插件判断框架：
   • Spring Boot：spring-boot-starter-parent、spring-boot-maven-plugin 或 org.springframework.boot Gradle 插件
   • Quarkus：io.quarkus BOM/插件或 quarkus-* 依赖项
   • Micronaut：io.micronaut 父项/插件或 micronaut-* 依赖项
   • 其他情况为纯 Java
3. 现有原生配置：native-build-tools 插件、META-INF/native-image/、原生 profile、application.properties 中的原生键。
4. 工具链：运行 java -version 和 native-image --version。本地原生编译需要使用带有 native-image 的 GraalVM JDK 作为构建所用的 JDK。容器或 buildpack 构建（Spring Boot buildpacks 使用 bootBuildImage/spring-boot:build-image，Quarkus 容器构建）会在容器内编译，无需本地 GraalVM，只需容器运行时。检查项目的 Java 版本是否与已安装的 GraalVM 版本匹配。

如果框架是 Quarkus，请在此处停止，并移交给 quarkus-native-and-container skill。该框架中的容器构建无需本地 GraalVM。

范围与 JVM 基线

• 添加原生支持并不意味着可以升级 JDK、框架、库、构建工具或包装器。保留现有由 BOM/父项管理的版本和测试约定；如果需要通过更改版本解决原生兼容性问题，请先征求同意。
• 编辑前运行项目现有的 JVM 构建和测试。记录已有失败，不要通过降低检查要求来掩盖问题。添加原生支持时，确保 JVM 打包/运行路径仍可正常工作。
• 每次获准更改依赖项或框架后，继续原生构建前都要重新运行 JVM 基线。在 JVM 和原生路径上验证相同行为。
• 创建或更改 CI 工作流、添加原生 CI 作业或更改运行器资源前，请先征求同意。如果未请求更改 CI，请单独提供建议命令。

第 2 步：获取 GraalVM 工具链

• Oracle GraalVM（根据 GraalVM Free Terms and Conditions 免费使用）和 GraalVM Community Edition 构建版本都提供 native-image。使用与项目 Java 版本匹配的发行版（例如 GraalVM for JDK 21 或更高版本；Spring Boot 3.x/4.x 需要 Java 17+ 基线，参见 Spring 参考文档）。
• 可通过 SDKMAN（sdk list java，然后使用列表中的标识符运行 sdk install java <identifier>）、供应商下载或 graalvm/setup-graalvm 等 CI 操作进行安装。从供应商当前的下载页面选择版本，不要硬编码版本号。
• Linux 需要 C 工具链和 zlib 头文件（build-essential、zlib1g-dev）；macOS 需要 Xcode 命令行工具；Windows 需要 Visual Studio Build Tools。请查阅当前 GraalVM “Native Image prerequisites” 页面。

步骤 3：添加原生支持

按框架区分：

• Spring Boot：使用 Maven 时，spring-boot-starter-parent 只会在其 native 配置文件中管理原生插件的版本和配置，因此如果缺少 native-maven-plugin 和 spring-boot-maven-plugin，请将它们声明在 <build><plugins> 中（无需指定版本）；使用 Gradle 时，请在 org.springframework.boot 旁应用 org.graalvm.buildtools.native；自定义父级需要手动添加该插件。不要重复配置父级已提供的内容。请参阅 references/spring-boot.md。
• Quarkus：交由 quarkus-native-and-container 技能处理。
• Micronaut：通过 Micronaut 构建插件内置支持。请参阅 references/micronaut.md。
• 纯 Java（或任何没有框架插件的项目）：添加 GraalVM Native Build Tools 插件。请参阅 references/build-tools.md。运行时从 Maven Central（org.graalvm.buildtools:native-maven-plugin）或 Gradle Plugin Portal（org.graalvm.buildtools.native）解析插件版本，并将其固定在构建文件中；不要凭记忆填写版本。

步骤 4：构建

设置	命令
纯 Maven	./mvnw -Pnative native:compile
纯 Gradle	./gradlew nativeCompile
Spring Boot Maven	./mvnw -Pnative native:compile（或使用 spring-boot:build-image 构建容器）
Spring Boot Gradle	./gradlew nativeCompile（或 bootBuildImage）
Micronaut Maven	./mvnw package -Dpackaging=native-image
Micronaut Gradle	./gradlew nativeCompile

原生构建速度较慢且占用大量内存（数 GB RAM）。请捕获完整输出以便检查。

步骤 5：反复迭代，直到构建成功

1. 阅读第一个真正的错误，而不是最终摘要。
2. 对照 references/troubleshooting.md 检查。
3. 按以下优先顺序应用最小幅度的修复：
   1. 检查是否有兼容的库／框架版本内置了原生支持（请参阅 可达性元数据仓库）。提出升级建议；仅在用户批准后应用，并重新运行 JVM 基准。如果用户拒绝，则尝试与当前版本兼容的元数据或框架提示。
   2. 使用框架自身的机制（Spring RuntimeHints、Quarkus @RegisterForReflection、Micronaut @Introspected）。
   3. 使用跟踪 Agent 收集元数据（请参阅 references/reachability-metadata.md）。
   4. 在 src/main/resources/META-INF/native-image/<groupId>/<artifactId>/ 下手动编写元数据。
   5. 仅针对特定类调整初始化方式（--initialize-at-build-time / --initialize-at-run-time）。
4. 重新构建。重复上述过程，直到构建无错误地完成。

步骤 6：验证可执行文件

构建成功还不够：许多问题只有在运行时才会出现。

• 运行二进制文件并测试主要路径（HTTP 端点、数据库访问、序列化、资源加载、定时任务）。
• 如果框架支持，请运行原生测试（native:test、nativeTest、Quarkus @QuarkusIntegrationTest）。
• 仅当用户提出要求时，才对比启动时间和内存使用量与 JVM 运行的差异。
• 报告实际运行的命令、构建和运行是否成功，以及仍存在的警告。

注意事项

• 建议在 CI 中使用明确指定的 GraalVM 版本进行原生构建和原生测试；只有获得用户同意后，才添加或更改 CI。
• Mockito 默认的内联 mock maker 无法用于 native image（Mockito 5.0.0 发行说明）；原生测试请使用子类 mock maker。
• 除非有合理原因，否则不要在生产构建中保留 --report-unsupported-elements-at-runtime 或详细输出标志。

参考资料

• GraalVM Native Image 文档
• Native Build Tools
• GraalVM 可达性元数据仓库
• Spring Boot GraalVM 原生镜像
• Quarkus 构建原生可执行文件
• Micronaut GraalVM 指南

上游来源（升级 GraalVM 或原生配置前请先阅读）

获取目标版本的页面；若与本指南有冲突，请优先参考该页面。

• GraalVM 发行说明：https://www.graalvm.org/release-notes/
• 可达性元数据格式：https://www.graalvm.org/latest/reference-manual/native-image/metadata/
• 构建配置选项：https://www.graalvm.org/latest/reference-manual/native-image/overview/BuildConfiguration/
• 元数据仓库（检查是否涵盖你的库版本）：https://github.com/oracle/graalvm-reachability-metadata