Spring Boot打包Jar运行时抛出ClassNotFoundException: PDFBox相关类

你遇到的java.lang.ClassNotFoundException: org.apache.pdfbox.pdmodel.PDDocument，核心原因是Maven的system scope依赖默认不会被打包到Spring Boot的可执行Jar中。本地启动时IDE能自动识别项目根目录libs下的Jar包，所以运行正常；但执行maven clean compile package打包后，这些外部Jar并没有被包含在最终的application.jar里，其他系统运行时自然找不到对应的类。

方案1：改用Maven中央仓库依赖（推荐） #

PDFBox的官方依赖都在Maven中央仓库，完全没必要用本地Jar包。把pom.xml里的system scope相关配置删掉，改成普通依赖即可：

<dependency>
    <groupId>org.digidoc4j.dss</groupId>
    <artifactId>dss-pades-pdfbox</artifactId>
    <version>5.11.1.d4j.1</version>
</dependency>

<dependency>
    <groupId>org.apache.pdfbox</groupId>
    <artifactId>pdfbox-xmpbox</artifactId>
    <version>2.0.29</version>
</dependency>
<dependency>
    <groupId>org.apache.pdfbox</groupId>
    <artifactId>pdfbox-tools</artifactId>
    <version>2.0.29</version>
</dependency>
<dependency>
    <groupId>org.apache.pdfbox</groupId>
    <artifactId>pdfbox-examples</artifactId>
    <version>2.0.29</version>
</dependency>
<dependency>
    <groupId>org.apache.pdfbox</groupId>
    <artifactId>pdfbox</artifactId>
    <version>2.0.29</version>
</dependency>
<dependency>
    <groupId>org.apache.pdfbox</groupId>
    <artifactId>fontbox</artifactId>
    <version>2.0.29</version>
</dependency>
<dependency>
    <groupId>commons-logging</groupId>
    <artifactId>commons-logging</artifactId>
    <version>1.2</version>
</dependency>

修改后重新执行maven clean compile package，打包后的Jar会自动包含所有依赖，直接用java -jar application.jar就能正常运行。

方案2：必须使用本地libs目录的Jar包时 #

如果这些Jar是定制版，无法从中央仓库获取，需要配置Spring Boot Maven插件，强制将system scope的依赖打包进可执行Jar：
在pom.xml的build/plugins下添加Spring Boot插件的配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <includeSystemScope>true</includeSystemScope>
            </configuration>
        </plugin>
    </plugins>
</build>

这个配置会让Spring Boot插件把所有system scope的依赖都打包到最终的Jar中，解决运行时找不到类的问题。

另外，也可以把本地Jar安装到本地Maven仓库，命令示例：

mvn install:install-file -Dfile=./libs/pdfbox-2.0.29.jar -DgroupId=org.apache.pdfbox -DartifactId=pdfbox -Dversion=2.0.29 -Dpackaging=jar

每个本地Jar都执行类似命令，之后pom里的依赖就可以去掉systemPath和scope=system，和普通依赖一样使用。

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