Java PDF水印实战：基于PDFBox实现自动换行与旋转的稳定方案-平芜编程栈

1. 项目缘起：为什么一个PDF水印功能能让人“贼透彻”？

最近在做一个内部文档管理系统，客户提了个需求：所有对外分发的PDF报告，都必须自动加上包含“内部传阅，严禁外泄”和生成时间的水印。听起来很简单对吧？我一开始也是这么想的，直接上手用了网上最常见的iText库，几行代码就把文字怼上去了。结果测试发回来的PDF，水印要么在换行处被截断，要么在旋转后字体样式变得模糊不清，更别提多页文档里水印位置飘忽不定了。那一刻我才明白，一个“能用”的水印和一个“好用且稳定”的水印，中间隔着一整个太平洋。

这个“贼透彻”的体验，正是来自于把这些坑一个个填平的过程。它不仅仅是调用一个API，而是涉及到PDF的坐标系理解、字体渲染机制、内容层的叠加顺序，以及如何在不同页面尺寸下保持一致性。网上很多教程只告诉你“怎么做”，但没告诉你“为什么这么做”以及“这么做可能会遇到什么”。今天，我就把自己从踩坑到填坑的全过程，结合代码和原理，掰开揉碎了讲清楚。无论你是需要给合同加“草稿”水印，还是给设计稿加版权信息，这篇都能让你彻底搞懂，实现一个支持自动换行、任意角度旋转且样式绝对稳定的Java PDF水印方案。

2. 核心武器库选型：为什么是Apache PDFBox？

做PDF处理，Java生态里主要有几个选择：老牌的iText、Apache旗下的PDFBox，以及一些商业库。我最终选择了Apache PDFBox 3.0，原因有以下几点，这也是你在做技术选型时需要考量的维度。

2.1 开源与许可的绝对优势

iText在早期版本（如2.x）是LGPL/MPL许可，但到了5.x及以后的商业版本，其AGPL许可非常严格，简单说，如果你的项目不是完全开源的，哪怕内部使用，也可能需要购买商业许可。这对于大多数商业项目来说是个潜在的法律风险和高昂成本。而Apache PDFBox始终采用宽松的Apache License 2.0，完全免费用于商业闭源项目，这一点就让它成为了企业级应用的首选。

2.2 功能与稳定性的平衡

PDFBox是一个纯Java库，不依赖本地组件，跨平台部署零成本。它提供了从创建、渲染、编辑到提取文本的全套功能。对于水印这种“编辑”操作，PDFBox的底层API给了我们极大的灵活性。我们可以直接操作PDF的内容流（Content Stream），像画家一样在页面的任何位置、以任何变换（旋转、缩放）绘制内容。这种底层能力是实现复杂水印（如倾斜、平铺）的基础。

2.3 社区与未来

作为Apache顶级项目，PDFBox有活跃的社区和持续的维护。3.x版本重写了大量内部架构，性能和对现代PDF特性的支持（如透明度、字体嵌入）更好。选择它，意味着你的代码在未来几年内都能获得良好的兼容性和支持。

注意：如果你正在使用iText 7（其社区版是AGPL），并且项目性质允许，它也是一个强大的选择。但本文基于PDFBox的解决方案，其思路和原理是相通的，你可以举一反三。

2.4 环境准备与依赖

在你的Maven项目pom.xml中添加以下依赖。建议使用3.x的最新版本，以获得更好的性能和API。

<dependency> <groupId>org.apache.pdfbox</groupId> <artifactId>pdfbox</artifactId> <version>3.0.2</version> </dependency>

如果你用的是Gradle，则是：

implementation 'org.apache.pdfbox:pdfbox:3.0.2'

3. 深入PDF坐标系：水印定位的基石

几乎所有水印位置错乱的问题，根源都在于对PDF坐标系的理解偏差。这一步没搞透，后面代码写得再漂亮也是空中楼阁。

3.1 与屏幕坐标的致命差异

我们熟悉的计算机屏幕坐标系，原点(0,0)通常在左上角，Y轴向下为正。但PDF采用的笛卡尔坐标系，原点(0,0)默认在页面的左下角，X轴向右为正，Y轴向上为正。这是一个根本性的区别。

假设你有一张A4纸（约595×842点，点是PDF的常用单位，1点=1/72英寸）。那么，这张纸左下角坐标是(0,0)，右上角坐标是(595,842)。如果你想在页面正中央画点东西，坐标应该是(297.5, 421)，而不是我们直觉中的屏幕中央算法。

3.2 内容流与变换矩阵（Transformation Matrix）

PDF页面上的所有图形、文字，都是通过一系列操作命令绘制在“内容流”（Content Stream）中的。其中，cm命令（Concatenate Matrix）是控制坐标系变换的核心。它通过一个3x3的变换矩阵，可以实现平移、旋转、缩放、错切等效果。

当我们想旋转水印时，并不是去旋转已经画好的文字，而是先旋转整个坐标系，然后在旋转后的新坐标系中绘制文字。理解这一点至关重要。例如，先执行旋转30度的变换，再在(100,100)位置绘制“水印”二字，那么“水印”二字就会相对于原始坐标系旋转30度。

3.3 确定水印的“锚点”

在绘制任何内容前，你必须明确一个“锚点”。对于文字，这个锚点通常是基线的起点（对于水平文字，是左下角；但受字体影响，更准确的是文本矩阵的位置）。当我们说“把水印放在页面中心”，指的是水印包围框（Bounding Box）的中心与页面中心对齐，还是文字基线的起点与页面中心对齐？这会导致完全不同的视觉效果。我们的方案需要计算文本的精确宽度和高度，来实现真正的居中。

4. 实现核心：支持换行与旋转的稳健水印引擎

下面我们一步步构建这个水印引擎。我将一个功能完整的PdfWatermarkUtil工具类拆解开来讲解。

4.1 骨架与参数设计

首先，我们设计一个包含所有必要参数的数据类或工具类方法。这些参数决定了水印的最终表现。

import org.apache.pdfbox.pdmodel.PDDocument; import org.apache.pdfbox.pdmodel.PDPage; import org.apache.pdfbox.pdmodel.PDPageContentStream; import org.apache.pdfbox.pdmodel.common.PDRectangle; import org.apache.pdfbox.pdmodel.font.PDFont; import org.apache.pdfbox.pdmodel.font.PDType1Font; import org.apache.pdfbox.pdmodel.graphics.state.PDExtendedGraphicsState; import org.apache.pdfbox.util.Matrix; import java.io.IOException; import java.util.List; public class PdfWatermarkUtil { /** * 添加水印核心方法 * * @param document PDF文档对象 * @param text 水印文本，支持用\n换行 * @param font 字体 * @param fontSize 字体大小 * @param opacity 透明度 (0.0f - 1.0f) * @param rotationAngle 旋转角度（度），如30, 45, -15 * @param isTiled 是否平铺（true为平铺满整个页面） * @param tileSpacingX 平铺时水平间距（点） * @param tileSpacingY 平铺时垂直间距（点） * @throws IOException */ public static void addWatermark(PDDocument document, String text, PDFont font, float fontSize, float opacity, float rotationAngle, boolean isTiled, float tileSpacingX, float tileSpacingY) throws IOException { // 后续实现... } }

4.2 单页水印绘制：攻克换行与居中的难点

我们先实现最核心的单次绘制功能，即在页面的指定坐标（x, y）绘制一段可能包含换行符（\n）的文本，并使其围绕自身中心点旋转。

难点在于：1. 准确计算多行文本的总宽度和总高度。2. 实现以文本块中心为轴心的旋转。

/** * 在指定位置绘制一段文本（支持换行），并使其绕自身中心旋转指定角度。 * * @param contentStream 页面内容流 * @param text 文本（可含\n） * @param font 字体 * @param fontSize 字号 * @param x 绘制锚点的原始X坐标（旋转前，通常期望是文本块中心） * @param y 绘制锚点的原始Y坐标（旋转前，通常期望是文本块中心） * @param rotationAngle 旋转角度（度） */ private static void drawRotatedText(PDPageContentStream contentStream, String text, PDFont font, float fontSize, float x, float y, float rotationAngle) throws IOException { // 1. 按换行符分割文本 String[] lines = text.split("\n"); // 2. 计算文本块的宽度和高度 float maxLineWidth = 0; for (String line : lines) { float lineWidth = font.getStringWidth(line) / 1000 * fontSize; if (lineWidth > maxLineWidth) { maxLineWidth = lineWidth; } } // 行高通常取字体的1.2倍作为舒适间距 float lineHeight = font.getFontDescriptor().getFontBoundingBox().getHeight() / 1000 * fontSize * 1.2f; float totalHeight = lines.length * lineHeight; // 3. 计算文本块左上角起始坐标（便于后续计算） // 因为我们希望传入的(x,y)是文本块中心，所以需要偏移。 float startX = x - (maxLineWidth / 2); float startY = y + (totalHeight / 2) - lineHeight; // 从第一行的基线开始 // 4. 关键步骤：应用旋转变换 // 先将坐标系平移到文本中心点(x, y)，然后旋转，再平移回绘图起点(startX, startY) // 这个顺序保证了旋转是围绕文本中心进行的。 Matrix rotationMatrix = Matrix.getRotateInstance(Math.toRadians(rotationAngle), x, y); contentStream.transform(rotationMatrix); // 5. 绘制每一行文本 float currentY = startY; for (String line : lines) { if (!line.isEmpty()) { // 计算该行文本的宽度，用于水平居中 float lineWidth = font.getStringWidth(line) / 1000 * fontSize; float lineStartX = startX + (maxLineWidth - lineWidth) / 2; contentStream.beginText(); contentStream.setFont(font, fontSize); contentStream.newLineAtOffset(lineStartX, currentY); contentStream.showText(line); contentStream.endText(); } currentY -= lineHeight; // Y轴向上为正，所以减行高 } // 6. 恢复坐标系（通过应用旋转矩阵的逆矩阵） // 更安全的做法是在绘制水印前保存图形状态（gsave），绘制后恢复（grestore）。 // 我们在外层方法统一处理。 }

实操心得：计算文本宽度时，font.getStringWidth(string) / 1000 * fontSize是标准公式。除以1000是因为PDF中字体度量单位是“千分之一字体单位”。行高的计算没有绝对标准，1.2f是一个经验值，你可以根据字体和视觉效果调整。getFontBoundingBox().getHeight()获取的是字体的最大上升和下降高度之和，作为行高基准比较可靠。

4.3 平铺水印与页面遍历

接下来，我们实现addWatermark方法的主体，处理透明度、平铺逻辑和遍历所有页面。

public static void addWatermark(PDDocument document, String text, PDFont font, float fontSize, float opacity, float rotationAngle, boolean isTiled, float tileSpacingX, float tileSpacingY) throws IOException { // 设置图形状态：透明度 PDExtendedGraphicsState graphicsState = new PDExtendedGraphicsState(); graphicsState.setNonStrokingAlphaConstant(opacity); graphicsState.setStrokingAlphaConstant(opacity); // 描边透明度也设置，更全面 List<PDPage> pages = document.getDocumentCatalog().getPages(); for (PDPage page : pages) { PDRectangle mediaBox = page.getMediaBox(); float pageWidth = mediaBox.getWidth(); float pageHeight = mediaBox.getHeight(); try (PDPageContentStream contentStream = new PDPageContentStream(document, page, PDPageContentStream.AppendMode.APPEND, true, // 压缩内容流 true)) { // 重置上下文 // 应用全局图形状态（透明度） contentStream.setGraphicsStateParameters(graphicsState); if (isTiled) { // --- 平铺模式 --- // 计算单个水印文本块的大小（用于平铺间距） String[] lines = text.split("\n"); float maxLineWidth = 0; for (String line : lines) { float lineWidth = font.getStringWidth(line) / 1000 * fontSize; maxLineWidth = Math.max(maxLineWidth, lineWidth); } float lineHeight = font.getFontDescriptor().getFontBoundingBox().getHeight() / 1000 * fontSize * 1.2f; float watermarkWidth = maxLineWidth; float watermarkHeight = lines.length * lineHeight; // 考虑到旋转后水印的包围盒会变大，我们需要一个更宽松的起始点和步进计算。 // 一个简单有效的策略：以未旋转的水印尺寸加上间距作为网格，在每个网格点绘制。 // 更精确的做法是计算旋转后的外接矩形，但为简化，我们使用放大后的安全区域。 float effectiveWidth = watermarkWidth + tileSpacingX; float effectiveHeight = watermarkHeight + tileSpacingY; // 在页面范围内循环平铺 for (float x = effectiveWidth / 2; x < pageWidth; x += effectiveWidth) { for (float y = effectiveHeight / 2; y < pageHeight; y += effectiveHeight) { // 在绘制每个水印前保存状态，确保旋转互不干扰 contentStream.saveGraphicsState(); drawRotatedText(contentStream, text, font, fontSize, x, y, rotationAngle); contentStream.restoreGraphicsState(); } } } else { // --- 单次居中模式 --- contentStream.saveGraphicsState(); float centerX = pageWidth / 2; float centerY = pageHeight / 2; drawRotatedText(contentStream, text, font, fontSize, centerX, centerY, rotationAngle); contentStream.restoreGraphicsState(); } } // contentStream自动关闭 } }

4.4 关键技巧解析：saveGraphicsState与restoreGraphicsState

这是保证样式（尤其是坐标系变换）不混乱的生命线。saveGraphicsState()（对应PDF操作符q）将当前的图形状态（包括坐标系变换矩阵、颜色、线条样式等）压入堆栈。restoreGraphicsState()（对应Q）将其弹出恢复。

在平铺循环中，每绘制一个水印前都save，绘制后立即restore。这样，无论drawRotatedText内部对坐标系做了多么复杂的旋转和平移，都不会影响到下一个水印的绘制起点。如果没有这个操作，第二个水印会在第一个水印旋转后的坐标系基础上继续变换，导致位置和角度完全失控。

5. 字体与样式：水印清晰度的保障

水印模糊、乱码，很多时候是字体问题。

5.1 使用标准字体还是嵌入字体？

PDType1Font提供了14种PDF标准字体（如HELVETICA,TIMES_ROMAN），它们在任何PDF阅读器中都存在，无需嵌入，文件小。但缺点是中文不支持，且样式固定。

PDFont font = PDType1Font.HELVETICA_BOLD; // 加粗的无衬线字体，适合水印

如果你的水印包含中文或特殊字符，必须嵌入字体。否则，这些字符要么不显示，要么被替换为乱码。

// 加载外部字体文件（如.ttf） PDType0Font font = PDType0Font.load(document, new File("path/to/your/SourceHanSansCN-Regular.ttf"));

踩坑实录：我曾直接用PDType1Font.HELVETICA写中文水印，生成PDF在开发机上看是好的（因为系统有字体），但发给别人就变成了方框。根本原因是PDF内部没有中文字形信息，依赖阅读器环境。所以，只要水印文本可能包含非标准字体字符，务必嵌入字体。

5.2 字体嵌入的副作用与优化

嵌入字体会显著增加PDF文件大小，尤其是中文字体文件很大。优化策略：

子集化：PDFBox在加载PDType0Font时，默认只会嵌入文本中实际用到的字符（子集），这能极大减小体积。
使用轻型字体：水印不需要太花哨的字体，选择文件体积较小的字体文件。
权衡：如果水印只是简单的英文和数字，优先使用标准字体。

5.3 颜色与透明度

水印颜色通常设为浅灰色，避免喧宾夺主。通过PDExtendedGraphicsState设置透明度（setNonStrokingAlphaConstant）是推荐做法，它比直接设置带透明度的颜色更标准、兼容性更好。

// 设置颜色（RGB，每个分量0-1） contentStream.setNonStrokingColor(0.75f, 0.75f, 0.75f); // 浅灰色 // 透明度已在graphicsState中统一设置

6. 实战整合与调用示例

让我们把上面的代码整合成一个完整的、可直接运行的示例。假设我们要给一个PDF的每一页都加上倾斜45度、半透明的“内部资料”水印，并且平铺满页面。

import org.apache.pdfbox.Loader; import org.apache.pdfbox.pdmodel.PDDocument; import org.apache.pdfbox.pdmodel.font.PDType1Font; import java.io.File; import java.io.IOException; public class PdfWatermarkDemo { public static void main(String[] args) { String inputPdfPath = "input.pdf"; String outputPdfPath = "output_with_watermark.pdf"; String watermarkText = "内部资料 - 严禁外传\n" + new java.text.SimpleDateFormat("yyyy-MM-dd").format(new java.util.Date()); try (PDDocument document = Loader.loadPDF(new File(inputPdfPath))) { // 1. 定义水印参数 PDFont font = PDType1Font.HELVETICA_BOLD; // 使用标准字体 float fontSize = 40; float opacity = 0.3f; // 30%透明度 float rotationAngle = 45f; // 旋转45度 boolean isTiled = true; float spacingX = 200; // 水平间距 float spacingY = 150; // 垂直间距 // 2. 调用工具类添加水印 PdfWatermarkUtil.addWatermark(document, watermarkText, font, fontSize, opacity, rotationAngle, isTiled, spacingX, spacingY); // 3. 保存文档 document.save(outputPdfPath); System.out.println("水印添加成功，文件保存至: " + outputPdfPath); } catch (IOException e) { System.err.println("处理PDF时发生错误: " + e.getMessage()); e.printStackTrace(); } } }

运行这段代码，你将得到一个每一页都布满了倾斜、半透明、自动换行水印的新PDF文件。

7. 进阶话题与性能调优

当你的PDF页数成百上千，或者水印非常复杂时，性能问题就会凸显。

7.1 内容流压缩与追加模式

注意我们创建PDPageContentStream时传递的参数：

AppendMode.APPEND：将新内容追加到页面现有内容之后。这是添加水印的正确模式，确保水印在最上层。
true：启用压缩。这会让生成的内容流经过压缩，稍微增加CPU时间，但能显著减小最终PDF的文件大小，通常建议开启。
true：重置上下文。这确保我们从一个干净的图形状态开始，避免受到页面原有绘制命令的干扰，对于水印这种独立操作更安全。

7.2 避免重复计算

在平铺模式下，我们对于每个水印都在drawRotatedText内部重新计算了文本尺寸。如果水印文本固定，这是一个巨大的浪费。优化方法是在循环外预先计算好maxLineWidth、lineHeight、watermarkWidth、watermarkHeight，然后作为参数传入。

7.3 大文件处理与内存管理

PDDocument.load()会尝试将整个PDF加载到内存。对于超大型PDF，这可能引发OutOfMemoryError。

使用内存映射文件方式加载（如果PDFBox和系统支持），可以减少堆内存压力。
考虑分页处理：对于极端情况，可以设计一个流式处理流程，读一页，处理一页，写一页，然后释放该页资源。但这需要更复杂的文档重组逻辑。
确保在finally块或try-with-resources中关闭PDDocument，这是释放底层资源（如字体、图片）的关键。

7.4 水印的“不可移除性”探讨

需要明确一点：本文实现的是视觉上的水印，它作为页面内容的一部分被绘制上去。一个具备一定技术知识的用户，仍然可以使用PDF编辑工具（甚至是用PDFBox、iText自己写程序）去分析并删除对应的内容流操作。要实现商业级别的“防移除”水印，通常需要：

多层混合：将水印文字打散为多条路径（strokePath）并与背景图混合，增加识别和移除难度。
作为背景：将水印写入页面的最底层内容流，但这样容易被上层内容遮挡。
数字签名与权限：通过PDF的数字签名和文档权限设置（禁止修改），从机制上保护内容。但这已超出纯水印生成的范畴。

对于绝大多数“声明版权”或“标识状态”的内部需求，视觉水印已经足够。

8. 避坑指南：那些让我“贼透彻”的典型问题

8.1 水印位置在每页飘忽不定

现象：水印在第一页位置正确，后面几页却跑偏了。
根因：没有在绘制每个水印前重置图形状态。页面原有的变换矩阵（可能来自之前的绘制操作）影响了你的水印坐标。
解决：在drawRotatedText方法调用前，务必使用contentStream.saveGraphicsState()，并在调用后使用contentStream.restoreGraphicsState()。如上文所述，这是隔离变换的关键。

8.2 旋转后文字模糊或锯齿严重

现象：文字旋转后，边缘出现明显的锯齿。
根因：PDF阅读器的渲染问题。对于旋转的文字，尤其是非90度倍数的旋转，如果字体没有嵌入轮廓信息（如标准Type1字体），或者阅读器抗锯齿设置不当，就会模糊。
解决：
1. 尝试使用PDType0Font嵌入TrueType或OpenType字体，这些字体的轮廓信息更完整。
2. 确保PDPageContentStream在绘制文本时使用了contentStream.setRenderingMode(RenderingMode.FILL_STROKE)？不，对于普通水印，保持默认的FILL模式即可。模糊更多是渲染器问题，可以尝试在代码中明确设置contentStream.setLineWidth(0.5f)并采用FILL模式，有时有改善。但根本上是阅读器端的限制。

8.3 换行符\n不生效，文本挤在一行

现象：输入的文本包含\n，但PDF上显示为空格或直接连在一起。
根因：PDFBox的showText方法本身不解析换行符。它只负责绘制给定的字符串。你必须手动处理换行逻辑。
解决：这正是我们在drawRotatedText方法里做的：用split("\n")分割字符串，然后分别计算每一行的位置并依次绘制。这是唯一正确的方法。

8.4 添加水印后文件体积暴增

现象：一个1MB的PDF，加水印后变成10MB。
根因：
1. 嵌入了大型字体（尤其是中文字体）。
2. 平铺水印数量极多，产生了海量的绘制指令。
3. 没有开启内容流压缩。
解决：
1. 评估是否必须使用嵌入字体。如果只是英文数字，换标准字体。
2. 调整平铺密度（tileSpacingX/Y），在可见性和文件大小间取得平衡。
3. 确保创建PDPageContentStream时第二个参数为true以启用压缩。
4. 考虑使用更简单的“单页居中”水印模式。

8.5OutOfMemoryError处理大PDF时内存不足

现象：处理几百页的PDF时程序崩溃。
根因：默认加载方式将整个文档结构（包括所有资源）载入堆内存。
解决：
1. 增加JVM堆内存：-Xmx1024m或更大。
2. 使用Loader.loadPDF(new File(...), memoryUsageSetting)，并配置MemoryUsageSetting.setupTempFileOnly()或setupMixed(100 * 1024 * 1024)，允许PDFBox使用临时文件来交换部分数据，减少内存占用。这是处理大文件的首选方案。

import org.apache.pdfbox.io.MemoryUsageSetting; // ... try (PDDocument document = Loader.loadPDF(new File(inputPdfPath), MemoryUsageSetting.setupTempFileOnly())) { // 处理文档 }

走完这一整套从原理、选型、实现、优化到排坑的流程，你对Java实现PDF水印的理解，应该不再是停留在API调用层面，而是真正洞悉了其背后的坐标系、图形状态、字体渲染和文件结构。下次再遇到水印相关的奇葩问题，你就能像老中医一样，一眼看穿病灶所在。这份“透彻”，才是解决一切复杂问题的底气。