升级PDFBox至3.0.2后出现异常，PDF报告无法生成求助

第一步：修复缺失的核心依赖 #

从异常栈可见java.lang.ClassNotFoundException: org.apache.commons.logging.LogFactory，这是因为PDFBox 3.x版本依赖Apache Commons Logging组件，你的项目未引入该依赖导致：

• 若使用Maven，在pom.xml中添加依赖：

<dependency>
    <groupId>commons-logging</groupId>
    <artifactId>commons-logging</artifactId>
    <version>1.2</version>
</dependency>

• 若使用Gradle，在build.gradle中添加：

implementation 'commons-logging:commons-logging:1.2'

第二步：适配PDFBox 3.x的API变更 #

PDFBox 3.0相对于2.0有大量API调整，需重点检查以下场景：

• 字体加载：2.x的PDType1Font.load()等方法已过时，3.x推荐使用PDType0Font.load(PDDocument, InputStream)加载自定义字体，内置字体可直接使用静态实例（如PDType1Font.HELVETICA）。
• 资源管理：3.x中PDDocument.close()会自动关闭关联的资源流，无需手动关闭字体、内容流等资源，避免资源泄漏。
• 内容流操作：PDPageContentStream的构造参数、文本绘制方法的重载逻辑有调整，需确保代码调用符合3.x的方法签名。

第三步：排查依赖冲突 #

检查项目中是否存在旧版本的PDFBox或其依赖组件（如fontbox、commons-logging），通过依赖分析工具确认所有PDFBox相关依赖均为3.0.2版本：

# Maven 查看依赖树
mvn dependency:tree | grep -i pdfbox
# Gradle 查看依赖
./gradlew dependencies | grep -i pdfbox

若发现冲突，需在依赖配置中排除旧版本组件。

第四步：验证最小化用例 #

先编写极简代码验证环境是否正常：

import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.PDPage;
import org.apache.pdfbox.pdmodel.PDPageContentStream;
import org.apache.pdfbox.pdmodel.font.PDType1Font;

import java.io.File;

public class TestPDFGen {
    public static void main(String[] args) throws Exception {
        try (PDDocument doc = new PDDocument()) {
            PDPage page = new PDPage();
            doc.addPage(page);
            try (PDPageContentStream contentStream = new PDPageContentStream(doc, page)) {
                contentStream.beginText();
                contentStream.setFont(PDType1Font.HELVETICA, 12);
                contentStream.newLineAtOffset(100, 700);
                contentStream.showText("PDFBox 3.0.2 Test");
                contentStream.endText();
            }
            doc.save(new File("test.pdf"));
        }
    }
}

若该用例能正常生成PDF，再逐步迁移业务代码，定位具体的API兼容问题。

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