传统 JVM 走到容器和云原生时代后很多以前用物理机堆出来的毛病开始现形。最典型的是服务启动太慢、内存太肥、预热期 CPU 拉满。我们用 Java 写服务的时候习惯了“编译一次到处跑”可到了 Kubernetes 里面这个模型的代价变得很具体。我一度以为只有换语言才能救直到认真用了一轮 GraalVM for JDK 21才意识到我们缺的不是换语言而是一种提前编译的思路。这篇快速上手指南我把实际迁移时碰到的重点都整理出来了安装、Native Image 参数、容器镜像、Spring Boot 3 接入以及 polyglot 要不要玩。目标读者是想做云原生改造、又不想丢掉 Java 生态的团队或个人。1. JIT 不是不好是容器环境把它养刁了启动预热与内存账本很多人一听到“告别传统 JVM”第一反应是很难理解Java 不是靠 JIT 才做到高性能的吗对但这个前提是进程活得足够长。容器和 Serverless 改变了这个前提所以原本的优势变成了负担。1.1 冷启动慢的本质字节码在等 JITJava 程序传统的运行方式是javac 先把源码编译成字节码JVM 启动后用解释器执行一边执行一边统计热点方法等某个方法被频繁调用之后再由 JIT 编译器把它编译成本地机器码。JIT 最大的优势是能看到真实运行 profile比如实际的分支走向、实际的类型分布然后做非常激进的内联和逃逸分析。代价也很明显它需要时间。物理机上的进程一跑就是几个月JVM 那点预热成本可以被忽略。但容器不是这样。扩容时每新建一个副本都是一次冷启动流量一波动几十个副本几乎同时“从头再来”。最典型的痛苦是Pod 从 Running 到 Ready 之后前几十秒还在疯狂做类加载、热点统计和编译优化CPU 不低、吞吐不高。从监控上看它好像“坏了”其实只是在热身。GraalVM for JDK 21 里的 Native Image 思路正好反着来既然你早晚要编译成本地代码那不如在构建阶段就把这一步做完。编译出来的产物不再依赖解释器也不需要在运行时去“发现热点”启动时直接执行机器码。这个差别在短生命周期进程里会被放大得非常明显。1.2 内存账本JVM 的固定开销比你想的多JVM 进程占用的内存从来不只是堆。堆之外还有 Metaspace、JIT 编译器本身、GC 线程、线程栈、字节码解释器相关结构。哪怕你的业务逻辑什么都不干只要把 JVM 拉起来固定开销就已经存在。我用一个非常普通的 Web 服务模板做过对比不压测、不接流量默认参数下 RSS 在 250MB 到 350MB 之间很正常换成 Native Image 编译出来的可执行文件同样服务启动后 RSS 往往能降到 100MB 上下。这里还没有算容器配额带来的另一个问题。很多团队在给 Java 容器设置 Xmx 之后以为内存就封顶了却忽略了堆外部分。结果就是容器 Limit 设了 512MB进程刚好卡在边缘一有流量波动就 OOMKilled。Native Image 的堆外开销小得多GC 是基础镜像里自带的 memory 管理没有 JIT 编译器那一大块实际可预测性高很多。1.3 过渡方案和真正该迁移的信号我必须说一句不是所有 Java 服务都需要立刻告别 JVM。如果你的服务是长时运行的批处理、大内存计算、或者一个一天只启动几次的老单体JIT 在长时间稳态运行下的优势会重新拉开AOT 的收益反而没那么大。这类场景更值得去优化 GC 参数、做 AppCDS而不是折腾 Native Image。真正该考虑迁移的信号通常是这几个扩容时 Pod 冷启动时间明显影响可用性内存配额和实际占用长期打架函数计算这类按调用次数计费、按运行时长计费的场景。换句话说哪个环节被“启动慢”和“内存大”拖惨了AOT 就先解决哪个环节。2. 把 JDK 换掉不代表换语言GraalVM for JDK 21 安装与基础验证GraalVM for JDK 21 本质上是一个完整的 JDK 发行版只不过它除了能当普通 JDK 用之外还带上了 Graal 编译器、Native Image、多语言运行时等额外能力。你不需要改 Java 语法不需要换项目语言原有代码依然能在上面编译运行。2.1 发行版选择认准 JDK 21 前缀下载时最需要注意的是版本号。GraalVM 有不同 JDK 基线的版本从旧的 JDK 8、JDK 11一直到现在的 JDK 21 都有对应发行版。既然标题强调的是“GraalVM for JDK”我建议直接选带 JDK 21 的最近稳定版。一来 Java 21 本身处于长期支持周期二来新版本对 Native Image 的构建效率和产物质量都有持续优化。社区版和商业版的功能不完全一样比如一些高级优化和企业级特性只在商业版里。但个人学习和中小团队做验证社区版完全够用。你只需要保证团队内部统一版本避免有人在 JDK 17 的 GraalVM 上验证另一个人却按 JDK 21 参数写构建脚本这种版本漂移最容易制造诡异问题。2.2 安装、环境变量与本机构建工具链安装方式没有花哨的下载对应平台的压缩包解压到一个固定目录。比如放在 ~/tools/graalvm-jdk-21然后把 JAVA_HOME 指过去PATH 也指过去。如果你不想动全局环境可以只在 IDE、命令行工具或者 Maven 设置里切换 JDK效果一样。需要额外留意的是系统构建工具链。Native Image 编译本地可执行文件时不是凭空生成机器码它要依赖操作系统的链接器。Linux 上需要 gcc 和 glibc 相关的开发头文件macOS 上需要 Xcode Command Line ToolsWindows 上需要 Visual Studio 的 C 构建工具。很多人安装完 GraalVM 后直接敲 native-image报错说找不到链接器就是因为少了这一步。安装完成后建议做两个验证命令java -version 看 JDK 版本native-image --version 看 Native Image 是否可用。如果某个发行版的 bin 目录里没有 native-image老版本通常需要执行类似 gu install native-image 的组件安装命令新版本很多已经把组建直接集成进去了。2.3 先用普通 Java 模式验证兼容性我先提醒一句不要一上来就编译 Native 可执行文件。先让项目以普通 Java 模式跑起来确认在 GraalVM for JDK 21 上没有任何兼容性问题。比如同一个项目里用了 Lombok、用了 Gradle 插件、用了某些在旧 JDK 上编译的第三方库先确保它们在 JDK 21 上正常。这个验证步骤很快你甚至可以写一个非常简单的类public class Hello { public static void main(String[] args) { System.out.println(hello graalvm); } }用 javac 编译再用 java 运行。如果这一步没问题基础兼容性就有保障了。真正要花时间的是下一步的 Native Image 编译和配置生成。3. 跑通 Native Image第一个可执行文件与参数解析Native Image 是这个发行版里最吸引人的部分。它做的事情和 JIT 恰好互补JIT 是在运行时“边跑边编译”Native Image 是在构建时“把所有能想到的路径都编完”。3.1 编译一个 Hello World 原生可执行文件刚才的 Hello.java 编译出 Hello.class 之后直接执行native-image -cp . Hello你会发现目录下多了一个名为 hello 的可执行文件。在 Linux 上直接 ./hello 就能跑整个过程不需要 JVM 再介入。我第一次跑通的时候最直观的感受是启动快到几乎没有感觉。用 time 去量普通 java 启动一个小程序还能看到几百毫秒native 可执行文件经常是几十毫秒甚至更低而且产物大小往往只有几 MB 到十几 MB。这个 hello 规模太小当然不能代表真实项目。但它能帮你验证工具链是否正常、native-image 是否真的能用以及你对整个流程的理解是否准确。3.2 封闭世界假设Native Image 到底在做什么Native Image 并不是简单地把字节码“翻译”成机器码。它要基于静态分析从入口方法出发扫描所有可达的类、方法、字段把决定能落地的执行路径提前编译。静态分析带来的一个核心前提是“封闭世界假设”程序运行时不能随意从外部搞新的类进来。传统 JVM 支持动态类加载、反射、动态接口实现、JNI这些机制在 Native Image 里默认都不会自动生效。比如你有一段代码用 Class.forName 加载类反射调某个方法那构建时静态分析是看不到这个类要被加载的它可能被判定为不可达直接被丢掉。所以真正需要花精力处理的就是反射、资源文件、序列化这些“动态点”。解决方式不是禁用它而是把这些动态行为预先登记到配置文件里。这也是后面谈 agent 自动收集配置的原因。3.3 native-image-agent让运行轨迹生成反射配置手动把所有反射点列出来不现实尤其项目一复杂谁也不知道哪个框架在什么时候反射调用了什么方法。GraalVM 提供了一个 native-image-agent可以挂在普通 Java 启动命令后面把实际运行过程中发生的反射、资源加载、接口配置等行为记录下来。操作方式很简单java -agentlib:native-image-agentconfig-output-dir./graal-config -jar your-app.jar接着把项目的主要业务场景都跑一遍包括登录、下单、查列表、执行异步任务这种典型路径。agent 会把 reflect 配置、resource 配置、serialization 配置等一系列 JSON 文件写到 graal-config 目录。构建时再把目录传给 native-imagenative-image \ -H:ReflectionConfigurationFilesgraal-config/reflect-config.json \ -H:ResourceConfigurationFilesgraal-config/resource-config.json \ -jar your-app.jar这里有一个心得配置宁可多收集也不要少收集。欠收集的配置不会立刻报错往往是你上线后某个冷门分支被调用时才炸过收集只是让可执行文件偏大、构建时间稍长但运行是安全的。所以 agent 收集阶段把测试用例尽量覆盖全。3.4 常用构建参数和构建期内存Native Image 的常用参数并不多但每个参数背后都有实际意义。我列一下平时最常碰到的几个参数作用--no-fallback禁止生成回退到普通 JVM 模式的产物保证纯 native-O1/-O2控制编译优化级别-O1构建更快-O2产物性能更好--static --libcmusl生成静态链接可执行文件适合放进精简容器-marchnative针对本机 CPU 指令集优化但不要跨机器分发-J-Xmx6g给 native-image 构建进程本身扩大内存--enable-url-protocolshttps允许运行时通过 HTTPS 发起请求很多人第一次构建失败不是代码有问题而是构建内存不足。Native Image 构建 Spring Boot 这类大项目构建进程消耗几个 GB 内存很正常。CI 机器如果只分配 2GB最好提前把构建内存调上去。构建日志里也能看到类似 Build memory 的提示遇到失败先看是不是构建端 OOM别急着怀疑业务代码。4. 容器镜像瘦身Dockerfile 怎么和 AOT 产物配合Native 可执行文件配合容器的价值不只是启动时间还包括镜像体积。普通 Java 容器镜像里经常要塞一个 JRE四五百 MB 很常见如果做多阶段构建把最终产物单独放进出痸镜像体积能压缩到真正让人意外的程度。4.1 多阶段构建编译容器与运行容器分离多阶段构建的思路很直接第一阶段用带 GraalVM 的构建镜像去编译 Native 可执行文件第二阶段只把编译好的文件复制到一个干净的新镜像里。一个典型的 Dockerfile 长这样# 第一阶段编译 Native 可执行文件 FROM ghcr.io/graalvm/graalvm-community:21 AS builder WORKDIR /build COPY . . RUN ./mvnw -Pnative package -DskipTests # 第二阶段只把产物放进干净镜像 FROM scratch COPY --frombuilder /build/target/your-app /app ENTRYPOINT [/app]如果你用的是 Spring Boot上个章节提到 nativeCompile 之后产物路径通常是 target/应用名按实际情况替换即可。scratch 镜像里没有任何 shell、没有包管理器、没有多余文件相当于整个运行环境就只有那一个可执行文件。这样的镜像体积通常只有几十 MB 到一百多 MB而且攻击面也小得多。4.2 静态链接与 musl 的取舍默认情况下Native Image 在 Linux 上生成的产物会动态链接 glibc。动态链接意味着它依赖基础镜像里的系统库不是随便拷到哪个容器都能跑。所以就有了 musl 静态编译这条路。--static --libcmusl可以把 C 库也静态编进去产物不再依赖动态库。这样做的好处是最终镜像可以用 scratch 或极简镜像直接承载。但代价是musl 和 glibc 在某些行为上有细微差别比如 DNS 解析、locale 处理如果你要用 HTTPS证书文件也得自己塞进镜像。我的习惯是纯内部 RPC 或工具类服务用静态 musl 走 scratch 镜像需要对外提供 HTTPS 的服务还是用带证书的轻量基础镜像更省心。4.3 更真实的小型服务如何控制镜像体积对真实项目我的建议是先用普通镜像把功能跑通别一上来就追求最小体积。第一步先验证 Native 可执行文件本身能在容器里稳定运行第二步再试 scratch 或更精简的基础镜像只有在功能验证通过后才去优化镜像体积。还要留一个心眼AOT 产物是平台相关的在 x86_64 上构建的二进制不能直接丢到 ARM64 机器上跑。跨架构发布要么在目标架构上重新构建要么用对应架构的构建环境。容器镜像正好帮我们把构建环境固定下来所以多阶段构建中的第一阶段最好也锁定具体架构和版本避免“本机能跑CI 编译出来的不能跑”这种奇怪问题。5. Spring Boot 3 接入 GraalVM依赖调整与坑位复盘很多项目不会只写一个 Hello World真正的大头是 Spring Boot 这类框架。Spring Boot 3 开始把原生支持提到了正式支持层面但接入过程还是有一些东西需要手动处理。5.1 Spring Boot 3 的 Maven 原生构建入口如果你用的是 Maven最简单的方式是在 pom.xml 里加一个 native 构建 profile。大致结构如下profiles profile idnative/id build plugins plugin groupIdorg.graalvm.buildtools/groupId artifactIdnative-maven-plugin/artifactId /plugin /plugins /build /profile /profiles然后用下面的命令启动原生构建./mvnw -Pnative nativeCompile这里有一点需要强调Spring Boot 版本和 Native Build Tools 版本最好保持配套。Spring Boot 官方文档里通常会给对应的版本组合不要随便拿最新插件配很旧的 Spring Boot。版本一旦错位构建过程里的自动配置可能识别不了出了错也很难判断是代码问题还是工具链问题。5.2 Spring AOT 能处理什么不能处理什么Spring Boot 3 之所以对 Native Image 友好是因为引入了 Spring AOT 引擎。它会在构建阶段提前处理大量的配置类、Bean 定义、条件注解省掉运行时扫描的步骤。你可以理解成Spring 自己也做了一次“提前分析和准备”把常规框架反射尽量转换成构建期的确定性数据。但 AOT 引擎也不是万能的。它不能替你解决所有第三方库的动态行为。比如你引了一个老旧的 JSON 库内部直接反射遍历对象字段Spring AOT 并不知道这个库会反射哪些类。这种时候要么自己写 Native Hint要么换一个对原生友好的库要么用 native-image-agent 去额外收集配置。5.3 常见报错与排查链路我在迁移过程中遇到过的最典型问题其实是几个固定模式。整理成表格方便对照现象常见原因处理思路启动后某个类报 ClassNotFoundException该类的加载路径在静态分析时未被识别用 agent 跑一遍主流程或写相关配置文件JSON 序列化字段异常或值为 null反射配置没覆盖到对象字段确认包含字段、构造函数、setter 的配置类似 AOP 中间类创建失败框架在运行时生成接口实现类用 agent 记录的运行轨迹配置或调整框架配置初始化阶段类型冲突某类初始化顺序和文件系统扫描有关用--trace-class-initialization定位初始化点遇到问题不要急着堆参数。我的排查顺序一般是这样的先把项目切回普通 Java 模式跑确认业务代码没问题再用 agent 重新收集配置、重新构建如果还报错就去看构建日志里是哪一步静态分析失败是反射找不到、资源找不到还是某个框架代码触发了不支持的 API。顺着链路走大部分问题都能落到“我少配了一个运行时动态行为”这个根因上。5.4 和 Micronaut、Quarkus 怎么选同样做 AOT 和对原生友好这件事Micronaut 和 Quarkus 的底子天生更贴近编译期。它们从框架设计上就更早把注解元数据、配置信息固化进字节码所以做 Native Image 时的“恶心事”会比 Spring Boot 少一些。但 Spring Boot 3 的官方支持和社区资料已经很丰富生态迁移成本也更低。实际选择标准不是谁原生优化更好而是团队对哪套开发模型更熟。如果你现在就是 Spring Boot 项目没有理由为了少写几个 Hint 就把全家桶打成一个更大的重构工程。反过来如果新项目从零开始又非常明确要面向函数计算、快速扩容那 Micronaut 或 Quarkus 更值得认真考虑。6. 多语言扩展polyglot 与 Truffle 的适合边界提到 GraalVM很多人还会被多语言能力吸引。它能在一个进程中同时跑 JavaScript、Python、Ruby、R、甚至 C/C 编译出来的 LLVM 位码底层靠的是 Truffle 框架实现的一套语言运行时。6.1 polyglot 快速体验体验多语言最直接的方式是 polyglot API。它允许你在 Java 代码里直接求值其他语言的表达式。一个最小的 JavaScript 示例是这样import org.graalvm.polyglot.Context; public class JsDemo { public static void main(String[] args) { try (Context ctx Context.newBuilder(js) .allowAllAccess(true) .build()) { int result ctx.eval(js, 1 2).asInt(); System.out.println(result); } } }这段代码在传统 JVM 上也能跑只要你用的是 GraalVM 发行版。它解决了一个很实际的问题Java 自带的脚本引擎被移除之后你再想给 Java 应用内置一个可热更新的“规则脚本”polyglot 是一个很值得考虑的选项。6.2 Truffle 运行时家族FastR 与 LLVMTruffle 上不止 JavaScript还有 Python、Ruby、R 等语言实现。FastR 就是其中一个基于 Truffle 的 R 语言运行时适合需要在 Java 体系内用 R 做统计计算的特殊项目。LLVM 运行时则可以加载 C/C 编译出的位码让你在 Java 侧调用过去写在 C 里的算法库。这些能力的共同点是它们都跑在同一套 GC、调试器、工具链体系里。听起来很美好但也要付出代价。每引入一个语言运行时构建产物和镜像体积都会明显变大而且 polyglot 的配置在 Native Image 场景下会更加复杂很多动态语言特性和 AOT 的“封闭世界假设”天然打架。6.3 什么时候不应该引入多语言我的建议是默认不要引入多语言。大多数项目里跨语言调用完全可以拆成独立进程通过接口或消息队列通信没必要共享同一份内存。独立进程的好处是故障隔离好、版本升级容易、每个语言可以用自己最擅长的运行方式。polyglot 最该用的场景是你需要在一个 Java 进程内完成高频率的跨语言数据交换和热更新逻辑且进程间通信已经明显成为性能瓶颈。我实际项目里很少用 polyglot但我会把这条能力记在脑海里。它是一个“备用武器”不是日常主武器。如果某个业务确实需要建议先单独做一个最小原型验证配置复杂度再决定要不要纳入正式架构。最后补一句我的操作习惯任何 Java 服务想上 Native Image我都会先在模拟环境里用 agent 跑完整功能用例把配置收集好再切到构建环境里编译。上生产前再回退到普通 JVM 模式对比一版行为确保差异不是来自 AOT 配置而是业务逻辑本身。你如果刚上手拿一个外围小服务练手是最稳妥的不要一上来就把核心链路押在未知的构建参数上。
传统 JVM 走到容器和云原生时代后很多以前用物理机堆出来的毛病开始现形。最典型的是服务启动太慢、内存太肥、预热期 CPU 拉满。我们用 Java 写服务的时候习惯了“编译一次到处跑”可到了 Kubernetes 里面这个模型的代价变得很具体。我一度以为只有换语言才能救直到认真用了一轮 GraalVM for JDK 21才意识到我们缺的不是换语言而是一种提前编译的思路。这篇快速上手指南我把实际迁移时碰到的重点都整理出来了安装、Native Image 参数、容器镜像、Spring Boot 3 接入以及 polyglot 要不要玩。目标读者是想做云原生改造、又不想丢掉 Java 生态的团队或个人。1. JIT 不是不好是容器环境把它养刁了启动预热与内存账本很多人一听到“告别传统 JVM”第一反应是很难理解Java 不是靠 JIT 才做到高性能的吗对但这个前提是进程活得足够长。容器和 Serverless 改变了这个前提所以原本的优势变成了负担。1.1 冷启动慢的本质字节码在等 JITJava 程序传统的运行方式是javac 先把源码编译成字节码JVM 启动后用解释器执行一边执行一边统计热点方法等某个方法被频繁调用之后再由 JIT 编译器把它编译成本地机器码。JIT 最大的优势是能看到真实运行 profile比如实际的分支走向、实际的类型分布然后做非常激进的内联和逃逸分析。代价也很明显它需要时间。物理机上的进程一跑就是几个月JVM 那点预热成本可以被忽略。但容器不是这样。扩容时每新建一个副本都是一次冷启动流量一波动几十个副本几乎同时“从头再来”。最典型的痛苦是Pod 从 Running 到 Ready 之后前几十秒还在疯狂做类加载、热点统计和编译优化CPU 不低、吞吐不高。从监控上看它好像“坏了”其实只是在热身。GraalVM for JDK 21 里的 Native Image 思路正好反着来既然你早晚要编译成本地代码那不如在构建阶段就把这一步做完。编译出来的产物不再依赖解释器也不需要在运行时去“发现热点”启动时直接执行机器码。这个差别在短生命周期进程里会被放大得非常明显。1.2 内存账本JVM 的固定开销比你想的多JVM 进程占用的内存从来不只是堆。堆之外还有 Metaspace、JIT 编译器本身、GC 线程、线程栈、字节码解释器相关结构。哪怕你的业务逻辑什么都不干只要把 JVM 拉起来固定开销就已经存在。我用一个非常普通的 Web 服务模板做过对比不压测、不接流量默认参数下 RSS 在 250MB 到 350MB 之间很正常换成 Native Image 编译出来的可执行文件同样服务启动后 RSS 往往能降到 100MB 上下。这里还没有算容器配额带来的另一个问题。很多团队在给 Java 容器设置 Xmx 之后以为内存就封顶了却忽略了堆外部分。结果就是容器 Limit 设了 512MB进程刚好卡在边缘一有流量波动就 OOMKilled。Native Image 的堆外开销小得多GC 是基础镜像里自带的 memory 管理没有 JIT 编译器那一大块实际可预测性高很多。1.3 过渡方案和真正该迁移的信号我必须说一句不是所有 Java 服务都需要立刻告别 JVM。如果你的服务是长时运行的批处理、大内存计算、或者一个一天只启动几次的老单体JIT 在长时间稳态运行下的优势会重新拉开AOT 的收益反而没那么大。这类场景更值得去优化 GC 参数、做 AppCDS而不是折腾 Native Image。真正该考虑迁移的信号通常是这几个扩容时 Pod 冷启动时间明显影响可用性内存配额和实际占用长期打架函数计算这类按调用次数计费、按运行时长计费的场景。换句话说哪个环节被“启动慢”和“内存大”拖惨了AOT 就先解决哪个环节。2. 把 JDK 换掉不代表换语言GraalVM for JDK 21 安装与基础验证GraalVM for JDK 21 本质上是一个完整的 JDK 发行版只不过它除了能当普通 JDK 用之外还带上了 Graal 编译器、Native Image、多语言运行时等额外能力。你不需要改 Java 语法不需要换项目语言原有代码依然能在上面编译运行。2.1 发行版选择认准 JDK 21 前缀下载时最需要注意的是版本号。GraalVM 有不同 JDK 基线的版本从旧的 JDK 8、JDK 11一直到现在的 JDK 21 都有对应发行版。既然标题强调的是“GraalVM for JDK”我建议直接选带 JDK 21 的最近稳定版。一来 Java 21 本身处于长期支持周期二来新版本对 Native Image 的构建效率和产物质量都有持续优化。社区版和商业版的功能不完全一样比如一些高级优化和企业级特性只在商业版里。但个人学习和中小团队做验证社区版完全够用。你只需要保证团队内部统一版本避免有人在 JDK 17 的 GraalVM 上验证另一个人却按 JDK 21 参数写构建脚本这种版本漂移最容易制造诡异问题。2.2 安装、环境变量与本机构建工具链安装方式没有花哨的下载对应平台的压缩包解压到一个固定目录。比如放在 ~/tools/graalvm-jdk-21然后把 JAVA_HOME 指过去PATH 也指过去。如果你不想动全局环境可以只在 IDE、命令行工具或者 Maven 设置里切换 JDK效果一样。需要额外留意的是系统构建工具链。Native Image 编译本地可执行文件时不是凭空生成机器码它要依赖操作系统的链接器。Linux 上需要 gcc 和 glibc 相关的开发头文件macOS 上需要 Xcode Command Line ToolsWindows 上需要 Visual Studio 的 C 构建工具。很多人安装完 GraalVM 后直接敲 native-image报错说找不到链接器就是因为少了这一步。安装完成后建议做两个验证命令java -version 看 JDK 版本native-image --version 看 Native Image 是否可用。如果某个发行版的 bin 目录里没有 native-image老版本通常需要执行类似 gu install native-image 的组件安装命令新版本很多已经把组建直接集成进去了。2.3 先用普通 Java 模式验证兼容性我先提醒一句不要一上来就编译 Native 可执行文件。先让项目以普通 Java 模式跑起来确认在 GraalVM for JDK 21 上没有任何兼容性问题。比如同一个项目里用了 Lombok、用了 Gradle 插件、用了某些在旧 JDK 上编译的第三方库先确保它们在 JDK 21 上正常。这个验证步骤很快你甚至可以写一个非常简单的类public class Hello { public static void main(String[] args) { System.out.println(hello graalvm); } }用 javac 编译再用 java 运行。如果这一步没问题基础兼容性就有保障了。真正要花时间的是下一步的 Native Image 编译和配置生成。3. 跑通 Native Image第一个可执行文件与参数解析Native Image 是这个发行版里最吸引人的部分。它做的事情和 JIT 恰好互补JIT 是在运行时“边跑边编译”Native Image 是在构建时“把所有能想到的路径都编完”。3.1 编译一个 Hello World 原生可执行文件刚才的 Hello.java 编译出 Hello.class 之后直接执行native-image -cp . Hello你会发现目录下多了一个名为 hello 的可执行文件。在 Linux 上直接 ./hello 就能跑整个过程不需要 JVM 再介入。我第一次跑通的时候最直观的感受是启动快到几乎没有感觉。用 time 去量普通 java 启动一个小程序还能看到几百毫秒native 可执行文件经常是几十毫秒甚至更低而且产物大小往往只有几 MB 到十几 MB。这个 hello 规模太小当然不能代表真实项目。但它能帮你验证工具链是否正常、native-image 是否真的能用以及你对整个流程的理解是否准确。3.2 封闭世界假设Native Image 到底在做什么Native Image 并不是简单地把字节码“翻译”成机器码。它要基于静态分析从入口方法出发扫描所有可达的类、方法、字段把决定能落地的执行路径提前编译。静态分析带来的一个核心前提是“封闭世界假设”程序运行时不能随意从外部搞新的类进来。传统 JVM 支持动态类加载、反射、动态接口实现、JNI这些机制在 Native Image 里默认都不会自动生效。比如你有一段代码用 Class.forName 加载类反射调某个方法那构建时静态分析是看不到这个类要被加载的它可能被判定为不可达直接被丢掉。所以真正需要花精力处理的就是反射、资源文件、序列化这些“动态点”。解决方式不是禁用它而是把这些动态行为预先登记到配置文件里。这也是后面谈 agent 自动收集配置的原因。3.3 native-image-agent让运行轨迹生成反射配置手动把所有反射点列出来不现实尤其项目一复杂谁也不知道哪个框架在什么时候反射调用了什么方法。GraalVM 提供了一个 native-image-agent可以挂在普通 Java 启动命令后面把实际运行过程中发生的反射、资源加载、接口配置等行为记录下来。操作方式很简单java -agentlib:native-image-agentconfig-output-dir./graal-config -jar your-app.jar接着把项目的主要业务场景都跑一遍包括登录、下单、查列表、执行异步任务这种典型路径。agent 会把 reflect 配置、resource 配置、serialization 配置等一系列 JSON 文件写到 graal-config 目录。构建时再把目录传给 native-imagenative-image \ -H:ReflectionConfigurationFilesgraal-config/reflect-config.json \ -H:ResourceConfigurationFilesgraal-config/resource-config.json \ -jar your-app.jar这里有一个心得配置宁可多收集也不要少收集。欠收集的配置不会立刻报错往往是你上线后某个冷门分支被调用时才炸过收集只是让可执行文件偏大、构建时间稍长但运行是安全的。所以 agent 收集阶段把测试用例尽量覆盖全。3.4 常用构建参数和构建期内存Native Image 的常用参数并不多但每个参数背后都有实际意义。我列一下平时最常碰到的几个参数作用--no-fallback禁止生成回退到普通 JVM 模式的产物保证纯 native-O1/-O2控制编译优化级别-O1构建更快-O2产物性能更好--static --libcmusl生成静态链接可执行文件适合放进精简容器-marchnative针对本机 CPU 指令集优化但不要跨机器分发-J-Xmx6g给 native-image 构建进程本身扩大内存--enable-url-protocolshttps允许运行时通过 HTTPS 发起请求很多人第一次构建失败不是代码有问题而是构建内存不足。Native Image 构建 Spring Boot 这类大项目构建进程消耗几个 GB 内存很正常。CI 机器如果只分配 2GB最好提前把构建内存调上去。构建日志里也能看到类似 Build memory 的提示遇到失败先看是不是构建端 OOM别急着怀疑业务代码。4. 容器镜像瘦身Dockerfile 怎么和 AOT 产物配合Native 可执行文件配合容器的价值不只是启动时间还包括镜像体积。普通 Java 容器镜像里经常要塞一个 JRE四五百 MB 很常见如果做多阶段构建把最终产物单独放进出痸镜像体积能压缩到真正让人意外的程度。4.1 多阶段构建编译容器与运行容器分离多阶段构建的思路很直接第一阶段用带 GraalVM 的构建镜像去编译 Native 可执行文件第二阶段只把编译好的文件复制到一个干净的新镜像里。一个典型的 Dockerfile 长这样# 第一阶段编译 Native 可执行文件 FROM ghcr.io/graalvm/graalvm-community:21 AS builder WORKDIR /build COPY . . RUN ./mvnw -Pnative package -DskipTests # 第二阶段只把产物放进干净镜像 FROM scratch COPY --frombuilder /build/target/your-app /app ENTRYPOINT [/app]如果你用的是 Spring Boot上个章节提到 nativeCompile 之后产物路径通常是 target/应用名按实际情况替换即可。scratch 镜像里没有任何 shell、没有包管理器、没有多余文件相当于整个运行环境就只有那一个可执行文件。这样的镜像体积通常只有几十 MB 到一百多 MB而且攻击面也小得多。4.2 静态链接与 musl 的取舍默认情况下Native Image 在 Linux 上生成的产物会动态链接 glibc。动态链接意味着它依赖基础镜像里的系统库不是随便拷到哪个容器都能跑。所以就有了 musl 静态编译这条路。--static --libcmusl可以把 C 库也静态编进去产物不再依赖动态库。这样做的好处是最终镜像可以用 scratch 或极简镜像直接承载。但代价是musl 和 glibc 在某些行为上有细微差别比如 DNS 解析、locale 处理如果你要用 HTTPS证书文件也得自己塞进镜像。我的习惯是纯内部 RPC 或工具类服务用静态 musl 走 scratch 镜像需要对外提供 HTTPS 的服务还是用带证书的轻量基础镜像更省心。4.3 更真实的小型服务如何控制镜像体积对真实项目我的建议是先用普通镜像把功能跑通别一上来就追求最小体积。第一步先验证 Native 可执行文件本身能在容器里稳定运行第二步再试 scratch 或更精简的基础镜像只有在功能验证通过后才去优化镜像体积。还要留一个心眼AOT 产物是平台相关的在 x86_64 上构建的二进制不能直接丢到 ARM64 机器上跑。跨架构发布要么在目标架构上重新构建要么用对应架构的构建环境。容器镜像正好帮我们把构建环境固定下来所以多阶段构建中的第一阶段最好也锁定具体架构和版本避免“本机能跑CI 编译出来的不能跑”这种奇怪问题。5. Spring Boot 3 接入 GraalVM依赖调整与坑位复盘很多项目不会只写一个 Hello World真正的大头是 Spring Boot 这类框架。Spring Boot 3 开始把原生支持提到了正式支持层面但接入过程还是有一些东西需要手动处理。5.1 Spring Boot 3 的 Maven 原生构建入口如果你用的是 Maven最简单的方式是在 pom.xml 里加一个 native 构建 profile。大致结构如下profiles profile idnative/id build plugins plugin groupIdorg.graalvm.buildtools/groupId artifactIdnative-maven-plugin/artifactId /plugin /plugins /build /profile /profiles然后用下面的命令启动原生构建./mvnw -Pnative nativeCompile这里有一点需要强调Spring Boot 版本和 Native Build Tools 版本最好保持配套。Spring Boot 官方文档里通常会给对应的版本组合不要随便拿最新插件配很旧的 Spring Boot。版本一旦错位构建过程里的自动配置可能识别不了出了错也很难判断是代码问题还是工具链问题。5.2 Spring AOT 能处理什么不能处理什么Spring Boot 3 之所以对 Native Image 友好是因为引入了 Spring AOT 引擎。它会在构建阶段提前处理大量的配置类、Bean 定义、条件注解省掉运行时扫描的步骤。你可以理解成Spring 自己也做了一次“提前分析和准备”把常规框架反射尽量转换成构建期的确定性数据。但 AOT 引擎也不是万能的。它不能替你解决所有第三方库的动态行为。比如你引了一个老旧的 JSON 库内部直接反射遍历对象字段Spring AOT 并不知道这个库会反射哪些类。这种时候要么自己写 Native Hint要么换一个对原生友好的库要么用 native-image-agent 去额外收集配置。5.3 常见报错与排查链路我在迁移过程中遇到过的最典型问题其实是几个固定模式。整理成表格方便对照现象常见原因处理思路启动后某个类报 ClassNotFoundException该类的加载路径在静态分析时未被识别用 agent 跑一遍主流程或写相关配置文件JSON 序列化字段异常或值为 null反射配置没覆盖到对象字段确认包含字段、构造函数、setter 的配置类似 AOP 中间类创建失败框架在运行时生成接口实现类用 agent 记录的运行轨迹配置或调整框架配置初始化阶段类型冲突某类初始化顺序和文件系统扫描有关用--trace-class-initialization定位初始化点遇到问题不要急着堆参数。我的排查顺序一般是这样的先把项目切回普通 Java 模式跑确认业务代码没问题再用 agent 重新收集配置、重新构建如果还报错就去看构建日志里是哪一步静态分析失败是反射找不到、资源找不到还是某个框架代码触发了不支持的 API。顺着链路走大部分问题都能落到“我少配了一个运行时动态行为”这个根因上。5.4 和 Micronaut、Quarkus 怎么选同样做 AOT 和对原生友好这件事Micronaut 和 Quarkus 的底子天生更贴近编译期。它们从框架设计上就更早把注解元数据、配置信息固化进字节码所以做 Native Image 时的“恶心事”会比 Spring Boot 少一些。但 Spring Boot 3 的官方支持和社区资料已经很丰富生态迁移成本也更低。实际选择标准不是谁原生优化更好而是团队对哪套开发模型更熟。如果你现在就是 Spring Boot 项目没有理由为了少写几个 Hint 就把全家桶打成一个更大的重构工程。反过来如果新项目从零开始又非常明确要面向函数计算、快速扩容那 Micronaut 或 Quarkus 更值得认真考虑。6. 多语言扩展polyglot 与 Truffle 的适合边界提到 GraalVM很多人还会被多语言能力吸引。它能在一个进程中同时跑 JavaScript、Python、Ruby、R、甚至 C/C 编译出来的 LLVM 位码底层靠的是 Truffle 框架实现的一套语言运行时。6.1 polyglot 快速体验体验多语言最直接的方式是 polyglot API。它允许你在 Java 代码里直接求值其他语言的表达式。一个最小的 JavaScript 示例是这样import org.graalvm.polyglot.Context; public class JsDemo { public static void main(String[] args) { try (Context ctx Context.newBuilder(js) .allowAllAccess(true) .build()) { int result ctx.eval(js, 1 2).asInt(); System.out.println(result); } } }这段代码在传统 JVM 上也能跑只要你用的是 GraalVM 发行版。它解决了一个很实际的问题Java 自带的脚本引擎被移除之后你再想给 Java 应用内置一个可热更新的“规则脚本”polyglot 是一个很值得考虑的选项。6.2 Truffle 运行时家族FastR 与 LLVMTruffle 上不止 JavaScript还有 Python、Ruby、R 等语言实现。FastR 就是其中一个基于 Truffle 的 R 语言运行时适合需要在 Java 体系内用 R 做统计计算的特殊项目。LLVM 运行时则可以加载 C/C 编译出的位码让你在 Java 侧调用过去写在 C 里的算法库。这些能力的共同点是它们都跑在同一套 GC、调试器、工具链体系里。听起来很美好但也要付出代价。每引入一个语言运行时构建产物和镜像体积都会明显变大而且 polyglot 的配置在 Native Image 场景下会更加复杂很多动态语言特性和 AOT 的“封闭世界假设”天然打架。6.3 什么时候不应该引入多语言我的建议是默认不要引入多语言。大多数项目里跨语言调用完全可以拆成独立进程通过接口或消息队列通信没必要共享同一份内存。独立进程的好处是故障隔离好、版本升级容易、每个语言可以用自己最擅长的运行方式。polyglot 最该用的场景是你需要在一个 Java 进程内完成高频率的跨语言数据交换和热更新逻辑且进程间通信已经明显成为性能瓶颈。我实际项目里很少用 polyglot但我会把这条能力记在脑海里。它是一个“备用武器”不是日常主武器。如果某个业务确实需要建议先单独做一个最小原型验证配置复杂度再决定要不要纳入正式架构。最后补一句我的操作习惯任何 Java 服务想上 Native Image我都会先在模拟环境里用 agent 跑完整功能用例把配置收集好再切到构建环境里编译。上生产前再回退到普通 JVM 模式对比一版行为确保差异不是来自 AOT 配置而是业务逻辑本身。你如果刚上手拿一个外围小服务练手是最稳妥的不要一上来就把核心链路押在未知的构建参数上。
