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，下面是一个Body，Body下面是一排块级元素，最主要的两种块是段落（<w:p>）和表格（<w:tbl>）。每个段落内部又有若干Run（<w:r>），Run才是真正承载文本的最小单位。一张图片在XML里不是一个独立的块，它是挂在某个Run下面的一串Drawing元素。

这就是关键点：POI里段落XWPFParagraph没有addPicture方法，能插图片的只有XWPFRun，也就是段落里某个Run。所以“指定位置插入图片”这句话拆开看，其实是两步：定位到目标位置对应的段落或Run，再调用那个Run上的addPicture。

理解了这一层，再看XWPFDocument.addPicture为什么没用就清楚了——它确实也能把图片加进文档，但它只能新建一个段落并把图片放进去，这个段落被追加在Body最后面。它不是“文档级”该有的操作，更像是一个方便追加的快捷方法。想要往文档中间、模板某个位置插图，必须自己控制游标和段落。

还有一个容易忽略的细节：Word中的Run是一段格式相同的文本。比如你写“第一段加粗，第二段普通”，这两段里就有不同的标签。图片挂在某个Run下，意味着图片会和这个Run拥有相同的段落格式、字体设置。这也是为什么插入图片后，它的缩进、行距、对齐方式经常要额外单独设置——因为图片事实上继承或者部分继承了Run所在的段落样式。

搞清楚对象模型之后，下一个问题自然就来了：怎么定位？标题里的“指定位置”到底怎么表达给POI？

2. 定位方案对比：索引、文本锚点、书签到底选哪个

“指定位置”说起来简单，但实现时定位方式有几种，选错后面全是坑。我把常见方案整理了一下，按实际体验排序。

索引定位是我最早试的方法。写起来最省事：doc.getParagraphs().get(index)，拿到段落就往前面插。但坏处非常致命，模板只要被编辑过一次，哪怕是多空了一行，索引全部位移。而且批量插入时，前一次插入会改变后续段落的索引位置，得从后往前倒着插，调试起来非常消耗耐心。这个方法只适合那种完全用代码动态生成的、结构永远不变化的文档，不适合模板填充。

书签定位理论上很优雅。Word里Ctrl+Shift+F2加个书签，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> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.2.3</version> </dependency>

poi-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返回的是List<XWPFParagraph>，和正文段落一样操作，没区别。

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, ""); List<XWPFRun> 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方法签名里的最后两个参数是EMU（English Metric Unit），不是像素。Word内部绘图单位是EMU，1英寸等于914400 EMU，1像素大概是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);

这里的单位是缇（twips），1磅等于20缇，200缇就是10磅，视觉上比较舒服。具体大小看实际效果微调。

5. 实测踩坑记录：这份避坑清单能省你大半天时间

这部分整理了我在实际项目中遇到过的坑，有些坑可能浪费了你几个小时也不一定想到。每一条都是从报错到排错到解决完整走过来的，不是从官方文档摘抄的。

5.1 占位符被Word拆到多个Run里，replace不掉

这是第一个真正恶心到我的坑。模板里手写的{{IMG_LOGO}}，存盘之后Word不一定把整串文字放在同一个Run里，可能{{在一个Run，IMG_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结构出了问题。我的排查顺序是：

1. 先把生成的文件用解压工具解压，打开word/document.xml，直接看新插入段落前后的XML标签是否闭合正常。段落嵌套层级不正确是最常见原因。
2. 检查是不是游标位置操作出了问题，比如在Body层级的段落外又插入了孤立节点，或者插入到了一个表格单元格的非法位置。
3. 单独跑一个最小复现用例，只插入一张图片、只操作一个占位符，看能不能复现。能复现，问题就在插入逻辑；不能复现，说明是模板本身有问题。

另外，所有插入操作完成后记得调用一次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 “可反复运行”的幂等处理

真实业务里往往要求同一个模板重复生成多份文档，比如批量套打证书。如果模板里的占位符被第一次运行改掉，第二次想再复用同一份模板文档，就会发现占位符没了。

我的做法是：每次生成前都从原始模板重新加载一份副本，占位符永远以原始模板为准。生成流程变成三条固定步骤：

1. new XWPFDocument(templateInputStream)加载原始模板
2. 查占位符、插入图片、清理占位符
3. 输出写入新的docx文件

模板文件只读，绝不写入。这样无论跑多少次，模板永远是干净的。

6.3 线程安全的取舍

XWPFDocument不是线程安全的，同一个模板对象多线程操作会互相干扰。如果并发量高，要么每个线程各自加载一份模板副本，要么用线程池串行化处理同一模板的生成任务。最省事的做法是：把模板内容readAllBytes()读进字节数组，每次new XWPFDocument(new ByteArrayInputStream(bytes))生成新实例。模板不大时开销可以忽略，换来的是完全隔离，不用加锁。

6.4 不要边遍历边改结构的深层原因

有些操作在循环内直接用doc.getParagraphs()并同时调用insertNewParagraph，这背后的隐患不只是索引偏移：XMLBeans的游标遍历逻辑在节点增删过程中，有时会抛出ConcurrentModificationException，有时会静默跳过新插入节点，导致插入顺序错乱。把“收集”和“操作”分成两阶段，不仅是性能考虑，更是规避这类诡异问题的根本手段。

我在批量插入场景里统一遵守一个规则：收集阶段只return段落引用，操作阶段只使用已收集到的引用做插入，绝不在遍历的同时修改文档结构。这套思路跑下来，上百张图片的文档生成也稳定。如果你也要做类似功能，建议先把这个原则定下来再写业务代码。