做企业级文档导出模块的时候我绕不开一个场景合同、报价单、设计图纸的PDF和Word版本导出时必须盖上一层可追溯的水印。前段时间客户拿着一份带自己姓名水印的报价单截图来反馈说“你们导出没加水印吗传了一圈都不知道源头是谁”其实水印只加在了网站预览页没加在导出文件上。这个锅最终落在后端PDF和Docx文件在导出时要能按当前登录人、订单号、时间戳组合出一行动态水印并牢牢固化到文件里。后来我把它沉淀成一个独立的文件水印工具类输入源文件和水印参数返回含水印的新文件。本文就是这套Pdf与Docx文件导出生成水印工具类的完整拆解从需求分析、技术选型到核心代码、踩坑记录都写出来。对正在做文档导出、需要给电子合同或报告加可见水印、或者想了解iText和POI底层机制的Java后端开发者应该有直接参考价值。1. 为什么PDF和Docx要一起处理先把需求拆明白1.1 水印不只是一种形式四种业务场景决定了你的选型先说清楚要解决什么问题。文档水印按业务目的大致分四类防外部泄露、内部溯源、版权声明和版本标识。防外部泄露常见于合同和标书看到一份截图就能从水印定位到是哪个人哪个项目泄露的内部溯源常用于企业内部资料分发把员工工号和水印绑定版权声明比较简单写“内部资料”或公司名版本标识则会在水印中带上“V2.0”“预览版”这类字样。我接手这个需求时系统已经有独立的前端预览水印和PDF导出逻辑但业务方要求Word导出也必须具备同等防护。这就引出一个关键结论水印必须放在文件生成这一层不能依赖前端和预览。前端只做展示导出要给到用户手里的文件“真正”加上水印。也就是说工具类必须以Pdf和Docx为输入对象在服务端对文件二进制进行处理。水印本身也有“可见”和“不可见”之分。业务方明确要求可见水印最好是半透明、旋转45度、多行多列平铺的那种因为截图时无法轻易避开。考虑到部分PDF要打印我最后选择了可感知但不遮挡主内容的低透明度文字水印。对于特殊项目我也预留了盲水印方案放在后面扩展部分单独说。1.2 技术选型iText、POI、docx4j、Aspose到底选哪个确定了文件格式和技术目标之后最核心的问题是选型。当时我详细对比过四类方案。第一类是基于iText的实现。iText对PDF的底层支持非常透彻可以直接操作PDF内容流往页面里写入文本和图形状态。关键是它提供了PdfContentByte和PdfGState可以精确控制坐标、旋转和透明度非常适合做平铺水印。官方许可证有AGPL和商业版之分但项目内使用iText 5的中小团队普遍能接受我最终选的也是它。第二类是PDFBox。Apache PDFBox也支持内容流写入但它的API更底层写文字、设置字体、管理图形状态都比iText繁琐。尤其中文支持PDFBox需要额外处理CID字体绕一圈下来不如iText顺手。优点是完全Apache许可生态不错但对我来说效率优先PDFBox被我排第二。第三类是Aspose.Slides/Aspose.PDF这类商业库。API很简洁一行代码加水印但授权费不便宜而且社区版会在文件里打上水印标识这本身就违背防泄露的目的。除非公司有预算否则我不建议在基础功能上引入。第四类是Docx处理。当时候选有Apache POI和docx4j。POI是Java操作Office文件的事实标准绝大多数后端团队已经在用版本迭代也比较稳定。docx4j对OpenXML的JAXB模型更贴近规范做复杂样式会方便一些但学习成本高。考虑到我们项目中已经有POI依赖我决定Docx水印也基于POI配合底层DOM操作来实现。下面是当时整理的一个对比表库支持格式中文支持水印API便利度性能许可/成本iText 5PDF好需注册标准字体很直接PdfContentByte足够单文件快大批量需注意AGPL/商业开源可用PDFBoxPDF一般需额外处理偏底层工作量大一般Apache LicenseAspose.PDFPDF很好一行代码但有限制优商业社区版带水印Apache POIDocx好原生水印支持弱需自己拼XML优Apache Licensedocx4jDocx好模型贴近OpenXML稍复杂优Apache LicenseAspose.WordsDocx很好最简单加文本水印优商业社区版带水印1.3 工具类的边界一次封装两边通吃选型定下来之后我定义的边界很清楚工具类对外只暴露一个统一方法输入是“文件字节数组 文件名/扩展名 水印参数对象”输出是含水印的字节数组。调用方不需要关心内部是PDF还是Docx也不需要关心是iText还是POI。接口上统一很舒服但内部必须做文件类型路由。我在工具类里根据扩展名判断文件类型最常见的是PDF和DOCXDOCM这种带宏的暂时只做兼容默认按Docx处理。判断完之后分别交给PdfWatermarkHandler和DocxWatermarkHandler两个Handler各自维护自己的依赖互不干扰。这样的好处有三个。第一业务系统集成时只需要在一个点上调用后续想在任何导出接口加印都很简单。第二内部实现与外部解耦以后从POI换到docx4j或者从iText 5升级到iText 7外部接口不变。第三水印参数可以统一比如都支持文字、透明度、角度、字号、平铺密度方便前端把这些配置做成动态选项。多说一句工具类不是无限膨胀的“上帝类”。它只负责“加一层水印”不做转格式、不做合并、不做文件预览。要和业务集成就应该在导出流程中调用而不是把整个导出逻辑塞进工具类。2. 核心细节PDF和Docx水印到底是怎么画上去的2.1 PDF水印在页面内容流里叠加一个透明图层PDF水印的原理可以这么理解。PDF页面本身是一段“内容流”里面记录着画了什么图形、写了什么文字。水印就是往这段内容流里追加一些绘制操作相当于在原本的文档图片上再叠一层半透明文字。这就是iText里PdfStamper存在的意义它可以读取原PDF复制所有页面并允许我们在每个页面内容流里插入新的操作。PDF支持两种叠加方向getOverContent(int pageNum)是把水印画在原有内容之上getUnderContent(int pageNum)是把水印放在原有内容之下。业务上我选择了OverContent因为只有覆盖在上层用户截图时一定带着水印。为了避免水印抢走正文可读性透明度设为0.15到0.25之间颜色用灰色而不是纯黑。透明度控制在PDF里叫作图形状态Graphics State。iText里对应PdfGState对象setFillOpacity(float)控制填充透明度setStrokeOpacity(float)控制线条透明度。文字使用填充模式所以两个最好都设置一下否则某些PDF阅读器渲染时会表现不一致。平铺水印的坐标计算也要讲清楚。PDF坐标系原点在页面左下角横轴向右、纵轴向上单位是磅。页面宽高可以通过reader.getPageSizeWithRotation(i)拿到。要让水印均匀铺满一种做法是沿着对角线一条条画但那样方向太单一。更通用的做法是先按页面尺寸和文字大小把页面划分为网格计算出中心点坐标在每个网格中心以45度角绘制一行文字。文字本身带旋转所以网格步长不能取太密否则会糊成一团。关于字体中文水印必须使用支持中文编码的BaseFont。iText 5里最常用的方案是BaseFont.createFont(STSong-Light, UniGB-UCS2-H, BaseFont.NOT_EMBEDDED)STSong-Light是Adobe字体库里的中文字体UniGB-UCS2-H是简体中文映射这样导出的PDF在主流阅读器里不会出现方块字。如果希望水印字体与公司品牌一致也可以加载系统TTF文件但要考虑版权和文件大小。2.2 Docx水印页眉VML中的Shape才是正主DOCX和PDF差异非常大。DOCX本质上是一个ZIP压缩包里面是若干XML和媒体文件。正文在word/document.xml页眉在word/header*.xml页面设置在每个节的sectPr里。Word打开文档时会把页眉内容绘制到每一页因此水印一般放在页眉里。但页眉里也不是随便插段文字就行的。Word原生水印的实现是在页眉XML中插入一个特殊的VMLVector Markup Language形状Shape形状内部有一个v:textpath或者引用一张水印图片同时用style控制它居中、旋转、置于文字下方。这个形状本质是一个“浮动对象”它不属于正文流而是绝对定位在页面中间。POI对XWPFDocument的常规操作能创建页眉但不会直接提供addWatermark()这样的方法。所以我在POI基础上直接对页眉的DOM节点做操作用header.getCTHdr().getDomNode()拿到w:hdr根节点然后通过W3C DOM接口往里追加w:pict和v:shape。这个方案的兼容性比较稳定。因为Word的OpenXML规范里VML水印是老版本Word一直沿用下来的实现。新版本Word虽然主推DrawingML但仍会兼容VML页眉水印。而且我只需要动态改文字内容不需要新增媒体文件也不需要改关系文件省掉了最复杂的部分。需要注意一个细节水印Shape要设置z-index为负数并放在文档内容下层。这样用户编辑正文时水印不会挡住鼠标操作。同时mso-position-horizontal-relativemargin和mso-position-vertical-relativemargin表示水平和垂直方向都相对于页面页边距居中正好是水印常见的“页面正中央斜着摊开”效果。2.3 统一参数模型从“能写死”到“可配置”最开始我只写了一个方法把文字、透明度、字号写死在常量里。后来需求一多有的项目要“内部资料”有的要“当前登录人工号”有的要“小程序二维码”配置项不断增加。我发现必须抽象出一个WatermarkParam对象。我设计的水印参数包括水印文字content、输出类型不必传根据文件名识别、字体大小fontSize、透明度opacity、旋转角度angleDegrees、是否平铺tile、平铺间距spacingMultiplier、颜色color、作用于哪些页pageStart和pageEnd、以及用于扩展的额外属性map。这些参数同时被PDF和Docx两个Handler读取。PDF和Docx对字号的单位不同PDF直接使用磅作为绝对单位Docx的页眉VML里字体大小在v:textpath的style上写二者没有标准换算关系所以我不在WatermarkParam里做单位统一而是由各Handler根据自己规则映射。这个坑我在第一版踩过强行统一单位导致PDF正常但Word水印要么太大要么太小。3. 实操把工具类真正撸出来3.1 Maven依赖版本坑先踩掉先说依赖版本。我以iText 5.5.13.2和POI 4.1.2为例这两个版本在Java 8和Java 11上都能跑API也相对稳定。理论上POI 5.x也能用但XWPFHeaderFooterPolicy.DEFAULT常量、CTHdr类包路径在5.x有微调如果你用的POI版本不同编译时注意调整。dependency groupIdcom.itextpdf/groupId artifactIditextpdf/artifactId version5.5.13.2/version /dependency dependency groupIdorg.apache.poi/groupId artifactIdpoi/artifactId version4.1.2/version /dependency dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version4.1.2/version /dependency dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml-schemas/artifactId version4.1.2/version /dependency这里有个细节iText 5和POI都依赖了不同的第三方库比如xmlbeans、commons-io等如果工程里有多版本冲突优先使用Maven的dependencyManagement统一版本不要一股脑升级到最新。我遇到过POI升级后原先生成DOCX的代码在空文档上创建页眉时抛NPE排查了半天发现是XWPFHeaderFooterPolicy构造行为变了。3.2 PDF水印完整实现平铺、旋转、透明度一起搞定下面先给出PDF水印的核心方法。为了直观点我直接返回byte数组生产环境建议直接操作OutputStream流。public static byte[] addWatermarkToPdf(byte[] sourcePdf, WatermarkParam param) throws Exception { PdfReader reader new PdfReader(sourcePdf); ByteArrayOutputStream bos new ByteArrayOutputStream(); PdfStamper stamper new PdfStamper(reader, bos); int total reader.getNumberOfPages(); int from Math.max(1, param.getPageStart()); int to param.getPageEnd() 0 ? total : Math.min(total, param.getPageEnd()); BaseFont baseFont BaseFont.createFont(STSong-Light, UniGB-UCS2-H, BaseFont.NOT_EMBEDDED); PdfGState gs new PdfGState(); gs.setFillOpacity(param.getOpacity()); gs.setStrokeOpacity(param.getOpacity()); for (int i from; i to; i) { Rectangle rect reader.getPageSizeWithRotation(i); PdfContentByte over stamper.getOverContent(i); over.saveState(); over.setGState(gs); over.setColorFill(param.getColor()); over.setFontAndSize(baseFont, param.getFontSize()); over.beginText(); // 根据平铺配置计算行列 float fontHeight param.getFontSize(); float stepX rect.getWidth() / 3f; float stepY rect.getHeight() / 3f; if (param.isTile()) { stepX param.getFontSize() * 6f; stepY param.getFontSize() * 2f; if (stepX 100) stepX 100; if (stepY 40) stepY 40; } for (float y stepY / 2; y rect.getHeight(); y stepY) { for (float x stepX / 2; x rect.getWidth(); x stepX) { over.showTextAligned(Element.ALIGN_CENTER, param.getContent(), x, y, param.getAngleDegrees()); } } over.endText(); over.restoreState(); } stamper.close(); reader.close(); return bos.toByteArray(); }使用平铺模式时stepX和stepY要根据页面尺寸动态调整。如果页面特别大比如A3图纸水印数量会非常多文字之间互相重叠视觉上会很脏。我建议在方法里加一个上限判断比如当前计算出的行列数超过100个时增大步长。上面的代码已经把min值设为100和40磅基本能避免太密集。旋转角度用45度是标准值。如果你做扫描件回传横向拉页会很多有时用30度加不透明黑色更好但普通电子文件用45度灰就够了。你可以通过WatermarkParam.angleDegrees自由控制。saveState()和restoreState()一定要配对。saveState()会记录当前图形状态改了新增的透明度、颜色和字体后restoreState()恢复回去这样后续页面绘制不会受到影响。漏写restoreState()在某些PDF阅读器里会出现后续页面颜色整体变浅的玄学问题。另外PdfReader和PdfStamper都必须在finally里关闭否则文件进程会一直被占用。我在工具类里封装了一个ByteArrayOutputStream通过toByteArray()复制出来再释放临时流。3.3 Docx水印完整实现POIDOM注入VMLShapeDocx水印的核心是往页眉加入VML形状。下面给出一个可直接使用的辅助方法基于POI 4.1.2。我用DOM操作是因为POI的XML模型没有直接暴露水印API直接操作DOM最可控。public static void addWatermarkToDocx(XWPFDocument document, WatermarkParam param) throws Exception { XWPFHeaderFooterPolicy policy document.getHeaderFooterPolicy(); if (policy null) { policy document.createHeaderFooterPolicy(); } XWPFHeader header policy.getDefaultHeader(); if (header null) { header policy.createHeader(XWPFHeaderFooterPolicy.DEFAULT); } Element hdrElement header.getCTHdr().getDomNode(); Document dom hdrElement.getOwnerDocument(); String wNs http://schemas.openxmlformats.org/wordprocessingml/2006/main; String vNs urn:schemas-microsoft-com:vml; String oNs urn:schemas-microsoft-com:office:office; String w10Ns urn:schemas-microsoft-com:office:word; hdrElement.setAttribute(xmlns:v, vNs); hdrElement.setAttribute(xmlns:o, oNs); hdrElement.setAttribute(xmlns:w10, w10Ns); Element p dom.createElementNS(wNs, w:p); Element r dom.createElementNS(wNs, w:r); Element pict dom.createElementNS(wNs, w:pict); Element shapeType dom.createElementNS(vNs, v:shapetype); shapeType.setAttribute(id, _x0000_t136); shapeType.setAttribute(coordsize, 1600,2160); shapeType.setAttribute(o:spt, 136); shapeType.setAttribute(path, m0,0l0,2160,1600,2160,1600,0e); Element pathNode dom.createElementNS(vNs, v:path); pathNode.setAttribute(gradientshapeok, t); pathNode.setAttribute(o:connecttype, rect); shapeType.appendChild(pathNode); Element shape dom.createElementNS(vNs, v:shape); shape.setAttribute(id, PowerPlusWaterMarkObject); shape.setAttribute(o:spid, _x0000_s2049); shape.setAttribute(type, #_x0000_t136); shape.setAttribute(style, position:absolute;margin-left:0;margin-top:0;width:600pt;height:400pt; rotation:315;z-index:-251658752;mso-wrap-edited:f; mso-position-horizontal:center;mso-position-horizontal-relative:margin; mso-position-vertical:center;mso-position-vertical-relative:margin); shape.setAttribute(o:allowincell, f); shape.setAttribute(filled, f); shape.setAttribute(fillcolor, clear); shape.setAttribute(stroked, f); Element textPath dom.createElementNS(vNs, v:textpath); textPath.setAttribute(style, font-family:Microsoft YaHei;font-size: param.getFontSize() pt;); textPath.setAttribute(string, param.getContent()); shape.appendChild(textPath); Element wrap dom.createElementNS(w10Ns, w10:wrap); wrap.setAttribute(type, none); Element anchorLock dom.createElementNS(w10Ns, w10:anchorlock); shape.appendChild(wrap); shape.appendChild(anchorLock); pict.appendChild(shapeType); pict.appendChild(shape); r.appendChild(pict); p.appendChild(r); hdrElement.appendChild(p); }这里有几个细节要特别说明。rotation:315和PDF里写45度在视觉上是等价的但VML的旋转方向定义不同315度才是逆时针45度对应PDF的顺时针45度。如果你第一次使用会发现旋转方向反了不要慌改一下数值即可。width:600pt;height:400pt指的是水印这个大形状的包围盒值大一点可以确保文字至少覆盖页面的大部分区域。真正文字大小由v:textpath里的font-size控制。如果你想要靠近Word原生水印的“大字斜排”效果font-size设为20到28pt比较合适。这个用文本path实现的方案不需要图片资源所以不用修改[Content_Types].xml和关系文件兼容性相对简单。缺点是某些严格校验的Word版本可能会提示“文档中存在损坏内容”多数情况下点击“修复”就能打开。如果你遇到批量用户反馈此类问题建议改成图片水印并嵌入关系文件后续4.1节我会讲排查思路。3.4 统一入口设计文件类型自动路由有了两个Handler之后统一入口只是一层很薄的封装。这里给出一个典型的实现。public class DocumentWatermarkUtils { public static byte[] addWatermark(String fileName, byte[] source, WatermarkParam param) throws Exception { String suffix getSuffix(fileName); if (pdf.equalsIgnoreCase(suffix)) { return PdfWatermarkHandler.addWatermarkToPdf(source, param); } else if (docx.equalsIgnoreCase(suffix) || doc.equalsIgnoreCase(suffix)) { return addWatermarkToDocx(source, param); } throw new UnsupportedOperationException(不支持的文件类型: suffix); } private static String getSuffix(String fileName) { int index fileName.lastIndexOf(.); return index -1 ? : fileName.substring(index 1); } private static byte[] addWatermarkToDocx(byte[] source, WatermarkParam param) throws Exception { ByteArrayInputStream bais new ByteArrayInputStream(source); XWPFDocument doc new XWPFDocument(bais); try { addWatermarkToDocx(doc, param); ByteArrayOutputStream baos new ByteArrayOutputStream(); doc.write(baos); return baos.toByteArray(); } finally { doc.close(); } } }注意这里的doc.write(baos)会把内存中的完整XML重新打包成DOCX。如果源文件非常大建议使用临时文件流来避免内存紧张。工具类内部我统一使用byte[]是为了调用方简单生产环境可以再加一个接受InputStream/OutputStream的重载让大文件走流式。4. 真实项目中的问题与排查技巧4.1 PDF水印中文乱码、文字被遮挡、透明失效PDF水印最常见的坑是中文乱码。如果你用的是Helvetica这类内置字体中文字符会直接变成问号。记住一定要用中文字体映射常见两条路STSong-Light搭配UniGB-UCS2-H或者加载系统字体文件new File(msyh.ttc)。前者文件无字体嵌入体积小后者能精确保证字体样式但会增加PDF体积也要注意字体授权。第二个坑是水印被正文“挡住”。实际上如果水印画在OverContent层正文不可能挡住它。出现“看上去被挡”多半是透明度太高或者水印文字太小、位置刚好落在页边空白区。我建议默认透明度0.2字号不小于20pt行列步长不要太密保证视觉上“看得到但不碍事”。如果客户反馈妨碍阅读先调透明度而不是字号。第三个坑是透明度不生效。我排查过几次原因都是只设置了setFillOpacity()而某些PDF渲染器读取的是描边透明度。在一个同时应用了PdfGState但没设置中文字体的场景里也会出现“文字有底色但看不到内容”的怪异表现。所以每次都要同时设置FillOpacity和StrokeOpacity并且彻底配对saveState/restoreState。还有一个细节容易被忽略reader.getPageSizeWithRotation(i)拿到的是旋转后的页面尺寸而getOverContent(i)是直接作用于页面内容流坐标原点已经处理了旋转。如果你用getPageSize(i)而不是getPageSizeWithRotation(i)在横竖混排的PDF里水印布局会错位。4.2 Docx水印打开文件报警、水印不显示、只显示一页Docx水印的两个高频问题一是“文件打开时提示损坏”二是“水印只在首页显示”。文件损坏多半是命名空间前缀和关系定义不一致。我是直接拼VML节点所以对命名空间很敏感。根节点上如果没有声明xmlns:v、xmlns:o、xmlns:w10Word无法解析shape。另外ID尽量不要重复比如PowerPlusWaterMarkObject这个ID在同一个页眉里出现多次时有些Word版本会直接打开报错。如果你多次点击“添加水印”按钮工具类要处理成先移除旧shape再插入新的。水印不显示先看是不是插错位置。如果header不是每一页都会使用的默认页眉只有奇偶页不同或者首页不同时就要分别处理。我一般会遍历document.getHeaderList()对每个页眉都注入一次。遇到节没有页眉的文档还要通过policy.createHeader(XWPFHeaderFooterPolicy.DEFAULT)先创建。只显示一页常见原因是某个section设置了“独立页眉”即titlePg或者页眉指定引用到其他header part。这种情况下仅修改默认页眉无法覆盖所有节。解决办法是遍历所有XWPFHeaderFooterPolicy中的header分别是default、firstPage和evenPage都执行注入。如果源文档来自WPS或LibreOffice生成的DOCX结构可能更乱按列表中全部header注入最保险。另外如果使用图片水印方案并出错检查word/_rels/header*.xml.rels里图片关系ID与VML中r:id是否一一对应以及[Content_Types].xml是否声明了png或jpeg扩展名。这个坑在最初测试时折腾了我一个下午。4.3 批量与并发工具类的性能自救清单批量给几千个合同加水印时CPU和内存可能出现明显压力。这里建议几点。第一PdfReader和PdfStamper都是重量级对象不要在每个页面循环里重新创建。上面的代码已经在整个文档范围内只创建一次这是正确姿势。第二ByteArrayOutputStream会带来双倍内存开销大批量场景一定要改造为FileInputStream/FileOutputStream处理完再删临时文件。第三如果同一份PDF要加不同人名的水印可以考虑模板优化先对无参模板做一次PDF预处理之后每次只需在页面内容流叠加不同文字而不是重新解析完整文件优化后性能能提升数倍。并发方面iText的PdfStamper不是线程安全的同一个实例不能并发写多个输出流。我的做法是用ThreadLocal管理或者最简单粗暴的方法是每个线程new一个实例。水印文字和参数是不变的常量时BaseFont和PdfGState可以静态初始化它们可以被多个实例安全共用。5. 从水印到防泄露体系还能怎么扩展5.1 从文字到图片Logo、二维码水印基础文字水印满足80%的防泄露需求但有些场景需要把公司Logo、个人头像或二维码也融进文件里。PDF方案很好扩展可以用iText的Image.getInstance(byte[])在内容流里over.addImage(image, width, 0, 0, height, x, y)再结合透明度。图片格式优先PNG带透明通道的原图效果最自然。Docx的图片水印稍微麻烦需要把图片作为资源加入包并在页眉VML里用v:imagedata r:idrIdX引用。实现思路是在POI的XWPFHeader中用run.addPicture(data, Document.PICTURE_TYPE_PNG, watermark.png, Units.toEMU(width), Units.toEMU(height))创建一个图片关系拿到关系ID后再把VML形状中的r:id替换成这个ID。这样做的兼容性比textpath更稳Word基本不会报损坏。5.2 水印与业务系统集成工具类独立出来后接入导出流程就变得非常自然。我在Spring Boot项目里一般在导出Controller层做统一处理先生成原始PDF或Word再调用DocumentWatermarkUtils.addWatermark()最后响应给前端。如果是内部平台还可以用AOP切面凡是带ExportWithWatermark注解的方法切面自动对返回值做水印处理。这种切面方案看似优雅但要注意返回值类型。如果Controller直接返回byte[]或ResponseEntitybyte[]切面很容易拿到字节数组。如果返回的是自定义的ExportResult就需要在切面里判断属性类型。另外大文件导出耗时长切面不适合做异步否则用户下载到的可能还是无水印文件。5.3 不依赖可见内容盲水印兜底可见水印再醒目也拦不住有心人用PS涂抹掉。我在方案里额外预留了盲水印能力也就是把一段不可见信息嵌入文件内容。PDF可以用频域方式向页面图像嵌入低频信号业务上叫“数字水印”。这个复杂度高但可以在法务取证时使用。具体实现上iText不适合直接做频域嵌入需要把PDF页面渲染成图像再用OpenCV等库做DCT变换。你要是真有这个需求可以把这条链路做成一个独立工具类不要在导出的那个环节同步执行因为DCT嵌入相当耗时。对于Docx可以在文档自定义属性中写入隐藏的MD5信息作为简单溯源。这不算严格意义上的数字水印但成本低、实用适合内部追溯。真正的盲水印需要把信息分散到字体、间距或页眉细微差异里这里就不展开讲了。最后再分享一点我的个人体会。工具类做得再完善也要在真实环境里反复验证尤其是不同Office版本对DOCX的解析差异。我第一次实现Docx水印时在WPS里看着很正常一到Microsoft Word就提示错误最后发现就是VML命名空间前缀不对。从那以后我每次改完水印逻辑都会准备一份“Windows Word WPS LibreOffice PDF阅读器”四件套测试清单。文档水印这件事细节差距往往是客户体验的分水岭把底层原理吃透再把每个参数调细才能让这份防护真正可用、可维护。