简介：本资源是一份基于Java的Word文档批量合并实战方案，面向Java后端开发者及办公自动化需求者，解决多份.docx报告、合同或通知需统一整合为单个文件的典型场景。方案深度结合Apache POI核心XWPF组件与POI-TL模板引擎，覆盖文档读取、段落/表格内容复制、样式保留、目标文档拼接及模板占位符动态填充等关键环节，适用于批量生成审计报告、学生成绩汇总、标准化合同等业务。压缩包为RAR格式，大小3.96MB，虽未提供具体文件列表，但根据技术描述可推知包含完整可运行Java工程（含依赖配置）、核心合并工具类源码、示例输入文档及合并结果样例，结构紧凑、即开即用。目前已有3524人学习下载，读者可直接复用代码逻辑，快速集成至现有系统，并掌握跨文档格式兼容处理与常见合并异常（如分页丢失、样式错乱）的规避方法。
1. POI-TL 合并多个Word文档：不是简单拼接，而是保留样式、页眉页脚、分节符的“无损缝合”
你试过用 Python 合并 12 个带页码、不同页眉、含表格和图片的 Word 报告吗？别急着写Document.append()——POI-TL 的XWPFDocument原生不支持跨文档样式继承，直接getParagraphs()拿段落再塞进新文档，结果往往是：标题变正文、中文乱码、页眉消失、表格错位、甚至整个文档在 Word 里打不开报“文件已损坏”。这不是玄学，是 Apache POI 对 OOXML 结构理解的边界。这个 POI-TL 合并项目，就是为解决这类真实翻车场景而生：它不靠字符串拼接，也不依赖外部 Word 进程（比如 win32com），而是深度操作.docx的底层 OPC 包结构——复用源文档的styles.xml、numbering.xml、header1.xml，把每个文档当作一个“样式上下文单元”，再通过XWPFDocument#insertDocument的扩展实现真正意义上的 DOM 级合并。适合需要批量生成合规报告、审计底稿、合同汇编的后端服务，也适合要嵌入到 OA 或低代码平台里的文档组装模块。如果你正被“合并后格式全崩”折磨，这个项目就是你的后悔药。
2. 技术栈与工程结构：基于 POI-TL 1.13.2 的轻量封装，拒绝黑匣子
这个项目不是一行命令就能跑通的玩具，它是一套可嵌入、可调试、可审计的文档处理逻辑。核心依赖只有poi-tl（注意不是apache-poi原生包），版本锁定在1.13.2——这是目前对.docx分节符（Section）和页眉页脚（HeaderFooter）支持最稳定的版本。高于 1.14 的某些快照版会破坏XWPFFootnote的引用链，低于 1.12 则无法正确解析w:sectPr节属性。项目采用 Maven 构建，无 Spring、无 Web 容器，纯 Java SE 环境即可运行，意味着你可以把它打成jar直接丢进调度任务或嵌入到任意 Java 服务中。
2.1 项目目录结构：5 个关键文件，全部直击痛点
src/main/java/ ├── com/example/poitl/merge/ │ ├── DocumentMerger.java ← 主入口：控制合并流程、异常兜底、资源释放 │ ├── SectionAwareMerger.java ← 核心：按节（Section）粒度合并，保留分页、页眉页脚绑定关系 │ ├── StyleResolver.java ← 关键：解决样式冲突——当两个文档都定义了“标题1”但字号不同，选哪个？ │ ├── ResourceCopier.java ← 底层：复制 styles.xml / numbering.xml / header*.xml / footer*.xml 到目标文档 ZIP 包内 │ └── XWPFDocumentWrapper.java ← 封装：给原生 XWPFDocument 加上 getSectionCount()、getHeaderById() 等缺失方法提示：
XWPFDocumentWrapper不是装饰器模式炫技，而是因为原生 POI-TL 没暴露CTDocument的getBody().getSectPrList()，必须反射绕过访问限制才能拿到节列表。这个 Wrapper 是后续所有节级操作的前提。
2.2 为什么不用apache-poi原生 API？
很多人第一反应是“直接用XWPFDocument的createParagraph()+createTable()不就行了？”——不行。原因有三：
- 样式丢失：原生
XWPFDocument创建的段落默认使用Normal样式，不会自动继承源文档中Heading1的字体、缩进、大纲级别； - 页眉页脚断裂：
.docx中页眉页脚通过header1.xml和footer1.xml文件与节（<w:sectPr>）绑定，原生 API 无法将源文档的header1.xml注册到目标文档的 OPC 包中； - 编号链失效：多级列表（如“1.1 → 1.1.1”）依赖
numbering.xml中的<w:abstractNum>和<w:num>双重 ID 映射，直接拷贝段落会导致w:numId指向不存在的抽象编号，Word 打开时自动降级为普通段落。
POI-TL 1.13.2 在XWPFDocument基础上补全了getStyles()、getNumbering()、getHeaders()等访问器，并提供了insertDocument(XWPFDocument)方法——这才是本项目能落地的底层支点。
2.3 Maven 依赖配置：精确到 patch 版本，拒绝“mvn clean compile 之后跑不通”
<!-- pom.xml --> <dependency> <groupId>com.deepoove</groupId> <artifactId>poi-tl</artifactId> <version>1.13.2</version> </dependency> <!-- 必须显式排除旧版 poi-ooxml-schemas，否则与 poi-tl 内置 schema 冲突 --> <exclusion> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml-schemas</artifactId> </exclusion>注意：
poi-tl1.13.2 自带poi-ooxml-schemas-4.1.2，若项目中其他依赖（如老版本 EasyExcel）引入了poi-ooxml-schemas-3.17，会导致CTNumbering类加载失败，报NoSuchMethodError。务必用mvn dependency:tree -Dverbose | grep poi-ooxml-schemas检查实际生效版本。
3. 核心合并逻辑拆解：从打开第一个文档到写出最终 .docx 的完整链路
合并不是“把 A 的段落 + B 的段落 + C 的段落”堆一起，而是重建一个符合 OOXML 规范的新 OPC 包。整个过程分为 4 个阶段：初始化目标文档 → 逐文档注入 → 样式与资源协调 → 节结构收尾。下面以DocumentMerger.merge(List<File> sources, File target)为入口，逐段拆解关键代码。
3.1 初始化目标文档：空壳 ≠ 空白，它必须携带基础样式骨架
// DocumentMerger.java public void merge(List<File> sources, File target) throws IOException { // 步骤1：创建空目标文档，但不是 new XWPFDocument() // 而是用模板文档（template.docx）初始化——哪怕它只有一行"Hello" XWPFDocument targetDoc = new XWPFDocument(POIXMLDocument.openTemplate( Objects.requireNonNull(getClass().getResourceAsStream("/template.docx")) )); // 步骤2：清空模板内容，但保留 styles.xml / numbering.xml / settings.xml 等核心 part targetDoc.getBody().clearParagraphs(); targetDoc.getBody().clearTables(); // 步骤3：强制触发 styles 加载（避免后续 getStyles() 返回 null） targetDoc.getStyles(); }逻辑说明：
- 不能
new XWPFDocument(new ByteArrayInputStream(new byte[0]))，那样生成的文档缺少styles.xml，后续插入任何带样式的段落都会抛NullPointerException； - 模板文档
/template.docx必须是真实由 Word 2016+ 保存的.docx，不能是 LibreOffice 导出的——后者styles.xml结构不兼容； targetDoc.getStyles()是个隐藏陷阱：POI-TL 默认延迟加载 styles，首次调用才解析styles.xml，若跳过这步，后续StyleResolver.resolve()会因targetDoc.getStyles()返回 null 而崩溃。
3.2 逐文档注入：SectionAwareMerger如何让每个源文档“自带节属性”
// SectionAwareMerger.java public void insertDocument(XWPFDocument target, XWPFDocument source) throws IOException { // 1. 先复制 source 的所有 headers/footers 到 target 的 OPC 包中 ResourceCopier.copyHeadersAndFooters(source, target); // 2. 复制 numbering.xml（解决多级列表 ID 冲突） ResourceCopier.copyNumbering(source, target); // 3. 复制 styles.xml 并合并（关键！见 3.3 节） StyleResolver.mergeStyles(source.getStyles(), target.getStyles()); // 4. 遍历 source 的每个 section，逐个插入 body 内容 XWPFDocumentWrapper wrapper = new XWPFDocumentWrapper(source); for (int i = 0; i < wrapper.getSectionCount(); i++) { CTBody sourceBody = wrapper.getSectionBody(i); // 插入前，先修正 sourceBody 中所有 w:sectPr 的 w:pgSz/w:pgMar —— // 否则合并后所有节共用最后一个文档的纸张大小 fixSectionPageSize(sourceBody, wrapper.getSectionPageSize(i)); // 调用 POI-TL 原生插入（它内部会处理 rId 重映射） target.insertDocument(sourceBody); } }参数说明：
wrapper.getSectionCount()：返回source文档中<w:sectPr>标签数量，即物理节个数（不是“分页符”个数）；wrapper.getSectionBody(i)：提取第i个节对应的CTBody对象，它是XWPFDocument的底层 XML DOM 节点，可直接被target.insertDocument()接收；fixSectionPageSize()：必须手动修正，因为insertDocument()不会自动同步w:sectPr中的页面设置，否则合并后所有节都变成 A4 或 Letter，丢失原始排版意图。
3.3 样式合并策略：当两个文档都叫“标题1”，谁说了算？
// StyleResolver.java public static void mergeStyles(XWPFStyles sourceStyles, XWPFStyles targetStyles) { // 获取 target 当前所有 styleId（如 "Title", "Heading1"） Set<String> targetStyleIds = targetStyles.getStyles().stream() .map(CTStyle::getStyleId).collect(Collectors.toSet()); // 遍历 source 的每个 style for (CTStyle sourceStyle : sourceStyles.getStyles()) { String id = sourceStyle.getStyleId(); if (!targetStyleIds.contains(id)) { // target 没有该 styleId → 直接添加（如 source 有 "CustomSubtitle"） targetStyles.addStyle(sourceStyle); } else { // target 已存在同名 styleId → 比较 basedOn 属性决定是否覆盖 CTStyle targetStyle = findStyleById(targetStyles, id); if (sourceStyle.isSetBasedOn() && !targetStyle.isSetBasedOn()) { // source 的 style 显式继承自其他 style，而 target 是独立定义 → 优先 source targetStyles.removeStyle(id); targetStyles.addStyle(sourceStyle); } // 其他情况（如都基于 Normal）则跳过，保留 target 原样式 } } }逻辑说明：
basedOn是 OOXML 中样式继承的关键字段，例如<w:style w:styleId="Heading1" w:basedOn="Normal">；- 该策略保证：如果源文档的 “Heading1” 是基于
Normal定义的，而目标文档的 “Heading1” 是独立定义（无basedOn），则保留目标样式——避免覆盖用户预设的全局样式； - 若源文档新增了
CustomReportTitle这种目标文档没有的样式，则无条件注入，确保后续段落能正确应用。
4. 避坑指南：5 条血泪经验，每一条都来自真实翻车现场
合并 Word 文档是典型的“表面平静、底层惊涛骇浪”场景。以下问题均在某高校教务系统批量生成成绩单时真实发生，排查耗时从 2 小时到 3 天不等。
4.1 现象：合并后文档在 Word 中提示“发现错误。此文件的部分内容可能已受损”，点击“是”后页眉全部消失
原因：源文档 A 的header1.xml中包含<w:hdr>标签，但未闭合；POI-TL 在复制时未做 XML 格式校验，导致目标文档的word/header1.xml成为非法 XML，Word 解析失败。
解决：在ResourceCopier.copyHeadersAndFooters()中增加 XML 校验：
// 使用 javax.xml.parsers.DocumentBuilder 校验 header XML 是否 well-formed DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder(); builder.parse(new InputSource(new StringReader(headerXmlContent)));4.2 现象：合并后第 3 个文档的页码从“1”开始，而不是接续前一个文档的末尾页码
原因：页码连续性由w:sectPr/w:pgNumType中的w:start属性控制，而insertDocument()不会自动重写该值。源文档的<w:pgNumType w:start="1"/>被原样复制，导致 Word 认为这是一个新节的起始。
解决：在fixSectionPageSize()后追加fixPageNumberStart()：
CTPgn pgn = sectPr.getPgNumType(); if (pgn != null && pgn.isSetStart()) { // 计算前一个文档总页数（需提前缓存每个文档的 pageCount） int prevTotalPages = getTotalPagesBefore(i); pgn.setStart(prevTotalPages + 1); }4.3 现象：合并后表格内文字全部左对齐，丢失源文档中设置的居中/右对齐
原因：表格单元格对齐由CTTcPr中的<w:vAlign>和<w:jc>控制，但XWPFTable的clone()方法未深拷贝CTTcPr，导致插入后对齐属性丢失。
解决：弃用table.clone()，改用XWPFTable构造函数重建：
XWPFTable newTable = new XWPFTable(table.getCTTbl(), targetDoc); // 手动遍历每个 cell，复制 vAlign/jc for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { CTTc ctCell = cell.getCTTc(); CTTcPr tcPr = ctCell.addNewTcPr(); if (ctCell.isSetTcPr() && ctCell.getTcPr().isSetVAlign()) { tcPr.setVAlign(ctCell.getTcPr().getVAlign()); } } }4.4 现象：合并后中文显示为方框（□□□），英文正常
原因：源文档使用了 Word 内嵌字体（如“微软雅黑 Bold”），其fonts.xml中的w:name为SimHei，但目标文档的styles.xml中<w:rFonts>指向KaiTi，且未声明w:cs字体。
解决：在StyleResolver.mergeStyles()中同步字体声明：
// 遍历 sourceStyles.getFonts()，将每个 font name 添加到 targetStyles.getFonts() for (CTFont sourceFont : sourceStyles.getFonts().getFontList()) { if (!targetStyles.getFonts().getFontList().stream() .anyMatch(f -> f.getName().equals(sourceFont.getName()))) { targetStyles.getFonts().addFont(sourceFont); } }4.5 现象：合并后文档体积暴涨 300%，打开缓慢
原因：ResourceCopier.copyHeadersAndFooters()未去重，多个源文档共用header1.xml，却被复制为header1.xml,header2.xml,header3.xml…… 实际只需一份。
解决：建立Map<String, byte[]>缓存已复制的 header/footers，key 为MD5(headerXmlContent)：
String headerHash = DigestUtils.md5Hex(headerXmlContent); if (!copiedHeaders.containsKey(headerHash)) { copiedHeaders.put(headerHash, headerBytes); // 写入 target OPC 包 }5. 运行与验证：从本地测试到生产部署的完整闭环
项目提供MergeRunner.java作为 CLI 入口，支持三种运行模式：单次合并、目录扫描、HTTP 接口。无论哪种，验证环节都不能跳过——因为 Word 文档的“看起来正常”和“结构合法”之间，隔着一整套 OPC 规范。
5.1 本地快速验证：三步确认合并结果可用
- 结构验证：用
zip -T merged.docx检查 ZIP 包完整性，再unzip -l merged.docx | grep -E "(header|footer|numbering|styles)"确认关键 part 存在； - XML 验证：解压后对
word/styles.xml、word/numbering.xml运行xmllint --noout --schema /path/to/officeOpenXML.xsd styles.xml（需下载 ECMA-376 标准 XSD）； - 人工抽检：重点检查页眉页脚是否随节切换、表格边框是否连续、中文是否未乱码、页码是否连续——这些是用户第一眼看到的“可信指标”。
5.2 生产环境部署：如何避免“上线后才发现页眉错位”
生产环境必须启用--strict-mode参数（对应DocumentMerger.setStrictMode(true)），它会开启三项强制检查：
- 每个
header*.xml必须有且仅有一个<w:hdr>根节点； - 所有
w:numId必须在numbering.xml中有对应<w:num>； styles.xml中每个w:styleId必须唯一。
一旦不满足，立即抛DocumentMergeException并记录详细位置（如header2.xml line 42），而非静默生成损坏文档。
5.3 HTTP 接口集成：暴露为 RESTful 服务的最小改造
项目内置MergeController.java（Spring Boot 风格），但不依赖 Spring：
// POST /api/v1/merge // RequestBody: {"sources": ["/path/a.docx", "/path/b.docx"], "output": "/tmp/out.docx"} public Response merge(@RequestBody MergeRequest req) { try { List<File> files = req.sources.stream() .map(File::new).collect(Collectors.toList()); merger.merge(files, new File(req.output)); return Response.ok("success").build(); } catch (DocumentMergeException e) { // 返回结构化错误，含具体 section index 和 part name return Response.status(400) .entity(Map.of("error", "style_conflict", "section", e.getSectionIndex(), "part", e.getPartName())) .build(); } }提示：生产部署时，务必限制
req.sources数量 ≤ 20，单个.docx≤ 5MB。.docx是 ZIP 包，恶意构造的超深嵌套 XML 可能触发Xerces解析栈溢出。
6. 二次开发实战：如何支持“合并时动态替换变量”与“按章节拆分导出”
这个项目不是终点，而是文档自动化流水线的起点。我最近在一个模拟项目X中，基于它扩展了两个高频需求：变量模板填充和章节级导出。下面给出可直接抄作业的改造路径。
6.1 支持${name}变量替换：在合并前注入动态内容
需求：合并前，把每个文档中的${report_date}替换为当前日期。
思路：不能在合并后全局搜索替换（会误伤表格内公式、页眉文本），必须在insertDocument()前，对sourceBody的每个CTP（段落）和CTTbl（表格）做 DOM 遍历。
// 在 SectionAwareMerger.insertDocument() 中，在 target.insertDocument() 前插入： replaceVariablesInBody(sourceBody, Map.of("report_date", "2024-06-15")); private void replaceVariablesInBody(CTBody body, Map<String, String> vars) { // 遍历所有段落 for (CTP p : body.getPList()) { replaceInParagraph(p, vars); } // 遍历所有表格 for (CTTbl tbl : body.getTblList()) { for (CTTr row : tbl.getTrList()) { for (CTTc cell : row.getTcList()) { for (CTP p : cell.getPList()) { replaceInParagraph(p, vars); } } } } } private void replaceInParagraph(CTP p, Map<String, String> vars) { for (CTR r : p.getRList()) { for (CTText t : r.getTList()) { String text = t.getStringValue(); for (Map.Entry<String, String> entry : vars.entrySet()) { text = text.replace(entry.getKey(), entry.getValue()); } t.setStringValue(text); } } }注意：
CTText.setStringValue()会自动更新rId引用，无需手动处理CTHyperlink或CTProofErr。
6.2 按章节拆分导出：把合并后的长文档切成 N 个子文档
需求：合并生成的《年度审计报告.docx》需按“第一章 财务分析”、“第二章 合规检查”自动切分成独立文件。
关键：识别CTP中的标题样式（如Heading1），并获取其所在CTBody的物理位置。
// Splitter.java public List<File> splitByHeading1(XWPFDocument doc, String outputDir) { List<File> outputs = new ArrayList<>(); List<CTP> headings = new ArrayList<>(); // 扫描所有段落，找出 styleId == "Heading1" 的 CTP for (XWPFParagraph p : doc.getParagraphs()) { if ("Heading1".equals(p.getStyle())) { headings.add(p.getCTP()); } } // 按 heading 位置切分 body CTBody body = doc.getDocument().getBody(); for (int i = 0; i < headings.size(); i++) { CTP start = headings.get(i); CTP end = (i == headings.size() - 1) ? null : headings.get(i + 1); // 提取 start 到 end 之间的所有 CTP/CTTbl 节点（需手写 DOM 截取逻辑） CTBody subBody = extractSubBody(body, start, end); // 创建新文档，写入 subBody XWPFDocument subDoc = new XWPFDocument(); subDoc.getDocument().setBody(subBody); File out = new File(outputDir, "chapter_" + (i + 1) + ".docx"); try (FileOutputStream outStream = new FileOutputStream(out)) { subDoc.write(outStream); } outputs.add(out); } return outputs; }从那以后我每次接到文档处理需求，都强制走一遍unzip -l xxx.docx查看 part 结构，再对照 ECMA-376 标准核对styles.xml是否合法——这比在 Word 里反复打开试错快十倍。希望帮到你。
本文还有配套的精品资源，点击获取
