做過Word模板導(dǎo)出功能開發(fā)的人多半都被“插入圖片”這件事卡過。客戶的描述永遠(yuǎn)很具體報(bào)告生成到第三頁這一段下面必須放質(zhì)檢照片或者一個(gè)大表格里某些單元格要貼圖。你翻遍POI的文檔找到addPicture這個(gè)方法調(diào)完之后圖片確實(shí)進(jìn)來了位置卻是文檔末尾。今天這篇就專門聊聊“用POI操作Word在指定位置插入圖片”的完整思路、代碼實(shí)現(xiàn)和踩坑記錄適合正在做報(bào)表導(dǎo)出、合同生成、批量證書打印或者任何用POI碰過Word模板填充的開發(fā)者。1. 別上來就寫代碼先搞清楚圖片在docx里到底存在哪第一次用POI往Word里插圖片的人基本都會(huì)走這么一條彎路先new XWPFDocument()然后doc.addPicture(...)圖片確實(shí)進(jìn)去了但永遠(yuǎn)在文檔末尾。這不是bug也不是POI故意坑你而是因?yàn)閐ocx的物理結(jié)構(gòu)和我們?nèi)粘慦ord時(shí)的直覺完全不一樣。一個(gè).docx文件本質(zhì)上是一堆XML打包在一起。正文內(nèi)容放在word/document.xml里結(jié)構(gòu)大致是文檔Document下面是一個(gè)BodyBody下面是一排塊級(jí)元素最主要的兩種塊是段落w:p和表格w:tbl。每個(gè)段落內(nèi)部又有若干Runw:rRun才是真正承載文本的最小單位。一張圖片在XML里不是一個(gè)獨(dú)立的塊它是掛在某個(gè)Run下面的一串Drawing元素。這就是關(guān)鍵點(diǎn)POI里段落XWPFParagraph沒有addPicture方法能插圖片的只有XWPFRun也就是段落里某個(gè)Run。所以“指定位置插入圖片”這句話拆開看其實(shí)是兩步定位到目標(biāo)位置對(duì)應(yīng)的段落或Run再調(diào)用那個(gè)Run上的addPicture。理解了這一層再看XWPFDocument.addPicture為什么沒用就清楚了——它確實(shí)也能把圖片加進(jìn)文檔但它只能新建一個(gè)段落并把圖片放進(jìn)去這個(gè)段落被追加在Body最后面。它不是“文檔級(jí)”該有的操作更像是一個(gè)方便追加的快捷方法。想要往文檔中間、模板某個(gè)位置插圖必須自己控制游標(biāo)和段落。還有一個(gè)容易忽略的細(xì)節(jié)Word中的Run是一段格式相同的文本。比如你寫“第一段加粗第二段普通”這兩段里就有不同的標(biāo)簽。圖片掛在某個(gè)Run下意味著圖片會(huì)和這個(gè)Run擁有相同的段落格式、字體設(shè)置。這也是為什么插入圖片后它的縮進(jìn)、行距、對(duì)齊方式經(jīng)常要額外單獨(dú)設(shè)置——因?yàn)閳D片事實(shí)上繼承或者部分繼承了Run所在的段落樣式。搞清楚對(duì)象模型之后下一個(gè)問題自然就來了怎么定位標(biāo)題里的“指定位置”到底怎么表達(dá)給POI2. 定位方案對(duì)比索引、文本錨點(diǎn)、書簽到底選哪個(gè)“指定位置”說起來簡單但實(shí)現(xiàn)時(shí)定位方式有幾種選錯(cuò)后面全是坑。我把常見方案整理了一下按實(shí)際體驗(yàn)排序。定位方式實(shí)現(xiàn)難度抗模板改動(dòng)能力模板可讀性實(shí)測推薦度段落索引定位低差模板多一個(gè)段落就全錯(cuò)位差靠猜不推薦文本錨點(diǎn)定位中好只要錨點(diǎn)文字不被刪就行好模板里一眼能看出標(biāo)記強(qiáng)推書簽定位中高好但POI對(duì)書簽的封裝比較繞一般Word里才看得見可以用但不優(yōu)先表格行/單元格定位中取決于具體場景一般特定場景用索引定位是我最早試的方法。寫起來最省事doc.getParagraphs().get(index)拿到段落就往前面插。但壞處非常致命模板只要被編輯過一次哪怕是多空了一行索引全部位移。而且批量插入時(shí)前一次插入會(huì)改變后續(xù)段落的索引位置得從后往前倒著插調(diào)試起來非常消耗耐心。這個(gè)方法只適合那種完全用代碼動(dòng)態(tài)生成的、結(jié)構(gòu)永遠(yuǎn)不變化的文檔不適合模板填充。書簽定位理論上很優(yōu)雅。Word里CtrlShiftF2加個(gè)書簽POI里也有XWPFBookmark、getBookmarks()之類的東西。實(shí)際試下來書簽要綁定到段落或者Run的XML節(jié)點(diǎn)上定位之后進(jìn)行操作還得自己轉(zhuǎn)游標(biāo)代碼繞模板使用者還未必會(huì)加書簽。不是不行是性價(jià)比低。我最后穩(wěn)定使用的是文本錨點(diǎn)定位。做法很簡單在Word模板里寫一行占位符比如{{IMG}}或者更具體的{{IMG_QUALITY}}、{{IMG_SIGNATURE}}代碼先遍歷所有段落包括表格里的段落找到包含這個(gè)標(biāo)記的段落然后在它前面或后面插入一個(gè)帶圖片的新段落。好處是模板長什么樣不影響定位編輯過也最多是標(biāo)記文字被改視覺上占位符本身對(duì)排版影響也小。占位符設(shè)計(jì)有兩個(gè)小經(jīng)驗(yàn)。第一標(biāo)記盡量加雙花括號(hào)比如{{IMG}}這和渲染模板的語法一致不容易和正文文字沖突第二每個(gè)插入位置用不同的標(biāo)記名稱而不是復(fù)用同一個(gè){{IMG}}這樣批量插入時(shí)不會(huì)出現(xiàn)“每次找到的都是第一個(gè)標(biāo)記”的問題。選定文本錨點(diǎn)方案之后剩下的核心就是游標(biāo)操作了。這也是POI插入圖片最繞、最容易出問題的地方。3. 游標(biāo)定位法完整實(shí)現(xiàn)從依賴到代碼一步步來先說環(huán)境。我用的是Maven工程最常用的POI版本是5.2.3用4.x也差不多但5.x的API更干凈推薦以5.x為準(zhǔn)。dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.3/version /dependencypoi-ooxml這個(gè)包會(huì)把poi、xmlbeans、poi-ooxml-lite等依賴一并帶進(jìn)來做Word段落、Run、圖片操作已經(jīng)足夠不需要額外引入poi-scratchpad。3.1 先在模板里埋好占位符打開Word模板在需要插入圖片的位置輸入{{IMG_LOGO}}比如公司技術(shù)認(rèn)證報(bào)告 {{IMG_LOGO}} 申請(qǐng)人信息如下……這里的{{IMG_LOGO}}會(huì)在運(yùn)行時(shí)被圖片替換掉。模板里這一行可以單獨(dú)占一個(gè)段落也可以和其他文字混在一起。為了排版省心我建議單獨(dú)占一行。3.2 查找錨點(diǎn)段落的核心代碼查找錨點(diǎn)有兩個(gè)層面要處理文檔正文段落和表格內(nèi)段落。很多人只寫了doc.getParagraphs()結(jié)果表格里的占位符永遠(yuǎn)定位不到這是最常見的坑之一。import org.apache.poi.xwpf.usermodel.*; public class AnchorFinder { /** * 在文檔所有段落含表格單元格中的段落中查找包含指定占位符的段落。 */ public static XWPFParagraph findAnchor(XWPFDocument doc, String placeholder) { // 1. 正文區(qū)段落 for (XWPFParagraph p : doc.getParagraphs()) { if (p.getText() ! null p.getText().contains(placeholder)) { return p; } } // 2. 表格內(nèi)單元格的段落 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和正文段落一樣操作沒區(qū)別。3.3 在錨點(diǎn)段落之前插入帶圖片的新段落定位到錨點(diǎn)段落之后最常用的需求是把圖片插到占位符所在位置。以“圖片插在錨點(diǎn)段落之前”為例完整代碼如下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 { /** * 在錨點(diǎn)段落之前插入一個(gè)包含圖片的新段落。 */ public static void insertImageBefore(XWPFParagraph anchor, String imagePath, int widthPx, int heightPx) throws Exception { // 關(guān)鍵拿到錨點(diǎn)段落的底層XML游標(biāo) XmlCursor cursor anchor.getCTP().newCursor(); // 在游標(biāo)當(dāng)前位置插入新段落。游標(biāo)正好指向錨點(diǎn)段落的開始 // 所以新段落會(huì)落在錨點(diǎn)段落之前。 XWPFParagraph imgParagraph anchor.getDocument().insertNewParagraph(cursor); // 讓圖片段落居中視覺效果最穩(wěn) imgParagraph.setAlignment(ParagraphAlignment.CENTER); // 新建Run圖片掛在Run上 XWPFRun run imgParagraph.createRun(); // 根據(jù)文件擴(kuò)展名判斷圖片類型 int picType getPictureType(imagePath); // addPicture的寬高單位是EMU不是像素這里用Units轉(zhuǎn)換 try (InputStream is new FileInputStream(imagePath)) { run.addPicture(is, picType, imagePath, Units.toEMU(widthPx), Units.toEMU(heightPx)); } // 插入完成之后把占位符從錨點(diǎn)段落里清掉 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()) { // 把清理后的文本放到第一個(gè)Run其他Run清空 runs.get(0).setText(newText, 0); for (int i 1; i runs.size(); i) { runs.get(i).setText(, 0); } } } } }這段代碼看起來不長但幾個(gè)關(guān)鍵點(diǎn)不解釋清楚換一個(gè)場景就抓瞎。XmlCursor是Apache XMLBeans提供的游標(biāo)它可以直接在底層XML節(jié)點(diǎn)上做前后移動(dòng)和插入操作。anchor.getCTP().newCursor()返回的游標(biāo)位置我實(shí)測下來是在錨點(diǎn)段落w:p的開始標(biāo)簽處。doc.insertNewParagraph(cursor)這個(gè)方法是XWPFDocument提供的專門用來在指定XML位置創(chuàng)建段落它和普通的createParagraph()不同后者只會(huì)追加到Body尾部前者才是真正的“指哪打哪”。寬高參數(shù)是另一個(gè)容易翻車的地方。addPicture方法簽名里的最后兩個(gè)參數(shù)是EMUEnglish Metric Unit不是像素。Word內(nèi)部繪圖單位是EMU1英寸等于914400 EMU1像素大概是9525 EMU。如果直接拿像素?cái)?shù)字傳進(jìn)去圖片會(huì)小得幾乎看不見或者大得離譜。Units.toEMU()就是干這個(gè)換算的沒這個(gè)工具類只能自己乘9525。clearPlaceholder做的事是把占位符文本從錨點(diǎn)段落里抹掉。為什么要單獨(dú)做這一步因?yàn)檎嘉环粼谀０謇锏谝淮芜\(yùn)行時(shí)被圖片替換了但如果不清掉第二次生成時(shí)同一個(gè)模板還會(huì)再匹配到它就會(huì)出現(xiàn)重復(fù)插入。3.4 想插到錨點(diǎn)段落之后怎么辦很多需求是“在某某段落后邊加一張圖”比如“以上為申請(qǐng)信息下方為簽字照片”。這種場景下圖片要插在錨點(diǎn)段落后面做法是先把游標(biāo)往后移動(dòng)到錨點(diǎn)段落的結(jié)束標(biāo)簽位置XmlCursor cursor anchor.getCTP().newCursor(); cursor.toEndToken(); XWPFParagraph imgParagraph anchor.getDocument().insertNewParagraph(cursor); // 后續(xù)邏輯同上創(chuàng)建Run、addPicture、清占位符toEndToken()把游標(biāo)移動(dòng)到當(dāng)前元素結(jié)束標(biāo)簽的位置此時(shí)調(diào)用insertNewParagraph新段落會(huì)落在錨點(diǎn)段落之后。這個(gè)和插入到前面剛好對(duì)稱。不過要提醒一句不同版本XMLBeans對(duì)游標(biāo)位置“在結(jié)束標(biāo)簽上”和“在結(jié)束標(biāo)簽后”的語義行為略有差異萬一插出來位置不對(duì)在toEndToken()之后補(bǔ)一行cursor.toNextToken()再插入通常就能糾正。如果你的場景比較復(fù)雜圖既要插在錨點(diǎn)前又要插在錨點(diǎn)后或者一時(shí)拿不準(zhǔn)方向最穩(wěn)妥的做法是模板里放一對(duì)占位符比如{{IMG_START}}和{{IMG_END}}圖片先插到{{IMG_END}}之前再把兩個(gè)占位符都清掉。這樣無論版本怎么變位置始終可控。4. 圖片大小、對(duì)齊和樣式繼承插進(jìn)去不難插得好看才難圖片能插進(jìn)去了不代表完事了。我見過很多初學(xué)者把圖插進(jìn)去之后一打開Word圖片要么大得超出頁面要么歪在頁面邊上要么和周圍文字?jǐn)D在一起版式完全沒法看。這一節(jié)把排版相關(guān)的細(xì)節(jié)一次說透。4.1 按比例縮放圖片而不是寫死寬高最樸素的寫法是直接傳固定像素值比如Units.toEMU(300)、Units.toEMU(200)。問題在于原圖可能是4000x3000的大圖傳300x200會(huì)變形原圖是800x600傳300x200又會(huì)模糊。正確做法是先讀圖片原始尺寸按目標(biāo)寬度等比計(jì)算高度。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)}; }至于最大寬高設(shè)多少要結(jié)合頁面實(shí)際可用寬度來算。A4紙寬度是21厘米默認(rèn)頁邊距左右各3.17厘米也就是說文字區(qū)的可用寬度大概是14.65厘米。如果你希望圖片鋪滿整個(gè)可用寬度14.65厘米換算成像素大概是14.65 / 2.54 * 96 ≈ 553像素。我一般取550作為最大寬度高度限制在350-400左右基本不會(huì)超出頁面。4.2 對(duì)齊方式單獨(dú)設(shè)置圖片段落既然是獨(dú)立的段落它的對(duì)齊方式就由段落屬性控制。居中是最常見的需求imgParagraph.setAlignment(ParagraphAlignment.CENTER);左右對(duì)齊也是同理。要注意的是如果錨點(diǎn)段落原來的對(duì)齊方式是左對(duì)齊而你新插入的圖片段落沒有顯式設(shè)置那么圖片會(huì)沿用段落默認(rèn)樣式可能是左對(duì)齊也可能是兩端對(duì)齊整體看起來就很隨機(jī)。所以每次插入都顯式setAlignment不要依賴默認(rèn)值。4.3 圖片段落繼承錨點(diǎn)段落的樣式模板里不同段落的字體、行距、縮進(jìn)可能不同。如果圖片段落是全新建的“裸段落”它的樣式可能和其他段落格格不入。最簡單的解法是把錨點(diǎn)段落的段落屬性拷貝過來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()); }這樣做的好處是行距、縮進(jìn)、段前段后間距全都和錨點(diǎn)段落保持一致。如果你連字體格式都希望圖片Run繼承可以再拷貝Run的RPr不過圖片本身沒有字體影響不大。4.4 圖片和周圍文字之間的間距圖片段落默認(rèn)的行距可能會(huì)讓圖片和上下文字貼得很近讀起來很擠?？梢栽趫D片段落的setSpacingBefore和setSpacingAfter上稍微加點(diǎn):imgParagraph.setSpacingBefore(200); imgParagraph.setSpacingAfter(200);這里的單位是緹twips1磅等于20緹200緹就是10磅視覺上比較舒服。具體大小看實(shí)際效果微調(diào)。5. 實(shí)測踩坑記錄這份避坑清單能省你大半天時(shí)間這部分整理了我在實(shí)際項(xiàng)目中遇到過的坑有些坑可能浪費(fèi)了你幾個(gè)小時(shí)也不一定想到。每一條都是從報(bào)錯(cuò)到排錯(cuò)到解決完整走過來的不是從官方文檔摘抄的。5.1 占位符被Word拆到多個(gè)Run里replace不掉這是第一個(gè)真正惡心到我的坑。模板里手寫的{{IMG_LOGO}}存盤之后Word不一定把整串文字放在同一個(gè)Run里可能{{在一個(gè)RunIMG_LOGO在另一個(gè)Run}}又在第三個(gè)Run。你用paragraph.getText()能拿到完整文本一replace卻發(fā)現(xiàn)段落里根本沒變化因?yàn)槟阋鎿Q的內(nèi)容跨越了Run邊界。clearPlaceholder里我用了“拼完整文本、改第一個(gè)Run、清空其余Run”的策略就是為了應(yīng)對(duì)這種情況。如果替換完發(fā)現(xiàn)錨點(diǎn)段落里還殘留半個(gè)大括號(hào)的文本多半是遍歷時(shí)遺漏了哪個(gè)Run的getText(0)返回null處理時(shí)判空就行。5.2 只查正文段落表格里的占位符永遠(yuǎn)找不到上文代碼里已經(jīng)處理了這個(gè)問題但我在實(shí)際開發(fā)中見到不少同事只寫了doc.getParagraphs()。文檔一旦涉及表格比如申請(qǐng)表、報(bào)價(jià)單占位符放在表格單元格里查正文段落就找不到程序直接往下走圖片就全堆到了文檔末尾。表面看是“插入位置不對(duì)”本質(zhì)是定位邏輯根本沒覆蓋到表格。排查這類問題先確認(rèn)錨點(diǎn)是不是在表格里再?zèng)Q定遍歷方式。5.3 重復(fù)插入同一個(gè)占位符被命中多次這不是死循環(huán)但效果類似。假設(shè)模板里有好幾處{{IMG}}你調(diào)用findAnchor每次都從頭遍歷那么返回的永遠(yuǎn)是第一個(gè){{IMG}}段落。第一張圖插入后會(huì)清理占位符但第二次查找時(shí)第一個(gè)段落已經(jīng)沒有標(biāo)記了可代碼是從頭再查的結(jié)果還是會(huì)找到第二個(gè)位置之前的第一個(gè){{IMG}}——如果只插入一次還好循環(huán)插入就會(huì)錯(cuò)亂。我的解法是模板里的占位符一律帶編號(hào){{IMG_1}}、{{IMG_2}}、{{IMG_3}}。這樣每個(gè)位置有唯一標(biāo)識(shí)查找時(shí)按編號(hào)精確匹配。如果要插入同一張圖到多個(gè)位置就顯式多次調(diào)用每次傳不同的占位符邏輯清晰也不容易錯(cuò)。5.4 圖片類型判斷錯(cuò)誤生成的docx打不開addPicture里的第二個(gè)參數(shù)必須和實(shí)際圖片字節(jié)格式匹配。之前出現(xiàn)過一次文件擴(kuò)展名是.png但實(shí)際內(nèi)容被改成了JPEG編碼getPictureType判斷成了PNG結(jié)果打開生成的Word時(shí)報(bào)“無法讀取圖片文件已損壞”。嚴(yán)格來說這不是判斷邏輯的問題而是圖片文件的真實(shí)格式問題。穩(wěn)妥做法是用ImageIO.read()解析圖片通過ImageIO.getImageReaders()獲取真實(shí)格式再映射到POI的圖片類型常量。如果項(xiàng)目里圖片來源可控都是程序生成的PNG用擴(kuò)展名判斷就夠了如果圖片是外部上傳的建議按真實(shí)格式判斷。5.5 生成的文件提示“要修復(fù)”的問題排查思路如果你插入后生成的docx在Word里提示“發(fā)現(xiàn)無法讀取的內(nèi)容是否嘗試修復(fù)”別慌九成是XML結(jié)構(gòu)出了問題。我的排查順序是先把生成的文件用解壓工具解壓打開word/document.xml直接看新插入段落前后的XML標(biāo)簽是否閉合正常。段落嵌套層級(jí)不正確是最常見原因。檢查是不是游標(biāo)位置操作出了問題比如在Body層級(jí)的段落外又插入了孤立節(jié)點(diǎn)或者插入到了一個(gè)表格單元格的非法位置。單獨(dú)跑一個(gè)最小復(fù)現(xiàn)用例只插入一張圖片、只操作一個(gè)占位符看能不能復(fù)現(xiàn)。能復(fù)現(xiàn)問題就在插入邏輯不能復(fù)現(xiàn)說明是模板本身有問題。另外所有插入操作完成后記得調(diào)用一次doc.write()刷新內(nèi)部結(jié)構(gòu)再關(guān)閉輸出流。不要用doc.getDocument().toString()直接拼字符串查問題那個(gè)是底層XML的toString和實(shí)際寫入文件的內(nèi)容不完全一樣。5.6 圖片流資源泄漏addPicture需要傳入InputStream如果你用裸寫new FileInputStream()不關(guān)流批量生成文檔時(shí)容易出現(xiàn)文件句柄耗盡或文件被占用刪除不掉。上面代碼全用了try-with-resources這個(gè)習(xí)慣一定要帶上。尤其是在循環(huán)內(nèi)插入幾十張圖片的場景不關(guān)流的后果會(huì)非常明顯。6. 批量插入場景的性能優(yōu)化與模板復(fù)用最后一個(gè)常見場景一份文檔里要插入幾十張圖比如產(chǎn)品目錄、員工證件照集合、訂單截圖列表。按前面的單張插入方法每張圖都從頭遍歷整篇文檔找錨點(diǎn)復(fù)雜度是O(n*m)文檔段落很多時(shí)會(huì)明顯變慢。這個(gè)環(huán)節(jié)給幾個(gè)優(yōu)化思路。6.1 一次性收集錨點(diǎn)避免反復(fù)全表掃描不管插入多少張圖先做一次遍歷把占位符和對(duì)應(yīng)的圖片路徑配對(duì)收集起來然后再統(tǒng)一處理?？梢杂靡粋€(gè)小結(jié)構(gòu)class ImageAnchor { String placeholder; String imagePath; XWPFParagraph anchor; }遍歷時(shí)只掃一遍所有段落含表格把每個(gè)占位符對(duì)應(yīng)的段落引用存下來。這樣后續(xù)插入直接拿對(duì)象操作不需要反復(fù)從頭找。插入新段落時(shí)注意底層XML是動(dòng)態(tài)變化的但你已經(jīng)拿到的XWPFParagraph對(duì)象引用依然有效因?yàn)樗腔贑TP包裝的不會(huì)因?yàn)椴迦胄露温涠А?.2 “可反復(fù)運(yùn)行”的冪等處理真實(shí)業(yè)務(wù)里往往要求同一個(gè)模板重復(fù)生成多份文檔比如批量套打證書。如果模板里的占位符被第一次運(yùn)行改掉第二次想再復(fù)用同一份模板文檔就會(huì)發(fā)現(xiàn)占位符沒了。我的做法是每次生成前都從原始模板重新加載一份副本占位符永遠(yuǎn)以原始模板為準(zhǔn)。生成流程變成三條固定步驟new XWPFDocument(templateInputStream)加載原始模板查占位符、插入圖片、清理占位符輸出寫入新的docx文件模板文件只讀絕不寫入。這樣無論跑多少次模板永遠(yuǎn)是干凈的。6.3 線程安全的取舍XWPFDocument不是線程安全的同一個(gè)模板對(duì)象多線程操作會(huì)互相干擾。如果并發(fā)量高要么每個(gè)線程各自加載一份模板副本要么用線程池串行化處理同一模板的生成任務(wù)。最省事的做法是把模板內(nèi)容readAllBytes()讀進(jìn)字節(jié)數(shù)組每次new XWPFDocument(new ByteArrayInputStream(bytes))生成新實(shí)例。模板不大時(shí)開銷可以忽略換來的是完全隔離不用加鎖。6.4 不要邊遍歷邊改結(jié)構(gòu)的深層原因有些操作在循環(huán)內(nèi)直接用doc.getParagraphs()并同時(shí)調(diào)用insertNewParagraph這背后的隱患不只是索引偏移XMLBeans的游標(biāo)遍歷邏輯在節(jié)點(diǎn)增刪過程中有時(shí)會(huì)拋出ConcurrentModificationException有時(shí)會(huì)靜默跳過新插入節(jié)點(diǎn)導(dǎo)致插入順序錯(cuò)亂。把“收集”和“操作”分成兩階段不僅是性能考慮更是規(guī)避這類詭異問題的根本手段。我在批量插入場景里統(tǒng)一遵守一個(gè)規(guī)則收集階段只return段落引用操作階段只使用已收集到的引用做插入絕不在遍歷的同時(shí)修改文檔結(jié)構(gòu)。這套思路跑下來上百張圖片的文檔生成也穩(wěn)定。如果你也要做類似功能建議先把這個(gè)原則定下來再寫業(yè)務(wù)代碼。