Quarkus中添加非Maven管理外部依赖至deployments/lib/main的类加载问题

针对你遇到的类加载器无法识别Dockerfile复制的外部jar问题，核心原因是Quarkus在构建阶段已确定依赖集并生成了依赖索引，/deployments/lib/main目录仅包含构建时打包的Maven依赖，运行时新增的jar不会被自动扫描。以下是两种可行的解决方法：

方法一：构建阶段集成（推荐） #

这种方式让Quarkus在构建时就将外部jar纳入依赖体系，能享受Quarkus的依赖优化，避免运行时类加载问题：

1. 将外部jar放到项目本地目录，比如src/main/lib
2. 修改pom.xml，添加system类型的依赖：

<dependency>
    <groupId>自定义groupId</groupId>
    <artifactId>自定义artifactId</artifactId>
    <version>自定义版本号</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/src/main/lib/你的外部jar文件名.jar</systemPath>
</dependency>

3. 在pom.xml的quarkus-maven-plugin配置中，添加add-system-packages参数，指定外部jar的包名，确保Quarkus打包时正确处理该依赖：

<plugin>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-maven-plugin</artifactId>
    <version>${quarkus.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>build</goal>
                <goal>generate-code</goal>
                <goal>generate-code-tests</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <add-system-packages>你的外部jar的根包名</add-system-packages>
    </configuration>
</plugin>

4. 正常构建Quarkus应用并生成镜像，此时外部jar会被正确打包到/deployments/lib/main，类加载器可直接识别。

方法二：运行时动态添加类路径 #

如果不想修改构建流程，可通过Quarkus的启动参数手动扩展类路径：

1. 在Dockerfile中将外部jar复制到一个独立目录（不要放到/deployments/lib/main）：

COPY --chown=185 components/mycomponent/*.jar /deployments/external-lib/

2. 修改启动命令，添加-Dquarkus.class-path.append参数指定外部jar目录：

CMD ["java", "-Dquarkus.class-path.append=/deployments/external-lib/*.jar", "-jar", "/deployments/quarkus-run.jar"]

这样Quarkus启动时会将该目录下的所有jar加入类路径，类加载器就能找到对应的类。

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