简介面向Java开发者的Word文档合并技术资源基于Apache POI的XWPF组件与POI-TL模板库解决多个.docx文件批量合并、模板占位符动态替换等核心需求适用于合同生成、批量报告整理等办公自动化场景。资源包为RAR格式大小约3.96MB涵盖合并文档的完整技术路径从创建XWPFDocument对象、读取源文档到遍历段落与表格并复制保留格式再到输出目标文件同时讲解了POI-TL模板化编程方式便于生成结构相似而内容各异的Word文档。已有3524人学习适合具有一定Java基础、希望提升POI与POI-TL应用能力的开发者参考可快速掌握Word文档读写、拼接及模板渲染的关键技巧减少手工处理文档的时间成本。1. 合并多个 Word 文档为什么选 POI-TL 而不是直接拼文件接手过一个棘手的活儿几十个 Word 文档要合并成一份完整报告每个文档有各自的图片、表格、列表和标题样式要求最后成品的排版看起来像是一个人从头写到尾的。拿文件流直接拼接的方式第一个被否掉因为 Word 本质是包含关系和样式的压缩包简单拼文件在打开时大概率直接报错不是格式损坏就是样式错乱。后来改用 Apache POI 底层操作 XWPFDocument能做但代码量大得吓人光处理图片复制就写了一整天。再后来用 poi-tl 这款基于 POI 的模板引擎事情才变得可控它把对 Word 的常见操作封装成标签语法合并文档这件事能靠插件机制和模板渲染组合实现代码量少了不止一半排错也直观。这篇笔记适合正在用 Java 做文档生成的开发者尤其是需要批量合并带图片、表格、样式的工作文档、合同或报告的人目的是把「POI-TL 合并多个 Word 文档」这条路从原理讲到落地落不了地的坑也一并交代清楚。2. POI-TL 能做什么、不能做什么合并前先弄清边界2.1 poi-tl 的核心模型模板 数据不是文档拼接器poi-tl 的设计初衷是「模板渲染」你先写一份带占位符的 docx 模板再用 Map 或对象绑定数据输出完整文档。它的标签语法很直接{{title}}、[图片]这类文本写在 Word 里代码里给对应 key 赋值渲染出来的就是填好内容的成品。这种模式对「一张模板套多条数据」的场景特别顺手批量生成合同、报告、通知单基本是业内默认方案。但「合并多个 Word 文档」和「渲染一个模板」是两码事。一个未经处理的 docx 文件没有可识别的标签语法poi-tl 不会主动去解析里面的正文段落然后帮你搬进另一个文档。要合并常见路线有两条一是放弃 poi-tl直接用 POI 的 XWPFDocument 遍历源文档的 body 元素逐段逐表 deep copy 进目标文档二是让每个子文档先按统一模板渲染生成再用 poi-tl 的合入能力或者 POI 层的拷贝把它们拼起来。第二条更像项目里常见的真实需求子公司各交一份填好的 Word总部要合并汇总。所以选型之前先想清一个问题你要合并的是已经存在的、格式随意的文档还是你能控制模板、让各端按统一格式生成再合并的文档。前者必须走 POI 底层后者才适合 poi-tl。2.2 为什么直接用 POI 拷贝容易翻车XWPF 的对象模型与关系引用先看一个典型场景。直接用 POI 合并两个 Word新手最常见的做法是遍历源文档的段落逐个new XWPFParagraph拷贝到目标文档。这样对付纯文本段落没问题但一遇到图片就完了。图片在 docx 里不是简单一个二进制字段它由图片字节流、内联图形对象、Drawing 关系 ID、锚字符等多层结构构成。你拷贝段落时只是把文本和游标复制过去了图片的 Drawing 关系没有同步注册到目标文档的关系表里结果就是这段文字在图是空的——破图这是新手入坑第一课。表格也是重灾区。XWPF 的表格由XWPFTable持有里面每一个XWPFTableRow和XWPFTableCell都有自己的属性对象合并单元格、单元格宽度、垂直对齐这些信息散落在多个 XML 节点上。POI 没有提供「一行代码深度复制表格」的 API要自己遍历 cell、复制内容、复制属性稍有遗漏表格渲染就缺边少框。还有页眉页脚、分页符、书签、目录域全都涉及关系引用和文档级配置每个都够写一篇文章的坑。所以除非源文档格式极其统一且简单我很少直接只用 POI 去合并。poi-tl 的价值在于它内部已经处理了图片、表格、列表这些复杂对象的渲染逻辑我们要做的是借用它的渲染管线把每一个子文档当成一个「整体渲染单元」来合。2.3 什么时候必须用 poi-tl 而不是纯 POI三个判断标准第一你的每个子文档来自同一个模板。子公司交上来的周报、分店传上来的销售明细、各项目组填的结项单只要大家都是从一个标准 docx 模板填出来的合并时就能用 poi-tl 做「模板级合流」把多份数据合并渲染进一个模板的多行区域而不是在文档对象层面做拼接。这条路最简单也最稳。第二你需要批量生成的中间步骤恰好是合并的输入。比如先拿 poi-tl 把一组数据渲染成若干分文档再做汇总合并两个环节用同一个库依赖统一、类型一致、风格不变比两套方案混着用省心。第三合并结果允许「基于模板重排」。如果你要的不是严格按原始顺序拼装而是把各文档的内容抽取出来按固定版式重新排版poi-tl 的表格循环和块引用能力恰好胜任。反过来如果源文档来自四面八方、样式千奇百怪、图片表格穿插随意poi-tl 的模板渲染帮不上忙poi-tl 也没有「智能排版」能力。这种情况就别指望一个库通吃老老实实基于 POI 深度拷贝再做好样式归一。不是不让用 poi-tl是标定预期它管的是「按模板生长」不是「任意文档无损拼接」。3. 用 POI-TL 合并多个 Word 文档的实现路径与关键参数3.1 环境准备与依赖选型poi-tl 版本要和 POI 配套先看 pom 依赖怎么配。poi-tl 对 POI 版本有明确要求版本不匹配会直接抛NoSuchMethodError或者ClassNotFoundException这是最典型的起步坑。以我常用的稳定组合为例dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.5/version /dependency dependency groupIdcom.deepoove/groupId artifactIdpoi-tl/artifactId version1.12.2/version /dependencypoi-tl1.12.x 需要配合 POI 5.x 使用如果项目里因为别的组件引了 POI 4.x那个poi-ooxml的传递依赖会冲突建议用mvn dependency:tree先看一眼。另外 poi-tl 内部依赖了ooxml-schemasPOI 5.x 之后这个包被拆成了poi-ooxml-lite如果日志里出现 schema 相关的类找不到再显式补一个dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml-lite/artifactId version5.2.5/version /dependency代码层面核心操作是构造XWPFTemplate渲染时绑定数据这一步和合并的关系是当我们把多个子文档产生的数据合并进同一个模板时poi-tl 的LoopRowTableRenderPolicy负责表格循环DocxRenderPolicy负责把一个已经渲染好的文档实例「作为整体」塞进另一个文档。后者才是合并多 Word 的关键接口。3.2 方法一多文档流合并入一个模板推荐做法这个思路是每个子文档先用同一个模板分别渲染成XWPFTemplate再创建一个汇总用的XWPFTemplate把前者的核心内容合入后者。关键在 poi-tl 提供的Configure和DocxRenderPolicy。看一段实际能跑的最小实现// 子文档渲染用同一模板 各自的业务数据 MapString, Object data1 new HashMap(); data1.put(title, 一季度销售报告); data1.put(author, A同学); // ... 更多字段 XWPFTemplate tpl1 XWPFTemplate.compile(report-template.docx) .render(data1); XWPFTemplate tpl2 XWPFTemplate.compile(report-template.docx) .render(data2); // 汇总文档的渲染配置注册一个自定义策略处理 {{childDoc}} 标签 Configure config Configure.builder() .bind(childDoc, new DocxRenderPolicy()) .build(); XWPFTemplate merged XWPFTemplate.compile(merge-main.docx, config) .render(new HashMapString, Object() {{ put(childDoc, tpl1); }});逻辑说明compile两次加载的模板是同一个物理文件但每次渲染各自独立不会互相污染。Config.bind(childDoc, new DocxRenderPolicy())告诉 poi-tl正文里遇到{{childDoc}}这个标签时不要走默认文本替换而是把一个已经渲染好的XWPFTemplate的内容整体插入这个位置。这里注意render的数据值类型是XWPFTemplate而不是 StringDocxRenderPolicy会去读取模板实例内部的 XWPFDocument 并做深度拷贝合入。合并多个文档就循环调整这段代码把tpl2、tpl3依次绑定到不同的标签位或者借助循环块策略对同一位做多次插入。参数说明merge-main.docx是汇总容器的模板里面的{{childDoc}}是占位符可以放多个比如{{childDoc1}}、{{childDoc2}}对应不同模块。DocxRenderPolicy默认不会自动插入分页符想要子文档之间分页需要在模板里的标签前后手动加Word 中的分页符或者在子文档模板的末尾加分页——这个细节后面避坑章节会展开。3.3 方法二原生 POI 层遍历 插入需要动样式时如果子文档格式不完全统一没法用统一模板渲染但你又不想完全丢掉 poi-tl 的依赖体系可以退一步只用 poi-tl 做最外层容器的渲染内层各子文档的内容用 POI 自身 API 遍历拷贝。这个方案代码更长但灵活性高也是很多人最终落到生产环境的形态。XWPFDocument srcDoc new XWPFDocument(new FileInputStream(child.docx)); XWPFDocument targetDoc new XWPFDocument(); // 遍历源文档的 body 元素 for (IBodyElement element : srcDoc.getBodyElements()) { if (element instanceof XWPFParagraph) { XWPFParagraph srcPara (XWPFParagraph) element; XWPFParagraph newPara targetDoc.createParagraph(); copyParagraphProperties(srcPara, newPara); for (XWPFRun run : srcPara.getRuns()) { XWPFRun newRun newPara.createRun(); newRun.setText(run.text()); newRun.setFontFamily(run.getFontFamily()); newRun.setFontSize(run.getFontSize()); newRun.setBold(run.isBold()); } } else if (element instanceof XWPFTable) { XWPFTable srcTable (XWPFTable) element; XWPFTable newTable targetDoc.createTable(); // 表格属性与单元格内容拷贝 copyTableContent(srcTable, newTable, targetDoc); } }逻辑说明核心不是createParagraph这种一眼懂的 API而是srcDoc.getBodyElements()返回的IBodyElement列表它把段落在先、表格在后的 Body 层级还原出来。拷贝时如果遇到段落里的图片这段代码里没有处理runs里的CTDrawing这是简化版能跑但不能覆盖全部场景的边界。copyParagraphProperties和copyTableContent是自定义工具方法实际上要深入CTPPr、CTTblPr这些底层 XML 对象才能完整复制属性。这个方法的价值在于明确了最终瓶颈不在 poi-tl在你的拷贝工具是否完整。参数与边界说明图片完整拷贝要额外注册XWPFRun.addPicture并且把源文档的图片字节流写入目标文档的包关系这一步需要遍历srcDoc.getAllPictures()拿到类型、文件名和数据字节。表格合并单元格涉及vMerge/hMerge属性POI 的XWPFTableCell.getCTTc().getTcPr()需要单独处理。样式定义、编号列表、页眉页脚这三类在这里默认不复制生产使用要按项目实际取舍。3.4 合并时的三个关键控制点分页、样式统一、图片处理合并 Word 和合并文本文件最本质的区别是可以控制的维度太多。先说分页每个子文档应该是独立的视觉单元所以子文档模板的末尾最好用段落 - 段落属性 - 分页符这种方式收尾而不是在两个内容之间留一堆空行那样合并出来的文档会有大量漂浮空白段落。如果你用的是DocxRenderPolicy注意它有policy.doRender的一系列内部状态分页符放在模板标签之外不要在标签内。样式统一这块比大多数人想的重要。多个来源的 Word 即使内容一致字体、字号、缩进、行距也可能天差地别。poi-tl 渲染基于模板模板里定义了统一的正文样式所以「统一模板 - 渲染子文档 - 合并」这条路天然保证样式一致性。而走 POI 底层拷贝的方案需要在拷贝段落属性后额外做一遍样式归一比如强制设置正文字体为宋体五号、标题为黑体三号、行距固定值 20 磅。我一般在拷贝工具里维护一个样式映射表源样式名称映射到目标文档已有的样式名避免拷贝后styleId引用失效。图片处理是要提前规划的点poi-tl 对图片有内置的PictureRenderPolicy遇到{{image}}标签时自动插图。但注意DocxRenderPolicy合入的图片宽度和位置取决于子文档模板里的图片占位尺寸如果各子文档的图片宽高比不一致合入后会有拉伸变形。更稳妥的做法是子文档渲染前先统一处理图片尺寸或者合入后再遍历目标文档的getAllPictures按图片宽高重新设置显示尺寸。4. 避坑指南合并多个 Word 文档的 5 条血泪经验4.1 图片合入后破图或变空白现象合并后的文档文字正常但图片位置显示一个红叉或完全空白。原因直接拷贝段落时没有把图片对应的二进制字节和 Drawing 关系一起注册进目标文档目标文档的关系表里缺了图片的 image part。解决要么统一走DocxRenderPolicy让 poi-tl 内部处理关系注册要么在 POI 层拷贝循环里单独处理XWPFRun.getEmbeddedPictures()并调用targetDoc.addPictureData建立新的关系 ID再把关系 ID 写回 Drawing 对象的embed属性。前者省事后者自由别混用。4.2 合并完成后第一个子文档的页眉页脚消失了现象用DocxRenderPolicy合入多个子文档最后生成的文档只有第一个子文档有页眉或页眉页脚错乱。原因docx 的页眉页脚是文档级配置XWPFDocument对应一个document.xml页眉页脚关系存储在SectPr级别。poi-tl 的合入策略只搬运 body 内容不会自动合并多个来源的页眉页脚定义。解决页眉页脚统一放在汇总模板merge-main.docx上子文档模板不带页眉页脚或者子文档模板的页眉页脚内容本来就是空的。如果你真的需要每个子文档有自己的页眉那DocxRenderPolicy帮不上要改为按分节符section break处理在每个节里独立配置页眉页脚这个复杂度直接加倍。绝大多数业务需求其实是要统一的页眉那就用第一种方案。4.3 合并后编号列表的自动编号全部变成乱码或丢失现象源文档里有「1. 2. 3.」这种自动编号列表合并后编号变成了「1. 1. 1.」或直接看不到编号。原因Word 的自动编号依赖numId与 numbering.xml 中的抽象编号定义。在 POI 底层拷贝时只复制了段落文本没有复制pPr.numPr中的numId而目标文档里也没有对应的 numbering 定义。poi-tl 的DocxRenderPolicy同样不会自动同步两个模板的 numbering 定义因为 numbering.xml 是一个独立 part。解决提交前统一约定子文档模板使用手动编号即在模板里就已经把「1.」「2.」写死成文本不依赖 Word 自动编号。这是成本最低的方案。如果一定要保留自动编号需要手动操作targetDoc.getNumbering()把源文档使用到的numId定义导入并重新映射这块逻辑相当绕建议非必须不碰。4.4 poi-tl 版本升级后出现 NoSuchMethodError现象换了一个 poi-tl 小版本原来能跑的项目直接启动报错。原因poi-tl 对 POI 的 API 有时依赖内部实现比如XWPFDocument.getDocument()这类 package-private 方法在 POI 5.x 某次重构后签名变了。解决先锁定 poi-tl 官方 README 里声明的 POI 版本范围不要随便升降 POI。poi-tl 1.12.x POI 5.2.x 是一个稳定组合升级到 1.13 前先把 POI 也升到对应新版本。另外注意项目里可能有别的依赖传递引入旧版 POI用mvn dependency:tree -Dincludesorg.apache.poi排查最直接。4.5 合并后的文档体积异常膨胀现象合并两个各 200KB 的文档产物体积到了 5MB。原因每一个子文档都把它自己的样式类、图片、字体信息原样搬运进目标文档但 Word 对重复资源的去重力度有限。特别是图片targetDoc.addPictureData每调用一次就新增一份二进制 part相同图片在多个子文档里各存了一份。解决先在子文档渲染前统一图片压缩或裁剪重复图片用哈希去重只插入一份数据并复用关系。合入后如果风格统一跑一次docx4j的MainDocumentPart清理或 Word 自带的「压缩图片」也能把体积压下来但治标不如治本。5. 进阶技巧合并之前先做数据校验合完以后验证完整性有经验的开发者都会在合并逻辑前加一道校验这步也是整个流程里唯一不用读 XML 就能拦截 80% 问题的步骤。每份子文档本质上是一组字段的渲染结果所以校验内容可以做得很具体必填文本节点是否为空、图片像素宽高是否超过预设阈值、表格行数是否在可接受范围、字数是否少到可能说明数据缺失。poi-tl 的好处是渲染前后都是同一个XWPFTemplate对象你可以在render之前校验数据 Map也可以在render之后直接读取模板中的文本做检查。// 渲染完成后校验关键节点 XWPFTemplate merged XWPFTemplate.compile(merge-main.docx, config) .render(dataMap); // 遍历所有段落检查空值占位符残留 try (XWPFDocument doc merged.getXWPFDocument()) { for (XWPFParagraph para : doc.getParagraphs()) { String text para.getText(); if (text ! null text.contains({{)) { throw new IllegalStateException(存在未渲染的模板标签: text); } } }这段校验的思路是poi-tl 渲染时如果绑定的 key 缺失模板标签不会被替换掉而是原样留在文档里。跑完合入后扫描一遍全文抓出任何残存的{{...}}就是抓到了漏数据。getXWPFDocument()是 poi-tl 暴露的底层访问入口拿到XWPFDocument就等于拿到完整操作权后续要做样式归一、尺寸调整、页眉页脚修补都在这个对象上操作。参数说明校验逻辑要放在所有子文档合入之后因为某个子文档渲染成功不代表合入成功合入时的异常通常发生在render内部会抛RenderException日志里会明确指向哪个标签绑定失败。这段代码的contains({{)还覆盖了另一种翻车场景数据里本身包含了模板标签字符比如某个字符串字段值是total {{count}}poi-tl 会把它拆成嵌套标签处理或直接报错。遇到这种数据基本的解决办法是数据写入前对特殊字符做转义或者在 Configure 里把标签语法改成不太可能冲突的[[...]]式样适配脏数据。验证合并结果还有更细的办法。拿合入后的XWPFDocument调用getAllPictures()统计图片数量跟所有子文档的图片总数做比对调用getTables()统计表格数量跟源文档表格总数比对。数字对得上说明对象级搬运完整对不上就要回去检查拷贝工具是不是漏了嵌套表格——注意getTables()不统计嵌套在单元格内部的表格Word 里表格套表格很常见这个坑值得单列一条经验XWPFTable的嵌套结构在 POI 里默认不展开要遍历到 cell 级别去统计。这个方向做多了会形成一套自己的惯例。我现在的习惯是能在模板层解决的问题绝不在代码层解决比如分页、页眉、编号、字体全部写进模板代码里只做数据绑定和校验必须走 POI 底层拷贝的部分只拷贝正文结构样式层信息在建模板时就统一。这样合并代码量稳定在两百行以内功能再怎么加也动不到核心逻辑。各子文档模板遵循同一个版本管理模板改动要过 review因为模板出问题影响的是所有子文档的渲染结果比代码 bug 扩散面大得多。要说经验这条最值得刻在墙上合并只是动作模板才是作品。希望这些思路能让你在这个需求上少走几圈弯路。本文还有配套的精品资源点击获取