1. 环境准备
1.1 Java 开发环境与版本建议
目标环境是搭建一个稳定的 Java 开发与运行环境，用于实现“Java 添加 PDF 水印”的完整流程。推荐使用 JDK 11 及以上版本，以获得更好的 API 支持和长期维护性。确保系统变量中正确配置 JAVA_HOME，并将 java 与 javac 命令加入到系统 PATH 中。
关键要点包括：确认 JVM 版本、配置环境变量、以及在 IDE 中选择合适的 JDK 进行编译和运行。若你使用多版本 JDK，请通过命令行验证默认 JDK 是否符合需求，例如执行 java -version 与 javac -version，并确保两者一致。
1.2 构建工具与依赖管理
Maven/Gradle 是常见的依赖管理工具，本文以 Maven 为示例，帮助你把 PDF 处理库引入到项目中，从而实现 Java 添加 PDF 水印 的核心功能。
在 pom.xml 中添加 PDF 处理库依赖后，可以通过 mvn clean package 快速构建可执行包。下面的依赖片段用于引入 PDF 处理能力，帮助你实现文本水印的绘制与页面遍历。
<dependencies><dependency><groupId>org.apache.pdfbox</groupId><artifactId>pdfbox</artifactId><version>2.0.27</version></dependency>
</dependencies>2. 项目搭建与依赖配置
2.1 项目结构与示例
简单的工程结构应包含源代码目录 src/main/java、资源目录 src/main/resources、测试目录 src/test。在实现 Java 添加 PDF 水印 的功能时，通常需要一个主入口类（如 WatermarkMain）来触发水印添加过程，并提供输入输出参数。
目标要点是确保程序能够找到输入的 PDF 文件、输出路径，以及水印文本或图片的配置项。合理的工程结构有助于后续的维护与扩展，例如支持图片水印、不同旋转角度等。最终实现应具备清晰的 API 调用入口，便于测试与二次开发。
2.2 引入与管理 PDFBox 依赖
关键步骤包括在构建工具中声明第三方库依赖，并让构建系统在编译阶段自动下载所需的 jar 文件。PDFBox 提供开源实现，适用于在 Java 应用中对 PDF 进行修改，如添加文本水印、图片水印、合并页面等。
要点提示是确保依赖版本与 JDK 版本兼容，在 Maven 的中央仓库中可以找到 PDFBox 的最新版本信息，并据此更新 pom.xml。通过 mvn dependency:tree 可以验证依赖树是否正确解析，避免版本冲突影响构建与运行。
3. 核心实现：文本水印
3.1 PDFBox 实现文本水印的思路
实现思路是逐页遍历目标 PDF，将文本水印绘制到每页内容之上，并保持水印在视觉上的渐变效果。核心步骤包括：打开 PDF、循环遍历每一页、创建追加的内容流、设置字体、颜色与旋转角度，以及最终保存输出文件。
在实现中，水印通常以较淡的颜色和较大字号呈现，并围绕页面中心或左上角等位置进行定位。通过为文本设置旋转矩阵（如 -45 度）可以实现对角线水印效果。此处所展现的实现侧重于可读性与可维护性，便于在实际应用中快速扩展为图片水印或多文字组合的水印。
3.2 Java 代码示例：文本水印的实现
示例代码展示了如何使用 PDFBox 2.x 对每一页添加水印文本，并将结果保存到输出文件。该示例仅演示文本水印的核心工作流，实际场景中可为水印文本提供外部配置、国际化字体等扩展。
import java.io.File;
import java.io.IOException;
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.PDType1Font;
import org.apache.pdfbox.util.Matrix;public class WatermarkText {public static void addTextWatermark(String srcPdf, String dstPdf, String watermark) throws IOException {try (PDDocument document = PDDocument.load(new File(srcPdf))) {PDRectangle pageSize;for (PDPage page : document.getPages()) {pageSize = page.getMediaBox();// 计算水印位置居中，角度 -45 度float fontSize = 72f;float x = (pageSize.getWidth()) / 2;float y = (pageSize.getHeight()) / 2;try (PDPageContentStream contentStream = new PDPageContentStream(document, page, PDPageContentStream.AppendMode.APPEND, true, true)) {contentStream.beginText();contentStream.setFont(PDType1Font.HELVETICA_BOLD, fontSize);// 设置旋转变换，居中并斜向放置Matrix rotate = Matrix.getRotateInstance(Math.toRadians(-45), x, y);contentStream.setTextMatrix(rotate);// 水印文本颜色偏灰contentStream.setNonStrokingColor(200, 200, 200);contentStream.showText(watermark);contentStream.endText();}}document.save(dstPdf);}}public static void main(String[] args) throws IOException {String input = "input.pdf";String output = "output_watermarked.pdf";addTextWatermark(input, output, "CONFIDENTIAL");}
}
4. 运行与验证
4.1 构建与打包
构建命令应在项目根目录执行，以确保所有依赖正确解析并打包。对于 Maven 项目，常见的命令是 mvn clean package，该命令会编译代码并生成可执行的 jar 或输出的 PDF 水印版本。通过构建 can 直接验证依赖与代码是否能够正确编译。构建成功后即可进入后续运行阶段。
4.2 运行水印处理程序
运行方式通常有两种：直接运行 Java 应用的 main()，或打包成可执行 jar。若采用前者，请使用 java 命令执行主类；若通过 jar，则使用 java -jar 方式执行。执行过程会读取 input.pdf，输出为 output_watermarked.pdf，文件中每一页都会显示文本水印。请注意确保输入文件存在且可访问。
常见验证点包括：水印是否覆盖每一页、文本颜色是否足够淡以不影响阅读、以及水印文本是否在合理的旋转角度实现预期视觉效果。
mvn clean package
java -cp target/your-project.jar your.package.WatermarkText
5. 进一步扩展：图片水印与配置化
5.1 将文本水印扩展为图片水印
扩展思路是在同一遍历流程中，将水印替换为图片。通过 PDImageXObject 将图片绘制在页面上，并结合坐标、缩放、旋转实现与文本水印类似的效果。对于需要版权保护的文档，图片水印通常提供更强的可视性与防篡改特性。
实现要点包括：加载图片资源、创建水印图像对象、在追加内容流中绘制图片、以及确保水印在每一页都可见且不遮挡原始内容。若使用图片水印，请注意图片的透明度和分辨率，以避免 PDF 体积过大或渲染性能下降。
5.2 水印的透明度、颜色与位置参数化
参数化配置可以通过将水印文本、颜色、字号、旋转角度和位置放到配置文件或命令行参数中，提升灵活性与可维护性。推荐将核心参数暴露为可配置项，以便在不同文档场景中快速调整而无需修改代码。
注意事项包括对不同 PDF 页面的尺寸差异进行自适应处理、确保水印不会遮挡关键内容，以及在大批量处理时保持性能稳定。通过实现一组可重复的单元测试，可以在变更水印策略时快速回滚并验证正确性。
