Quarkus原生镜像构建失败：已配置运行时初始化类仍报错

问题描述 #

作为Quarkus新手，执行mvn package -Pnative构建原生镜像时，遇到错误：

Error: Classes that should be initialized at run time got initialized during image building:

在pom.xml中添加额外构建参数--initialize-at-run-time，用逗号分隔指定相关类后，再次构建时这些类依然被提示需要在运行时初始化。

操作细节 #

• 在Intellij终端执行mvn package -Pnative命令
• 日志显示native-image命令已包含添加的--initialize-at-run-time参数及指定类列表
• 构建进入初始化与分析阶段时，仍出现相同类的初始化错误，报错列出的类和指定的完全一致
• 添加--trace-class-initialization参数后，发现初始化触发源包含com.azure.cosmos.implementation.directconnectivity.rntbd.RntbdLoopNativeDetector等类，将这些类加入参数后问题仍未解决
• 最终构建失败提示：

[ERROR] Failed to execute goal io.quarkus.platform:quarkus-maven-plugin:2.13.1.Final:build on project: Failed to build quarkus application: io.quarkus.builder.BuildException: Build failure: Build failed due to errors

环境信息 #

• M1/aarch64架构Mac（Monterey 12.6）
• GraalVM CE 22.3.0（openjdk 11.0.17）
• Quarkus-maven-plugin 2.13.1.Final
• Maven 3.8.6

排查与解决步骤 #

1. 核对参数配置格式
   确认--initialize-at-run-time后的类名是完整全限定名，包名、类名拼写和大小写完全匹配。另外在pom.xml中配置多个类时，逗号后不要加空格——GraalVM对参数格式要求严格，空格会被当成类名的一部分。参考正确配置：

<plugin>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-maven-plugin</artifactId>
    <version>${quarkus.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>build</goal>
            </goals>
            <configuration>
                <nativeImageArgs>
                    <nativeImageArg>--initialize-at-run-time=com.your.package.ProblemClass,com.azure.cosmos.implementation.directconnectivity.rntbd.RntbdLoopNativeDetector</nativeImageArg>
                </nativeImageArgs>
            </configuration>
        </execution>
    </executions>
</plugin>

2. 尝试包级批量配置
   如果单个类配置无效，直接指定整个包来覆盖所有相关类，比如针对Cosmos的问题包：

--initialize-at-run-time=com.azure.cosmos.implementation.directconnectivity.rntbd

这样可以避免遗漏那些间接触发初始化的依赖类。

3. 升级依赖版本
   当前使用的Quarkus 2.13.1是2022年的旧版本，M1/aarch64架构下的原生镜像兼容性问题在后续版本中修复了不少。建议升级到Quarkus 2.16.x（LTS）或更高版本，同时搭配对应兼容的GraalVM版本（比如GraalVM CE 23.0.0+），很多初始化相关的BUG在新版本中已被解决。

4. 精准追踪初始化触发链
   用--trace-class-initialization=具体类名单独追踪报错类的初始化路径，比如：

--trace-class-initialization=com.azure.cosmos.implementation.directconnectivity.rntbd.RntbdLoopNativeDetector

从日志里找到到底是哪个类在构建期调用了它的静态代码或字段，再把那个触发类也加入--initialize-at-run-time列表。

5. 检查Cosmos客户端兼容性
   如果项目依赖Azure Cosmos，确保用的是Quarkus官方的Cosmos扩展（io.quarkus:quarkus-azure-cosmos）而非原生的Azure SDK，并且版本和Quarkus版本匹配。原生Azure SDK的旧版本在原生镜像构建中经常出现初始化问题，改用Quarkus扩展能减少这类麻烦。

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