简介：使用iText操作PDF文档的完整示例工程，面向有一定Java基础、需要在项目中处理PDF的开发者，重点解决PDF创建、电子签章、斜字水印、文本替换四类高频需求。整个工程按Eclipse项目组织，共包含32个文件，整个压缩包大小为8.77MB；其中7个Java源文件与9个class文件构成核心示例代码，5个jar包提供itextpdf、bcprov等依赖库，另有p12证书用于数字签名，png/jpg作为图片素材，prefs/project/classpath便于直接导入IDE，readme.txt给出使用指引。当前已有1571人学习下载。源码覆盖PdfWriter生成文档、PdfStamper签名与替换文本、PdfFormXObject绘制旋转水印等关键操作，并给出证书设置、中文字体、文件体积控制等实用建议，可帮助开发者快速迁移到真实业务，减少踩坑成本。示例中还针对大型文档分批处理、避免内存溢出等实践做了说明。无论是生成报表、合同签署还是批量加水印，都能直接参考这套实现。
1. 一次跑通 iText 的四个硬需求：建 PDF、盖印章、斜水印、替换文本
我在上家做结算系统时，每周要批量生成带水印的对账单 PDF，还要把合同模板里的旧乙方名称替换成新主体，最后财务又要求盖签章。那阵子把 iText 相关的帖子翻了个遍，发现资料全是碎片：讲创建的不讲替换，讲水印的不讲签章，真正动手时连版本 API 都对不上。这篇按生产环境的落地顺序把四件事串成一条流程：用 iText 创建 PDF、文本替换、斜字水印、数字签章，每步给出可以直接粘进项目跑的 Java 代码，参数设成什么样、什么地方容易翻车都写在旁边。适合用 Java 写后端服务的读者，做报表、合同、票务类文档生成基本都能落到这四个动作上。希望你看完能直接在业务里复现，而不是再对着搜索引擎熬一宿。
2. 用 iText 创建 PDF：版本选型、依赖与第一个中文文档
2.1 Maven 依赖里 iText 5 和 iText 7 怎么选，包名为什么总对不上
先用 Maven 把依赖请进来。iText 从 7.0 开始把模块拆成了 kernel、layout、io、pdfa 等一堆，日常做创建和编辑直接用聚合包itext7-core最省事：
<dependency> <groupId>com.itextpdf</groupId> <artifactId>itext7-core</artifactId> <version>7.2.x</version> <type>pom</type> </dependency>版本号里的x建议用你本地 Maven 仓库能拉到的最新稳定版，不要长期锁一个过于老的版本。很多人照着老博客写代码，报错说找不到com.itextpdf.text.Document，就是因为那是 iText 5 的包名，iText 7 里内核对象几乎全搬到了com.itextpdf.kernel.*和com.itextpdf.layout.*。
我一般建议新项目直接上 7，理由有三点：一是 7 对 PDF/A、PDF/UA 这类标准化格式支持更完整，二是它的底层对象模型比 5 清晰，调试时能直接看到页面和资源对象，三是 7 还在持续维护，再往后做签章、替换这类操作时资料也更接近当前版本。如果你们项目是存量代码，那先确认下现在用的包名再决定迁移节奏，避免顺手把依赖升上去然后一夜之间编译错几百处。
2.2 第一个中文创档程序：PdfWriter、PdfDocument 与 Document 的最小闭环
下面这段就是生成demo.pdf的最小闭环，我特意把中文字体加载也放进来了，因为不设置字体的 PDF 一秒变“方块文”。
import com.itextpdf.kernel.pdf.PdfDocument; import com.itextpdf.kernel.pdf.PdfWriter; import com.itextpdf.kernel.pdf.PdfEncodings; import com.itextpdf.kernel.font.PdfFont; import com.itextpdf.kernel.font.PdfFontFactory; import com.itextpdf.layout.Document; import com.itextpdf.layout.element.Paragraph; import java.io.FileOutputStream; public class CreatePdfDemo { public static void main(String[] args) throws Exception { String outputPath = "./demo.pdf"; PdfWriter writer = new PdfWriter(new FileOutputStream(outputPath)); PdfDocument pdfDoc = new PdfDocument(writer); Document document = new Document(pdfDoc); // 中文字体：优先从系统字体目录加载，避免 iText 默认字体缺 CJK 字形 PdfFont chineseFont = PdfFontFactory.createFont( "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc", PdfEncodings.IDENTITY_H, PdfFontFactory.EmbeddingStrategy.PREFER_NOT_EMBEDDED); document.setFont(chineseFont); document.add(new Paragraph("第一个 iText 生成的 PDF 文件")); document.add(new Paragraph("这一行是中文内容，用来确认字体生效。")); document.close(); } }逻辑上这条链子是：PdfWriter负责真正向文件流里写字节，PdfDocument是内存里的 PDF 对象树，Document是高层布局入口，你往里add的Paragraph会被排版成页面内容。document.close()必须放在最后，它会触发页面销毁、对象写入和资源释放。
参数上有几个值得说：PdfEncodings.IDENTITY_H表示按 Unicode 字面值写入，不乱转码；EmbeddingStrategy.PREFER_NOT_EMBEDDED是“能不全量嵌入就不嵌入”，生成的 PDF 体积小，但换一台没有这个字体的机器打开就会缺字形。生产环境我更推荐把 Noto、思源黑体这类开源字体跟服务一起打包，改成PREFER_EMBEDDED强制嵌入，虽然包大几百 KB，但换机器不乱码，这个代价值得。
2.3 用 Table 把内容排成合同骨架，为后面替换和签章留出位置
报表、合同、结算单这类文档光靠段落是不够的，用 Table 把字段和值排成两列，才是真实业务形态：
import com.itextpdf.layout.element.Table; import com.itextpdf.layout.element.Cell; import com.itextpdf.layout.properties.UnitValue; Table table = new Table(2); table.setWidth(UnitValue.createPercentValue(100)); table.addCell(new Cell().add(new Paragraph("客户名称")).setBold()); table.addCell(new Cell().add(new Paragraph("北京某某科技有限公司"))); table.addCell(new Cell().add(new Paragraph("结算金额")).setBold()); table.addCell(new Cell().add(new Paragraph("¥12,800.00"))); table.setHeaderRows(1); // 如果表格跨页，表头会重复出现 document.add(table);new Table(2)的 2 是列数，列宽默认均分；setWidth按百分比撑满页面宽度，后续调整只需改一个比例，比写死 pt 值好用得多。setHeaderRows(1)特别适合跨页报表，它让第一行在分页后自动重现在下一页顶部，省去手工补表头的蠢操作。
这里先留心一件事：Table 的行数超过当前页剩余高度时，iText 会自动把内容流到下一页。这个“分页”行为也是后面水印必须按页面事件处理的原因——你不能在 add 完所有内容后再画水印，因为那时你已经不知道每一页真正的边界在哪。
3. 斜字水印：用页面结束回调自动盖到每一页
3.1 为什么“加个水印”实现上要挂在页面结束事件上，而不是画完内容再补
水印最常见的做法是在每页内容渲染完成之后、页面关闭之前，追加一段透明文字。听起来简单，但如果你在Document.add(...)全部执行完后再拿 PdfCanvas 去画水印，只会画在最后一个“当前页”上，前面几页一个都没有。正确姿势是给PdfDocument注册一个事件处理器，监听END_PAGE事件：每当一页渲染完，回调马上执行，画完水印再翻篇。
斜字水印为什么是“斜”的，也在这个环节体现出意义。旋转 30 到 45 度之后，水印与正文形成交叉，肉眼很容易辨识，复印扫描后也不容易被裁剪掉一块就看不出来。这是内容版权保护场景里最常见的视觉策略，不是审美玄学。
3.2 用 PdfPageEvent 思路实现水印处理器：旋转角、透明度、字体一次配齐
iText 7 里事件处理器实现IEventHandler接口，核心代码放在handleEvent：
import com.itextpdf.kernel.events.IEventHandler; import com.itextpdf.kernel.events.Event; import com.itextpdf.kernel.events.PdfDocumentEvent; import com.itextpdf.kernel.pdf.PdfPage; import com.itextpdf.kernel.pdf.canvas.PdfCanvas; import com.itextpdf.kernel.pdf.extgstate.PdfExtGState; import com.itextpdf.kernel.colors.ColorConstants; import com.itextpdf.kernel.font.PdfFont; public class WatermarkEventHandler implements IEventHandler { private final String text; private final float angleDegrees; private final float alpha; private final PdfFont font; public WatermarkEventHandler(String text, float angleDegrees, float alpha, PdfFont font) { this.text = text; this.angleDegrees = angleDegrees; this.alpha = alpha; this.font = font; } @Override public void handleEvent(Event event) { PdfDocumentEvent docEvent = (PdfDocumentEvent) event; PdfPage page = docEvent.getPage(); PdfCanvas canvas = new PdfCanvas(page); canvas.saveState(); float radians = (float) Math.toRadians(angleDegrees); canvas.setExtGState(new PdfExtGState().setFillOpacity(alpha)); canvas.setFillColor(ColorConstants.BLACK); canvas.beginText(); canvas.setTextMatrix( (float) Math.cos(radians), (float) Math.sin(radians), (float) -Math.sin(radians), (float) Math.cos(radians), page.getPageSize().getWidth() / 2 - 120, page.getPageSize().getHeight() / 2); canvas.setFontAndSize(font, 48); canvas.showText(text); canvas.endText(); canvas.restoreState(); } }在生成新文档时把它挂上事件链就行：
pdfDoc.addEventHandler(PdfDocumentEvent.END_PAGE, new WatermarkEventHandler("内部资料", 45, 0.25f, chineseFont));逻辑上，setTextMatrix的前四个参数就是旋转矩阵的cos/sin/-sin/cos，后两个是平移坐标；alpha控制透明度，0.25f表示 25% 不透明度，既能看到又不会盖住正文。坐标中心取getPageSize()的一半，但水印文字本身也有宽度，后面参数部分再讲怎么防截断。
另一个高频场景是给存量 PDF 加水印。思路不是挂事件，因为文档已经生成了，而是自己遍历每一页：
try (PdfDocument pdfDoc = new PdfDocument(new PdfReader(src), new PdfWriter(dest))) { for (int i = 1; i <= pdfDoc.getNumberOfPages(); i++) { PdfPage page = pdfDoc.getPage(i); PdfCanvas canvas = new PdfCanvas(page); // 把上面 beginText 到 endText 那段抽成一个方法，循环调用 drawWatermark(canvas, page, "内部资料", 45, 0.25f, chineseFont); } }注意这个场景里new PdfWriter(dest)会生成一个新文件，不要让它覆盖原文件，否则中途报错时原始文件就没了，到时候连后悔药都没得吃。
3.3 斜字水印的四组参数：角度、透明度、字号和密度到底调到多少
角度我一般用 45，这是最经典的斜水印角度，计算也方便。如果内容页有横向表格，45 度可能压住关键数据，那就改成 30，视觉效果依然明显但遮字少。
透明度里 0.2 到 0.3 是个安全区间。低于 0.1，打印出来几乎看不见；高于 0.5，正文阅读会明显受阻。如果你水印文字和正文同色，还会产生灰阶融合，所以颜色上建议统一用黑或深灰。
字号要看页面大小。A4 页面单行水印用 40 到 60 比较常见；如果公司要求“多行多列文字水印”，比如每页要铺 3 行 3 列，那字号降到 20 到 24 更合适，不然九个大字糊满全页。铺多行多列时多做一层循环：
for (int row = 0; row < 3; row++) { for (int col = 0; col < 3; col++) { float x = page.getPageSize().getWidth() / 3 * col + 20; float y = page.getPageSize().getHeight() / 3 * row + 20; canvas.beginText() .setFontAndSize(font, 24) .setTextMatrix(cos, sin, -sin, cos, x, y) .showText(text) .endText(); } }每一格的起点坐标别从边界 0 开始，留出 20 到 30 的点间距，避免水印紧贴裁切边。算坐标时还要考虑文字旋转后的包围盒长度，文本越长，中心点就越要向页面中心回缩，否则右上角那一两个水印常被切掉一半。
4. 文本替换：定位旧文本、重绘新文本的两种落地法
4.1 为什么 PDF 文本替换容易翻车，这跟业务系统里替换字符串完全是两码事
很多从 Word 开发转过来的人，第一次做 PDF 文本替换就懵：明明 PDF 里能看到“乙方法人”，代码提取出来一段乱码，或者替换后位置错乱。原因在 PDF 的结构模型上。PDF 页面内容不是“文字块”组成的，而是一连串文本绘制指令：什么字体、什么字号、在哪个坐标画什么字符，彼此之间没有段落概念。尤其当原始 PDF 由某些工具生成时，字符序列还被压缩过，甚至字体子集把部分字形单独抽走。你说“替换字符串”，对 PDF 来说只是“在图像内容流里找一段绘制指令”，这天然不稳定。
所以做文本替换前先定策略。如果你的模板是自己用 iText 或 Word 生成的，我强烈建议不要走“搜索旧文本再替换”的路，而是用占位符方案：生成模板时就把要变的字段用固定位置矩形记下来，替换时直接往矩形区域写新内容。这绕过了 80% 的文本提取问题，也是生产里最稳的做法。
4.2 基于占位符区域的替换：一个矩形搞定乙方名称、金额、日期
下面这段代码处理“模板里预留好的空白位置”——比如一个月结算单模板，乙方名称那一栏是固定区域，你只需替换这个矩形里的内容：
import com.itextpdf.kernel.pdf.PdfDocument; import com.itextpdf.kernel.pdf.PdfReader; import com.itextpdf.kernel.pdf.PdfWriter; import com.itextpdf.kernel.pdf.canvas.PdfCanvas; import com.itextpdf.kernel.colors.ColorConstants; import com.itextpdf.kernel.font.PdfFont; import com.itextpdf.kernel.font.PdfFontFactory; import com.itextpdf.kernel.pdf.PdfEncodings; import com.itextpdf.kernel.geom.Rectangle; public void replaceSlot(String srcPath, String destPath, int pageNo, Rectangle slotRect, String fontPath, String newText) throws Exception { try (PdfDocument pdf = new PdfDocument(new PdfReader(srcPath), new PdfWriter(destPath))) { PdfCanvas canvas = new PdfCanvas(pdf.getPage(pageNo)); // 第一步：用底色盖住旧文本，旧文本如果是白底黑字就用白色 canvas.saveState(); canvas.setFillColor(ColorConstants.WHITE); canvas.rectangle(slotRect.getX(), slotRect.getY(), slotRect.getWidth(), slotRect.getHeight()); canvas.fill(); canvas.restoreState(); // 第二步：在区域内重绘新文本 PdfFont font = PdfFontFactory.createFont(fontPath, PdfEncodings.IDENTITY_H); float fontSize = 12f; canvas.saveState(); canvas.setFillColor(ColorConstants.BLACK); canvas.beginText() .setFontAndSize(font, fontSize) .setTextMatrix(slotRect.getX() + 4, slotRect.getY() + 2) .showText(newText) .endText(); canvas.restoreState(); } catch (Exception e) { // 建议把 srcPath 和 pageNo 打到日志里，替换失败时方便回溯 throw new RuntimeException("替换PDF文本失败: page=" + pageNo, e); } }逻辑上这段代码先画了一个白色矩形遮住旧内容，再在同一个位置用新字体写字。白色矩形的坐标你从哪拿？我一般先输出一版带坐标的 PDF，用面积标注工具或者直接拿阅读器量一下文字边缘位置，填进Rectangle就行。
fontSize不是硬编码就完事。如果newText比旧文本长，固定字号会把文字挤出矩形右边界。稳妥做法是按矩形宽度估算字号：
float estimatedSize = Math.min(12f, slotRect.getWidth() / newText.length() * 1.2f);这个估算公式不严谨但够用，1.2f是中文汉字宽度的经验系数。英文数字可以降到0.7f。
4.3 如果非要全文搜索替换：先拿坐标块，再精准重绘
占位符方案的前提是你会改模板。第三方给的 PDF 没法预留矩形时，就得做全文定位。iText 7 里可以用LocationTextExtractionStrategy拿到文本块坐标，再结合重绘逻辑实现“搜索式替换”：
import com.itextpdf.kernel.pdf.canvas.parser.listener.LocationTextExtractionStrategy; import com.itextpdf.kernel.pdf.canvas.parser.PdfTextExtractor; LocationTextExtractionStrategy strategy = new LocationTextExtractionStrategy(); PdfTextExtractor.getTextFromPage(page, strategy); for (TextChunk chunk : strategy.getTextChunks()) { if (chunk.getText().contains("旧公司名")) { // chunk.getStartLocation() 拿到 Vector(x, y, z)，z 忽略 float x = chunk.getStartLocation().get(Vector.I1); float y = chunk.getStartLocation().get(Vector.I2); // 在这里调用上面 replaceSlot 的第二步逻辑 } }文本块TextChunk可能不是一个完整的词或句子，PDF 内容流经常把一个词拆成多个块。所以你大概率要做邻近块聚合，把坐标接近、同一行的块拼起来再比对。这一步没有银弹，属于“拿到原始坐标后自己拼业务逻辑”的活。
对比三条路的取舍：占位符替换最稳，适合自己生成的模板，成本低；全文搜索替换适合一次性处理第三方文档，但要处理分块、间距、字体偏差，人力成本高；还有一种“看到哪里改哪里”的重绘法只适合少量页面的临时微调，不适合大批量业务。我通常第一选择永远是占位符，全文搜索替换只当作救火方案。
5. iText 避坑手记：资源回收、中文乱码、坐标偏移与签名失效
5.1 数据量大的时候回收资源报错，服务直接 OutOfMemory
现象：高并发批量生成 PDF，比如每天上万份对账单，跑一段时间后 JVM 报内存溢出，或者日志里反复出现PdfDocument has not been closed之类的警告。
原因：最常见的是Document或PdfDocument没有在 finally 里关闭。另一个隐蔽原因是有人把 PDF 直接写进ByteArrayOutputStream再整体转 byte[]，批量场景下几百份大 PDF 同时挤在堆内存里，GC 根本来不及回收。
解决：所有 PDF 创建和编辑操作都放 try-with-resources 里，先关Document再关PdfDocument，顺序颠倒在某些版本里会提示文档未正确结束。输出目标用临时文件而不是内存流，落盘完成后再读文件内容。如果 JVM 内存实在紧张，控制并发线程数，比如用一个固定线程池把生成任务限流。
// 推荐写法：三个资源按依赖顺序一次性声明 try (PdfWriter writer = new PdfWriter(tempFile); PdfDocument pdf = new PdfDocument(writer); Document doc = new Document(pdf)) { // 业务逻辑 }这里的窍门是tempFile用File.createTempFile生成，处理完再删，避免一堆临时垃圾堆在磁盘上。
5.2 文本替换后中文变成豆腐块，新内容全是方框
现象：替换出来的中文字符在阅读器里显示成一个个空心方块，英文数字正常。
原因：重绘时用的字体不是中文字体。iText 的默认字体基线通常是 Helvetica 或内置标准字体，它们只有拉丁字符集，没有 CJK 字形。
解决：替换逻辑里必须显式加载中文字体，并且最好用嵌入方式。用系统字体目录的 Noto Sans CJK 时，同时设置PdfFontFactory.EmbeddingStrategy.PREFER_EMBEDDED，保证换一台机器打开也不丢字形。这里有个细节：替换用字体最好和原 PDF 所用字体接近，否则新旧文字视觉风格明显不一致，财务一眼就挑出毛病。
5.3 签章或水印坐标对不上，笔刷位置和阅读器显示完全两回事
现象：代码里写印章坐标x=100, y=100，打开 PDF 发现印章跑到了页面左边或偏下，跟肉眼预期差很多。
原因：PDF 坐标系原点在页面左下角，x 向右、y 向上，而很多人在页面预览工具里看到的坐标是“左上角为原点”。更麻烦的是部分 PDF 页面带旋转属性，页面宽高在视觉上和getPageSize()返回的宽高不一致。
解决：写一个统一坐标转换工具，先读page.getRotation()，如果旋转了，用page.getPageSizeWithRotation()拿旋转后的实际页面尺寸再去算坐标。凡是涉及“左上角量距离”的场景，先把目标点转成左下角坐标系。这个坑我踩过不止一次，后来强制要求所有签章相关代码先打印一遍页面旋转角再动手。
5.4 水印文字被页面边缘裁掉，最后一列水印总是一半
现象：多行多列水印铺完后，页面右上角的水印文字明显不完整。
原因：文字中心点直接按页面宽高的一半算，但水印本身有宽度和高度，旋转 45 度后包围盒更大，边缘部分超出页面裁切区。
解决：铺水印前先估算单行文本在目标字号下的宽度，用font.getWidth(text, fontSize)拿到长度，再根据旋转角算出横向和纵向投影，把中心点往页面中心方向回缩。经验公式是横向偏移至少减去width * cos(θ) + height * sin(θ)的一半，这样边缘就不会切字。
5.5 签名弄完后再被改一版，打开提示“文档已被更改，签名无效”
现象：业务部门先盖了电子章，后边又想改一个金额，开发直接拿 iText 再打开 PDF 做了文本替换，结果阅读器里提示签名失效。
原因：盖章后的 PDF 一旦被后续编辑，增量更新区里保存的签名摘要与修改后的内容不匹配，服务端校验直接判无效。
解决：把签章放在整条处理链的最后一步。所有文本替换、加水印、内容调整必须发生在盖章之前，程序上强制规定：已签名的文件绝不作为输入再次执行写入操作。如果业务非要改，就让流程重新走一遍生成、替换、水印、章。
6. 签章与验真：盖章图片的坐标技巧和验证手段
先说清楚一个概念：贴图章和数字签名不是一回事。直接把 PNG 印章图片画到 PDF 上，解决的是“视觉上有章”，并不具备防篡改能力。真要让签章具备法律效力，得用证书走PdfSigner做增量签名。但绝大多数企业内部流程第一步需要的是“盖章效果”，下面这段就能用：
import com.itextpdf.kernel.pdf.PdfDocument; import com.itextpdf.kernel.pdf.PdfReader; import com.itextpdf.kernel.pdf.PdfWriter; import com.itextpdf.kernel.pdf.canvas.PdfCanvas; import com.itextpdf.kernel.pdf.xobject.PdfImageXObject; import com.itextpdf.io.image.ImageData; import com.itextpdf.io.image.ImageDataFactory; try (PdfDocument pdf = new PdfDocument(new PdfReader(src), new PdfWriter(dest))) { PdfCanvas canvas = new PdfCanvas(pdf.getPage(1)); ImageData stampImage = ImageDataFactory.create("stamp.png"); float width = 100f; float height = 100f; canvas.addImageAt(stampImage, x, y, width, height, false); }这里的x, y是印章左下角坐标，不是图片中心，落章前先按 5.3 的旋转规则换算。印章图片我建议用透明背景 PNG，红色圆章四周的留白如果是不透明白底，盖上去像贴了一块创可贴。图片宽高要等比例传，别硬压，否则椭圆章变畸变。
验证环节分两层。第一层是人工验证：用阅读器打开 PDF，点一下印章区域查看注释属性；如果只是图片章，阅读器显示的是图片对象信息。第二层是代码验证，对于真正的数字签名，可以用SignatureUtil枚举全文档签名，再逐个检查摘要匹配。我一般会做一次双重验证：先程序输出“签名个数、是否有签名”，再让业务同事在 Adobe Reader 打开确认不报“文档已被更改”。如果代码校验过了但阅读器仍然报错，通常就是字体嵌入或增量更新顺序出了问题。
做签章最怕的是流程顺序错了：先盖了章再改内容，最后所有验证一起崩。我的习惯是签章永远排在文档产线的最末尾，水印、替换、排版全部结束，才允许调用签章逻辑。顺序守住了，这套 iText 流程才算真正能交给业务长期跑。希望帮到你。
本文还有配套的精品资源，点击获取
