用Java导出Word报表十次里有八次会撞上“表格里相同字段的单元格要合并”这个需求。比如人员名单按部门导出一个部门下有十个人“部门”这一列就会重复十次打印出来又乱又占地方需求方看到第一眼就会提把相同部门合并成大单元格。这就是我这次要写透的问题怎么用Java操作Word表格按照某个字段的值来合并单元格同时保证样式、边框、跨页表现都正常。网上搜这个需求的资料很碎大多是“用POI可以合并”但真正能直接复现的完整代码和避坑记录很少。我把自己在实际项目中踩过的坑、总结出的通用方法、和一批能直接落地的Java代码整理成这篇。适合正在做Java后端、尤其是处理办公文档导出的同学哪怕你之前没碰过POI照着下面的思路也能把功能写出来。1. 需求拆解为什么Word导出总绕不开“按字段合并单元格”1.1 这个需求到底长什么样先还原一个真实场景。假设要导出一张员工清单数据结构大概是这样的部门姓名工号岗位技术部张三1001后端工程师技术部李四1002后端工程师技术部王五1003前端工程师产品部赵六2001产品经理这张表最直观的问题就是“部门”列在视觉上非常重复。Word表格不像Excel那样自带“合并相同单元格”的菜单需求方说的“按字段合并”本质就是找出某一列中值相同的连续行把它们的单元格纵向合并成一个大单元格内容只保留第一个。合并后的效果应该是这样部门姓名工号岗位技术部跨3行张三1001后端工程师李四1002后端工程师王五1003前端工程师产品部赵六2001产品经理这种需求在月度考勤、商品清单、订单明细、项目排期里非常常见。字段可以是部门、状态、日期、类型甚至多个字段联合分组。核心逻辑是一样的先按合并字段排序再找到连续相同值的区间最后对区间执行合并动作。1.2 方案对比别急着写代码先想清楚用什么工具Java生态里生成Word文档的方案不少我先把我实际对比过的几个说清楚Freemarker docx模板适合结构完全固定的合同、证明文件用占位符往模板里套数据。但遇到“行数不确定”“合并单元格动态变化”这种需求模板法会非常痛苦。因为你得提前在模板里画好合并区域数据一变方案就塌了。docx4j功能很强改XML的能力不逊于POI但API风格和POI差异大文档资料相对少。如果你团队没人用过上手成本不低。Apache POI我用得最多的方案。XWPF模块提供了一套面向对象的模型能直接创建表格、遍历单元格、修改底层XML理论上Word表格能做的操作它都能碰。缺点是API偏底层很多“看起来很简单”的功能其实没有一键方法比如合并单元格。直接改document.xmlWord文档本质是ZIP包里的XML理论上可以直接手动生成或改造XML。但几乎没人会这么干可维护性太差只适合拿来理解底层原理。我的选择是Apache POI理由很简单资料相对多、社区活跃、能动态处理任意表格而且合并单元格的底层标记通过它操作最直观。后面所有代码都基于POI。2. 基础准备POI操作Word表格的核心模型2.1 Maven依赖与版本说明要用POI操作Word表格核心依赖是两个dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.5/version /dependency这里有个坑必须先说poi和poi-ooxml的版本必须一致不然运行时极容易遇到NoSuchMethodError这类诡异报错。如果你项目里还用了poi-tl、EasyPOI这类封装库更要注意版本冲突最好统一用一个版本。JDK方面POI 5.x要求JDK 8以上实际我建议至少JDK 11因为较新版本的POI在内存管理和处理大文件上更稳。2.2 表格在POI里到底长什么样要理解合并单元格先要明白POI里Word表格的层级模型XWPFDocument // 对应整个docx └─ XWPFTable // 对应文档中的一个表格 └─ XWPFTableRow // 表格的一行 └─ XWPFTableCell // 一行中的一个单元格 └─ XWPFParagraph // 单元格里的段落 └─ XWPFRun // 段落里的文本片段合并单元格这件事POI没有提供merge()这种现成方法你要操作的是每个单元格底层的XML对象CTTc。Word描述单元格合并的方式并不复杂第一个单元格标记为合并起点(START)后续单元格标记为合并继续(CONTINUE)。这个标记位于单元格属性CTTcPr下的vMerge节点。打个比方Word中的合并单元格很像一个拼图起点格子是第一块后面被合并的格子只是“隐藏了自己”在渲染时被前一个格子“吸”过去。所以合并后你会看到那几行里只有第一个格子里有内容其余格子是空的但边框是连成一块的。理解这一点后代码思路就清晰了给起点格设置vMergeSTART给后续格设置vMergeCONTINUE并清空内容。2.3 定位目标表格和动态表头一个Word文档里可能有很多表格必须先定位你要操作的那个。最简单的方案是按索引取XWPFDocument document new XWPFDocument(inputStream); ListXWPFTable tables document.getTables(); // 例如取文档中的第二个表格索引是1 XWPFTable targetTable tables.get(1);如果你想更稳妥可以遍历表格判断行数和列数是否符合预期或者给目标表格加一个书签再通过书签定位。实际项目中我更喜欢“按索引行列数验证”的组合简单可靠。说到表头很多人会忽略一个细节表头字段名不一定等于数据库字段名更常见的是“字段注释”。像MySQL里字段有COMMENT注释这些注释才适合展示给用户。用JDBC可以这样取DatabaseMetaData metaData connection.getMetaData(); ResultSet columns metaData.getColumns(null, null, tableName, %); while (columns.next()) { String columnName columns.getString(COLUMN_NAME); String remarks columns.getString(REMARKS); System.out.println(columnName - remarks); }这里有个隐藏坑MySQL驱动下如果连接URL没有加useInformationSchematruegetColumns()返回的REMARKS很可能为空。我自己就因为这个排查了半天。把这个开关加上之后字段注释才能正常读出来。顺带说一句这个思路可以让你的导出工具表头动态生成而不是写死在代码里。3. 核心实现按字段合并单元格的完整代码3.1 合并前必须先做数据排序合并的逻辑是基于“连续相同值”的所以数据必须先排序。如果从数据库查直接ORDER BY要合并的字段ORDER BY dept_name, position。如果数据是接口返回的就在内存里排ListEmployee list getEmployeeList(); list.sort(Comparator .comparing(Employee::getDeptName) .thenComparing(Employee::getPosition, Comparator.nullsLast(String::compareTo)));排序时一定要注意空值的处理。建议把null当成普通值参与排序并统一转换成空字符串避免NullPointerException。排序的意义在于让相同字段值的记录扎堆出现否则后面找“连续区间”的算法就会出错。很多初次做这个功能的人跳过排序结果合并结果东一块西一块原因就在这里。3.2 纵向合并的底层方法无论按哪个字段合并最终都会落到同一个动作把某一列的某几行纵向合并。我封装了一个通用方法private void mergeVertical(XWPFTable table, int col, int startRow, int endRow) { if (startRow endRow) { return; } // 第一个单元格标记为合并起点 XWPFTableCell startCell table.getRow(startRow).getCell(col); CTTc startTc startCell.getCTTc(); CTTcPr startTcPr startTc.isSetTcPr() ? startTc.getTcPr() : startTc.addNewTcPr(); CTVMerge startMerge startTcPr.isSetVMerge() ? startTcPr.getVMerge() : startTcPr.addNewVMerge(); startMerge.setVal(STMerge.START); for (int r startRow 1; r endRow; r) { XWPFTableCell cell table.getRow(r).getCell(col); CTTc tc cell.getCTTc(); CTTcPr tcPr tc.isSetTcPr() ? tc.getTcPr() : tc.addNewTcPr(); CTVMerge vMerge tcPr.isSetVMerge() ? tcPr.getVMerge() : tcPr.addNewVMerge(); vMerge.setVal(STMerge.CONTINUE); clearCellContent(cell); } }为什么CONTINUE的单元格必须清空内容因为Word渲染时合并区域虽然显示成一个大格子但每个单元格内部的段落文本仍然存在。如果你不清空会出现文字堆叠、内容重叠甚至乱码的情况尤其在转PDF时特别明显。清空内容时我建议保留一个空段落避免后续操作读取单元格时出现NPEprivate void clearCellContent(XWPFTableCell cell) { for (int i cell.getParagraphs().size() - 1; i 0; i--) { cell.removeParagraph(i); } cell.addParagraph(); }这里要特别注意行索引从0开始。如果第0行是表头那么数据行是从第1行开始的合并区间千万不要把表头带进去。3.3 单字段分组合并的主流程有了底层合并方法主流程就清晰了遍历数据行比较当前行和上一行在目标列的值值相同就继续向后值不同就把已统计的区间执行一次合并。下面是一段完整示例。我假设表格已经用数据填充好了表格结构是第一行表头后续行为数据行目标合并列是第0列public void mergeByField(XWPFTable table, int dataStartRow, int mergeCol) { int rowCount table.getNumberOfRows(); if (rowCount dataStartRow) { return; } int mergeStart dataStartRow; String prevValue getCellText(table.getRow(dataStartRow).getCell(mergeCol)); for (int r dataStartRow 1; r rowCount; r) { String currentValue getCellText(table.getRow(r).getCell(mergeCol)); if (!equalsWithNull(prevValue, currentValue)) { mergeVertical(table, mergeCol, mergeStart, r - 1); mergeStart r; } prevValue currentValue; } mergeVertical(table, mergeCol, mergeStart, rowCount - 1); }辅助方法private String getCellText(XWPFTableCell cell) { if (cell null) { return ; } return cell.getText().trim(); } private boolean equalsWithNull(String a, String b) { if (a null b null) return true; if (a null) return false; return a.equals(b); }这个流程可以用一个例子推演一遍。表格第1行到第3行的“部门”都是技术部第4行是产品部。遍历时r从1到3一直相等到r4时“产品部”不等于“技术部”于是对第1到3行执行合并mergeStart更新为4。循环结束后再对第4到末尾执行合并。逻辑不难但容易漏掉最后一段区间所以循环结束后必须再调用一次mergeVertical。3.4 多字段联合分组比如“部门岗位”一起合并实际需求往往不止按一个字段。常见情况是一个是部门一个是岗位希望部门大合并岗位在部门内部小合并。比如技术部里“后端工程师”占两行这两行岗位也要合并。这时候不能简单地把两列分别跑一遍合并因为第一列的合并已经改变了部分行的结构状态再对第二列跑一次时区间容易错位。正确做法是先定义一个组合分组键把两列的值拼起来作为“大区间”判断依据。比如String key deptName \u0001 position;用这个key来划分区间区间内再对第二列岗位执行二次合并。实际封装时我会定义一个配置列表按优先级排列需要合并的列第0列部门最外层大合并第1列岗位在部门合并区间内的小合并代码大体是这样ListInteger mergeColumns Arrays.asList(0, 1); // 联合合并列顺序很重要遍历时以“所有合并列的值组合”作为分组键分组键变化时先对当前区间内的所有列从后往前执行合并同一个分组区间内再逐列细分。原则是先大后小、从外层到内层。如果先合并内层岗位列再合并外层部门列部门的大合并会把岗位合并的边界打乱渲染上就容易出现奇怪的格子边界。4. 格式与渲染合并只是开始好看才是交付4.1 合并后边框断裂怎么补这是合并单元格最典型的翻车现场合并完之后用Word预览发现单元格里面的竖线少了或者横线断成了几截。原因是VMerge标记的单元格本身没有显式设置边框Word在渲染时可能不会自动补齐。我的经验是给整个表格设置统一边框再给被合并的单元格单独设置边框双保险。表格级边框可以这样写private void setTableBorders(XWPFTable table) { CTTblPr tblPr table.getCTTbl().isSetTblPr() ? table.getCTTbl().getTblPr() : table.getCTTbl().addNewTblPr(); CTTblBorders borders tblPr.isSetTblBorders() ? tblPr.getTblBorders() : tblPr.addNewTblBorders(); borders.addNewTop().setVal(STBorder.SINGLE); borders.addNewBottom().setVal(STBorder.SINGLE); borders.addNewLeft().setVal(STBorder.SINGLE); borders.addNewRight().setVal(STBorder.SINGLE); borders.addNewInsideH().setVal(STBorder.SINGLE); borders.addNewInsideV().setVal(STBorder.SINGLE); setBorderSize(borders.getTop(), 000000, 4); setBorderSize(borders.getBottom(), 000000, 4); setBorderSize(borders.getLeft(), 000000, 4); setBorderSize(borders.getRight(), 000000, 4); setBorderSize(borders.getInsideH(), 000000, 4); setBorderSize(borders.getInsideV(), 000000, 4); }同时给每个被合并的单元格也设置tcBorders。这一步在样式敏感的交付场景里几乎必做。如果做完了还是缺线就检查是不是模板里自带了样式模板的样式优先级有时会影响最终效果。4.2 列宽、单元格宽度与自适应合并单元格之后列宽是另一个高频问题。尤其是“部门”这种内容短的列合并后Word可能按内容自适应宽度导致整张表格排版松散。正确做法是同时设置表格网格列宽和单元格宽度。Word的宽度单位是DXA1厘米约等于567 DXAm1英寸是1440 DXAm。提供一个常用方法private void setCellWidth(XWPFTableCell cell, int widthDXA) { CTTcPr tcPr cell.getCTTc().isSetTcPr() ? cell.getCTTc().getTcPr() : cell.getCTTc().addNewTcPr(); CTTblWidth tcW tcPr.isSetTcW() ? tcPr.getTcW() : tcPr.addNewTcW(); tcW.setW(BigInteger.valueOf(widthDXA)); tcW.setType(STTblWidth.DXA); }同时还要改tblGrid里的网格列宽CTTblGrid tblGrid table.getCTTbl().getTblGrid(); tblGrid.getGridColArray()[colIndex].setW(BigInteger.valueOf(widthDXA));两个都设列宽在Word里才能稳定生效。如果只是设tcWWord有时还是会按内容自动调整我之前在模板导出时就遇到过“列宽设了但显示不生效”的问题最后发现是tblGrid没改。另外如果你想做“表格宽度占满页面”的自适应效果可以给表格设置tblW为pct类型数值设为5000表示宽度占页面可用宽度的100%。4.3 跨页断行、表头重复与合并单元格显示数据量一大表格必然跨页。这里有两个很烦人的表现第一个是整行被整体移到了下一页导致当前页留白。这是因为表格行默认可能不允许跨页断行。解决方案是给所有行设置允许跨页对应XML是cantSplitfalse。POI里这样处理private void allowRowSplit(XWPFTableRow row) { CTTrPr trPr row.getCtRow().isSetTrPr() ? row.getCtRow().getTrPr() : row.getCtRow().addNewTrPr(); if (trPr.isSetCantSplit()) { trPr.unsetCantSplit(); } }默认情况下POI新建的行cantSplit通常不会显式设置问题不大。但如果你是基于模板复制出来的行模板里可能带上了cantSplittrue那就必须处理掉否则跨页时会出现大段空白。第二个是跨页后表头不见了。这个简单把第一行标记为标题行在每页重复出现private void setRepeatHeader(XWPFTable table, int headerRowIndex) { XWPFTableRow headerRow table.getRow(headerRowIndex); CTTrPr trPr headerRow.getCtRow().isSetTrPr() ? headerRow.getCtRow().getTrPr() : headerRow.getCtRow().addNewTrPr(); trPr.addNewTblHeader(); }这个细节非常影响阅读体验尤其是月度报表第一页有表头第二页只有数据用户很容易看错列。另外Excel打印合并单元格跨页出现空白内容的问题在Word里也有类似表现合并的单元格跨页后内容可能出现在后半部分整体观感不连贯。如果合并区间跨页且内容一定不能横跨两页就要提前在数据侧或者分页侧做处理这个没有绝对通用的解法通常是在数据量上做控制或在模板里安排合适的分页符位置。5. 踩坑实录与排查技巧5.1 合并后文字重叠或显示空白这是我被问的最多的问题。同一个症状两种原因。一是CONTINUE单元格没清空内容。前面已经说过合并动作会把多个格子在视觉上变成一个但每个格子的段落文本和样式都还在。不清空的话内容会在同一块区域里重叠显示。解决方法是清空继续格的内容只保留起点格文本。二是起点格内部有多个段落。如果你填充单元格时用了addParagraph()叠加内容起点格会显示好几段“重复感很强的文字”。解决方法是每次写单元格前先清空该格现有段落再写入文本。5.2 模板中已有表格合并后格子“乱套”如果你用的是Word模板模板里自带表格要特别小心。为什么因为模板表格里可能已经有合并过或隐藏过的格子这些历史属性会在你合并时和新设置冲突。尤其是“复制行”的场景用已有行当模板复制出多行复制时会连同旧的vMerge标记一起复制导致新行还没合并就已经处于合并状态。我的建议是如果模板表格结构简单直接用POI往现有表格里填数据如果结构复杂且涉及大量合并干脆在代码里从零创建表格虽然代码多一点但状态完全可控。5.3 大批量数据导出慢、内存高XWPFDocument是把整个文档加载到内存的数据量很大的时候容易触发OOM。我做过的实际项目里单个表格达到上万行时性能下降非常明显。这不是POI有bug而是docx的XML结构本身就是一大坨文本全量加载的模型自然吃内存。可行的规避办法有几个控制单个Word文档里的表格行数比如一个文档最多几千行数据量再大就拆分多个文档或一个文档里分多个表格表格之间用分页符隔开如果只是导出数据给用户做二次处理优先考虑Excel而不是WordExcel对应的SXSSF是流式写入内存表现好得多合并单元格本身也能减少最终XML里的冗余内容而且合并后格子数更少文件体积也小一点。5.4 嵌套表格与循环输出的合并问题Word表格里还能嵌套表格POI遇到这种结构时getTable()拿到的外层表格和嵌套表格是各自独立的对象。如果你在外层表格里做合并行索引只作用于外层如果嵌套表格也需要合并必须单独取出内层表格再走一遍合并逻辑。还有一个和“循环输出”相关的点如果你的表格是嵌套循环生成的比如外层遍历部门内层遍历员工每次循环都会新增行。这时候不建议每次循环都即时做合并因为行还有可能继续增加合并区间算不准。正确做法是先完整填充所有数据行再按字段统一扫描合并。5.5 中文文件名与模板字体问题下载文件时如果文件名是中文直接在响应头里放原始中文名可能乱码需要用URLEncoder.encode或filename*UTF-8处理String fileName URLEncoder.encode(员工名单, UTF-8).replace(, %20); response.setHeader(Content-Disposition, attachment; filename*UTF-8 fileName);字体是另一个隐藏问题。同一个docx在Windows上打开是一个样在Linux服务器上生成后再打开字体可能变了。原因是Word文档本身不内嵌字体只记录字体名称渲染时依赖阅读端字体。导出时最好显式指定中文字体比如宋体、微软雅黑避免默认字体跨平台不稳定。5.6 字段注释与动态映射的坑前面提到用getColumns()读字段注释。实际开发中我建议把“数据库字段名”和“表格列索引”的映射关系显示定义出来而不是靠硬编码列号。比如MapString, Integer columnIndexMap new HashMap(); columnIndexMap.put(deptName, 0); columnIndexMap.put(employeeName, 1); columnIndexMap.put(jobNumber, 2);这样做的好处是后面需求变更调整列顺序只需要改映射关系不用改合并逻辑。6. 进一步封装与建议6.1 做一个通用的合并配置器把上面的逻辑收拢成一个工具类并不复杂。核心配置项就三样表格对象、数据起始行、要合并的列索引集合。public void mergeTableCells(XWPFTable table, int dataStartRow, ListInteger mergeColumns) { if (mergeColumns null || mergeColumns.isEmpty()) { return; } // 按合并列值组合分组 int rowCount table.getNumberOfRows(); int groupStart dataStartRow; String previousKey buildGroupKey(table, dataStartRow, mergeColumns); for (int r dataStartRow 1; r rowCount; r) { String currentKey buildGroupKey(table, r, mergeColumns); if (!Objects.equals(previousKey, currentKey)) { mergeGroup(table, groupStart, r - 1, mergeColumns); groupStart r; } previousKey currentKey; } mergeGroup(table, groupStart, rowCount - 1, mergeColumns); }buildGroupKey就是把每行的合并列值拼接成字符串拼接时用不可见分隔符避免字段值本身撞车。mergeGroup从后往前合并列保证外层列不破坏内层列的合并边界。这样封装后你只需要调用一个方法就能完成任意数量字段的联合合并。6.2 调试docx的杀手锏直接看XML如果你遇到特别诡异的样式或合并问题有个终极调试手段把docx文件后缀改成zip并解压直接打开word/document.xml看XML结构。你可以搜vMerge看看START和CONTINUE标记是否配对也可以搜tcBorders检查边框节点是否存在。这个方法远比用代码打日志直观。更高效的是用Microsoft Open XML SDK的Productivity Tool它可以清晰展示文档的所有XML节点还能帮你对照文档对象映射。我排查复杂合并问题时几乎全靠它确认是“代码逻辑错了”还是“XML结构本来就不对”。这一步很多资料不会提但确实能省大量时间。6.3 这些需求还能怎么扩展按字段合并单元格只是办公文档导出的一个基础能力。搞定它之后顺理成章能扩展的方向其实不少多级表头表头不止一行跨行跨列的表头本身也可以用合并实现单元格内多段文本一个格子里既有标题又有说明涉及段落级别样式控制生成图表POI的XWPFChart支持在Word里插入柱状图、饼图但配置和刷新的复杂度比表格合并高一个量级批量导出归档把多个表格模板拼到一个文档里配合书签跳转和目录生成。个人在实际操作中的体会是Word导出这类需求代码结构本身不难难的是“格式永远比预期复杂”。合并单元格只是入门后面还有边框、跨页、字体、页边距等一系列细节等着你。一旦把这次讲的这套底层模型理解透再遇到类似功能就会顺手很多。最后再提醒一句任何改动上线前务必先导一个几行的小样本文档解压看看XML再交给用户验收。这一步做好了能帮你少挨至少十次“这个样式不对”的投诉。