GraalVM native-image需用官方JDK构建版（如graalvm-jdk-21.0.3+11.1），禁用OpenJDK 17+；必须安装native-image插件、配置反射/资源文件、加--no-fallback等关键参数；Spring Boot 3.x需配合Spring AOT或Spring Native；非纯静态链接需注意libc及系统库依赖。
装 GraalVM 之前先确认 JDK 版本兼容性
GraalVM 的 native-image 不是所有 JDK 都能用，尤其别拿 OpenJDK 17+ 官方构建版直接上——它缺 native-image 插件，也压根不支持。必须用 GraalVM 官方发布的 JDK 构建版本（比如 graalvm-jdk-21.0.3+11.1），且要匹配你的 Java 项目目标版本。
常见错误现象：native-image: command not found 或运行时报 java.lang.UnsupportedOperationException: Substrate VM is not supported，基本就是 JDK 混用了。
- 检查是否真在用 GraalVM：运行
java -version，输出里必须含GraalVM字样 - 确认插件已安装：执行
gu list，看到native-image状态为installed - 没装就补：运行
gu install native-image（注意：GraalVM 22.3+ 默认不预装，必须手动） - Mac 用户特别注意：M1/M2 芯片需用
aarch64版本，x64 版本跑native-image会静默失败或生成无效二进制
native-image 命令的关键参数不能省
native-image 不是 javac，不加参数默认只做最简编译，几乎必然失败——反射、JNI、动态代理、资源加载全被砍掉。必须显式告诉它“哪些东西得保留”。
典型场景：Spring Boot 应用想转 native，不配 --reflect-config-file 和 --resource-config-file，启动就报 ClassNotFoundException 或空指针。
-
--no-fallback必加：强制失败而非退化到 JVM 模式，避免你以为成功了其实还是 jar 包 -
--enable-http或--enable-https：用 HttpClient 或 Spring Web 的必须开，否则 DNS 解析失败 -
--initialize-at-build-time：把类初始化提前到构建期，但别乱加，加错会导致运行时类未初始化而崩溃 - 路径别写错：
--reflect-config-file=src/main/resources/reflect-config.json，文件必须存在且 JSON 格式合法，否则构建直接中断
Spring Boot 3.x + GraalVM 22.3+ 的坑最多
Spring Boot 3 默认要求 Jakarta EE 9+，而 GraalVM 22.3 开始对 jakarta.* 包的反射处理更严格，老配置方式（比如靠 @TypeHint）容易漏。
错误现象：应用能编译过，但一发 HTTP 请求就 NullPointerException 在 HttpMessageConverter 或 ObjectMapper 初始化阶段。
- 必须用 Spring Native 0.13.x（对应 Boot 3.1.x）或 Spring AOT（Boot 3.2+ 内置），别试图手写 reflect-config.json 覆盖全部 Jackson 类
-
spring-aot:generate生成的resources/META-INF/native-image/下配置才是可信的，手动改要同步更新target/classes/META-INF/native-image/ - GraalVM 23.1+ 对
record类的序列化支持仍不稳定，含 record 的 DTO 建议暂时避开或加@Serializers显式声明 - 别信 “加个
--report-unsupported-elements-at-runtime就能跑”，这只是延迟报错，上线后第一个异常请求就崩
本地验证 native 可执行文件前先查依赖树
生成的二进制看着小，但一运行就 libz.so: cannot open shared object file，说明它偷偷 link 了系统库——这不是纯静态，而是半静态（partial static），GraalVM 默认只静态链接 libc，其他像 zlib、openssl 还是动态找。
尤其在 Alpine Linux 或容器里，ldd your-app 会暴露一堆 missing，而你本地 Ubuntu 能跑只是因为系统恰好有这些 so。
- 用
file your-app看是不是statically linked；如果不是，就得加--libc=musl（配合 Alpine）或确保基础镜像含对应 so - Docker 构建时别用
FROM openjdk:17-jre-slim，改用FROM ghcr.io/graalvm/native-image:22.3-java17或FROM alpine:3.19+ 手动装 musl-dev - 验证命令建议三步走：
./your-app && echo ok→strace -e trace=openat,open ./your-app 2>&1 | head -20→docker run --rm -v $(pwd):/app ubuntu:22.04 /app/your-app
真正纯静态、零外部依赖的 native-image，在 Java 生态里目前只对极简 CLI 工具现实。只要碰网络、JSON、时间时区、国际化，就一定有隐藏的动态链入点——得一个个用 ldd 和 objdump 掀开看。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
