Apache PDFBox 3文本渲染前出现额外空白问题求助

PDFBox 3.x对文本渲染的初始状态逻辑做了调整，和2.x版本的默认行为不一致，这就是你遇到额外内边距/空白行的核心原因。以下是经过验证的解决方案：

1. 显式指定文本起始坐标，抛弃默认位置 #

PDFBox 2.x中beginText()后的默认文本位置可能更贴近预期，但3.x版本修改了文本矩阵的初始值，导致默认起始位置存在偏移。解决方法是在调用beginText()后立刻通过newLineAtOffset()或setTextMatrix()明确设置坐标：

try (PDPageContentStream contentStream = new PDPageContentStream(doc, page)) {
    contentStream.beginText();
    contentStream.setFont(pdFont, 12);
    
    // 基于页面媒体框计算起始位置（左下角为原点，向上为Y轴正方向）
    PDRectangle mediaBox = page.getMediaBox();
    float leftMargin = 50;
    float topMargin = 50;
    float startX = mediaBox.getLowerLeftX() + leftMargin;
    float startY = mediaBox.getUpperRightY() - topMargin;
    
    // 直接设置初始文本位置
    contentStream.newLineAtOffset(startX, startY);
    
    contentStream.setLeading(14);
    contentStream.showText("第一行文本");
    contentStream.newLine();
    contentStream.showText("第二行文本");
    contentStream.endText();
}

2. 重置文本状态，避免累积偏移 #

如果你的代码中多次调用beginText()/endText()，或者使用了追加模式（PDPageContentStream构造器的append参数为true），需要在每次beginText()后显式重置文本矩阵，防止之前的文本状态残留：

contentStream.beginText();
// 重置文本矩阵为初始状态
contentStream.setTextMatrix(Matrix.getTranslateInstance(0, 0));
// 再设置自定义起始位置
contentStream.newLineAtOffset(startX, startY);

3. 检查页面边界的处理逻辑 #

PDFBox 3.x对页面的CropBox、MediaBox处理更严格，如果你之前的代码硬编码了页面尺寸（比如直接用612,792），改成动态获取页面实际边界：

// 优先用CropBox，没有则用MediaBox
PDRectangle pageRect = page.getCropBox() != null ? page.getCropBox() : page.getMediaBox();
float startX = pageRect.getLowerLeftX() + leftMargin;
float startY = pageRect.getUpperRightY() - topMargin;

4. 避免误用newLine() #

PDFBox 3.x中newLine()会严格按照当前leading值偏移，如果你在showText()之前调用了newLine()，会直接产生空白行，检查代码中是否有多余的newLine()调用。

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