做过Word模板导出功能开发的人多半都被“插入图片”这件事卡过。客户的描述永远很具体报告生成到第三页这一段下面必须放质检照片或者一个大表格里某些单元格要贴图。你翻遍POI的文档找到addPicture这个方法调完之后图片确实进来了位置却是文档末尾。今天这篇就专门聊聊“用POI操作Word在指定位置插入图片”的完整思路、代码实现和踩坑记录适合正在做报表导出、合同生成、批量证书打印或者任何用POI碰过Word模板填充的开发者。1. 别上来就写代码先搞清楚图片在docx里到底存在哪第一次用POI往Word里插图片的人基本都会走这么一条弯路先new XWPFDocument()然后doc.addPicture(...)图片确实进去了但永远在文档末尾。这不是bug也不是POI故意坑你而是因为docx的物理结构和我们日常写Word时的直觉完全不一样。一个.docx文件本质上是一堆XML打包在一起。正文内容放在word/document.xml里结构大致是文档Document下面是一个BodyBody下面是一排块级元素最主要的两种块是段落w:p和表格w:tbl。每个段落内部又有若干Runw:rRun才是真正承载文本的最小单位。一张图片在XML里不是一个独立的块它是挂在某个Run下面的一串Drawing元素。这就是关键点POI里段落XWPFParagraph没有addPicture方法能插图片的只有XWPFRun也就是段落里某个Run。所以“指定位置插入图片”这句话拆开看其实是两步定位到目标位置对应的段落或Run再调用那个Run上的addPicture。理解了这一层再看XWPFDocument.addPicture为什么没用就清楚了——它确实也能把图片加进文档但它只能新建一个段落并把图片放进去这个段落被追加在Body最后面。它不是“文档级”该有的操作更像是一个方便追加的快捷方法。想要往文档中间、模板某个位置插图必须自己控制游标和段落。还有一个容易忽略的细节Word中的Run是一段格式相同的文本。比如你写“第一段加粗第二段普通”这两段里就有不同的标签。图片挂在某个Run下意味着图片会和这个Run拥有相同的段落格式、字体设置。这也是为什么插入图片后它的缩进、行距、对齐方式经常要额外单独设置——因为图片事实上继承或者部分继承了Run所在的段落样式。搞清楚对象模型之后下一个问题自然就来了怎么定位标题里的“指定位置”到底怎么表达给POI2. 定位方案对比索引、文本锚点、书签到底选哪个“指定位置”说起来简单但实现时定位方式有几种选错后面全是坑。我把常见方案整理了一下按实际体验排序。定位方式实现难度抗模板改动能力模板可读性实测推荐度段落索引定位低差模板多一个段落就全错位差靠猜不推荐文本锚点定位中好只要锚点文字不被删就行好模板里一眼能看出标记强推书签定位中高好但POI对书签的封装比较绕一般Word里才看得见可以用但不优先表格行/单元格定位中取决于具体场景一般特定场景用索引定位是我最早试的方法。写起来最省事doc.getParagraphs().get(index)拿到段落就往前面插。但坏处非常致命模板只要被编辑过一次哪怕是多空了一行索引全部位移。而且批量插入时前一次插入会改变后续段落的索引位置得从后往前倒着插调试起来非常消耗耐心。这个方法只适合那种完全用代码动态生成的、结构永远不变化的文档不适合模板填充。书签定位理论上很优雅。Word里CtrlShiftF2加个书签POI里也有XWPFBookmark、getBookmarks()之类的东西。实际试下来书签要绑定到段落或者Run的XML节点上定位之后进行操作还得自己转游标代码绕模板使用者还未必会加书签。不是不行是性价比低。我最后稳定使用的是文本锚点定位。做法很简单在Word模板里写一行占位符比如{{IMG}}或者更具体的{{IMG_QUALITY}}、{{IMG_SIGNATURE}}代码先遍历所有段落包括表格里的段落找到包含这个标记的段落然后在它前面或后面插入一个带图片的新段落。好处是模板长什么样不影响定位编辑过也最多是标记文字被改视觉上占位符本身对排版影响也小。占位符设计有两个小经验。第一标记尽量加双花括号比如{{IMG}}这和渲染模板的语法一致不容易和正文文字冲突第二每个插入位置用不同的标记名称而不是复用同一个{{IMG}}这样批量插入时不会出现“每次找到的都是第一个标记”的问题。选定文本锚点方案之后剩下的核心就是游标操作了。这也是POI插入图片最绕、最容易出问题的地方。3. 游标定位法完整实现从依赖到代码一步步来先说环境。我用的是Maven工程最常用的POI版本是5.2.3用4.x也差不多但5.x的API更干净推荐以5.x为准。dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.3/version /dependencypoi-ooxml这个包会把poi、xmlbeans、poi-ooxml-lite等依赖一并带进来做Word段落、Run、图片操作已经足够不需要额外引入poi-scratchpad。3.1 先在模板里埋好占位符打开Word模板在需要插入图片的位置输入{{IMG_LOGO}}比如公司技术认证报告 {{IMG_LOGO}} 申请人信息如下……这里的{{IMG_LOGO}}会在运行时被图片替换掉。模板里这一行可以单独占一个段落也可以和其他文字混在一起。为了排版省心我建议单独占一行。3.2 查找锚点段落的核心代码查找锚点有两个层面要处理文档正文段落和表格内段落。很多人只写了doc.getParagraphs()结果表格里的占位符永远定位不到这是最常见的坑之一。import org.apache.poi.xwpf.usermodel.*; public class AnchorFinder { /** * 在文档所有段落含表格单元格中的段落中查找包含指定占位符的段落。 */ public static XWPFParagraph findAnchor(XWPFDocument doc, String placeholder) { // 1. 正文区段落 for (XWPFParagraph p : doc.getParagraphs()) { if (p.getText() ! null p.getText().contains(placeholder)) { return p; } } // 2. 表格内单元格的段落 for (XWPFTable table : doc.getTables()) { for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { for (XWPFParagraph p : cell.getParagraphs()) { if (p.getText() ! null p.getText().contains(placeholder)) { return p; } } } } } return null; } }这里注意cell.getParagraphs()在POI 5.x返回的是ListXWPFParagraph和正文段落一样操作没区别。3.3 在锚点段落之前插入带图片的新段落定位到锚点段落之后最常用的需求是把图片插到占位符所在位置。以“图片插在锚点段落之前”为例完整代码如下import org.apache.poi.util.Units; import org.apache.poi.xwpf.usermodel.*; import org.apache.xmlbeans.XmlCursor; import java.io.FileInputStream; import java.io.InputStream; public class WordImageInserter { /** * 在锚点段落之前插入一个包含图片的新段落。 */ public static void insertImageBefore(XWPFParagraph anchor, String imagePath, int widthPx, int heightPx) throws Exception { // 关键拿到锚点段落的底层XML游标 XmlCursor cursor anchor.getCTP().newCursor(); // 在游标当前位置插入新段落。游标正好指向锚点段落的开始 // 所以新段落会落在锚点段落之前。 XWPFParagraph imgParagraph anchor.getDocument().insertNewParagraph(cursor); // 让图片段落居中视觉效果最稳 imgParagraph.setAlignment(ParagraphAlignment.CENTER); // 新建Run图片挂在Run上 XWPFRun run imgParagraph.createRun(); // 根据文件扩展名判断图片类型 int picType getPictureType(imagePath); // addPicture的宽高单位是EMU不是像素这里用Units转换 try (InputStream is new FileInputStream(imagePath)) { run.addPicture(is, picType, imagePath, Units.toEMU(widthPx), Units.toEMU(heightPx)); } // 插入完成之后把占位符从锚点段落里清掉 clearPlaceholder(anchor, {{IMG_LOGO}}); } private static int getPictureType(String imagePath) { String lower imagePath.toLowerCase(); if (lower.endsWith(.png)) return XWPFDocument.PICTURE_TYPE_PNG; if (lower.endsWith(.jpg) || lower.endsWith(.jpeg)) return XWPFDocument.PICTURE_TYPE_JPEG; if (lower.endsWith(.emf)) return XWPFDocument.PICTURE_TYPE_EMF; if (lower.endsWith(.wmf)) return XWPFDocument.PICTURE_TYPE_WMF; if (lower.endsWith(.dib)) return XWPFDocument.PICTURE_TYPE_DIB; throw new IllegalArgumentException(不支持的图片格式: imagePath); } private static void clearPlaceholder(XWPFParagraph paragraph, String placeholder) { StringBuilder sb new StringBuilder(); for (XWPFRun run : paragraph.getRuns()) { sb.append(run.getText(0) null ? : run.getText(0)); } if (sb.indexOf(placeholder) 0) { String newText sb.toString().replace(placeholder, ); ListXWPFRun runs paragraph.getRuns(); if (!runs.isEmpty()) { // 把清理后的文本放到第一个Run其他Run清空 runs.get(0).setText(newText, 0); for (int i 1; i runs.size(); i) { runs.get(i).setText(, 0); } } } } }这段代码看起来不长但几个关键点不解释清楚换一个场景就抓瞎。XmlCursor是Apache XMLBeans提供的游标它可以直接在底层XML节点上做前后移动和插入操作。anchor.getCTP().newCursor()返回的游标位置我实测下来是在锚点段落w:p的开始标签处。doc.insertNewParagraph(cursor)这个方法是XWPFDocument提供的专门用来在指定XML位置创建段落它和普通的createParagraph()不同后者只会追加到Body尾部前者才是真正的“指哪打哪”。宽高参数是另一个容易翻车的地方。addPicture方法签名里的最后两个参数是EMUEnglish Metric Unit不是像素。Word内部绘图单位是EMU1英寸等于914400 EMU1像素大概是9525 EMU。如果直接拿像素数字传进去图片会小得几乎看不见或者大得离谱。Units.toEMU()就是干这个换算的没这个工具类只能自己乘9525。clearPlaceholder做的事是把占位符文本从锚点段落里抹掉。为什么要单独做这一步因为占位符留在模板里第一次运行时被图片替换了但如果不清掉第二次生成时同一个模板还会再匹配到它就会出现重复插入。3.4 想插到锚点段落之后怎么办很多需求是“在某某段落后边加一张图”比如“以上为申请信息下方为签字照片”。这种场景下图片要插在锚点段落后面做法是先把游标往后移动到锚点段落的结束标签位置XmlCursor cursor anchor.getCTP().newCursor(); cursor.toEndToken(); XWPFParagraph imgParagraph anchor.getDocument().insertNewParagraph(cursor); // 后续逻辑同上创建Run、addPicture、清占位符toEndToken()把游标移动到当前元素结束标签的位置此时调用insertNewParagraph新段落会落在锚点段落之后。这个和插入到前面刚好对称。不过要提醒一句不同版本XMLBeans对游标位置“在结束标签上”和“在结束标签后”的语义行为略有差异万一插出来位置不对在toEndToken()之后补一行cursor.toNextToken()再插入通常就能纠正。如果你的场景比较复杂图既要插在锚点前又要插在锚点后或者一时拿不准方向最稳妥的做法是模板里放一对占位符比如{{IMG_START}}和{{IMG_END}}图片先插到{{IMG_END}}之前再把两个占位符都清掉。这样无论版本怎么变位置始终可控。4. 图片大小、对齐和样式继承插进去不难插得好看才难图片能插进去了不代表完事了。我见过很多初学者把图插进去之后一打开Word图片要么大得超出页面要么歪在页面边上要么和周围文字挤在一起版式完全没法看。这一节把排版相关的细节一次说透。4.1 按比例缩放图片而不是写死宽高最朴素的写法是直接传固定像素值比如Units.toEMU(300)、Units.toEMU(200)。问题在于原图可能是4000x3000的大图传300x200会变形原图是800x600传300x200又会模糊。正确做法是先读图片原始尺寸按目标宽度等比计算高度。import javax.imageio.ImageIO; import java.awt.image.BufferedImage; import java.io.File; public static int[] calcScaledSize(String imagePath, int maxWidthPx, int maxHeightPx) throws Exception { BufferedImage img ImageIO.read(new File(imagePath)); int width img.getWidth(); int height img.getHeight(); double scale Math.min( (double) maxWidthPx / width, (double) maxHeightPx / height ); if (scale 1) { return new int[]{width, height}; } return new int[]{(int)(width * scale), (int)(height * scale)}; }至于最大宽高设多少要结合页面实际可用宽度来算。A4纸宽度是21厘米默认页边距左右各3.17厘米也就是说文字区的可用宽度大概是14.65厘米。如果你希望图片铺满整个可用宽度14.65厘米换算成像素大概是14.65 / 2.54 * 96 ≈ 553像素。我一般取550作为最大宽度高度限制在350-400左右基本不会超出页面。4.2 对齐方式单独设置图片段落既然是独立的段落它的对齐方式就由段落属性控制。居中是最常见的需求imgParagraph.setAlignment(ParagraphAlignment.CENTER);左右对齐也是同理。要注意的是如果锚点段落原来的对齐方式是左对齐而你新插入的图片段落没有显式设置那么图片会沿用段落默认样式可能是左对齐也可能是两端对齐整体看起来就很随机。所以每次插入都显式setAlignment不要依赖默认值。4.3 图片段落继承锚点段落的样式模板里不同段落的字体、行距、缩进可能不同。如果图片段落是全新建的“裸段落”它的样式可能和其他段落格格不入。最简单的解法是把锚点段落的段落属性拷贝过来import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTP; import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTPPr; CTP anchorCtp anchor.getCTP(); CTP imgCtp imgParagraph.getCTP(); if (anchorCtp.isSetPPr()) { imgCtp.setPPr((CTPPr) anchorCtp.getPPr().copy()); }这样做的好处是行距、缩进、段前段后间距全都和锚点段落保持一致。如果你连字体格式都希望图片Run继承可以再拷贝Run的RPr不过图片本身没有字体影响不大。4.4 图片和周围文字之间的间距图片段落默认的行距可能会让图片和上下文字贴得很近读起来很挤。可以在图片段落的setSpacingBefore和setSpacingAfter上稍微加点:imgParagraph.setSpacingBefore(200); imgParagraph.setSpacingAfter(200);这里的单位是缇twips1磅等于20缇200缇就是10磅视觉上比较舒服。具体大小看实际效果微调。5. 实测踩坑记录这份避坑清单能省你大半天时间这部分整理了我在实际项目中遇到过的坑有些坑可能浪费了你几个小时也不一定想到。每一条都是从报错到排错到解决完整走过来的不是从官方文档摘抄的。5.1 占位符被Word拆到多个Run里replace不掉这是第一个真正恶心到我的坑。模板里手写的{{IMG_LOGO}}存盘之后Word不一定把整串文字放在同一个Run里可能{{在一个RunIMG_LOGO在另一个Run}}又在第三个Run。你用paragraph.getText()能拿到完整文本一replace却发现段落里根本没变化因为你要替换的内容跨越了Run边界。clearPlaceholder里我用了“拼完整文本、改第一个Run、清空其余Run”的策略就是为了应对这种情况。如果替换完发现锚点段落里还残留半个大括号的文本多半是遍历时遗漏了哪个Run的getText(0)返回null处理时判空就行。5.2 只查正文段落表格里的占位符永远找不到上文代码里已经处理了这个问题但我在实际开发中见到不少同事只写了doc.getParagraphs()。文档一旦涉及表格比如申请表、报价单占位符放在表格单元格里查正文段落就找不到程序直接往下走图片就全堆到了文档末尾。表面看是“插入位置不对”本质是定位逻辑根本没覆盖到表格。排查这类问题先确认锚点是不是在表格里再决定遍历方式。5.3 重复插入同一个占位符被命中多次这不是死循环但效果类似。假设模板里有好几处{{IMG}}你调用findAnchor每次都从头遍历那么返回的永远是第一个{{IMG}}段落。第一张图插入后会清理占位符但第二次查找时第一个段落已经没有标记了可代码是从头再查的结果还是会找到第二个位置之前的第一个{{IMG}}——如果只插入一次还好循环插入就会错乱。我的解法是模板里的占位符一律带编号{{IMG_1}}、{{IMG_2}}、{{IMG_3}}。这样每个位置有唯一标识查找时按编号精确匹配。如果要插入同一张图到多个位置就显式多次调用每次传不同的占位符逻辑清晰也不容易错。5.4 图片类型判断错误生成的docx打不开addPicture里的第二个参数必须和实际图片字节格式匹配。之前出现过一次文件扩展名是.png但实际内容被改成了JPEG编码getPictureType判断成了PNG结果打开生成的Word时报“无法读取图片文件已损坏”。严格来说这不是判断逻辑的问题而是图片文件的真实格式问题。稳妥做法是用ImageIO.read()解析图片通过ImageIO.getImageReaders()获取真实格式再映射到POI的图片类型常量。如果项目里图片来源可控都是程序生成的PNG用扩展名判断就够了如果图片是外部上传的建议按真实格式判断。5.5 生成的文件提示“要修复”的问题排查思路如果你插入后生成的docx在Word里提示“发现无法读取的内容是否尝试修复”别慌九成是XML结构出了问题。我的排查顺序是先把生成的文件用解压工具解压打开word/document.xml直接看新插入段落前后的XML标签是否闭合正常。段落嵌套层级不正确是最常见原因。检查是不是游标位置操作出了问题比如在Body层级的段落外又插入了孤立节点或者插入到了一个表格单元格的非法位置。单独跑一个最小复现用例只插入一张图片、只操作一个占位符看能不能复现。能复现问题就在插入逻辑不能复现说明是模板本身有问题。另外所有插入操作完成后记得调用一次doc.write()刷新内部结构再关闭输出流。不要用doc.getDocument().toString()直接拼字符串查问题那个是底层XML的toString和实际写入文件的内容不完全一样。5.6 图片流资源泄漏addPicture需要传入InputStream如果你用裸写new FileInputStream()不关流批量生成文档时容易出现文件句柄耗尽或文件被占用删除不掉。上面代码全用了try-with-resources这个习惯一定要带上。尤其是在循环内插入几十张图片的场景不关流的后果会非常明显。6. 批量插入场景的性能优化与模板复用最后一个常见场景一份文档里要插入几十张图比如产品目录、员工证件照集合、订单截图列表。按前面的单张插入方法每张图都从头遍历整篇文档找锚点复杂度是O(n*m)文档段落很多时会明显变慢。这个环节给几个优化思路。6.1 一次性收集锚点避免反复全表扫描不管插入多少张图先做一次遍历把占位符和对应的图片路径配对收集起来然后再统一处理。可以用一个小结构class ImageAnchor { String placeholder; String imagePath; XWPFParagraph anchor; }遍历时只扫一遍所有段落含表格把每个占位符对应的段落引用存下来。这样后续插入直接拿对象操作不需要反复从头找。插入新段落时注意底层XML是动态变化的但你已经拿到的XWPFParagraph对象引用依然有效因为它是基于CTP包装的不会因为插入新段落而失效。6.2 “可反复运行”的幂等处理真实业务里往往要求同一个模板重复生成多份文档比如批量套打证书。如果模板里的占位符被第一次运行改掉第二次想再复用同一份模板文档就会发现占位符没了。我的做法是每次生成前都从原始模板重新加载一份副本占位符永远以原始模板为准。生成流程变成三条固定步骤new XWPFDocument(templateInputStream)加载原始模板查占位符、插入图片、清理占位符输出写入新的docx文件模板文件只读绝不写入。这样无论跑多少次模板永远是干净的。6.3 线程安全的取舍XWPFDocument不是线程安全的同一个模板对象多线程操作会互相干扰。如果并发量高要么每个线程各自加载一份模板副本要么用线程池串行化处理同一模板的生成任务。最省事的做法是把模板内容readAllBytes()读进字节数组每次new XWPFDocument(new ByteArrayInputStream(bytes))生成新实例。模板不大时开销可以忽略换来的是完全隔离不用加锁。6.4 不要边遍历边改结构的深层原因有些操作在循环内直接用doc.getParagraphs()并同时调用insertNewParagraph这背后的隐患不只是索引偏移XMLBeans的游标遍历逻辑在节点增删过程中有时会抛出ConcurrentModificationException有时会静默跳过新插入节点导致插入顺序错乱。把“收集”和“操作”分成两阶段不仅是性能考虑更是规避这类诡异问题的根本手段。我在批量插入场景里统一遵守一个规则收集阶段只return段落引用操作阶段只使用已收集到的引用做插入绝不在遍历的同时修改文档结构。这套思路跑下来上百张图片的文档生成也稳定。如果你也要做类似功能建议先把这个原则定下来再写业务代码。 
长河君 · 2026/10/23 23:08:08 · 阅读 1.2k POI操作Word指定位置插入图片：占位符与游标定位实战
做过Word模板导出功能开发的人多半都被“插入图片”这件事卡过。客户的描述永远很具体报告生成到第三页这一段下面必须放质检照片或者一个大表格里某些单元格要贴图。你翻遍POI的文档找到addPicture这个方法调完之后图片确实进来了位置却是文档末尾。今天这篇就专门聊聊“用POI操作Word在指定位置插入图片”的完整思路、代码实现和踩坑记录适合正在做报表导出、合同生成、批量证书打印或者任何用POI碰过Word模板填充的开发者。1. 别上来就写代码先搞清楚图片在docx里到底存在哪第一次用POI往Word里插图片的人基本都会走这么一条弯路先new XWPFDocument()然后doc.addPicture(...)图片确实进去了但永远在文档末尾。这不是bug也不是POI故意坑你而是因为docx的物理结构和我们日常写Word时的直觉完全不一样。一个.docx文件本质上是一堆XML打包在一起。正文内容放在word/document.xml里结构大致是文档Document下面是一个BodyBody下面是一排块级元素最主要的两种块是段落w:p和表格w:tbl。每个段落内部又有若干Runw:rRun才是真正承载文本的最小单位。一张图片在XML里不是一个独立的块它是挂在某个Run下面的一串Drawing元素。这就是关键点POI里段落XWPFParagraph没有addPicture方法能插图片的只有XWPFRun也就是段落里某个Run。所以“指定位置插入图片”这句话拆开看其实是两步定位到目标位置对应的段落或Run再调用那个Run上的addPicture。理解了这一层再看XWPFDocument.addPicture为什么没用就清楚了——它确实也能把图片加进文档但它只能新建一个段落并把图片放进去这个段落被追加在Body最后面。它不是“文档级”该有的操作更像是一个方便追加的快捷方法。想要往文档中间、模板某个位置插图必须自己控制游标和段落。还有一个容易忽略的细节Word中的Run是一段格式相同的文本。比如你写“第一段加粗第二段普通”这两段里就有不同的标签。图片挂在某个Run下意味着图片会和这个Run拥有相同的段落格式、字体设置。这也是为什么插入图片后它的缩进、行距、对齐方式经常要额外单独设置——因为图片事实上继承或者部分继承了Run所在的段落样式。搞清楚对象模型之后下一个问题自然就来了怎么定位标题里的“指定位置”到底怎么表达给POI2. 定位方案对比索引、文本锚点、书签到底选哪个“指定位置”说起来简单但实现时定位方式有几种选错后面全是坑。我把常见方案整理了一下按实际体验排序。定位方式实现难度抗模板改动能力模板可读性实测推荐度段落索引定位低差模板多一个段落就全错位差靠猜不推荐文本锚点定位中好只要锚点文字不被删就行好模板里一眼能看出标记强推书签定位中高好但POI对书签的封装比较绕一般Word里才看得见可以用但不优先表格行/单元格定位中取决于具体场景一般特定场景用索引定位是我最早试的方法。写起来最省事doc.getParagraphs().get(index)拿到段落就往前面插。但坏处非常致命模板只要被编辑过一次哪怕是多空了一行索引全部位移。而且批量插入时前一次插入会改变后续段落的索引位置得从后往前倒着插调试起来非常消耗耐心。这个方法只适合那种完全用代码动态生成的、结构永远不变化的文档不适合模板填充。书签定位理论上很优雅。Word里CtrlShiftF2加个书签POI里也有XWPFBookmark、getBookmarks()之类的东西。实际试下来书签要绑定到段落或者Run的XML节点上定位之后进行操作还得自己转游标代码绕模板使用者还未必会加书签。不是不行是性价比低。我最后稳定使用的是文本锚点定位。做法很简单在Word模板里写一行占位符比如{{IMG}}或者更具体的{{IMG_QUALITY}}、{{IMG_SIGNATURE}}代码先遍历所有段落包括表格里的段落找到包含这个标记的段落然后在它前面或后面插入一个带图片的新段落。好处是模板长什么样不影响定位编辑过也最多是标记文字被改视觉上占位符本身对排版影响也小。占位符设计有两个小经验。第一标记尽量加双花括号比如{{IMG}}这和渲染模板的语法一致不容易和正文文字冲突第二每个插入位置用不同的标记名称而不是复用同一个{{IMG}}这样批量插入时不会出现“每次找到的都是第一个标记”的问题。选定文本锚点方案之后剩下的核心就是游标操作了。这也是POI插入图片最绕、最容易出问题的地方。3. 游标定位法完整实现从依赖到代码一步步来先说环境。我用的是Maven工程最常用的POI版本是5.2.3用4.x也差不多但5.x的API更干净推荐以5.x为准。dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.3/version /dependencypoi-ooxml这个包会把poi、xmlbeans、poi-ooxml-lite等依赖一并带进来做Word段落、Run、图片操作已经足够不需要额外引入poi-scratchpad。3.1 先在模板里埋好占位符打开Word模板在需要插入图片的位置输入{{IMG_LOGO}}比如公司技术认证报告 {{IMG_LOGO}} 申请人信息如下……这里的{{IMG_LOGO}}会在运行时被图片替换掉。模板里这一行可以单独占一个段落也可以和其他文字混在一起。为了排版省心我建议单独占一行。3.2 查找锚点段落的核心代码查找锚点有两个层面要处理文档正文段落和表格内段落。很多人只写了doc.getParagraphs()结果表格里的占位符永远定位不到这是最常见的坑之一。import org.apache.poi.xwpf.usermodel.*; public class AnchorFinder { /** * 在文档所有段落含表格单元格中的段落中查找包含指定占位符的段落。 */ public static XWPFParagraph findAnchor(XWPFDocument doc, String placeholder) { // 1. 正文区段落 for (XWPFParagraph p : doc.getParagraphs()) { if (p.getText() ! null p.getText().contains(placeholder)) { return p; } } // 2. 表格内单元格的段落 for (XWPFTable table : doc.getTables()) { for (XWPFTableRow row : table.getRows()) { for (XWPFTableCell cell : row.getTableCells()) { for (XWPFParagraph p : cell.getParagraphs()) { if (p.getText() ! null p.getText().contains(placeholder)) { return p; } } } } } return null; } }这里注意cell.getParagraphs()在POI 5.x返回的是ListXWPFParagraph和正文段落一样操作没区别。3.3 在锚点段落之前插入带图片的新段落定位到锚点段落之后最常用的需求是把图片插到占位符所在位置。以“图片插在锚点段落之前”为例完整代码如下import org.apache.poi.util.Units; import org.apache.poi.xwpf.usermodel.*; import org.apache.xmlbeans.XmlCursor; import java.io.FileInputStream; import java.io.InputStream; public class WordImageInserter { /** * 在锚点段落之前插入一个包含图片的新段落。 */ public static void insertImageBefore(XWPFParagraph anchor, String imagePath, int widthPx, int heightPx) throws Exception { // 关键拿到锚点段落的底层XML游标 XmlCursor cursor anchor.getCTP().newCursor(); // 在游标当前位置插入新段落。游标正好指向锚点段落的开始 // 所以新段落会落在锚点段落之前。 XWPFParagraph imgParagraph anchor.getDocument().insertNewParagraph(cursor); // 让图片段落居中视觉效果最稳 imgParagraph.setAlignment(ParagraphAlignment.CENTER); // 新建Run图片挂在Run上 XWPFRun run imgParagraph.createRun(); // 根据文件扩展名判断图片类型 int picType getPictureType(imagePath); // addPicture的宽高单位是EMU不是像素这里用Units转换 try (InputStream is new FileInputStream(imagePath)) { run.addPicture(is, picType, imagePath, Units.toEMU(widthPx), Units.toEMU(heightPx)); } // 插入完成之后把占位符从锚点段落里清掉 clearPlaceholder(anchor, {{IMG_LOGO}}); } private static int getPictureType(String imagePath) { String lower imagePath.toLowerCase(); if (lower.endsWith(.png)) return XWPFDocument.PICTURE_TYPE_PNG; if (lower.endsWith(.jpg) || lower.endsWith(.jpeg)) return XWPFDocument.PICTURE_TYPE_JPEG; if (lower.endsWith(.emf)) return XWPFDocument.PICTURE_TYPE_EMF; if (lower.endsWith(.wmf)) return XWPFDocument.PICTURE_TYPE_WMF; if (lower.endsWith(.dib)) return XWPFDocument.PICTURE_TYPE_DIB; throw new IllegalArgumentException(不支持的图片格式: imagePath); } private static void clearPlaceholder(XWPFParagraph paragraph, String placeholder) { StringBuilder sb new StringBuilder(); for (XWPFRun run : paragraph.getRuns()) { sb.append(run.getText(0) null ? : run.getText(0)); } if (sb.indexOf(placeholder) 0) { String newText sb.toString().replace(placeholder, ); ListXWPFRun runs paragraph.getRuns(); if (!runs.isEmpty()) { // 把清理后的文本放到第一个Run其他Run清空 runs.get(0).setText(newText, 0); for (int i 1; i runs.size(); i) { runs.get(i).setText(, 0); } } } } }这段代码看起来不长但几个关键点不解释清楚换一个场景就抓瞎。XmlCursor是Apache XMLBeans提供的游标它可以直接在底层XML节点上做前后移动和插入操作。anchor.getCTP().newCursor()返回的游标位置我实测下来是在锚点段落w:p的开始标签处。doc.insertNewParagraph(cursor)这个方法是XWPFDocument提供的专门用来在指定XML位置创建段落它和普通的createParagraph()不同后者只会追加到Body尾部前者才是真正的“指哪打哪”。宽高参数是另一个容易翻车的地方。addPicture方法签名里的最后两个参数是EMUEnglish Metric Unit不是像素。Word内部绘图单位是EMU1英寸等于914400 EMU1像素大概是9525 EMU。如果直接拿像素数字传进去图片会小得几乎看不见或者大得离谱。Units.toEMU()就是干这个换算的没这个工具类只能自己乘9525。clearPlaceholder做的事是把占位符文本从锚点段落里抹掉。为什么要单独做这一步因为占位符留在模板里第一次运行时被图片替换了但如果不清掉第二次生成时同一个模板还会再匹配到它就会出现重复插入。3.4 想插到锚点段落之后怎么办很多需求是“在某某段落后边加一张图”比如“以上为申请信息下方为签字照片”。这种场景下图片要插在锚点段落后面做法是先把游标往后移动到锚点段落的结束标签位置XmlCursor cursor anchor.getCTP().newCursor(); cursor.toEndToken(); XWPFParagraph imgParagraph anchor.getDocument().insertNewParagraph(cursor); // 后续逻辑同上创建Run、addPicture、清占位符toEndToken()把游标移动到当前元素结束标签的位置此时调用insertNewParagraph新段落会落在锚点段落之后。这个和插入到前面刚好对称。不过要提醒一句不同版本XMLBeans对游标位置“在结束标签上”和“在结束标签后”的语义行为略有差异万一插出来位置不对在toEndToken()之后补一行cursor.toNextToken()再插入通常就能纠正。如果你的场景比较复杂图既要插在锚点前又要插在锚点后或者一时拿不准方向最稳妥的做法是模板里放一对占位符比如{{IMG_START}}和{{IMG_END}}图片先插到{{IMG_END}}之前再把两个占位符都清掉。这样无论版本怎么变位置始终可控。4. 图片大小、对齐和样式继承插进去不难插得好看才难图片能插进去了不代表完事了。我见过很多初学者把图插进去之后一打开Word图片要么大得超出页面要么歪在页面边上要么和周围文字挤在一起版式完全没法看。这一节把排版相关的细节一次说透。4.1 按比例缩放图片而不是写死宽高最朴素的写法是直接传固定像素值比如Units.toEMU(300)、Units.toEMU(200)。问题在于原图可能是4000x3000的大图传300x200会变形原图是800x600传300x200又会模糊。正确做法是先读图片原始尺寸按目标宽度等比计算高度。import javax.imageio.ImageIO; import java.awt.image.BufferedImage; import java.io.File; public static int[] calcScaledSize(String imagePath, int maxWidthPx, int maxHeightPx) throws Exception { BufferedImage img ImageIO.read(new File(imagePath)); int width img.getWidth(); int height img.getHeight(); double scale Math.min( (double) maxWidthPx / width, (double) maxHeightPx / height ); if (scale 1) { return new int[]{width, height}; } return new int[]{(int)(width * scale), (int)(height * scale)}; }至于最大宽高设多少要结合页面实际可用宽度来算。A4纸宽度是21厘米默认页边距左右各3.17厘米也就是说文字区的可用宽度大概是14.65厘米。如果你希望图片铺满整个可用宽度14.65厘米换算成像素大概是14.65 / 2.54 * 96 ≈ 553像素。我一般取550作为最大宽度高度限制在350-400左右基本不会超出页面。4.2 对齐方式单独设置图片段落既然是独立的段落它的对齐方式就由段落属性控制。居中是最常见的需求imgParagraph.setAlignment(ParagraphAlignment.CENTER);左右对齐也是同理。要注意的是如果锚点段落原来的对齐方式是左对齐而你新插入的图片段落没有显式设置那么图片会沿用段落默认样式可能是左对齐也可能是两端对齐整体看起来就很随机。所以每次插入都显式setAlignment不要依赖默认值。4.3 图片段落继承锚点段落的样式模板里不同段落的字体、行距、缩进可能不同。如果图片段落是全新建的“裸段落”它的样式可能和其他段落格格不入。最简单的解法是把锚点段落的段落属性拷贝过来import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTP; import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTPPr; CTP anchorCtp anchor.getCTP(); CTP imgCtp imgParagraph.getCTP(); if (anchorCtp.isSetPPr()) { imgCtp.setPPr((CTPPr) anchorCtp.getPPr().copy()); }这样做的好处是行距、缩进、段前段后间距全都和锚点段落保持一致。如果你连字体格式都希望图片Run继承可以再拷贝Run的RPr不过图片本身没有字体影响不大。4.4 图片和周围文字之间的间距图片段落默认的行距可能会让图片和上下文字贴得很近读起来很挤。可以在图片段落的setSpacingBefore和setSpacingAfter上稍微加点:imgParagraph.setSpacingBefore(200); imgParagraph.setSpacingAfter(200);这里的单位是缇twips1磅等于20缇200缇就是10磅视觉上比较舒服。具体大小看实际效果微调。5. 实测踩坑记录这份避坑清单能省你大半天时间这部分整理了我在实际项目中遇到过的坑有些坑可能浪费了你几个小时也不一定想到。每一条都是从报错到排错到解决完整走过来的不是从官方文档摘抄的。5.1 占位符被Word拆到多个Run里replace不掉这是第一个真正恶心到我的坑。模板里手写的{{IMG_LOGO}}存盘之后Word不一定把整串文字放在同一个Run里可能{{在一个RunIMG_LOGO在另一个Run}}又在第三个Run。你用paragraph.getText()能拿到完整文本一replace却发现段落里根本没变化因为你要替换的内容跨越了Run边界。clearPlaceholder里我用了“拼完整文本、改第一个Run、清空其余Run”的策略就是为了应对这种情况。如果替换完发现锚点段落里还残留半个大括号的文本多半是遍历时遗漏了哪个Run的getText(0)返回null处理时判空就行。5.2 只查正文段落表格里的占位符永远找不到上文代码里已经处理了这个问题但我在实际开发中见到不少同事只写了doc.getParagraphs()。文档一旦涉及表格比如申请表、报价单占位符放在表格单元格里查正文段落就找不到程序直接往下走图片就全堆到了文档末尾。表面看是“插入位置不对”本质是定位逻辑根本没覆盖到表格。排查这类问题先确认锚点是不是在表格里再决定遍历方式。5.3 重复插入同一个占位符被命中多次这不是死循环但效果类似。假设模板里有好几处{{IMG}}你调用findAnchor每次都从头遍历那么返回的永远是第一个{{IMG}}段落。第一张图插入后会清理占位符但第二次查找时第一个段落已经没有标记了可代码是从头再查的结果还是会找到第二个位置之前的第一个{{IMG}}——如果只插入一次还好循环插入就会错乱。我的解法是模板里的占位符一律带编号{{IMG_1}}、{{IMG_2}}、{{IMG_3}}。这样每个位置有唯一标识查找时按编号精确匹配。如果要插入同一张图到多个位置就显式多次调用每次传不同的占位符逻辑清晰也不容易错。5.4 图片类型判断错误生成的docx打不开addPicture里的第二个参数必须和实际图片字节格式匹配。之前出现过一次文件扩展名是.png但实际内容被改成了JPEG编码getPictureType判断成了PNG结果打开生成的Word时报“无法读取图片文件已损坏”。严格来说这不是判断逻辑的问题而是图片文件的真实格式问题。稳妥做法是用ImageIO.read()解析图片通过ImageIO.getImageReaders()获取真实格式再映射到POI的图片类型常量。如果项目里图片来源可控都是程序生成的PNG用扩展名判断就够了如果图片是外部上传的建议按真实格式判断。5.5 生成的文件提示“要修复”的问题排查思路如果你插入后生成的docx在Word里提示“发现无法读取的内容是否尝试修复”别慌九成是XML结构出了问题。我的排查顺序是先把生成的文件用解压工具解压打开word/document.xml直接看新插入段落前后的XML标签是否闭合正常。段落嵌套层级不正确是最常见原因。检查是不是游标位置操作出了问题比如在Body层级的段落外又插入了孤立节点或者插入到了一个表格单元格的非法位置。单独跑一个最小复现用例只插入一张图片、只操作一个占位符看能不能复现。能复现问题就在插入逻辑不能复现说明是模板本身有问题。另外所有插入操作完成后记得调用一次doc.write()刷新内部结构再关闭输出流。不要用doc.getDocument().toString()直接拼字符串查问题那个是底层XML的toString和实际写入文件的内容不完全一样。5.6 图片流资源泄漏addPicture需要传入InputStream如果你用裸写new FileInputStream()不关流批量生成文档时容易出现文件句柄耗尽或文件被占用删除不掉。上面代码全用了try-with-resources这个习惯一定要带上。尤其是在循环内插入几十张图片的场景不关流的后果会非常明显。6. 批量插入场景的性能优化与模板复用最后一个常见场景一份文档里要插入几十张图比如产品目录、员工证件照集合、订单截图列表。按前面的单张插入方法每张图都从头遍历整篇文档找锚点复杂度是O(n*m)文档段落很多时会明显变慢。这个环节给几个优化思路。6.1 一次性收集锚点避免反复全表扫描不管插入多少张图先做一次遍历把占位符和对应的图片路径配对收集起来然后再统一处理。可以用一个小结构class ImageAnchor { String placeholder; String imagePath; XWPFParagraph anchor; }遍历时只扫一遍所有段落含表格把每个占位符对应的段落引用存下来。这样后续插入直接拿对象操作不需要反复从头找。插入新段落时注意底层XML是动态变化的但你已经拿到的XWPFParagraph对象引用依然有效因为它是基于CTP包装的不会因为插入新段落而失效。6.2 “可反复运行”的幂等处理真实业务里往往要求同一个模板重复生成多份文档比如批量套打证书。如果模板里的占位符被第一次运行改掉第二次想再复用同一份模板文档就会发现占位符没了。我的做法是每次生成前都从原始模板重新加载一份副本占位符永远以原始模板为准。生成流程变成三条固定步骤new XWPFDocument(templateInputStream)加载原始模板查占位符、插入图片、清理占位符输出写入新的docx文件模板文件只读绝不写入。这样无论跑多少次模板永远是干净的。6.3 线程安全的取舍XWPFDocument不是线程安全的同一个模板对象多线程操作会互相干扰。如果并发量高要么每个线程各自加载一份模板副本要么用线程池串行化处理同一模板的生成任务。最省事的做法是把模板内容readAllBytes()读进字节数组每次new XWPFDocument(new ByteArrayInputStream(bytes))生成新实例。模板不大时开销可以忽略换来的是完全隔离不用加锁。6.4 不要边遍历边改结构的深层原因有些操作在循环内直接用doc.getParagraphs()并同时调用insertNewParagraph这背后的隐患不只是索引偏移XMLBeans的游标遍历逻辑在节点增删过程中有时会抛出ConcurrentModificationException有时会静默跳过新插入节点导致插入顺序错乱。把“收集”和“操作”分成两阶段不仅是性能考虑更是规避这类诡异问题的根本手段。我在批量插入场景里统一遵守一个规则收集阶段只return段落引用操作阶段只使用已收集到的引用做插入绝不在遍历的同时修改文档结构。这套思路跑下来上百张图片的文档生成也稳定。如果你也要做类似功能建议先把这个原则定下来再写业务代码。