简介本资源面向需要在Java环境中批量生成定制化Word文档的开发者重点解决基于模板替换占位符、动态填充表格与图片的自动化文档生成问题适合具备一定Java基础、希望掌握POI模板引擎用法的中高级程序员。压缩包共11个文件约7.37MB包含5个jar依赖包poi、poi-ooxml、xmlbeans、dom4j等核心库、3个java源码文件CustomXWPFDocument、WordUtil、SimpleDocument覆盖文档封装与工具类实现、2个docx模板示例及1张效果图便于直接导入项目运行调试。目前已有4138人学习下载说明该方案在实际业务中认可度较高。读者可从中获得完整的模板占位符替换思路、表格单元格数据填充方法、文档写出与资源关闭的规范流程以及可复用的工具类代码帮助快速落地报告、合同等文档的自动化生成需求。1. 模板化生成 Word 的真实价值为什么我放弃了手写 POI 代码很多团队第一次接到「导出 Word 报告」需求时第一反应是打开文档用 XWPFDocument 一行行 addParagraph、addTable硬编码出一份文档。结果需求方一句「标题字号再大两号」「表格加个斑马纹」「页眉换成公司 Logo」代码就得推倒重来。我踩过这个坑一份 30 页的检测报告光调样式就写了 800 多行 Java维护成本高得离谱。Java POI 通过模板生成 Word 文档核心思路是把「内容」和「样式」彻底解耦。设计同学在 Word 里把版式、字体、页眉页脚、表格样式全部调好留出占位符后端只负责把数据塞进去。这样样式改动零代码内容填充逻辑稳定可复用。它适合需要批量出报告、合同、通知单的团队尤其是样式频繁变动、文档结构固定的场景。下面我把这套方案从选型到落地拆开讲包括我实际用过的占位符约定、表格行循环、图片替换和几个必踩的坑。2. 模板方案选型XWPF 与 XWPF-Template 到底怎么选2.1 原生 XWPF 的边界在哪里POI 的 XWPF 模块能读写 .docx这是所有方案的基础。它提供了 XWPFDocument、XWPFParagraph、XWPFRun、XWPFTable 这些类理论上你能操作文档里的每一个 XML 节点。但原生 API 有个明显问题它面向的是「文档结构」不是「模板填充」。你要替换一个占位符得自己遍历所有段落、所有 Run判断文本里有没有{{name}}还要处理占位符被 Word 拆成多个 Run 的情况——这是最常见的翻车点后面避坑章节会细说。原生 XWPF 适合什么场景文档结构完全动态、每次生成都不一样比如根据用户输入拼出一份全新合同。这种场景没有「模板」可言只能靠代码构建。但只要你的文档有固定版式哪怕只是页眉页脚固定用模板都会比纯代码省力。2.2 XWPF-Template 这类封装库解决了什么社区里有若干基于 XWPF 的模板引擎封装常见做法是定义一套占位符语法比如{{var}}表示文本替换、{{#list}}...{{/list}}表示表格行循环、{{image}}表示图片替换。它们内部帮你处理了 Run 拆分、段落合并、表格行复制这些脏活。选型时重点看三件事是否支持表格行循环、是否支持图片替换、是否还在维护。我一般会先评估需求复杂度。如果只是替换十几个文本占位符原生 XWPF 写个工具类就够了引入第三方库反而增加依赖风险。如果涉及表格动态增行、嵌套列表、图片插入用封装库能省掉大量边界处理。下面给一个原生 XWPF 的最小可用工具类你可以直接拿去改。import org.apache.poi.xwpf.usermodel.*; import java.io.*; import java.util.Map; public class WordTemplateUtil { /** * 替换段落和表格中的文本占位符 * param templatePath 模板文件路径 * param data 占位符 - 值 的映射 * param outPath 输出路径 */ public static void fill(String templatePath, MapString, String data, String outPath) throws IOException { try (FileInputStream fis new FileInputStream(templatePath); XWPFDocument doc new XWPFDocument(fis); FileOutputStream fos new FileOutputStream(outPath)) { // 处理正文段落 for (XWPFParagraph p : doc.getParagraphs()) { replaceInParagraph(p, data); } // 处理表格内段落 for (XWPFTable table : doc.getTables()) { for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { for (XWPFParagraph p : cell.getParagraphs()) { replaceInParagraph(p, data); } } } } doc.write(fos); } } private static void replaceInParagraph(XWPFParagraph p, MapString, String data) { // 关键先把段落所有 Run 的文本拼起来再整体替换最后写回第一个 Run StringBuilder sb new StringBuilder(); for (XWPFRun run : p.getRuns()) { String text run.getText(0); if (text ! null) sb.append(text); } String fullText sb.toString(); boolean changed false; for (Map.EntryString, String e : data.entrySet()) { String placeholder {{ e.getKey() }}; if (fullText.contains(placeholder)) { fullText fullText.replace(placeholder, e.getValue() null ? : e.getValue()); changed true; } } if (changed !p.getRuns().isEmpty()) { // 清空除第一个 Run 外的所有 Run把完整文本写回第一个 Run for (int i p.getRuns().size() - 1; i 0; i--) { p.removeRun(i); } XWPFRun first p.getRuns().get(0); first.setText(fullText, 0); } } }这段代码的核心逻辑是「先合并再替换」。Word 在保存时经常把一个{{name}}拆成{{、name、}}三个 Run如果你逐个 Run 去 replace永远匹配不到。所以先把段落内所有 Run 的文本拼成一个完整字符串替换完再写回第一个 Run同时删掉多余的 Run。参数上data的 key 不带花括号方法内部自动拼{{key}}这样调用方不用关心占位符格式。注意run.getText(0)里的 0 是文本位置索引一般用 0 即可。2.3 依赖引入与版本注意Maven 项目引入 POI 时生成 Word 只需要poi-ooxml它会自动带上poi和poi-ooxml-lite。不要同时引入poi-scratchpad那是处理 .doc 老格式的混在一起容易出类冲突。dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.3/version /dependency版本选择上5.x 系列对 JDK 要求是 8 及以上如果项目还在 JDK 8用 5.2.x 比较稳。4.x 和 5.x 在 API 上有一些不兼容改动比如XWPFRun.setText的重载行为升级时要注意回归测试。我一般会在 pom 里锁定版本避免传递依赖拉到不同版本导致NoSuchMethodError。3. 从模板设计到代码填充一套可复现的落地流程3.1 模板里占位符怎么设计才不容易翻车占位符设计直接决定后期维护成本。我的经验是文本占位符统一用{{字段名}}字段名用英文小写下划线不要用中文避免编码问题。表格行循环用{{#list}}和{{/list}}包裹循环标记单独占一行不要和内容混在同一行。图片占位符用{{logo}}这种带前缀的形式和文本区分开。还有一个细节占位符不要放在文本框、艺术字、页眉页脚里除非你确认封装库支持。原生 XWPF 对页眉页脚的处理是单独的 XWPFHeaderFooterPolicy遍历逻辑和正文不一样很容易漏。如果页眉需要动态内容建议单独写处理逻辑。3.2 表格动态增行的正确姿势表格行循环是模板生成里最复杂的部分。假设模板里有一个 3 行的表格第 2 行是数据行里面写着{{name}}、{{age}}你要根据列表数据复制这一行 N 次。原生 XWPF 没有现成的「复制行」API常见做法是手动创建 XWPFTableRow复制样式和单元格内容。/** * 根据模板行复制出数据行 * param table 目标表格 * param templateRowIndex 模板行下标从 0 开始 * param dataList 数据列表每个元素是一行的字段映射 */ public static void fillTableRows(XWPFTable table, int templateRowIndex, ListMapString, String dataList) { XWPFTableRow templateRow table.getRow(templateRowIndex); int insertIndex templateRowIndex; for (MapString, String rowData : dataList) { // 在模板行位置插入新行 XWPFTableRow newRow table.insertNewTableRow(insertIndex); // 复制模板行的单元格数量和宽度 for (int c 0; c templateRow.getTableCells().size(); c) { XWPFTableCell templateCell templateRow.getCell(c); XWPFTableCell newCell newRow.createCell(); // 复制段落文本并替换占位符 for (XWPFParagraph tp : templateCell.getParagraphs()) { XWPFParagraph np newCell.addParagraph(); np.setAlignment(tp.getAlignment()); XWPFRun nr np.createRun(); String text tp.getText(); for (Map.EntryString, String e : rowData.entrySet()) { text text.replace({{ e.getKey() }}, e.getValue()); } nr.setText(text); } } insertIndex; } // 删除模板行 table.removeRow(templateRowIndex dataList.size()); }这段代码的关键点是「插入位置」和「删除模板行」。insertNewTableRow(insertIndex)会在指定位置插入空行然后我们逐单元格复制模板行的段落和样式。注意这里只复制了文本和对齐方式如果模板行有背景色、边框、字体加粗需要额外复制 CTTcPr 属性否则新行样式会丢。最后删除原始模板行避免多出一行空数据。参数templateRowIndex要传模板中数据行的实际下标如果表格有表头通常是 1。3.3 图片替换为什么你的图片总是变形图片替换比文本麻烦。XWPF 里插入图片要用run.addPicture需要图片的输入流、图片类型和宽高单位是 EMU1 厘米约 360000 EMU。常见翻车是图片变形原因是宽高没按原图比例算。我的做法是先读原图尺寸按目标宽度等比算出高度。// 假设占位符 {{logo}} 在某个 Run 里 String imagePath /data/logo.png; try (FileInputStream picIn new FileInputStream(imagePath)) { // 目标宽度 4 厘米换算成 EMU int targetWidthEmu (int) (4 * 360000); // 读取原图宽高计算比例 java.awt.image.BufferedImage img javax.imageio.ImageIO.read(new File(imagePath)); int targetHeightEmu targetWidthEmu * img.getHeight() / img.getWidth(); // 清空占位符文本后插入图片 run.setText(, 0); run.addPicture(picIn, XWPFDocument.PICTURE_TYPE_PNG, logo.png, Units.toEMU(targetWidthEmu / 360000.0), Units.toEMU(targetHeightEmu / 360000.0)); }这里用Units.toEMU把厘米转成 EMU 更直观。注意addPicture的第四个参数是宽度 EMU第五个是高度 EMU别传反了。如果图片是 JPEG类型改成PICTURE_TYPE_JPEG。另外图片插入后如果发现位置不对检查占位符所在的 Run 是否在正确的段落里有时候占位符被拆到多个 Run需要先合并再插入。4. 避坑与排查模板生成 Word 最常见的 5 个翻车现场4.1 占位符替换不生效文档里还是{{name}}现象代码跑完没报错打开生成的文档占位符原封不动。原因Word 把{{name}}拆成了多个 Run逐个 Run 替换匹配不到。解决用 2.2 节里的「先合并再替换」逻辑把段落内所有 Run 文本拼起来再处理。如果占位符跨段落那只能改模板让占位符在同一段落内。4.2 表格行循环后样式全丢新行没有边框和底色现象动态增行的表格新行是白底无边框和模板行不一致。原因createCell创建的是默认样式的单元格没有复制模板单元格的 CTTcPr表格单元格属性。解决复制模板行的 XML 属性或者用cell.getCTTc().setTcPr(templateCell.getCTTc().getTcPr())把属性拷过去。更稳妥的做法是直接克隆模板行的 XML 节点再替换文本。4.3 生成的文档打开提示「内容有问题」现象Word 打开时弹窗提示文档损坏需要修复。原因通常是流没关干净或者doc.write(fos)之后又往同一个流写了东西。解决用 try-with-resources 确保 XWPFDocument 和输出流都正确关闭write之后不要再操作流。另外模板文件本身如果是 .doc 改后缀成 .docx也会导致这个问题确认模板是真正的 .docx 格式。4.4 中文乱码或字体丢失现象生成的文档里中文变成方框或乱码。原因模板里用的字体在运行环境不存在或者 Run 的字体设置没复制。解决模板统一用常见字体宋体、微软雅黑复制 Run 时把字体设置也带上包括setFontFamily和setFontSize。如果是在 Linux 服务器生成确认服务器装了对应中文字体否则即使文档里有字体名渲染时也会回退。4.5 大数据量生成时内存溢出现象批量生成几百份文档时 OOM。原因每份文档都 new 一个 XWPFDocument没有及时释放或者模板文件太大。解决生成完一份就关闭并置空引用用循环复用模板流。如果单份文档超过 50 页考虑拆分模板或者用 SXSSF 类似的流式思路——不过 POI 对 Word 没有流式写入支持只能控制单次处理量。5. 进阶技巧让模板方案在生产环境跑得更稳5.1 用单元测试守住模板契约模板和代码之间的契约就是占位符名称。一旦模板改了占位符但代码没同步线上就会生成一堆带{{}}的文档。我的习惯是写一个单元测试加载模板文件扫描所有段落和表格提取出所有{{...}}占位符和代码里定义的字段集合做比对不一致就测试失败。这样模板一改CI 就会报警。Test public void testTemplatePlaceholders() throws IOException { SetString expected Set.of(name, date, amount, logo); SetString actual new HashSet(); try (XWPFDocument doc new XWPFDocument(new FileInputStream(template.docx))) { Pattern p Pattern.compile(\\{\\{(.?)}}); for (XWPFParagraph para : doc.getParagraphs()) { Matcher m p.matcher(para.getText()); while (m.find()) actual.add(m.group(1)); } for (XWPFTable table : doc.getTables()) { for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { Matcher m p.matcher(cell.getText()); while (m.find()) actual.add(m.group(1)); } } } } assertEquals(expected, actual); }这个测试跑起来很快但能挡住 80% 的模板改错问题。注意para.getText()拿到的是段落纯文本如果占位符被拆成多个 RungetText()会自动拼接所以能匹配到。5.2 模板版本管理与灰度生产环境里模板文件不要直接覆盖建议按版本号命名比如report_v1.2.docx代码里配置当前使用的版本。新模板上线前先用一批历史数据生成样本人工比对样式和内容确认无误再切流量。如果发现样式异常回滚模板文件即可不用改代码。5.3 性能优化模板缓存与批量写出如果 QPS 不高每次读模板文件问题不大。但如果要批量生成上千份可以把模板文件读成 byte[] 缓存在内存里每次用new XWPFDocument(new ByteArrayInputStream(templateBytes))创建文档省掉磁盘 IO。注意 XWPFDocument 不是线程安全的每个线程要独立创建实例。写出时用 BufferedOutputStream 包一层减少系统调用。优化点做法收益模板缓存启动时读入 byte[]省去重复磁盘读流缓冲BufferedOutputStream写出速度提升明显对象复用线程内复用工具类减少 GC 压力批量提交攒够 N 份再写盘降低 IO 次数最后说个我自己的教训早期做模板生成时我图省事把占位符直接写在文本框里结果原生 XWPF 遍历不到排查了一下午才发现是文本框的锅。从那以后我定了个规矩——模板里所有动态内容必须放在正文段落或表格单元格里文本框、艺术字、SmartArt 一律不用。这个习惯帮我省掉了无数次玄学调试。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/13 15:38:36 · 阅读 1.2k Java POI模板化生成Word：告别手写代码，实现样式与内容解耦
简介本资源面向需要在Java环境中批量生成定制化Word文档的开发者重点解决基于模板替换占位符、动态填充表格与图片的自动化文档生成问题适合具备一定Java基础、希望掌握POI模板引擎用法的中高级程序员。压缩包共11个文件约7.37MB包含5个jar依赖包poi、poi-ooxml、xmlbeans、dom4j等核心库、3个java源码文件CustomXWPFDocument、WordUtil、SimpleDocument覆盖文档封装与工具类实现、2个docx模板示例及1张效果图便于直接导入项目运行调试。目前已有4138人学习下载说明该方案在实际业务中认可度较高。读者可从中获得完整的模板占位符替换思路、表格单元格数据填充方法、文档写出与资源关闭的规范流程以及可复用的工具类代码帮助快速落地报告、合同等文档的自动化生成需求。1. 模板化生成 Word 的真实价值为什么我放弃了手写 POI 代码很多团队第一次接到「导出 Word 报告」需求时第一反应是打开文档用 XWPFDocument 一行行 addParagraph、addTable硬编码出一份文档。结果需求方一句「标题字号再大两号」「表格加个斑马纹」「页眉换成公司 Logo」代码就得推倒重来。我踩过这个坑一份 30 页的检测报告光调样式就写了 800 多行 Java维护成本高得离谱。Java POI 通过模板生成 Word 文档核心思路是把「内容」和「样式」彻底解耦。设计同学在 Word 里把版式、字体、页眉页脚、表格样式全部调好留出占位符后端只负责把数据塞进去。这样样式改动零代码内容填充逻辑稳定可复用。它适合需要批量出报告、合同、通知单的团队尤其是样式频繁变动、文档结构固定的场景。下面我把这套方案从选型到落地拆开讲包括我实际用过的占位符约定、表格行循环、图片替换和几个必踩的坑。2. 模板方案选型XWPF 与 XWPF-Template 到底怎么选2.1 原生 XWPF 的边界在哪里POI 的 XWPF 模块能读写 .docx这是所有方案的基础。它提供了 XWPFDocument、XWPFParagraph、XWPFRun、XWPFTable 这些类理论上你能操作文档里的每一个 XML 节点。但原生 API 有个明显问题它面向的是「文档结构」不是「模板填充」。你要替换一个占位符得自己遍历所有段落、所有 Run判断文本里有没有{{name}}还要处理占位符被 Word 拆成多个 Run 的情况——这是最常见的翻车点后面避坑章节会细说。原生 XWPF 适合什么场景文档结构完全动态、每次生成都不一样比如根据用户输入拼出一份全新合同。这种场景没有「模板」可言只能靠代码构建。但只要你的文档有固定版式哪怕只是页眉页脚固定用模板都会比纯代码省力。2.2 XWPF-Template 这类封装库解决了什么社区里有若干基于 XWPF 的模板引擎封装常见做法是定义一套占位符语法比如{{var}}表示文本替换、{{#list}}...{{/list}}表示表格行循环、{{image}}表示图片替换。它们内部帮你处理了 Run 拆分、段落合并、表格行复制这些脏活。选型时重点看三件事是否支持表格行循环、是否支持图片替换、是否还在维护。我一般会先评估需求复杂度。如果只是替换十几个文本占位符原生 XWPF 写个工具类就够了引入第三方库反而增加依赖风险。如果涉及表格动态增行、嵌套列表、图片插入用封装库能省掉大量边界处理。下面给一个原生 XWPF 的最小可用工具类你可以直接拿去改。import org.apache.poi.xwpf.usermodel.*; import java.io.*; import java.util.Map; public class WordTemplateUtil { /** * 替换段落和表格中的文本占位符 * param templatePath 模板文件路径 * param data 占位符 - 值 的映射 * param outPath 输出路径 */ public static void fill(String templatePath, MapString, String data, String outPath) throws IOException { try (FileInputStream fis new FileInputStream(templatePath); XWPFDocument doc new XWPFDocument(fis); FileOutputStream fos new FileOutputStream(outPath)) { // 处理正文段落 for (XWPFParagraph p : doc.getParagraphs()) { replaceInParagraph(p, data); } // 处理表格内段落 for (XWPFTable table : doc.getTables()) { for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { for (XWPFParagraph p : cell.getParagraphs()) { replaceInParagraph(p, data); } } } } doc.write(fos); } } private static void replaceInParagraph(XWPFParagraph p, MapString, String data) { // 关键先把段落所有 Run 的文本拼起来再整体替换最后写回第一个 Run StringBuilder sb new StringBuilder(); for (XWPFRun run : p.getRuns()) { String text run.getText(0); if (text ! null) sb.append(text); } String fullText sb.toString(); boolean changed false; for (Map.EntryString, String e : data.entrySet()) { String placeholder {{ e.getKey() }}; if (fullText.contains(placeholder)) { fullText fullText.replace(placeholder, e.getValue() null ? : e.getValue()); changed true; } } if (changed !p.getRuns().isEmpty()) { // 清空除第一个 Run 外的所有 Run把完整文本写回第一个 Run for (int i p.getRuns().size() - 1; i 0; i--) { p.removeRun(i); } XWPFRun first p.getRuns().get(0); first.setText(fullText, 0); } } }这段代码的核心逻辑是「先合并再替换」。Word 在保存时经常把一个{{name}}拆成{{、name、}}三个 Run如果你逐个 Run 去 replace永远匹配不到。所以先把段落内所有 Run 的文本拼成一个完整字符串替换完再写回第一个 Run同时删掉多余的 Run。参数上data的 key 不带花括号方法内部自动拼{{key}}这样调用方不用关心占位符格式。注意run.getText(0)里的 0 是文本位置索引一般用 0 即可。2.3 依赖引入与版本注意Maven 项目引入 POI 时生成 Word 只需要poi-ooxml它会自动带上poi和poi-ooxml-lite。不要同时引入poi-scratchpad那是处理 .doc 老格式的混在一起容易出类冲突。dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.3/version /dependency版本选择上5.x 系列对 JDK 要求是 8 及以上如果项目还在 JDK 8用 5.2.x 比较稳。4.x 和 5.x 在 API 上有一些不兼容改动比如XWPFRun.setText的重载行为升级时要注意回归测试。我一般会在 pom 里锁定版本避免传递依赖拉到不同版本导致NoSuchMethodError。3. 从模板设计到代码填充一套可复现的落地流程3.1 模板里占位符怎么设计才不容易翻车占位符设计直接决定后期维护成本。我的经验是文本占位符统一用{{字段名}}字段名用英文小写下划线不要用中文避免编码问题。表格行循环用{{#list}}和{{/list}}包裹循环标记单独占一行不要和内容混在同一行。图片占位符用{{logo}}这种带前缀的形式和文本区分开。还有一个细节占位符不要放在文本框、艺术字、页眉页脚里除非你确认封装库支持。原生 XWPF 对页眉页脚的处理是单独的 XWPFHeaderFooterPolicy遍历逻辑和正文不一样很容易漏。如果页眉需要动态内容建议单独写处理逻辑。3.2 表格动态增行的正确姿势表格行循环是模板生成里最复杂的部分。假设模板里有一个 3 行的表格第 2 行是数据行里面写着{{name}}、{{age}}你要根据列表数据复制这一行 N 次。原生 XWPF 没有现成的「复制行」API常见做法是手动创建 XWPFTableRow复制样式和单元格内容。/** * 根据模板行复制出数据行 * param table 目标表格 * param templateRowIndex 模板行下标从 0 开始 * param dataList 数据列表每个元素是一行的字段映射 */ public static void fillTableRows(XWPFTable table, int templateRowIndex, ListMapString, String dataList) { XWPFTableRow templateRow table.getRow(templateRowIndex); int insertIndex templateRowIndex; for (MapString, String rowData : dataList) { // 在模板行位置插入新行 XWPFTableRow newRow table.insertNewTableRow(insertIndex); // 复制模板行的单元格数量和宽度 for (int c 0; c templateRow.getTableCells().size(); c) { XWPFTableCell templateCell templateRow.getCell(c); XWPFTableCell newCell newRow.createCell(); // 复制段落文本并替换占位符 for (XWPFParagraph tp : templateCell.getParagraphs()) { XWPFParagraph np newCell.addParagraph(); np.setAlignment(tp.getAlignment()); XWPFRun nr np.createRun(); String text tp.getText(); for (Map.EntryString, String e : rowData.entrySet()) { text text.replace({{ e.getKey() }}, e.getValue()); } nr.setText(text); } } insertIndex; } // 删除模板行 table.removeRow(templateRowIndex dataList.size()); }这段代码的关键点是「插入位置」和「删除模板行」。insertNewTableRow(insertIndex)会在指定位置插入空行然后我们逐单元格复制模板行的段落和样式。注意这里只复制了文本和对齐方式如果模板行有背景色、边框、字体加粗需要额外复制 CTTcPr 属性否则新行样式会丢。最后删除原始模板行避免多出一行空数据。参数templateRowIndex要传模板中数据行的实际下标如果表格有表头通常是 1。3.3 图片替换为什么你的图片总是变形图片替换比文本麻烦。XWPF 里插入图片要用run.addPicture需要图片的输入流、图片类型和宽高单位是 EMU1 厘米约 360000 EMU。常见翻车是图片变形原因是宽高没按原图比例算。我的做法是先读原图尺寸按目标宽度等比算出高度。// 假设占位符 {{logo}} 在某个 Run 里 String imagePath /data/logo.png; try (FileInputStream picIn new FileInputStream(imagePath)) { // 目标宽度 4 厘米换算成 EMU int targetWidthEmu (int) (4 * 360000); // 读取原图宽高计算比例 java.awt.image.BufferedImage img javax.imageio.ImageIO.read(new File(imagePath)); int targetHeightEmu targetWidthEmu * img.getHeight() / img.getWidth(); // 清空占位符文本后插入图片 run.setText(, 0); run.addPicture(picIn, XWPFDocument.PICTURE_TYPE_PNG, logo.png, Units.toEMU(targetWidthEmu / 360000.0), Units.toEMU(targetHeightEmu / 360000.0)); }这里用Units.toEMU把厘米转成 EMU 更直观。注意addPicture的第四个参数是宽度 EMU第五个是高度 EMU别传反了。如果图片是 JPEG类型改成PICTURE_TYPE_JPEG。另外图片插入后如果发现位置不对检查占位符所在的 Run 是否在正确的段落里有时候占位符被拆到多个 Run需要先合并再插入。4. 避坑与排查模板生成 Word 最常见的 5 个翻车现场4.1 占位符替换不生效文档里还是{{name}}现象代码跑完没报错打开生成的文档占位符原封不动。原因Word 把{{name}}拆成了多个 Run逐个 Run 替换匹配不到。解决用 2.2 节里的「先合并再替换」逻辑把段落内所有 Run 文本拼起来再处理。如果占位符跨段落那只能改模板让占位符在同一段落内。4.2 表格行循环后样式全丢新行没有边框和底色现象动态增行的表格新行是白底无边框和模板行不一致。原因createCell创建的是默认样式的单元格没有复制模板单元格的 CTTcPr表格单元格属性。解决复制模板行的 XML 属性或者用cell.getCTTc().setTcPr(templateCell.getCTTc().getTcPr())把属性拷过去。更稳妥的做法是直接克隆模板行的 XML 节点再替换文本。4.3 生成的文档打开提示「内容有问题」现象Word 打开时弹窗提示文档损坏需要修复。原因通常是流没关干净或者doc.write(fos)之后又往同一个流写了东西。解决用 try-with-resources 确保 XWPFDocument 和输出流都正确关闭write之后不要再操作流。另外模板文件本身如果是 .doc 改后缀成 .docx也会导致这个问题确认模板是真正的 .docx 格式。4.4 中文乱码或字体丢失现象生成的文档里中文变成方框或乱码。原因模板里用的字体在运行环境不存在或者 Run 的字体设置没复制。解决模板统一用常见字体宋体、微软雅黑复制 Run 时把字体设置也带上包括setFontFamily和setFontSize。如果是在 Linux 服务器生成确认服务器装了对应中文字体否则即使文档里有字体名渲染时也会回退。4.5 大数据量生成时内存溢出现象批量生成几百份文档时 OOM。原因每份文档都 new 一个 XWPFDocument没有及时释放或者模板文件太大。解决生成完一份就关闭并置空引用用循环复用模板流。如果单份文档超过 50 页考虑拆分模板或者用 SXSSF 类似的流式思路——不过 POI 对 Word 没有流式写入支持只能控制单次处理量。5. 进阶技巧让模板方案在生产环境跑得更稳5.1 用单元测试守住模板契约模板和代码之间的契约就是占位符名称。一旦模板改了占位符但代码没同步线上就会生成一堆带{{}}的文档。我的习惯是写一个单元测试加载模板文件扫描所有段落和表格提取出所有{{...}}占位符和代码里定义的字段集合做比对不一致就测试失败。这样模板一改CI 就会报警。Test public void testTemplatePlaceholders() throws IOException { SetString expected Set.of(name, date, amount, logo); SetString actual new HashSet(); try (XWPFDocument doc new XWPFDocument(new FileInputStream(template.docx))) { Pattern p Pattern.compile(\\{\\{(.?)}}); for (XWPFParagraph para : doc.getParagraphs()) { Matcher m p.matcher(para.getText()); while (m.find()) actual.add(m.group(1)); } for (XWPFTable table : doc.getTables()) { for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { Matcher m p.matcher(cell.getText()); while (m.find()) actual.add(m.group(1)); } } } } assertEquals(expected, actual); }这个测试跑起来很快但能挡住 80% 的模板改错问题。注意para.getText()拿到的是段落纯文本如果占位符被拆成多个 RungetText()会自动拼接所以能匹配到。5.2 模板版本管理与灰度生产环境里模板文件不要直接覆盖建议按版本号命名比如report_v1.2.docx代码里配置当前使用的版本。新模板上线前先用一批历史数据生成样本人工比对样式和内容确认无误再切流量。如果发现样式异常回滚模板文件即可不用改代码。5.3 性能优化模板缓存与批量写出如果 QPS 不高每次读模板文件问题不大。但如果要批量生成上千份可以把模板文件读成 byte[] 缓存在内存里每次用new XWPFDocument(new ByteArrayInputStream(templateBytes))创建文档省掉磁盘 IO。注意 XWPFDocument 不是线程安全的每个线程要独立创建实例。写出时用 BufferedOutputStream 包一层减少系统调用。优化点做法收益模板缓存启动时读入 byte[]省去重复磁盘读流缓冲BufferedOutputStream写出速度提升明显对象复用线程内复用工具类减少 GC 压力批量提交攒够 N 份再写盘降低 IO 次数最后说个我自己的教训早期做模板生成时我图省事把占位符直接写在文本框里结果原生 XWPF 遍历不到排查了一下午才发现是文本框的锅。从那以后我定了个规矩——模板里所有动态内容必须放在正文段落或表格单元格里文本框、艺术字、SmartArt 一律不用。这个习惯帮我省掉了无数次玄学调试。希望帮到你。本文还有配套的精品资源点击获取