GraalVM 原生镜像构建失败主因是 JDK 版本不匹配、反射等配置缺失及环境适配错误；必须严格对齐项目 JDK 版本，手动配置反射/资源，启用 --no-fallback 定位问题，并通过 -H:+PrintAnalysisCallTree 等日志分析类加载。
下载 GraalVM 时选错 JDK 版本会直接导致 native-image 构建失败
Java 原生镜像编译不是“装个插件就行”，GraalVM 本身是独立 JDK 发行版，必须和你的项目 JDK 版本对齐。常见错误是：项目用 JDK 17 编译，却下了 GraalVM for JDK 11，结果 native-image 命令能运行，但一构建就报 Unsupported class file major version。
- 查清你项目用的
java -version输出主版本号（如 17），就去 GraalVM 官方发布页 找对应graalvm-ce-java17开头的包 - Mac 用户注意：Apple Silicon（ARM64）需选
-darwin-aarch64后缀；Intel 芯片选-darwin-x64，混用会导致Bad CPU type in executable - Windows 用户别用 ZIP 包解压后直接跑——务必用
gu install native-image安装组件，否则native-image命令根本不存在
native-image 构建前必须手动启用反射、资源、动态代理配置
GraalVM AOT 编译时不做运行时扫描，所有反射调用、Class.forName、JSON 序列化、Spring 的 @Value 注入等，默认全被剪掉。不配就崩溃，报 ClassNotFoundException 或空指针，而且错误堆栈不指向你代码，只显示 Substrate VM 内部路径。
- 最简验证法：先加
--no-fallback参数，它会让构建失败时立刻报错，而不是退化成 JVM 模式继续跑——这是定位缺失配置的关键开关 - Spring Boot 3+ 用户：必须用
spring-native已废弃，改用spring-aot+spring-graal-native插件，且需在build.gradle中显式声明nativeImage { resources = true } - 手写
reflect-config.json时，类名必须用完整内部名（如java.time.LocalDate），不能写LocalDate；方法名字段名大小写敏感，漏一个字母就白配
构建产物体积大、启动快，但首次运行仍可能触发隐式类加载
原生镜像不是“绝对静态”——它仍依赖系统 libc（Linux）、libz（压缩）、甚至某些 JDK 内置 JNI 库。你看到的 50MB 可执行文件里，约 30MB 是嵌入的 JVM 运行时子集，不是你的代码。
- 用
ldd your-app（Linux）或otool -L your-app（macOS）检查动态链接，若出现libjvm.so或libnio.so，说明构建没走纯 AOT 路径，而是 fallback 到了 JIT 模式 - Spring Boot 项目默认带 Tomcat，但原生镜像下 Web 容器必须换成 Netty 或 Jetty（且要用
spring-boot-starter-webflux），否则构建通过、运行时报No suitable HttpServerFactory -
-H:EnableURLProtocols=http,https必须显式加，否则RestTemplate或WebClient发请求直接抛NullPointerException，因为 URL 处理协议处理器没注册
调试原生镜像崩溃只能靠日志 + -H:+PrintAnalysisCallTree
没有 jstack，没有 jmap，JVM 工具链全失效。崩溃时只有一行 Segmentation fault (core dumped) 或静默退出，连异常堆栈都不打。
立即学习“Java免费学习笔记（深入）”；
- 加
-H:+PrintAnalysisCallTree会输出长达数万行的静态分析调用树，重点搜你用到的类名（如ObjectMapper），看它是否出现在 “reason: reflection registration” 下面——不在就是漏配 - 加
-H:Log=registerForReflection可单独打印所有被注册为反射可用的类，比大海捞针强 - 别信 IDE 的“Run as Native Image”按钮，它常忽略 profile 或 active profiles，真实构建请始终用命令行：
./gradlew nativeCompile -PspringProfilesActive=prod
