作为常年和 POI 打交道的 Java 开发我最初以为处理 Word 文档比 Excel 简单——毕竟 Word 不就是几段文字嘛结果第一次交付就翻车了。后来踩完一堆坑才明白Word 文档在开发眼里从来不是“一页纸”它是一个带样式层、表格网格、图表缓存、页眉页脚、修订记录的 XML 包裹结构每一个你以为“没问题”的细节最后都可能变成用户的报错截图。这篇博文我不打算写成官方文档的复读机只讲那些我在实际项目里验证过、摔过、然后修好的东西。内容围绕 Apache POI 操作 Word 文档展开覆盖段落样式、表格宽度、图片插入、变量替换、图表数据联动、批量导出以及热搜里反复出现的“表格宽度设了没用”“三级标题变二级”“修改图表后文档打不开”“表格下多出一行”这些真实问题。适合刚接手 POI 生成 Word 任务的开发也适合已经写了几个版本但总被格式问题折磨的同行。对了搜索资料时你可能会看到“高德 POI 下载工具”这类词那是指地图兴趣点和 Apache POI 完全是两个物种别搞混。下文所有 POI 均指 Apache 基金会的 Java 库。1. 先别急着写代码Word 文档的几个“反直觉”真相1.1 Word 不是“一页纸”它是一棵 XML 树我刚接触 POI 时有一个根深蒂固的错觉Word 文档就像 PDF 一样是一个“渲染完成”的平面。实际操作后才知道一个 .docx 文件本质上是一个 zip 压缩包里面装着 word/document.xml、word/styles.xml、word/settings.xml、word/numbering.xml、word/media/ 等一堆 XML 和资源文件。document.xml 里的内容是一棵树主体 body 下面挂着一堆块级元素段落是w:p表格是w:tbl表格又有若干行w:tr行里有单元格w:tc单元格里又嵌套段落。每个段落下面再挂若干个 runw:rrun 里才是真正的文字w:t。同一段话里字体、加粗、颜色不一样就会被拆成多个 run。这个结构意味着两件重要的事。第一修改一段文字不是“找到字符串然后替换”而是可能要跨多个 run 重新组装第二格式不是孤立的段落样式w:pStyle引用了 styles.xml 里的定义表格宽度同时受表格属性、网格列、单元格属性三重控制。如果只盯着某个 API 看很容易忽略它背后还有一层 XML 在起作用。摸清这棵树的长相后面所有问题都事半功倍。1.2 用 Excel 思维写 Word是所有人的第一个坑很多人从 POI 操作 Excel 转过来会带着一套惯性Worksheet 是网格Cell 是格子setCellValue 写数据然后指望 Word 也一样规整。但 Word 的主题是“流式排版”不是“表格定位”。段落是一个紧跟一个的表格虽然是块级元素但它内部的行列并不会自动撑满页面也不会像 Excel 那样天然有网格线。Excel 里你可以随意在某一行某一列写东西Word 里你必须先创建段落或表格再往里填 run。Excel 里合并单元格只是一条属性Word 里:w:vMerge需要配对设置而且合并后还要处理单元格里的残留段落。Excel API 里设置列宽很直观Word 里你设了tcW还可能被“自动适应窗口”干掉。举一个具体的例子。用XWPFTable table doc.createTable(3, 3)创建表格后如果你觉得“给每个单元格 setWidth 就完事了”那 Word 打开后大概率表格宽度完全不受控。因为表格本身有一个tblLayout控制布局模式如果 Word 处于“自动适应”它会根据内容重新分配列宽你设的值会被忽略。这就是为什么很多教程强调要先把 tblLayout 设成 fixed再分别设置 gridCol 和 tcW。如果带着 Excel 的思维去写最多半天就会发现代码没报错生成的文件长风不羁。转过身来承认“Word 是树、是流、是 XML”心态就稳了。1.3 路线怎么选纯 POI 还是模板填充动手之前先想清楚采用哪种实现路线。常见的有三条第一条是纯代码从零生成new XWPFDocument()然后一个段落一个段落地创建。优点是灵活适合文档结构简单的场景缺点也很明显任何复杂格式多级列表、专业页眉页脚、复杂表格都得手写大量配置维护成本高。第二条是模板填充。预先在 Word 里把模板做好用${xxx}这类占位符标记动态内容程序加载模板后只做替换和局部操作。这是我实际项目里的主力方案因为文档的排版、页眉页脚、水印这些视觉工作由 Word 完成最自然程序员只需要关心数据。缺点是占位符可能被 Word 拆成多个 run需要专门处理。第三条是模板 图表/图片联动。如果业务报表里有图表纯 POI 原生生成图表的功能很有限一般做法是模板中预置好图表程序只更新图表背后的数据缓存。这条路线比较冷门但真实场景很常见。没有绝对最好的路线只有最合适的。如果动态内容少、格式简单纯代码没问题如果要做排班表、合同、报告这类重格式文档模板填充几乎是唯一选项。2. 核心实操段落样式、表格宽度与图文混排2.1 段落样式与标题层级三级标题为什么会变二级关于“三级标题变二级标题格式不对”这个热搜问题POI 场景下出现的原因非常集中XWPFParagraph.setStyle()只是设置了一个样式 ID 字符串它不会帮你检查 styles.xml 里有没有这个 ID也不会管这个 ID 对应的outlineLvl是多少级。假如你要生成三级标题代码是这样的XWPFParagraph para doc.createParagraph(); para.setStyle(Heading3); XWPFRun run para.createRun(); run.setText(这是一个三级标题);这段代码看着没问题但它成立的前提是模板或文档的 styles.xml 里存在 styleId 为Heading3的段落样式该样式的w:outlineLvl值是 2对应大纲级别第三级字体、段落间距等属性都由样式接管。如果模板里根本没有 Heading3POI 不会报错打开后 Word 会自动用默认样式渲染形态就可能落到 Heading2 甚至 Normal 上。还有一种情况你用的是setStyle(3)而不是setStyle(Heading3)而文档样式库里恰好没有 ID 为“3”的样式抛出文档主题样式混乱标题层级自然不对。我的排查套路是三步。第一步用压缩工具打开模板 docx直接看 word/styles.xml 里有哪些 styleId。第二步检查 Heading3 对应样式的w:outlineLvl w:val2/是否在。第三步如果要在代码里确保安全干脆不进样式表直接给段落 run 设置字体、字号、加粗、段前段后间距写成一组工具方法相当于“手动模拟”标题样式。从底层来看Word 的“标题层级”不只靠肉眼字体大小区分更关键的是大纲级别它影响导航窗格和目录生成。所以诊断问题别只看字体大小对不对要抓 outlineLvl 这个根因。2.2 表格单元格宽度设置了两遍还是失效根源在 tblW 和 tcW这是热搜词里出现频率极高的一项poi 设置 word 表格单元格宽度。很多人卡在一个现象上——代码里已经给XWPFTableCell调用了setWidth()甚至给表格也设了宽度但生成的 Word 打开后列宽完全不受控。根因是我在 1.2 提到的“三重控制”。Word 表格宽度由三层属性共同决定第一层是表格级属性w:tblPr里的w:tblW这是表格整体宽度可以填具体数值单位是 twips1 厘米约等于 567 twips也可以填auto或百分比。第二层是w:tblGrid里的w:gridCol它定义了每一列的默认宽度。第三层是单元格级属性w:tcPr里的w:tcW它可以覆盖 gridCol。只设置tcW但表格级tblLayout还是autofitWord 会根据内容自动重算宽度你的设置等于白做。正确姿势是三步走XWPFTable table doc.createTable(2, 3); // 第一步表格布局设为固定 CTTblPr tblPr table.getCTTbl().getTblPr(); CTTblLayoutType layout tblPr.addNewTblLayout(); layout.setType(STTblLayoutType.FIXED); // 第二步设置表格整体宽度建议用固定值不用 percent table.setWidth(100%); // 第三步设置每个网格列的宽度 CTTblGrid grid table.getCTTbl().getTblGrid() null ? table.getCTTbl().addNewTblGrid() : table.getCTTbl().getTblGrid(); for (int i 0; i 3; i) { CTTblGridCol col grid.sizeOfGridColArray() i ? grid.getGridColArray(i) : grid.addNewGridCol(); col.setW(BigInteger.valueOf(2400)); // 2400 twips ≈ 4.23cm } // 第四步同步设置每个单元格的 tcW for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { cell.getCTTc().addNewTcPr().addNewTcW().setW(BigInteger.valueOf(2400)); } }我在给表格设置宽度时习惯让三处数值保持一致。gridCol 是整个表格的“骨架子”tcW 是每个单元格的实际表现如果只有其中一处生成的 docx 虽然也能打开但列宽在不同 Word 版本里表现可能不一致。另外如果表格是从已有模板复制的还要检查模板里是否有一个w:tblW w:typepct w:w5000/这种百分比宽度它和代码里的 twips 值会叠加产生奇怪结果务必统一。2.3 图片插入与“文本以外”的内容清理热搜词里有一条“word 文档怎么去除文本以外的”开发视角下它对应的常见操作有两类插入图片后清理多余区域以及删除文档里残留的水印、批注、修订记录。先讲图片插入。POI 的图片插入没有想象中那么复杂但有几个细节决定成败XWPFParagraph para doc.createParagraph(); para.setAlignment(ParagraphAlignment.CENTER); XWPFRun run para.createRun(); try (InputStream in new FileInputStream(chart.png)) { run.addPicture(in, Document.PICTURE_TYPE_PNG, chart.png, Units.toEMU(360), Units.toEMU(200)); } catch (Exception e) { // 图片格式不支持时这里会抛异常 }注意Units.toEMU()这个转换。Word 内部图片尺寸用的是 EMUEnglish Metric Unit1 像素在 96 DPI 下约等于 9525 EMU。直接传360这种数字会被当作 EMU图片就变成比针尖还小。我见过不少同事栽在这里图片插入成功但什么都看不见。至于“去除文本以外的内容”要分对象处理。水印通常在页眉区域可能是图片也可能是艺术字清除需要拿到 header 的段落逐个删除 run 里的 drawing批注在 word/comments.xml 里POI 没有现成的删除 API要拿到 XML 节点再移除修订痕迹表现为w:ins和w:del节点需要遍历 body 把这些节点替换为普通文本。写一个通用清理方法时我建议直接操作底层 CT 对象而不是依赖高层 XWPF 类。原因是很多“文本以外的内容”在高层 API 里根本没有暴露对应的方法与其反射绕路不如用document.getDocument().getBody()拿 CTBody再配合 XPath 找到目标节点删除。这种方式代码看起来丑一点但能处理的情况广得多。3. 高阶玩法变量替换、图表数据联动与批量导出3.1 变量替换占位符被拆成好几段 run是原生的核心痛点模板填充最核心的痛点就是${name}这个占位符在 Word 里被拆成了好几个 run比如${一个 runname一个 run}一个 run。如果你直接用paragraph.getText()去搜找到的是拼接后的字符串但没法定位到具体哪个 run 要替换。我最早的处理方案是“整段重写”发现段落文本包含占位符后把段落里所有 run 的文字清空用第一个 run 重新写入替换后的文本。这样做简单但会丢失段落内部的特殊格式。比如一段话里“金额是 ${amount} 元”其中“元”是红色字体整段重写后红色字体就没了。后来我换成一种更稳妥的做法基于 CT 层遍历 run把每个w:r下的w:t文本收集起来和目标字符串做前缀匹配。匹配到占位符开始位置后把占位符所在的 run 拆开处理——保留格式不变只修改w:t的文本内容。思路类似字符串处理里的“区间替换”但落点放在 run 上。public static void replaceInParagraph(XWPFParagraph paragraph, String oldText, String newText) { ListXWPFRun runs paragraph.getRuns(); StringBuilder fullText new StringBuilder(); for (XWPFRun run : runs) { fullText.append(run.text()); } int idx fullText.indexOf(oldText); if (idx 0) { return; } // 将整段文本重组后用第一个 run 写入其余 run 置空 // 适合占位符分散在多个 run 且段落内不需要复杂格式的情况 String first fullText.substring(0, idx); String last fullText.substring(idx oldText.length()); if (runs.size() 0) { runs.get(0).setText(first newText last, 0); for (int i 1; i runs.size(); i) { runs.get(i).setText(, 0); } } }上面这段代码属于“能用但不完美”的级别适合段落格式简单、占位符是独立词的场景。如果段落里既有占位符又有复杂格式我建议引入第三方封装库比如 poi-tl它内部已经处理了 run 拆分问题。虽然标题是“POI 生成 Word”但实际工作中合理借助成熟轮子并不丢人。还有一个容易忽略的点替换后生成的文档可能残留空格。Word 在输入${name}时词法检查会自动在单词前后加空格这些空格在 XML 里是实实在在的字符替换时要把它们一并考虑进去。否则你会看到“金额是 500 元”变成“金额是 500 元”中间多个空格用户一眼就能看出是程序生成的。3.2 图表能生成吗修改模板图表数据才是主流方案热搜词里有好几条关于图表java poi word 能生成图表吗、通过修改模板中的图表数据修改 word 图表、poi word 替换 word 中的图表数据。结论先说POI 能拿到文档里的图表对象但想从零创建一个美观的图表非常痛苦主流的可靠方案是“模板预置图表 程序改数据”。一个 docx 里的图表实际上由两部分组成图表定义 XML在 word/charts/chartXXX.xml和一份内嵌的 Excel 工作表在 word/embeddings/Microsoft_Excel_工作表.xlsx。Word 打开文档时图表显示的图形来自 chart XML但图表对应的原始数据表来自内嵌 Excel。这就是“修改数据后无法打开生成的 word”这条热搜的根本原因——很多人只改了 chart XML忘了内嵌的 Excel 缓存Word 打开时发现两边数据对不上就直接报错或要求修复。正确的修改流程要两条线一起走。首先通过 POI 拿到图表对象读取它的底层 CTChartListXWPFChart charts doc.getCharts(); if (!charts.isEmpty()) { XWPFChart chart charts.get(0); CTChart ctChart chart.getCTChart(); // 找到要修改的序列更新 c:numCache 或 c:strCache 里的值 // ctChart.getPlotArea().getLineChartArray(0).getSerArray(0)... }第二步是同步更新内嵌 Excel。POI 对 embedding 这类关联文件的支持不算好我实际项目中是直接用一个额外的XSSFWorkbook打开那份内嵌 xlsx修改对应单元格再写回 zip。因为 docx 是 zip用 ZipInputStream 拆开、改掉 charts 和 embeddings 两份文件、再 ZipOutputStream 拼回去这条路看着原始但最可控。这里有一个经验之谈每次更新图表数据后都要留一份“修改前”的原始模板做对比。如果用户反馈某个图表打开报错先检查是不是只更新了 chart XML 而没有更新 embedding这是九成图表损坏问题的来源。3.3 批量导出多份文档如何给每份加上独立编号“多表单导出”和“每份打印带不同编号”这两个热搜本质是同一个需求循环模板每次替换不同的数据生成多份文档。先给一个最简单的框架FileInputStream templateStream new FileInputStream(template.docx); for (int i 0; i list.size(); i) { XWPFDocument doc new XWPFDocument(templateStream); replaceTokens(doc, list.get(i)); try (FileOutputStream out new FileOutputStream(output_ i .docx)) { doc.write(out); } doc.close(); templateStream.getChannel().position(0); // 重置流位置或者干脆每次重新 new }注意上面这段代码有个隐藏问题——XWPFDocument构造函数会读取整个模板到内存同一个模板重复创建十份内存里就有十份完整的文档树。模板稍微复杂一点带图表、图片、页眉页脚单份可能吃掉几十 MB 堆内存循环一多就容易 OOM。我的改良做法是模板解析一次得到XWPFDocument后存入变量每次导出时通过深拷贝文档树来获得新实例如果不想引入深拷贝库就在每次循环里重新从模板文件读取并立即使用用完马上 close把存活时间压到最短。给不同文档加编号也有几种方案。最简单的是把${docNo}作为普通变量替换如果编号需要出现在页眉或页脚就要定位到 header/footer 里的段落再替换。更“高级”一点的做法是利用 docx 的 custom properties把编号写入文档属性这样在系统的“文档信息”里也能看到编号。我之前在合同批量生成项目里就把合同编号同时写进正文和文档属性用户查文件时不用打开就能确认是哪份合同。还有一个实战细节批量导出失败时不要一个文件覆盖一个文件地写。先写到临时目录全部成功后再统一移动到目标位置。否则中途报错时目标目录里可能残留一批“半成品”文档用户不小心打开还以为生成成功了。4. 问题排查实录从报错到格式错乱逐一拆给你看4.1 图表数据修改后生成的文件打不开或提示修复这类问题我在 3.2 说了根因——chart XML 和内嵌 Excel 数据不一致。但实际现场还有几种变体值得单独列出来。第一种是修改了 chart XML 里的数值但忘记同步数字格式。比如图表数据是金额你在 chart XML 里写了1234.5但内嵌 Excel 里的单元格格式还是“文本”Word 打开图表后无法正常格式化表现就是图表数据错乱。第二种是只改了序列的显示值没改分类轴标签。柱状图、折线图都有w:cat和w:val两套数据只改 val 不改 cat图表会显示旧标签配新数值用户一看就是“数据对不上”。第三种最隐蔽图表里带有缓存数据w:numCache和w:strCache这里的数据是图表渲染前预先生成的快照。你改了w:numRef指向的外部引用但如果 cache 没更新Word 还是会用旧的 cache 渲染。这也是为什么很多修改图表数据的代码“看起来改了、打开没变”。我的处理原则是宁可把图表相关的所有缓存节点全部更新也不要偷懒只改一处。虽然代码多一些但生成的文件在 Word 和 WPS 里打开都稳定。让我整理一份常见问题速查表把项目里遇到过的典型问题列在一起问题现象根源排查方向表格列宽设置无效tblLayout 不是 fixedgridCol 与 tcW 不一致检查 TblPr、TblGrid、TcPr 三处三级标题变成二级样式 ID 不存在或 outlineLvl 不对检查 styles.xml修改图表后文件损坏chart XML 与 embedding xlsx 不同步对比两份数据占位符没被替换占位符被多个 run 拆分先合并全文再替换表格下多出一行表格末尾有空白段落或分节符检查 body 元素顺序图片不显示EMU 换算错误尺寸为 0用 Units.toEMU 转换文档打开很慢图片过大或 run 数量过多压缩图片、合并 run4.2 表格下方多出一行删不掉、局部空白无法删除“word 文档表格下多出一行在下一页如何删除”和“局部有空白无法删除”这两条热搜在开发生成的文档里非常典型。先说表格下多出一行。POI 创建表格时表格后面会跟着一个空段落这是 Word 文档结构的硬性要求——表格不能是 body 的最后一个元素必须有一个段落跟在后面。如果你在表格后直接创建新表格或分页符这个“厂”出来的空段落就会被挤到下一页用户看到的就是“表格下面多出一行且删不掉”。应对办法有两种。一种是把空段落的字号设为 1pt、段前段后间距设为 0让它变得几乎不可见。另一种是保留空段落但把它的样式设为模板里的“正文无间距”样式避免占用额外空间。至于“局部空白无法删除”常见原因有两个。第一个是单元格或段落里有大量的w:spacing w:before.../和w:spacing w:after.../视觉上空出一大块但用户怎么按删除键都没反应。第二个是文档里残留了分页符w:br w:typepage/或分节符它们是不可见字符却强制把后续内容推到下一页。排查这类问题时我习惯用 Notepad 打开生成的 docx 的 document.xml直接搜索w:br和w:spacing。代码里看不到的问题在 XML 里通常一目了然。4.3 文档体量一大就卡死性能与内存的取舍热搜词“mac 运行大型 word 文档卡顿”是桌面端用户遇到的性能问题但我们在生成端同样会遇到几 MB 的模板循环填充数据后生成 500 页的报告POI 的XWPFDocument.write()耗时十几秒内存飙到上 GB甚至直接 OOM。原因要从 POI 的模型结构说起。XWPFDocument 把整个文档树加载到内存段落、run、表格、图片全部是 Java 对象。一个 500 页的文档动辄几十万个 run 对象每个 run 又持有 XML 节点引用。再加上模板里如果嵌入了多张高清图片内存压力会更大。我的优化手段按收益从高到低排列第一压缩图片。插入前先用 ImageIO 把图片缩放到目标尺寸不要直接把 4000x3000 的高清大图塞进文档。一张压缩后的图片可能从 5MB 降到 100KB效果立竿见影。第二合并 run。Word 编辑文档时会产生大量内容碎片POI 生成时如果反复在同一个段落里createRun()就会生成很多细碎的 run。可以在每段写完时做一个合并把同一段落内格式相同的 run 合并为一个。这个优化能显著减少 XML 节点数量。第三分批写入。如果业务上可行不要一次性生成 500 页而是按章节生成多个 docx 再合并。合并时只操作 XML 层面的 body 内容绕开高层 API。第四及时关闭。doc.close()不只是释放文件句柄它还会清理内部缓存。批量导出场景里忘记 close 是内存泄漏的头号原因。结合桌面端的卡顿还有一个思路给到前端用户尽量用“另存为”而不是在同一个大文档里持续编辑因为 Word 在编辑时会在内存里维护整个文档的撤销栈文档越大越容易卡。这不是开发能解决的问题但可以在交付说明里提醒用户。最后说点实际操作里的体会。用 POI 生成 Word 文档最大的成本不是学会 API而是建立起“文档底层是 XML”这个心智模型。遇到任何诡异问题先解压 docx 看 XML比在 Java 代码里盲猜快得多。我在一个合同生成项目里维护了一个公共工具类里面就三个方法清理无效节点、修复表格宽度、合并碎 run这个工具类帮我把大部分“玄学格式问题”都变成了确定性的代码问题。另外一个值得分享的经验是每次生成完文档后不要只看结果对不对要用 Word 的“打开并修复”功能跑一遍或者用 LibreOffice 转换一次把转 PDF 的过程作为回归测试。能通过转换的文档才大概率在用户的各种环境下表现正常。POI 这条路走到后面拼的其实是细心——你替用户多想一层格式问题用户就少发一次脾气。