GraalVM构建native-image时方法替换未生效且未出现在报告问题

执行native-image构建时@Substitute替换逻辑不触发、不在替换报告中展示，基本是以下配置遗漏导致：

• 替换类未被Native Image构建进程识别
  替换类不能随便放在普通源码包路径下，要么放到jar包内META-INF/native-image/[任意分组名]/[任意项目名]/substitutions/目录下让构建器自动扫描，要么在native-image配置文件中显式添加-H:SubstitutionClasses=[替换类全限定名]参数指定。打fat jar后必须先确认替换类的class文件确实被打进了最终jar包，否则构建时根本不会加载你的替换逻辑。
• 替换方法签名不匹配
  被@Substitute标记的方法，必须和目标类中待替换的方法签名完全一致：方法名、参数类型及顺序、返回值类型、方法修饰符（static/private等）必须完全对应，@TargetClass注解中填写的目标类全限定名不能有拼写错误，内部类需要用$分隔外部类和内部类名，只要有一处不匹配，替换就会静默失败，不会抛出明显报错。
• 目标方法不可达
  Native Image是静态分析优先的构建模式，如果待替换的目标方法在整个程序调用链中不可达（也就是运行时根本不会被执行到），对应的替换逻辑也不会执行，自然不会出现在替换报告中。可以先在程序入口写一段显式调用目标方法的代码，排除可达性问题。
• fat jar打包问题
  用-jar参数构建时，要确认最终的fat jar中同时包含了替换类、目标依赖类，没有出现类文件遗漏、依赖冲突导致目标类版本和你写替换逻辑时参照的版本不一致的问题，可以通过jar tf target/graal-substitutions-full.jar命令列出jar内文件逐一核对。

调整完配置后重新执行构建命令native-image -jar target/graal-substitutions-full.jar -H:+ReportPerformedSubstitutions，替换生效时会在构建日志中打印明确的替换执行记录。

内容的提问来源于stack exchange，提问作者Vikas Godara