1. 项目概述为什么PDF水印处理是个“技术活”给PDF文件加水印听起来是个挺简单的需求对吧不就是把一段文字或者一张图片盖在每一页的固定位置嘛。但真正动手做过的人都知道这里面的坑一个比一个深。特别是当你需要支持换行、旋转还要保证样式在各种复杂的PDF文档上都不错乱时事情就变得棘手了。我最早接手这类需求是在一个文档管理系统中。客户要求能批量给合同、报告加上包含多行信息的动态水印比如“内部传阅 - 部门销售部 - 日期2023-10-27”并且为了不影响正文阅读水印需要倾斜一定角度。一开始用了一些简单的库结果不是换行后对不齐就是旋转后文字跑到页面外或者在某些从Word转来的、版式复杂的PDF上水印直接“消失”在背景里。这些问题本质上是因为PDF的页面坐标系、内容层的叠加顺序Z-order以及字体嵌入的机制远比我们想象的要复杂。所以今天我们就来彻底拆解一下如何用Java实现一个支持自动换行、任意角度旋转并且能确保样式稳定、不跑偏的PDF水印方案。这个方案不仅适用于后台批量处理也能为需要动态生成带水印文档的Web应用提供核心能力。我们会从原理讲到实现从工具选型讲到避坑指南目标就是让你看完之后能直接拿去用并且清楚每一个步骤背后的“为什么”。2. 核心原理与工具选型为什么是iText要实现一个健壮的PDF水印功能我们首先得理解PDF的“图层”模型。你可以把一个PDF页面想象成一张画布上面的内容是一层一层叠加上去的。最底层是页面本身的内容文字、图片我们添加的水印通常需要放在一个单独的“图层”上并且这个图层应该位于所有内容之上或之下具体看你是要“覆盖”水印还是“背景”水印。2.1 为什么选择iText库Java领域处理PDF的库不少比如Apache PDFBox、iText、JPedal等。经过多次项目实战我最终将iText作为生产环境的首选原因如下对PDF标准的支持最全面、最严谨iText是PDF标准的核心贡献者之一它对PDF规范ISO 32000的实现非常精确。这意味着在处理字体、坐标、透明度、图层混合等复杂特性时iText的行为最可预测最不容易出现兼容性问题。而其他一些库可能在处理某些边缘情况时比如包含特定压缩算法的图片、复杂的字体子集会出现渲染错误。高性能与低内存占用iText在流式处理Stamper模式方面做得非常好。它允许我们打开一个已有的PDF在其上“盖章”添加水印然后直接输出而不需要将整个PDF文档完全加载到内存中重构。这对于处理几十、上百页的大文档以及高并发的服务器环境至关重要。精细的底层控制能力iText提供了从非常高级的用Paragraph、Image对象到非常底层的直接操作PdfContentByte图形指令API。实现复杂水印如旋转、精确换行恰恰需要这种底层控制能力。注意iText分为AGPL协议的社区版和商业授权的商业版。如果你的项目是开源且遵循AGPL的或者已购买商业许可可以放心使用。对于闭源的商业项目务必评估 licensing 风险。本文的示例基于AGPL v3协议的iText 7社区版com.itextpdf:itext7-core这是目前最活跃的版本。2.2 坐标系与旋转的核心概念这是保证水印“不错乱”的数学基础。PDF页面的默认坐标系原点(0, 0)在左下角X轴向右Y轴向上。这与很多图形库原点在左上角Y轴向下不同是第一个容易搞错的地方。当我们说“旋转水印”通常有两种理解旋转页面坐标系相当于把整张画布旋转一定角度然后在新坐标系下绘制水印。这样绘制的水印其文字基线方向随着坐标系改变了。旋转文字绘制矩阵在绘制每个文字或图形时通过变换矩阵Transformation Matrix来施加旋转而不改变整个页面的坐标系。这种方式更灵活也是我们通常采用的方式。iText的PdfCanvas由PdfContentByte演化而来提供了concatMatrix等方法来进行矩阵变换。一个常见的需求是将水印旋转45度并居中这涉及到坐标系平移、旋转、再平移回的逻辑计算公式需要精确。3. 实现详解从文字水印到多行旋转水印接下来我们分步实现一个功能完整的水印工具类。我们将实现两种常见水印平铺的单个文字/图标水印以及包含多行信息、可自动换行的文本块水印。3.1 基础环境搭建与依赖首先在你的Maven项目pom.xml中添加依赖dependency groupIdcom.itextpdf/groupId artifactIditext7-core/artifactId version7.2.5/version typepom/type /dependency如果你需要处理中文务必引入字体库因为PDF需要嵌入字体信息才能在所有设备上正确显示。我们可以使用操作系统字体但更推荐将字体文件如.ttf打包到资源目录下确保部署环境的一致性。dependency groupIdcom.itextpdf/groupId artifactIdfont-asian/artifactId version7.2.5/version /dependency3.2 核心工具类设计我们创建一个PdfWatermarkUtil类它提供静态方法核心方法签名如下public static void addTextWatermark(String sourcePdfPath, String targetPdfPath, WatermarkTextParams params); public static void addMultiLineWatermark(String sourcePdfPath, String targetPdfPath, WatermarkMultiLineParams params);我们先定义水印参数的配置类这是实现灵活性的关键import com.itextpdf.kernel.colors.Color; import com.itextpdf.kernel.colors.DeviceRgb; public class WatermarkTextParams { private String text; // 水印文字 private Color color new DeviceRgb(128, 128, 128); // 默认灰色 private float fontSize 48f; private float opacity 0.3f; // 不透明度0完全透明1完全不透明 private float rotationRadians (float) (Math.PI / 4); // 默认45度 // 平铺相关参数 private boolean tile true; // 是否平铺 private float horizontalSpacing 200f; // 水平间距 private float verticalSpacing 150f; // 垂直间距 // 字体 private PdfFont font; // 构造方法、getter、setter省略... }3.3 实现单个文字水印支持旋转与平铺这是最常见的水印形式比如“机密”、“草稿”字样倾斜地铺满整个页面。public static void addTextWatermark(String sourcePath, String destPath, WatermarkTextParams params) throws IOException { PdfDocument pdfDoc new PdfDocument(new PdfReader(sourcePath), new PdfWriter(destPath)); PdfFont font params.getFont() ! null ? params.getFont() : PdfFontFactory.createFont(StandardFonts.HELVETICA); int pageCount pdfDoc.getNumberOfPages(); for (int i 1; i pageCount; i) { PdfPage page pdfDoc.getPage(i); // 获取页面的原始尺寸 Rectangle pageSize page.getPageSize(); float width pageSize.getWidth(); float height pageSize.getHeight(); // 关键步骤获取PdfCanvas用于直接绘制 PdfCanvas canvas new PdfCanvas(page.newContentStreamBefore(), page.getResources(), pdfDoc); // 设置图形状态不透明度和混合模式 PdfExtGState gs new PdfExtGState(); gs.setFillOpacity(params.getOpacity()); canvas.setExtGState(gs); // 设置字体和颜色 canvas.setFontAndSize(font, params.getFontSize()); canvas.setFillColor(params.getColor()); // 核心逻辑计算平铺位置并绘制 if (params.isTile()) { float spacingX params.getHorizontalSpacing(); float spacingY params.getVerticalSpacing(); // 计算水印文本的宽度近似值用于布局 float textWidth font.getWidth(params.getText(), params.getFontSize()); // 平铺网格的起始偏移为了美观通常让第一个水印从页面外开始营造交错感 float offsetX -width / 2; float offsetY -height / 2; for (float y offsetY; y height * 1.5; y spacingY) { for (float x offsetX; x width * 1.5; x spacingX) { // 1. 保存当前绘图状态坐标系 canvas.saveState(); // 2. 将坐标系原点平移到当前绘制点 (x, y) canvas.concatMatrix(Matrix.getTranslateInstance(x, y)); // 3. 绕当前原点旋转指定角度 canvas.concatMatrix(Matrix.getRotateInstance(params.getRotationRadians())); // 4. 绘制文本。此时文本在旋转后的坐标系中其基线是水平的。 // 为了让文字以旋转点为中心通常需要再平移文本宽度的一半在旋转后的X轴上 canvas.beginText(); canvas.moveText(-textWidth / 2, 0); // 微调使文字中心大致在(x,y) canvas.showText(params.getText()); canvas.endText(); // 5. 恢复绘图状态坐标系回到页面初始状态准备画下一个水印 canvas.restoreState(); } } } else { // 如果不平铺只在页面中心画一个水印 canvas.saveState(); canvas.concatMatrix(Matrix.getTranslateInstance(width / 2, height / 2)); canvas.concatMatrix(Matrix.getRotateInstance(params.getRotationRadians())); canvas.beginText(); canvas.moveText(-font.getWidth(params.getText(), params.getFontSize()) / 2, 0); canvas.showText(params.getText()); canvas.endText(); canvas.restoreState(); } canvas.release(); // 释放资源 } pdfDoc.close(); }关键点解析与避坑newContentStreamBefore()vsnewContentStreamAfter()这决定了水印图层的位置。Before意味着水印内容会被添加到现有页面内容之下作为背景。After则添加在现有内容之上作为覆盖。大多数“水印”场景应该用Before。这是解决“水印遮盖正文”或“水印被图片遮挡”问题的关键。矩阵变换的顺序图形学中矩阵变换的应用顺序是相反的。代码中我们先平移(x, y)再旋转。这意味着旋转是绕平移后的新原点(x, y)进行的。这个顺序不能错否则水印会跑到莫名其妙的位置。saveState()和restoreState()这是图形绘制中的“栈”操作。saveState保存当前的坐标系状态、颜色、字体等设置restoreState恢复。在循环中为每个水印单独保存和恢复状态确保了它们之间互不干扰。忘记restoreState会导致后续绘制坐标系错乱是常见的错误。文本宽度计算font.getWidth()得到的是字符串在当前字体大小下未经旋转的宽度。当我们旋转后这个宽度值仅用于粗略的水平居中微调。对于精确的多行文本布局需要更复杂的计算。3.4 实现多行文本水印支持自动换行与整体旋转业务场景中更复杂的水印是多行信息块例如合同编号HT20231027001 甲方某某科技有限公司 签署日期2023-10-27 状态已归档我们需要这个文本块能自动换行每行宽度固定并且整个文本块可以作为一个整体进行旋转和定位。思路我们不能再用canvas.showText()直接画了因为换行逻辑复杂。iText的高级APICanvas注意不是底层的PdfCanvas和Paragraph可以帮我们轻松管理文本布局。但Canvas需要在指定的矩形区域内绘制并且其坐标系是“文本模式”我们需要巧妙地将它和底层的旋转矩阵结合起来。public static void addMultiLineWatermark(String sourcePath, String destPath, WatermarkMultiLineParams params) throws IOException { PdfDocument pdfDoc new PdfDocument(new PdfReader(sourcePath), new PdfWriter(destPath)); PdfFont font params.getFont() ! null ? params.getFont() : PdfFontFactory.createFont(StandardFonts.HELVETICA); int pageCount pdfDoc.getNumberOfPages(); for (int i 1; i pageCount; i) { PdfPage page pdfDoc.getPage(i); Rectangle pageSize page.getPageSize(); float width pageSize.getWidth(); float height pageSize.getHeight(); // 底层画布用于施加旋转 PdfCanvas pdfCanvas new PdfCanvas(page.newContentStreamBefore(), page.getResources(), pdfDoc); PdfExtGState gs new PdfExtGState(); gs.setFillOpacity(params.getOpacity()); pdfCanvas.setExtGState(gs); pdfCanvas.setFillColor(params.getColor()); // 1. 计算文本块在不旋转时所需的宽度和高度 // 我们创建一个虚拟的Paragraph来计算布局 Paragraph para new Paragraph(); for (String line : params.getLines()) { para.add(new Text(line \n).setFont(font).setFontSize(params.getFontSize())); } // 设置一个固定的最大宽度文本将在此宽度内自动换行 float maxTextBlockWidth params.getMaxWidth(); // 使用LayoutResult来模拟布局获取所需高度 IRenderer paraRenderer para.createRendererSubTree(); paraRenderer.setParent(new DocumentRenderer(new Document(pdfDoc))); // 需要设置一个虚拟的DocumentRenderer上下文 LayoutResult layoutResult paraRenderer.layout(new LayoutContext(new LayoutArea(1, new Rectangle(maxTextBlockWidth, 1000f)))); float textBlockHeight layoutResult.getOccupiedArea().getBBox().getHeight(); // 2. 确定文本块在页面上的期望位置例如右下角偏移20点 float desiredX width - params.getRightMargin() - maxTextBlockWidth; // 右下角X float desiredY params.getBottomMargin(); // 右下角Y // 注意这是文本块**左下角**的坐标。因为PDF坐标系Y轴向上。 // 3. 关键步骤进行坐标系变换使得在(desiredX, desiredY)位置绘制一个水平文本块然后整体旋转 pdfCanvas.saveState(); // 3.1 先将原点平移到期望的绘制点 pdfCanvas.concatMatrix(Matrix.getTranslateInstance(desiredX, desiredY)); // 3.2 然后旋转坐标系 pdfCanvas.concatMatrix(Matrix.getRotateInstance(params.getRotationRadians())); // 此时在当前的坐标系下(0,0)点就是我们想要的文本块位置并且坐标系已经旋转。 // 4. 在当前变换后的坐标系下创建一个固定大小的矩形区域作为文本画布 // 这个矩形的左下角是(0,0)宽度是maxTextBlockWidth高度是textBlockHeight Rectangle textRect new Rectangle(0, 0, maxTextBlockWidth, textBlockHeight); // 5. 在这个矩形区域内使用高级Canvas进行文本绘制。Canvas会自动处理换行。 Canvas canvas new Canvas(pdfCanvas, pdfDoc, textRect); // 重新构建Paragraph并添加到Canvas Paragraph paraToDraw new Paragraph(); for (String line : params.getLines()) { // 这里我们不再手动加\n让Paragraph根据宽度自动换行。如果需要强制分行则保留\n。 // 假设params.getLines()的每个元素就是一行我们手动换行。 paraToDraw.add(new Text(line).setFont(font).setFontSize(params.getFontSize())); paraToDraw.add(new Text(\n)); } paraToDraw.setOpacity(params.getOpacity()); canvas.add(paraToDraw); canvas.close(); // 完成绘制将内容刷新到底层PdfCanvas pdfCanvas.restoreState(); pdfCanvas.release(); } pdfDoc.close(); }关键点解析与避坑布局计算先行在应用旋转矩阵之前我们必须先知道文本块在水平状态下的精确尺寸maxTextBlockWidth和计算出的textBlockHeight。这是保证旋转后文本块不会“溢出”预期区域的关键。我们通过IRenderer.layout进行了一次“预布局”来获得高度。坐标系变换的魔力代码中最精妙的部分在于坐标系变换的顺序。我们先平移到目标点(desiredX, desiredY)再旋转。这意味着之后我们在新坐标系的原点(0,0)处绘制一个水平的文本块时这个文本块在原始的页面坐标系中看起来就是在(desiredX, desiredY)位置旋转后的样子。这比直接计算每个文字旋转后的坐标要简单和可靠得多。Canvas与PdfCanvas的协作Canvas是一个高级API它封装了文本布局、换行、分页等复杂逻辑。但它需要一个PdfCanvas作为底层绘制目标和一个Rectangle作为绘制区域。我们通过变换PdfCanvas的坐标系让Canvas在变换后的“局部坐标系”中工作从而轻松实现了整体旋转。换行与强制换行示例中假设传入的ListString lines的每个元素就是一行即强制换行。如果你传入一个长字符串希望自动换行只需构建一个Paragraph对象设置其宽度然后添加一个Text元素即可Paragraph会自动处理单词断字和换行。需要注意中英文混排时的换行规则差异。4. 字体、样式与性能优化4.1 中文字体处理乱码与嵌入的坑这是中文环境下的头号问题。如果不显式指定中文字体iText会使用默认字体通常是Helvetica它不包含中文字形导致中文显示为空白或乱码。解决方案将字体文件放入资源目录将.ttf或.otf字体文件如simsun.ttf宋体、simhei.ttf黑体放到项目的src/main/resources/fonts目录下。程序加载字体import com.itextpdf.io.font.PdfEncodings; import com.itextpdf.kernel.font.PdfFont; import com.itextpdf.kernel.font.PdfFontFactory; String fontPath fonts/simsun.ttf; // 资源路径 InputStream fontStream getClass().getClassLoader().getResourceAsStream(fontPath); PdfFont chineseFont PdfFontFactory.createFont(fontStream.readAllBytes(), PdfEncodings.IDENTITY_H, true);PdfEncodings.IDENTITY_H表示使用Unicode水平书写编码这是支持中文等复杂文字所必需的。第三个参数true表示将字体子集嵌入PDF文件。这非常重要嵌入后接收方即使没有安装该字体也能正确显示。不嵌入会导致在某些阅读器上显示异常。实操心得生产环境中建议将常用字体如宋体、黑体在应用启动时就加载并缓存为PdfFont实例避免每次处理PDF都重复读取字体文件影响性能。4.2 水印样式进阶透明度、颜色与混合模式透明度Opacity通过PdfExtGState.setFillOpacity()设置。值在0.0全透明到1.0不透明之间。通常水印设置在0.2到0.4之间既能看清又不喧宾夺主。颜色Color除了灰色常用的是浅红色new DeviceRgb(255, 0, 0)或浅蓝色new DeviceRgb(0, 0, 255)并配合较低的透明度。混合模式Blend Mode通过PdfExtGState.setBlendMode()可以设置水印与下层内容的混合效果如BlendMode.MULTIPLY正片叠底、BlendMode.SCREEN滤色等可以创造出不同的视觉效果。但需谨慎使用避免影响正文可读性。4.3 性能优化要点资源复用PdfFont、常用Color对象应该在循环外创建并复用。流式处理始终坚持使用PdfReader和PdfWriter配合让iText以流的方式处理避免用PdfDocument的byte[]构造函数将整个文件读入内存。及时释放对于PdfCanvas和Canvas在绘制完成后调用release()或close()是个好习惯。批量处理对于大批量文件考虑使用线程池但要注意每个线程独立的PdfDocument实例避免共享导致状态混乱。5. 常见问题排查与实战技巧即使按照上面的步骤在实际部署中你还是可能遇到一些诡异的问题。下面是我踩过的一些坑和解决方案。5.1 水印在特定PDF上不显示或位置错误可能原因1PDF有裁剪框CropBox或艺术框ArtBox。排查使用page.getCropBox()或page.getMediaBox()查看页面实际使用的边界框。getPageSize()默认返回的是MediaBox。解决绘制水印时以page.getCropBox()的坐标作为参考系而不是page.getPageSize()。计算位置时要基于CropBox的原点。Rectangle effectiveBox page.getCropBox() ! null ? page.getCropBox() : page.getMediaBox(); float width effectiveBox.getWidth(); float height effectiveBox.getHeight(); // 计算位置时也要考虑effectiveBox.getLeft()和effectiveBox.getBottom()作为偏移。 float baseX effectiveBox.getLeft(); float baseY effectiveBox.getBottom();可能原因2PDF内容本身是扫描的图片。现象水印添加成功但被图片完全覆盖。解决确保使用newContentStreamBefore()将水印作为背景添加。如果必须作为前景可能需要调整现有内容的图形状态这非常复杂且可能破坏原文档。通常背景水印是更安全的选择。5.2 旋转后文字模糊或有锯齿可能原因字体未嵌入或嵌入方式问题。排查用Adobe Acrobat等专业工具检查生成PDF的字体属性看所需字体是否已“嵌入子集”。解决确保创建PdfFont时第三个参数嵌入设置为true。对于旋转和缩放后的文字使用TrueType或OpenType字体.ttf/.otf比Type 1字体效果更好。5.3 多行水印换行后行间距异常或重叠可能原因手动计算高度不准确或Paragraph样式冲突。排查检查预布局时使用的maxTextBlockWidth是否与最终绘制时Canvas的矩形宽度一致。检查Paragraph是否设置了额外的Margin、Padding或Leading行距。解决在预布局和实际绘制时使用完全相同的Paragraph对象或配置。显式设置行距para.setFixedLeading(leadingValue);。Leading通常设置为字体大小的1.2到1.5倍。如果行间是简单的\n确保没有额外的MarginTop/MarginBottom。5.4 内存消耗过大OutOfMemoryError场景处理一个几百页且包含大量高分辨率图片的PDF。解决检查iText版本使用最新的iText 7它在内存管理上比iText 5有显著优化。确保使用Stamper模式确认你是用PdfReader和PdfWriter配对而不是用PdfDocument的byte[]构造函数。调整JVM参数适当增加堆内存-Xmx。分片处理对于极端大的文件可以考虑先分割PDF分别加水印再合并但这本身也是耗资源的操作。5.5 水印添加后文件体积暴增可能原因字体完全嵌入而非子集嵌入。排查创建字体时使用了PdfFontFactory.createFont(fontPath, PdfEncodings.IDENTITY_H, false)第三个参数为false表示不嵌入。但更常见的是虽然嵌入了但嵌入的是整个字体文件如果iText无法提取子集。解决对于中文等大字库字体务必使用true进行子集嵌入。iText会自动只将PDF中实际用到的字形嵌入大幅减少体积。如果字体文件本身有问题导致无法提取子集尝试更换一个标准、无损坏的字体文件。最后分享一个调试小技巧当你对水印的位置或旋转效果不确定时可以先用一个醒目的、不透明的红色矩形代替文字进行绘制这样可以直观地看到你定义的矩形区域和旋转中心到底在哪里快速定位坐标计算的问题。确认位置正确后再换回半透明的文字水印。这个技巧在调试复杂布局时非常管用。