1. 为什么“带图片的Excel导出”是个高频刚需做过企业级后台系统的人大概率都遇到过这种需求运营要导出一份商品清单每行商品除了名称、价格、库存还得把商品主图塞进单元格里或者HR要导出一份员工花名册每行带一张一寸照片再或者质检部门要导出一份巡检记录每条记录附一张现场照片。这类需求听起来简单真动手做的时候坑一个接一个。纯文本的Excel导出用POI的SXSSFWorkbook或者XSSFWorkbook就能搞定代码写起来也顺手。但一旦涉及图片事情就变得微妙了图片怎么锚定到指定单元格图片尺寸怎么控制行高列宽怎么配合图片多了内存会不会炸导出几万行带图的数据服务器扛不扛得住这些问题不解决导出的文件要么图片错位要么直接OOM。而Freemarker在这里扮演的角色是把“Excel模板”这件事做得更优雅。传统做法是用Java代码一行一行画表格、设样式、插图片代码又臭又长改个表头都得重新编译。用Freemarker做模板引擎可以把Excel的样式、表头、固定文案抽离成模板文件Java只负责往模板里灌数据图片的插入逻辑单独处理。这样业务人员改表头、调样式不用碰Java代码维护成本直接降一个量级。这套方案适合谁适合正在做后台管理系统、报表系统、数据导出功能的开发者尤其是那些被“Excel导出带图片”折磨过一轮的人。不管你用的是Spring Boot还是传统SSM只要项目里引入了POI和Freemarker这套思路都能直接抄。下面我会从整体设计、核心细节、实操过程到踩坑排查把这件事掰开揉碎讲清楚。2. 整体方案设计与技术选型拆解2.1 为什么是Freemarker加POI的组合先说说为什么不用纯POI硬编码。纯POI写Excel样式和内容耦合在Java代码里一个稍微复杂的报表代码轻松上千行。表头改一个字得找到对应代码位置改完重新打包。而Freemarker的模板文件是纯文本的改完直接生效甚至可以让运营自己维护模板。那为什么不用EasyExcelEasyExcel确实在读写大文件上有优势但它在“模板填充图片插入”这个组合场景下灵活度不如POI直接操作。EasyExcel的图片支持相对有限尤其是图片锚定到具体单元格、控制图片与单元格边距这些细节POI的DrawingPatriarch和ClientAnchor给的控制力更强。所以这套方案的定位很清晰Freemarker负责模板渲染表头、样式、固定文案、数据占位POI负责最终的文件生成和图片插入。两者各司其职模板归模板图片归图片。2.2 模板文件的设计思路模板文件本质上是一个“半成品Excel”。我的做法是先用Excel软件手工做一个样板文件把表头、列宽、行高、字体、边框、背景色全部调好然后把需要动态填充的地方用Freemarker的占位符替换掉最后把文件后缀改成.ftl。比如一个商品清单模板表头是固定的数据行是循环的模板里大概长这样#list items as item ${item.name} | ${item.price} | ${item.stock} | [图片占位] /#list但这里有个关键问题Excel的.xlsx文件本质是个ZIP压缩包里面是一堆XML。Freemarker直接渲染.xlsx文件会破坏其二进制结构。所以正确的做法是模板文件用.xls格式老版Excel本质是二进制流Freemarker可以处理或者用POI先读取模板再填充。我实测下来更稳的方案是用POI读取.xlsx模板文件然后用Freemarker渲染一个“数据模型”Java代码根据模型往Workbook里填数据。这样既保留了模板的样式又避免了直接渲染二进制文件的坑。2.3 图片插入的核心机制POI插入图片的核心API是DrawingPatriarch和ClientAnchor。简单说DrawingPatriarch是画布ClientAnchor是锚点用来指定图片放在哪个单元格、跨几行几列、偏移多少。关键参数有四个col1、row1、col2、row2。前两个是起始单元格的列和行后两个是结束单元格的列和行。如果col1和col2相同、row1和row2相同图片就锚定在一个单元格内。如果不同图片就跨多个单元格。图片的尺寸控制有两种方式一是通过ClientAnchor的偏移量控制二是通过Picture.resize()方法控制。我一般用后者因为更直观。resize()接受两个参数缩放比例和单位。比如resize(0.5, Units.EMU_PER_PIXEL)表示按像素单位缩放50%。2.4 内存与性能的权衡带图片的Excel导出最大的性能瓶颈在内存。每张图片都要加载到内存、转换成POI的PictureData、再写入Workbook。如果一次导出几千行、每行一张图内存直接飙升。解决方案有两个方向一是用SXSSFWorkbook做流式写入但SXSSFWorkbook对图片的支持有限图片仍然会驻留内存二是控制图片数量和大小比如限制单次导出最多500行带图数据或者对图片做压缩后再插入。我的经验是如果单次导出超过1000张图片建议拆分成多个文件或者改用异步导出下载链接的方式。同步导出1000张图响应时间基本在10秒以上用户体验很差。3. 核心细节解析与实操要点3.1 模板文件的制作与占位符规范制作模板文件时有几个细节必须注意。第一占位符的命名要统一比如统一用${item.xxx}的格式避免${name}和${item.name}混用否则Freemarker渲染时会报错。第二占位符所在单元格的样式要提前设好因为POI填充数据时不会自动继承样式需要手动复制样式。第三图片占位单元格要留足空间。我一般会把图片所在列的列宽设为20左右行高设为80左右这样插入的图片不会挤压变形。具体数值可以根据图片的实际尺寸调整公式是列宽字符数× 7 ≈ 像素宽度行高磅值× 1.33 ≈ 像素高度。第四模板文件不要用合并单元格做数据行。合并单元格在POI里处理起来很麻烦尤其是循环填充时容易错位。如果表头需要合并只在表头区域合并数据行保持单单元格。3.2 Freemarker数据模型的构建Freemarker渲染需要一个数据模型通常用MapString, Object来构建。对于列表数据用ListMapString, Object。图片数据比较特殊不能直接塞进模型里让Freemarker渲染因为Freemarker不认识二进制图片。我的做法是数据模型里只放图片的标识比如图片路径或图片IDJava代码在填充完文本数据后再根据标识去加载图片并插入到对应单元格。这样Freemarker只负责文本渲染图片插入完全由POI控制职责清晰。数据模型的结构大概是这样MapString, Object model new HashMap(); model.put(title, 商品清单); model.put(exportDate, 2024-01-15); ListMapString, Object items new ArrayList(); for (Product p : productList) { MapString, Object item new HashMap(); item.put(name, p.getName()); item.put(price, p.getPrice()); item.put(stock, p.getStock()); item.put(imageId, p.getImageId()); // 图片标识不直接放图片 items.add(item); } model.put(items, items);3.3 图片加载与格式处理POI支持多种图片格式PNG、JPEG、BMP、GIF等。但实际用下来PNG和JPEG最稳其他格式在某些Excel版本里可能显示异常。图片加载时我一般用ImageIO.read()读取然后转成ByteArrayOutputStream再通过workbook.addPicture()添加。这里有个坑图片的宽高比要保持。如果原图是长方形直接塞进正方形单元格会变形。我的做法是先计算原图的宽高比然后根据单元格的可用空间按比例缩放。比如单元格可用宽度是100像素、高度是80像素原图是200×100宽高比2:1那就按宽度100像素缩放高度变成50像素居中显示。图片格式转换的代码大概是这样BufferedImage bufferedImage ImageIO.read(new File(imagePath)); int originalWidth bufferedImage.getWidth(); int originalHeight bufferedImage.getHeight(); double ratio (double) originalWidth / originalHeight; int targetWidth 100; int targetHeight (int) (targetWidth / ratio); if (targetHeight 80) { targetHeight 80; targetWidth (int) (targetHeight * ratio); } ByteArrayOutputStream baos new ByteArrayOutputStream(); ImageIO.write(bufferedImage, png, baos); byte[] imageBytes baos.toByteArray(); int pictureIdx workbook.addPicture(imageBytes, Workbook.PICTURE_TYPE_PNG);3.4 图片锚定与单元格对齐图片锚定是整个过程里最考验细节的地方。ClientAnchor的构造函数有多个重载我一般用new XSSFClientAnchor(dx1, dy1, dx2, dy2, col1, row1, col2, row2)。其中dx1、dy1是起始单元格内的偏移量dx2、dy2是结束单元格内的偏移量单位是EMUEnglish Metric Unit1像素约等于9525 EMU。如果想让图片完全填充一个单元格col1和col2相同、row1和row2相同dx1和dy1设为0dx2和dy2设为单元格的宽高对应的EMU值。但这样图片会拉伸变形所以更好的做法是保持图片原始比例通过偏移量让图片在单元格内居中。居中的计算逻辑是dx1 (cellWidth - imageWidth) / 2dy1 (cellHeight - imageHeight) / 2。这样图片就会在单元格内水平垂直居中。3.5 样式复制的正确姿势POI填充数据时新创建的单元格默认没有样式。如果模板里已经设好了样式需要用CellStyle复制过来。但CellStyle不能直接赋值必须通过workbook.createCellStyle()创建新样式然后逐个属性复制。我一般写一个工具方法把模板单元格的样式复制到目标单元格public static void copyCellStyle(CellStyle source, CellStyle target) { target.setAlignment(source.getAlignment()); target.setVerticalAlignment(source.getVerticalAlignment()); target.setBorderBottom(source.getBorderBottom()); target.setBorderLeft(source.getBorderLeft()); target.setBorderRight(source.getBorderRight()); target.setBorderTop(source.getBorderTop()); target.setBottomBorderColor(source.getBottomBorderColor()); target.setFillBackgroundColor(source.getFillBackgroundColor()); target.setFillForegroundColor(source.getFillForegroundColor()); target.setFillPattern(source.getFillPattern()); target.setFont(source.getFont()); // 其他属性按需复制 }注意CellStyle的数量在Excel里是有限制的最多64000个如果每行都创建新样式很容易超限。正确的做法是复用样式对象比如表头样式创建一个数据行样式创建一个所有行共用。4. 完整实操流程与核心环节实现4.1 环境准备与依赖引入先确认项目里引入了POI和Freemarker的依赖。Maven项目的话pom.xml里加这几项dependency groupIdorg.apache.poi/groupId artifactIdpoi/artifactId version5.2.3/version /dependency dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.3/version /dependency dependency groupIdorg.freemarker/groupId artifactIdfreemarker/artifactId version2.3.32/version /dependencyPOI 5.x版本对.xlsx的支持更完善建议用5.0以上。Freemarker 2.3.32是稳定版兼容性好。4.2 模板文件的制作步骤第一步用Excel软件新建一个.xlsx文件设计好表头、列宽、行高、字体、边框。第二步把需要动态填充的单元格内容替换成Freemarker占位符比如${title}、${exportDate}。第三步数据行用#list items as item包裹循环体内的单元格填${item.name}这类占位符。第四步保存文件把后缀改成.ftl放到项目的resources/templates目录下。这里有个细节模板文件里的占位符不要放在合并单元格里否则Freemarker渲染后POI读取时容易出错。如果表头必须合并合并区域只放静态文本不放占位符。4.3 Java代码的完整实现整个导出流程分五步加载模板、渲染数据、填充文本、插入图片、输出文件。public void exportExcelWithImages(HttpServletResponse response, ListProduct productList) throws Exception { // 1. 加载模板 Configuration cfg new Configuration(Configuration.VERSION_2_3_32); cfg.setClassLoaderForTemplateLoading(this.getClass().getClassLoader(), templates); cfg.setDefaultEncoding(UTF-8); Template template cfg.getTemplate(product_template.ftl); // 2. 构建数据模型 MapString, Object model new HashMap(); model.put(title, 商品清单); model.put(exportDate, new SimpleDateFormat(yyyy-MM-dd).format(new Date())); ListMapString, Object items new ArrayList(); for (int i 0; i productList.size(); i) { Product p productList.get(i); MapString, Object item new HashMap(); item.put(name, p.getName()); item.put(price, p.getPrice()); item.put(stock, p.getStock()); item.put(imageId, p.getImageId()); item.put(rowIndex, i); items.add(item); } model.put(items, items); // 3. 渲染模板到临时文件 File tempFile File.createTempFile(export_, .xlsx); try (Writer writer new FileWriter(tempFile)) { template.process(model, writer); } // 4. 用POI读取渲染后的文件 try (FileInputStream fis new FileInputStream(tempFile); XSSFWorkbook workbook new XSSFWorkbook(fis)) { XSSFSheet sheet workbook.getSheetAt(0); // 5. 插入图片 XSSFDrawing drawing sheet.createDrawingPatriarch(); int imageColIndex 3; // 图片所在列 int startRow 1; // 数据起始行 for (int i 0; i productList.size(); i) { Product p productList.get(i); if (p.getImagePath() null) continue; // 加载图片 BufferedImage bufferedImage ImageIO.read(new File(p.getImagePath())); ByteArrayOutputStream baos new ByteArrayOutputStream(); ImageIO.write(bufferedImage, png, baos); byte[] imageBytes baos.toByteArray(); int pictureIdx workbook.addPicture(imageBytes, Workbook.PICTURE_TYPE_PNG); // 创建锚点 XSSFClientAnchor anchor new XSSFClientAnchor( 0, 0, 0, 0, imageColIndex, startRow i, imageColIndex 1, startRow i 1 ); anchor.setAnchorType(ClientAnchor.AnchorType.MOVE_AND_RESIZE); // 插入图片 XSSFPicture picture drawing.createPicture(anchor, pictureIdx); picture.resize(0.8); // 缩放80% } // 6. 输出到响应流 response.setContentType(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet); response.setHeader(Content-Disposition, attachment; filenameexport.xlsx); workbook.write(response.getOutputStream()); } finally { tempFile.delete(); } }4.4 图片尺寸与单元格的精确匹配上面代码里用了picture.resize(0.8)这是最简单的缩放方式。但实际项目中图片尺寸往往需要精确控制。我的做法是先获取单元格的宽高像素再根据图片原始比例计算缩放后的尺寸最后通过ClientAnchor的偏移量实现居中。获取单元格宽高的代码int cellWidth (int) (sheet.getColumnWidthInPixels(imageColIndex)); int cellHeight (int) (sheet.getRow(startRow i).getHeightInPoints() * 1.33);然后计算图片缩放后的尺寸double ratio (double) originalWidth / originalHeight; int targetWidth cellWidth - 10; // 留10像素边距 int targetHeight (int) (targetWidth / ratio); if (targetHeight cellHeight - 10) { targetHeight cellHeight - 10; targetWidth (int) (targetHeight * ratio); }最后设置锚点偏移量让图片居中int dx1 (cellWidth - targetWidth) / 2 * 9525; int dy1 (cellHeight - targetHeight) / 2 * 9525; int dx2 dx1 targetWidth * 9525; int dy2 dy1 targetHeight * 9525; XSSFClientAnchor anchor new XSSFClientAnchor(dx1, dy1, dx2, dy2, col, row, col, row);这样图片就会精确地居中显示在单元格内不会变形也不会溢出。4.5 大数据量导出的分批处理如果一次导出几千行带图数据内存和响应时间都是问题。我的处理策略是分批查询、分批写入、最后合并。具体做法是每500行一批每批生成一个临时Workbook最后把所有临时Workbook的内容合并到一个主Workbook里。但合并Workbook在POI里比较麻烦尤其是图片的合并。更简单的做法是限制单次导出的图片数量比如最多500张超过的部分提示用户分批导出。或者用异步导出后台生成文件后存到文件服务器用户通过下载链接获取。我实测下来500行带图数据同步导出耗时约3-5秒内存占用约200MB。1000行的话耗时翻倍内存接近400MB。所以500行是个比较安全的阈值。5. 常见问题与排查技巧实录5.1 图片错位、偏移、不显示这是最常见的问题原因通常有三个。第一锚点的col1、row1、col2、row2设置错误。比如图片应该在第3列第5行结果写成了第2列第4行。排查方法是打印锚点参数和实际单元格位置对比。第二图片的resize()比例过大导致图片溢出单元格。排查方法是把resize()参数调小比如从1.0改成0.5看是否正常显示。第三模板文件里的行高列宽和代码里设置的不一致。比如模板里行高是60磅代码里按80磅计算图片就会偏上。排查方法是统一用模板里的行高列宽不要代码里再改。5.2 内存溢出与性能瓶颈带图导出最容易OOM。排查思路是先看图片数量再看图片大小。如果单张图片超过1MB100张就是100MB加上Workbook本身的开销很容易超过JVM默认堆内存。解决方案有三个一是压缩图片插入前用ImageIO把图片质量降到0.7左右二是限制图片尺寸比如最大宽度不超过200像素三是增大JVM堆内存启动参数加-Xmx1024m。我一般会写一个图片压缩工具方法public static byte[] compressImage(BufferedImage image, float quality) throws IOException { ImageWriter writer ImageIO.getImageWritersByFormatName(jpeg).next(); ImageWriteParam param writer.getDefaultWriteParam(); param.setCompressionMode(ImageWriteParam.MODE_EXPLICIT); param.setCompressionQuality(quality); ByteArrayOutputStream baos new ByteArrayOutputStream(); try (ImageOutputStream ios ImageIO.createImageOutputStream(baos)) { writer.setOutput(ios); writer.write(null, new IIOImage(image, null, null), param); } writer.dispose(); return baos.toByteArray(); }5.3 模板渲染后文件损坏这个问题通常是因为Freemarker直接渲染了.xlsx文件。.xlsx是ZIP格式Freemarker按文本处理会破坏其二进制结构。正确的做法是模板文件用.xls格式或者用POI读取模板后再填充数据不要直接用Freemarker渲染.xlsx。如果非要用Freemarker渲染可以把模板文件改成.xml格式Excel 2003 XML这种格式是纯文本Freemarker可以安全渲染。但.xml格式的Excel在样式和图片支持上不如.xlsx所以不推荐。5.4 中文乱码与编码问题中文乱码通常出现在两个地方一是Freemarker模板文件的编码二是响应流的编码。模板文件保存时要用UTF-8编码Freemarker配置里设置cfg.setDefaultEncoding(UTF-8)。响应流设置response.setCharacterEncoding(UTF-8)并且Content-Disposition里的文件名要用URLEncoder.encode()编码。String fileName URLEncoder.encode(商品清单.xlsx, UTF-8); response.setHeader(Content-Disposition, attachment; filename fileName);5.5 常见问题速查表问题现象可能原因排查方法解决方案图片不显示锚点参数错误打印锚点参数对比单元格位置修正col1/row1/col2/row2图片变形宽高比未保持检查resize比例按原始比例计算缩放图片错位行高列宽不一致对比模板和代码设置统一使用模板设置内存溢出图片过大过多查看图片数量和大小压缩图片、限制数量文件损坏直接渲染xlsx检查模板文件格式改用xls或POI填充中文乱码编码不一致检查模板和响应编码统一UTF-8样式丢失未复制样式检查CellStyle复制逻辑复用样式对象提示如果导出后发现图片位置总是差一点点大概率是EMU单位换算的问题。1像素9525 EMU1磅12700 EMU换算时注意单位统一。5.6 几个我踩过的坑第一个坑模板文件里的占位符被Excel自动转义。比如${item.name}被Excel识别成公式保存后变成了${item.name}的转义形式。解决办法是在占位符前面加一个单引号或者把单元格格式设为“文本”。第二个坑图片插入后文件体积暴涨。一张1MB的图片插入Excel后文件体积可能变成3MB。原因是POI会把图片重新编码而且.xlsx本身是ZIP压缩图片压缩率不高。解决办法是插入前先压缩图片或者用SXSSFWorkbook的setCompressTempFiles(true)。第三个坑多线程导出时Workbook线程不安全。POI的Workbook不是线程安全的多个线程同时操作同一个Workbook会出问题。解决办法是每个线程创建独立的Workbook或者用线程池加锁。第四个坑图片路径包含中文或空格。ImageIO.read(new File(path))在路径包含中文时可能返回null。解决办法是用URLDecoder.decode()解码路径或者用ClassLoader.getResourceAsStream()读取。6. 进阶优化与扩展思路6.1 图片异步加载与缓存如果图片来自远程URL同步加载会拖慢导出速度。我的做法是用线程池异步加载图片加载完成后缓存到本地临时目录导出时直接从缓存读取。这样第二次导出同一批数据时速度会快很多。ExecutorService executor Executors.newFixedThreadPool(10); MapString, Futurebyte[] futures new HashMap(); for (Product p : productList) { futures.put(p.getImageId(), executor.submit(() - downloadImage(p.getImageUrl()))); } // 导出时从future获取 byte[] imageBytes futures.get(p.getImageId()).get();6.2 模板的动态列与条件样式Freemarker模板支持条件判断可以根据数据动态决定是否显示某一列或者根据数值大小设置不同的样式。比如库存小于10的行标红#list items as item #if item.stock 10 #assign rowStyle red #else #assign rowStyle normal /#if ... /#list但POI的样式设置需要在Java代码里做Freemarker只能控制内容。所以更实际的做法是Freemarker渲染时给需要特殊样式的单元格加一个标记Java代码根据标记设置样式。6.3 导出进度与用户体验大数据量导出时用户看不到进度体验很差。我的做法是前端发起导出请求后后端返回一个任务ID前端轮询任务状态导出完成后返回下载链接。这样用户可以看到“正在导出已完成30%”这样的提示。任务状态可以用Redis或内存Map存储导出线程每完成一批就更新进度。导出完成后把文件存到临时目录返回下载URL。6.4 兼容不同Excel版本.xlsx是Excel 2007以后的格式.xls是Excel 2003的格式。如果用户可能用老版本Excel打开建议同时提供两种格式。POI的HSSFWorkbook对应.xlsXSSFWorkbook对应.xlsx。代码上可以抽象一个接口根据文件后缀选择不同的Workbook实现。但.xls对图片的支持不如.xlsx图片数量多了容易出问题。所以我的建议是默认导出.xlsx如果用户明确要求.xls再单独处理。7. 一些个人经验与建议这套方案我在几个项目里都用过从商品清单到员工花名册从巡检记录到质检报告基本都能覆盖。最大的感受是图片插入这件事细节决定成败。锚点参数差一个像素图片就偏了行高列宽差一磅图片就变形了。所以调试的时候一定要耐心多打印参数多对比效果。另外不要试图用Freemarker直接渲染.xlsx文件这个坑我踩过文件直接损坏排查了半天才发现是二进制结构被破坏。正确的做法是Freemarker渲染文本内容POI负责文件生成和图片插入两者分工明确。最后分享一个小技巧如果图片总是对不齐可以先把图片插入到一个空白单元格里用Excel手动调整好位置和大小然后记录下锚点参数再把这些参数写到代码里。这样比盲调参数快得多。这套方案后续还可以扩展比如支持图片水印、支持多Sheet导出、支持导出时自动生成缩略图。核心思路不变都是Freemarker管模板、POI管文件、图片单独处理。把这套流程跑通一次以后遇到类似需求直接改模板和参数就行效率提升非常明显。
1. 为什么“带图片的Excel导出”是个高频刚需做过企业级后台系统的人大概率都遇到过这种需求运营要导出一份商品清单每行商品除了名称、价格、库存还得把商品主图塞进单元格里或者HR要导出一份员工花名册每行带一张一寸照片再或者质检部门要导出一份巡检记录每条记录附一张现场照片。这类需求听起来简单真动手做的时候坑一个接一个。纯文本的Excel导出用POI的SXSSFWorkbook或者XSSFWorkbook就能搞定代码写起来也顺手。但一旦涉及图片事情就变得微妙了图片怎么锚定到指定单元格图片尺寸怎么控制行高列宽怎么配合图片多了内存会不会炸导出几万行带图的数据服务器扛不扛得住这些问题不解决导出的文件要么图片错位要么直接OOM。而Freemarker在这里扮演的角色是把“Excel模板”这件事做得更优雅。传统做法是用Java代码一行一行画表格、设样式、插图片代码又臭又长改个表头都得重新编译。用Freemarker做模板引擎可以把Excel的样式、表头、固定文案抽离成模板文件Java只负责往模板里灌数据图片的插入逻辑单独处理。这样业务人员改表头、调样式不用碰Java代码维护成本直接降一个量级。这套方案适合谁适合正在做后台管理系统、报表系统、数据导出功能的开发者尤其是那些被“Excel导出带图片”折磨过一轮的人。不管你用的是Spring Boot还是传统SSM只要项目里引入了POI和Freemarker这套思路都能直接抄。下面我会从整体设计、核心细节、实操过程到踩坑排查把这件事掰开揉碎讲清楚。2. 整体方案设计与技术选型拆解2.1 为什么是Freemarker加POI的组合先说说为什么不用纯POI硬编码。纯POI写Excel样式和内容耦合在Java代码里一个稍微复杂的报表代码轻松上千行。表头改一个字得找到对应代码位置改完重新打包。而Freemarker的模板文件是纯文本的改完直接生效甚至可以让运营自己维护模板。那为什么不用EasyExcelEasyExcel确实在读写大文件上有优势但它在“模板填充图片插入”这个组合场景下灵活度不如POI直接操作。EasyExcel的图片支持相对有限尤其是图片锚定到具体单元格、控制图片与单元格边距这些细节POI的DrawingPatriarch和ClientAnchor给的控制力更强。所以这套方案的定位很清晰Freemarker负责模板渲染表头、样式、固定文案、数据占位POI负责最终的文件生成和图片插入。两者各司其职模板归模板图片归图片。2.2 模板文件的设计思路模板文件本质上是一个“半成品Excel”。我的做法是先用Excel软件手工做一个样板文件把表头、列宽、行高、字体、边框、背景色全部调好然后把需要动态填充的地方用Freemarker的占位符替换掉最后把文件后缀改成.ftl。比如一个商品清单模板表头是固定的数据行是循环的模板里大概长这样#list items as item ${item.name} | ${item.price} | ${item.stock} | [图片占位] /#list但这里有个关键问题Excel的.xlsx文件本质是个ZIP压缩包里面是一堆XML。Freemarker直接渲染.xlsx文件会破坏其二进制结构。所以正确的做法是模板文件用.xls格式老版Excel本质是二进制流Freemarker可以处理或者用POI先读取模板再填充。我实测下来更稳的方案是用POI读取.xlsx模板文件然后用Freemarker渲染一个“数据模型”Java代码根据模型往Workbook里填数据。这样既保留了模板的样式又避免了直接渲染二进制文件的坑。2.3 图片插入的核心机制POI插入图片的核心API是DrawingPatriarch和ClientAnchor。简单说DrawingPatriarch是画布ClientAnchor是锚点用来指定图片放在哪个单元格、跨几行几列、偏移多少。关键参数有四个col1、row1、col2、row2。前两个是起始单元格的列和行后两个是结束单元格的列和行。如果col1和col2相同、row1和row2相同图片就锚定在一个单元格内。如果不同图片就跨多个单元格。图片的尺寸控制有两种方式一是通过ClientAnchor的偏移量控制二是通过Picture.resize()方法控制。我一般用后者因为更直观。resize()接受两个参数缩放比例和单位。比如resize(0.5, Units.EMU_PER_PIXEL)表示按像素单位缩放50%。2.4 内存与性能的权衡带图片的Excel导出最大的性能瓶颈在内存。每张图片都要加载到内存、转换成POI的PictureData、再写入Workbook。如果一次导出几千行、每行一张图内存直接飙升。解决方案有两个方向一是用SXSSFWorkbook做流式写入但SXSSFWorkbook对图片的支持有限图片仍然会驻留内存二是控制图片数量和大小比如限制单次导出最多500行带图数据或者对图片做压缩后再插入。我的经验是如果单次导出超过1000张图片建议拆分成多个文件或者改用异步导出下载链接的方式。同步导出1000张图响应时间基本在10秒以上用户体验很差。3. 核心细节解析与实操要点3.1 模板文件的制作与占位符规范制作模板文件时有几个细节必须注意。第一占位符的命名要统一比如统一用${item.xxx}的格式避免${name}和${item.name}混用否则Freemarker渲染时会报错。第二占位符所在单元格的样式要提前设好因为POI填充数据时不会自动继承样式需要手动复制样式。第三图片占位单元格要留足空间。我一般会把图片所在列的列宽设为20左右行高设为80左右这样插入的图片不会挤压变形。具体数值可以根据图片的实际尺寸调整公式是列宽字符数× 7 ≈ 像素宽度行高磅值× 1.33 ≈ 像素高度。第四模板文件不要用合并单元格做数据行。合并单元格在POI里处理起来很麻烦尤其是循环填充时容易错位。如果表头需要合并只在表头区域合并数据行保持单单元格。3.2 Freemarker数据模型的构建Freemarker渲染需要一个数据模型通常用MapString, Object来构建。对于列表数据用ListMapString, Object。图片数据比较特殊不能直接塞进模型里让Freemarker渲染因为Freemarker不认识二进制图片。我的做法是数据模型里只放图片的标识比如图片路径或图片IDJava代码在填充完文本数据后再根据标识去加载图片并插入到对应单元格。这样Freemarker只负责文本渲染图片插入完全由POI控制职责清晰。数据模型的结构大概是这样MapString, Object model new HashMap(); model.put(title, 商品清单); model.put(exportDate, 2024-01-15); ListMapString, Object items new ArrayList(); for (Product p : productList) { MapString, Object item new HashMap(); item.put(name, p.getName()); item.put(price, p.getPrice()); item.put(stock, p.getStock()); item.put(imageId, p.getImageId()); // 图片标识不直接放图片 items.add(item); } model.put(items, items);3.3 图片加载与格式处理POI支持多种图片格式PNG、JPEG、BMP、GIF等。但实际用下来PNG和JPEG最稳其他格式在某些Excel版本里可能显示异常。图片加载时我一般用ImageIO.read()读取然后转成ByteArrayOutputStream再通过workbook.addPicture()添加。这里有个坑图片的宽高比要保持。如果原图是长方形直接塞进正方形单元格会变形。我的做法是先计算原图的宽高比然后根据单元格的可用空间按比例缩放。比如单元格可用宽度是100像素、高度是80像素原图是200×100宽高比2:1那就按宽度100像素缩放高度变成50像素居中显示。图片格式转换的代码大概是这样BufferedImage bufferedImage ImageIO.read(new File(imagePath)); int originalWidth bufferedImage.getWidth(); int originalHeight bufferedImage.getHeight(); double ratio (double) originalWidth / originalHeight; int targetWidth 100; int targetHeight (int) (targetWidth / ratio); if (targetHeight 80) { targetHeight 80; targetWidth (int) (targetHeight * ratio); } ByteArrayOutputStream baos new ByteArrayOutputStream(); ImageIO.write(bufferedImage, png, baos); byte[] imageBytes baos.toByteArray(); int pictureIdx workbook.addPicture(imageBytes, Workbook.PICTURE_TYPE_PNG);3.4 图片锚定与单元格对齐图片锚定是整个过程里最考验细节的地方。ClientAnchor的构造函数有多个重载我一般用new XSSFClientAnchor(dx1, dy1, dx2, dy2, col1, row1, col2, row2)。其中dx1、dy1是起始单元格内的偏移量dx2、dy2是结束单元格内的偏移量单位是EMUEnglish Metric Unit1像素约等于9525 EMU。如果想让图片完全填充一个单元格col1和col2相同、row1和row2相同dx1和dy1设为0dx2和dy2设为单元格的宽高对应的EMU值。但这样图片会拉伸变形所以更好的做法是保持图片原始比例通过偏移量让图片在单元格内居中。居中的计算逻辑是dx1 (cellWidth - imageWidth) / 2dy1 (cellHeight - imageHeight) / 2。这样图片就会在单元格内水平垂直居中。3.5 样式复制的正确姿势POI填充数据时新创建的单元格默认没有样式。如果模板里已经设好了样式需要用CellStyle复制过来。但CellStyle不能直接赋值必须通过workbook.createCellStyle()创建新样式然后逐个属性复制。我一般写一个工具方法把模板单元格的样式复制到目标单元格public static void copyCellStyle(CellStyle source, CellStyle target) { target.setAlignment(source.getAlignment()); target.setVerticalAlignment(source.getVerticalAlignment()); target.setBorderBottom(source.getBorderBottom()); target.setBorderLeft(source.getBorderLeft()); target.setBorderRight(source.getBorderRight()); target.setBorderTop(source.getBorderTop()); target.setBottomBorderColor(source.getBottomBorderColor()); target.setFillBackgroundColor(source.getFillBackgroundColor()); target.setFillForegroundColor(source.getFillForegroundColor()); target.setFillPattern(source.getFillPattern()); target.setFont(source.getFont()); // 其他属性按需复制 }注意CellStyle的数量在Excel里是有限制的最多64000个如果每行都创建新样式很容易超限。正确的做法是复用样式对象比如表头样式创建一个数据行样式创建一个所有行共用。4. 完整实操流程与核心环节实现4.1 环境准备与依赖引入先确认项目里引入了POI和Freemarker的依赖。Maven项目的话pom.xml里加这几项dependency groupIdorg.apache.poi/groupId artifactIdpoi/artifactId version5.2.3/version /dependency dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.3/version /dependency dependency groupIdorg.freemarker/groupId artifactIdfreemarker/artifactId version2.3.32/version /dependencyPOI 5.x版本对.xlsx的支持更完善建议用5.0以上。Freemarker 2.3.32是稳定版兼容性好。4.2 模板文件的制作步骤第一步用Excel软件新建一个.xlsx文件设计好表头、列宽、行高、字体、边框。第二步把需要动态填充的单元格内容替换成Freemarker占位符比如${title}、${exportDate}。第三步数据行用#list items as item包裹循环体内的单元格填${item.name}这类占位符。第四步保存文件把后缀改成.ftl放到项目的resources/templates目录下。这里有个细节模板文件里的占位符不要放在合并单元格里否则Freemarker渲染后POI读取时容易出错。如果表头必须合并合并区域只放静态文本不放占位符。4.3 Java代码的完整实现整个导出流程分五步加载模板、渲染数据、填充文本、插入图片、输出文件。public void exportExcelWithImages(HttpServletResponse response, ListProduct productList) throws Exception { // 1. 加载模板 Configuration cfg new Configuration(Configuration.VERSION_2_3_32); cfg.setClassLoaderForTemplateLoading(this.getClass().getClassLoader(), templates); cfg.setDefaultEncoding(UTF-8); Template template cfg.getTemplate(product_template.ftl); // 2. 构建数据模型 MapString, Object model new HashMap(); model.put(title, 商品清单); model.put(exportDate, new SimpleDateFormat(yyyy-MM-dd).format(new Date())); ListMapString, Object items new ArrayList(); for (int i 0; i productList.size(); i) { Product p productList.get(i); MapString, Object item new HashMap(); item.put(name, p.getName()); item.put(price, p.getPrice()); item.put(stock, p.getStock()); item.put(imageId, p.getImageId()); item.put(rowIndex, i); items.add(item); } model.put(items, items); // 3. 渲染模板到临时文件 File tempFile File.createTempFile(export_, .xlsx); try (Writer writer new FileWriter(tempFile)) { template.process(model, writer); } // 4. 用POI读取渲染后的文件 try (FileInputStream fis new FileInputStream(tempFile); XSSFWorkbook workbook new XSSFWorkbook(fis)) { XSSFSheet sheet workbook.getSheetAt(0); // 5. 插入图片 XSSFDrawing drawing sheet.createDrawingPatriarch(); int imageColIndex 3; // 图片所在列 int startRow 1; // 数据起始行 for (int i 0; i productList.size(); i) { Product p productList.get(i); if (p.getImagePath() null) continue; // 加载图片 BufferedImage bufferedImage ImageIO.read(new File(p.getImagePath())); ByteArrayOutputStream baos new ByteArrayOutputStream(); ImageIO.write(bufferedImage, png, baos); byte[] imageBytes baos.toByteArray(); int pictureIdx workbook.addPicture(imageBytes, Workbook.PICTURE_TYPE_PNG); // 创建锚点 XSSFClientAnchor anchor new XSSFClientAnchor( 0, 0, 0, 0, imageColIndex, startRow i, imageColIndex 1, startRow i 1 ); anchor.setAnchorType(ClientAnchor.AnchorType.MOVE_AND_RESIZE); // 插入图片 XSSFPicture picture drawing.createPicture(anchor, pictureIdx); picture.resize(0.8); // 缩放80% } // 6. 输出到响应流 response.setContentType(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet); response.setHeader(Content-Disposition, attachment; filenameexport.xlsx); workbook.write(response.getOutputStream()); } finally { tempFile.delete(); } }4.4 图片尺寸与单元格的精确匹配上面代码里用了picture.resize(0.8)这是最简单的缩放方式。但实际项目中图片尺寸往往需要精确控制。我的做法是先获取单元格的宽高像素再根据图片原始比例计算缩放后的尺寸最后通过ClientAnchor的偏移量实现居中。获取单元格宽高的代码int cellWidth (int) (sheet.getColumnWidthInPixels(imageColIndex)); int cellHeight (int) (sheet.getRow(startRow i).getHeightInPoints() * 1.33);然后计算图片缩放后的尺寸double ratio (double) originalWidth / originalHeight; int targetWidth cellWidth - 10; // 留10像素边距 int targetHeight (int) (targetWidth / ratio); if (targetHeight cellHeight - 10) { targetHeight cellHeight - 10; targetWidth (int) (targetHeight * ratio); }最后设置锚点偏移量让图片居中int dx1 (cellWidth - targetWidth) / 2 * 9525; int dy1 (cellHeight - targetHeight) / 2 * 9525; int dx2 dx1 targetWidth * 9525; int dy2 dy1 targetHeight * 9525; XSSFClientAnchor anchor new XSSFClientAnchor(dx1, dy1, dx2, dy2, col, row, col, row);这样图片就会精确地居中显示在单元格内不会变形也不会溢出。4.5 大数据量导出的分批处理如果一次导出几千行带图数据内存和响应时间都是问题。我的处理策略是分批查询、分批写入、最后合并。具体做法是每500行一批每批生成一个临时Workbook最后把所有临时Workbook的内容合并到一个主Workbook里。但合并Workbook在POI里比较麻烦尤其是图片的合并。更简单的做法是限制单次导出的图片数量比如最多500张超过的部分提示用户分批导出。或者用异步导出后台生成文件后存到文件服务器用户通过下载链接获取。我实测下来500行带图数据同步导出耗时约3-5秒内存占用约200MB。1000行的话耗时翻倍内存接近400MB。所以500行是个比较安全的阈值。5. 常见问题与排查技巧实录5.1 图片错位、偏移、不显示这是最常见的问题原因通常有三个。第一锚点的col1、row1、col2、row2设置错误。比如图片应该在第3列第5行结果写成了第2列第4行。排查方法是打印锚点参数和实际单元格位置对比。第二图片的resize()比例过大导致图片溢出单元格。排查方法是把resize()参数调小比如从1.0改成0.5看是否正常显示。第三模板文件里的行高列宽和代码里设置的不一致。比如模板里行高是60磅代码里按80磅计算图片就会偏上。排查方法是统一用模板里的行高列宽不要代码里再改。5.2 内存溢出与性能瓶颈带图导出最容易OOM。排查思路是先看图片数量再看图片大小。如果单张图片超过1MB100张就是100MB加上Workbook本身的开销很容易超过JVM默认堆内存。解决方案有三个一是压缩图片插入前用ImageIO把图片质量降到0.7左右二是限制图片尺寸比如最大宽度不超过200像素三是增大JVM堆内存启动参数加-Xmx1024m。我一般会写一个图片压缩工具方法public static byte[] compressImage(BufferedImage image, float quality) throws IOException { ImageWriter writer ImageIO.getImageWritersByFormatName(jpeg).next(); ImageWriteParam param writer.getDefaultWriteParam(); param.setCompressionMode(ImageWriteParam.MODE_EXPLICIT); param.setCompressionQuality(quality); ByteArrayOutputStream baos new ByteArrayOutputStream(); try (ImageOutputStream ios ImageIO.createImageOutputStream(baos)) { writer.setOutput(ios); writer.write(null, new IIOImage(image, null, null), param); } writer.dispose(); return baos.toByteArray(); }5.3 模板渲染后文件损坏这个问题通常是因为Freemarker直接渲染了.xlsx文件。.xlsx是ZIP格式Freemarker按文本处理会破坏其二进制结构。正确的做法是模板文件用.xls格式或者用POI读取模板后再填充数据不要直接用Freemarker渲染.xlsx。如果非要用Freemarker渲染可以把模板文件改成.xml格式Excel 2003 XML这种格式是纯文本Freemarker可以安全渲染。但.xml格式的Excel在样式和图片支持上不如.xlsx所以不推荐。5.4 中文乱码与编码问题中文乱码通常出现在两个地方一是Freemarker模板文件的编码二是响应流的编码。模板文件保存时要用UTF-8编码Freemarker配置里设置cfg.setDefaultEncoding(UTF-8)。响应流设置response.setCharacterEncoding(UTF-8)并且Content-Disposition里的文件名要用URLEncoder.encode()编码。String fileName URLEncoder.encode(商品清单.xlsx, UTF-8); response.setHeader(Content-Disposition, attachment; filename fileName);5.5 常见问题速查表问题现象可能原因排查方法解决方案图片不显示锚点参数错误打印锚点参数对比单元格位置修正col1/row1/col2/row2图片变形宽高比未保持检查resize比例按原始比例计算缩放图片错位行高列宽不一致对比模板和代码设置统一使用模板设置内存溢出图片过大过多查看图片数量和大小压缩图片、限制数量文件损坏直接渲染xlsx检查模板文件格式改用xls或POI填充中文乱码编码不一致检查模板和响应编码统一UTF-8样式丢失未复制样式检查CellStyle复制逻辑复用样式对象提示如果导出后发现图片位置总是差一点点大概率是EMU单位换算的问题。1像素9525 EMU1磅12700 EMU换算时注意单位统一。5.6 几个我踩过的坑第一个坑模板文件里的占位符被Excel自动转义。比如${item.name}被Excel识别成公式保存后变成了${item.name}的转义形式。解决办法是在占位符前面加一个单引号或者把单元格格式设为“文本”。第二个坑图片插入后文件体积暴涨。一张1MB的图片插入Excel后文件体积可能变成3MB。原因是POI会把图片重新编码而且.xlsx本身是ZIP压缩图片压缩率不高。解决办法是插入前先压缩图片或者用SXSSFWorkbook的setCompressTempFiles(true)。第三个坑多线程导出时Workbook线程不安全。POI的Workbook不是线程安全的多个线程同时操作同一个Workbook会出问题。解决办法是每个线程创建独立的Workbook或者用线程池加锁。第四个坑图片路径包含中文或空格。ImageIO.read(new File(path))在路径包含中文时可能返回null。解决办法是用URLDecoder.decode()解码路径或者用ClassLoader.getResourceAsStream()读取。6. 进阶优化与扩展思路6.1 图片异步加载与缓存如果图片来自远程URL同步加载会拖慢导出速度。我的做法是用线程池异步加载图片加载完成后缓存到本地临时目录导出时直接从缓存读取。这样第二次导出同一批数据时速度会快很多。ExecutorService executor Executors.newFixedThreadPool(10); MapString, Futurebyte[] futures new HashMap(); for (Product p : productList) { futures.put(p.getImageId(), executor.submit(() - downloadImage(p.getImageUrl()))); } // 导出时从future获取 byte[] imageBytes futures.get(p.getImageId()).get();6.2 模板的动态列与条件样式Freemarker模板支持条件判断可以根据数据动态决定是否显示某一列或者根据数值大小设置不同的样式。比如库存小于10的行标红#list items as item #if item.stock 10 #assign rowStyle red #else #assign rowStyle normal /#if ... /#list但POI的样式设置需要在Java代码里做Freemarker只能控制内容。所以更实际的做法是Freemarker渲染时给需要特殊样式的单元格加一个标记Java代码根据标记设置样式。6.3 导出进度与用户体验大数据量导出时用户看不到进度体验很差。我的做法是前端发起导出请求后后端返回一个任务ID前端轮询任务状态导出完成后返回下载链接。这样用户可以看到“正在导出已完成30%”这样的提示。任务状态可以用Redis或内存Map存储导出线程每完成一批就更新进度。导出完成后把文件存到临时目录返回下载URL。6.4 兼容不同Excel版本.xlsx是Excel 2007以后的格式.xls是Excel 2003的格式。如果用户可能用老版本Excel打开建议同时提供两种格式。POI的HSSFWorkbook对应.xlsXSSFWorkbook对应.xlsx。代码上可以抽象一个接口根据文件后缀选择不同的Workbook实现。但.xls对图片的支持不如.xlsx图片数量多了容易出问题。所以我的建议是默认导出.xlsx如果用户明确要求.xls再单独处理。7. 一些个人经验与建议这套方案我在几个项目里都用过从商品清单到员工花名册从巡检记录到质检报告基本都能覆盖。最大的感受是图片插入这件事细节决定成败。锚点参数差一个像素图片就偏了行高列宽差一磅图片就变形了。所以调试的时候一定要耐心多打印参数多对比效果。另外不要试图用Freemarker直接渲染.xlsx文件这个坑我踩过文件直接损坏排查了半天才发现是二进制结构被破坏。正确的做法是Freemarker渲染文本内容POI负责文件生成和图片插入两者分工明确。最后分享一个小技巧如果图片总是对不齐可以先把图片插入到一个空白单元格里用Excel手动调整好位置和大小然后记录下锚点参数再把这些参数写到代码里。这样比盲调参数快得多。这套方案后续还可以扩展比如支持图片水印、支持多Sheet导出、支持导出时自动生成缩略图。核心思路不变都是Freemarker管模板、POI管文件、图片单独处理。把这套流程跑通一次以后遇到类似需求直接改模板和参数就行效率提升非常明显。
