GraalVM 生成的原生二进制文件在项目目录外运行失败（报错“Could not find or load main class Main”），本质是静态编译时未正确捕获反射、资源加载及动态类加载行为；需通过 native-image-agent 自动生成配置文件，再重新构建 native image 才能实现跨目录可移植性。
graalvm 生成的原生二进制文件在项目目录外运行失败（报错“could not find or load main class main”），本质是静态编译时未正确捕获反射、资源加载及动态类加载行为；需通过 `native-image-agent` 自动生成配置文件，再重新构建 native image 才能实现跨目录可移植性。
当使用 GraalVM 的 native-image 工具将 Java 应用（尤其含 Picocli、第三方库或动态资源访问）编译为原生二进制时，默认静态分析无法自动识别所有运行时依赖——例如 Picocli 在解析命令行参数时会通过反射调用用户类方法，JAR 中的 META-INF/MANIFEST.MF 指定的 Main-Class 可能被忽略，或资源路径（如配置文件、模板）因编译时未显式声明而丢失。这导致二进制在脱离原始构建环境（如 out/artifacts/ 目录）后，因类加载器缺失、反射失败或资源定位异常而崩溃。
✅ 正确做法是启用 运行时配置采集代理（-agentlib:native-image-agent），让应用在 JVM 下真实执行一次，自动记录所有反射、JNI、资源和动态代理需求：
# Step 1：运行 JAR 并生成配置（指定 config-output-dir） java \ -agentlib:native-image-agent=config-output-dir=src/main/resources/META-INF/native-image \ -jar metadata-processor.jar \ -i input/Claimant.json \ -o output/Claimant_output.json
该命令会在 src/main/resources/META-INF/native-image/ 下生成 reflect-config.json、resource-config.json、jni-config.json 等文件，精准描述运行时行为。
✅ Step 2：确保构建的 JAR 包含所有依赖（推荐使用 Maven Shade Plugin 或 IntelliJ “Extracted JAR with dependencies”），并确认 MANIFEST.MF 中 Main-Class 正确指向入口类（如 picocli.CommandLine 子类或直接含 main() 的类）。然后执行：
# Step 2：基于配置 + 完整 JAR 构建 native image native-image -jar app-1.0-SNAPSHOT-jar-with-dependencies.jar
GraalVM 会自动读取 META-INF/native-image/ 下的配置，将反射目标、资源路径等嵌入二进制，使其具备完整可移植性。
⚠️ 注意事项：
- 配置采集必须覆盖所有典型执行路径（如不同参数组合、异常分支），建议用代表性输入多次运行；
- 若项目使用 Spring Boot 或复杂框架，还需额外配置 --initialize-at-build-time 或排除特定类；
- 构建后的二进制不依赖 JVM、无需 CLASSPATH，可直接复制到任意目录（如 ~/Downloads）执行：
./app-1.0-SNAPSHOT-jar-with-dependencies -i abc -o xyz； - 验证是否生效：检查输出二进制大小（通常 >5MB 表明已嵌入必要元数据），并用 ldd ./binary（Linux）或 otool -L（macOS）确认无外部 JVM 依赖。
总结：GraalVM 原生镜像不是“一键打包”，而是以运行时行为驱动的精准静态链接。跳过 native-image-agent 配置步骤，仅靠 -jar 直接编译，几乎必然导致跨目录失效。唯有通过真实执行采集配置，才能让二进制真正“自包含”——这也是生产级 GraalVM 应用的标准实践。
