Java读取WPS Excel嵌入图片：深入OOXML底层解析与POI扩展实践

1. 项目缘起：一个被“图片”卡住的Excel导入需求

最近在做一个后台管理系统的数据导入模块，需求方给过来的Excel模板里，有一个“产品主图”列，里面不是图片的URL链接，而是直接嵌入了WPS编辑生成的图片。开发小哥跑过来跟我说，用Apache POI的XSSFWorkbook读这个文件，其他文本数据都正常，唯独图片读不出来，getAllPictures()返回的列表是空的，但用微软的Office打开文件，图片明明就在那里。

这其实是个挺典型的场景。很多业务人员习惯用WPS Office进行日常办公，他们在制作数据模板时，会直接使用WPS的“插入图片”功能。从用户视角看，这和在Excel里操作没区别。但从技术实现看，WPS在处理嵌入式对象（尤其是OLE对象）时，其底层存储结构和序列化方式，与微软Office存在一些微妙的差异。当Java程序使用标准的POI库去解析时，如果只处理标准的<x:drawing>标签和对应的v:shape、v:imagedata关系，很可能就会漏掉WPS特有的存储部分，导致图片“消失”。

所以，这个项目的核心目标很明确：实现一个Java读取Excel文件的组件，不仅要能读取常规的单元格数据，还必须完整支持读取由WPS嵌入的图片。这意味着我们不能只满足于标准POI API，必须深入文件内部（OOXML），去适配和解析WPS可能采用的存储格式。

2. 技术选型与底层原理：为什么是POI，以及它的局限

要实现这个需求，Apache POI几乎是Java生态下的唯一选择。它是一个功能强大的开源库，用于读写Microsoft Office格式文件，如Excel、Word和PowerPoint。对于Excel，它主要提供两种模型：

• HSSF (Horrible SpreadSheet Format)： 用于处理老旧的.xls格式（Excel 97-2003）。
• XSSF (XML SpreadSheet Format)： 用于处理现代的.xlsx格式（Excel 2007及以后），基于OOXML（Office Open XML）标准。

我们的场景显然是.xlsx文件，所以核心是XSSFWorkbook。一个.xlsx文件本质上是一个ZIP压缩包，里面包含了描述工作表、样式、关系的多个XML文件以及二进制资源（如图片）。当你用POI读取一个包含图片的Excel时，其标准流程是：

1. POI解压ZIP包。
2. 解析xl/drawings/drawingX.xml文件，找到所有绘图对象（形状）的定义。
3. 根据形状中<a:blip>元素的r:embed属性，找到对应的关系ID（例如rId1）。
4. 去xl/drawings/_rels/drawingX.xml.rels关系文件中，根据ID找到对应的图片资源路径（例如../media/image1.png）。
5. 最后从xl/media/目录下读取对应的图片二进制数据。

那么，问题出在哪里？POI的实现严格遵循了微软定义的OOXML标准。然而，WPS作为另一个实现者，在追求高度兼容的同时，有时会采用一些“扩展”或“变通”的存储方式。特别是在处理早期版本WPS或某些特定操作（如从其他文档复制粘贴带格式内容）生成的OLE对象时，它可能：

• 将图片数据以不同的MIME类型或格式进行封装。
• 使用非标准的Relationship类型或ID引用方式。
• 甚至将图片数据直接以Base64编码的形式内联在drawingX.xml中，而非作为独立媒体文件存放。

标准的XSSFWorkbook.getAllPictures()方法，其内部逻辑是基于一套预定义的、针对微软Office格式的解析器。当它遇到WPS的这些“非标”存储时，解析链就可能中断，无法正确识别和收集图片资源。

因此，我们的解决方案不能停留在Workbook的层面，必须下沉到OPCPackage（代表整个OOXML包）和PackagePart（代表包内的各个部分，如XML文件、图片文件）的层级，进行更底层的、定制化的扫描和解析。

3. 核心实现：深入OOXML包，捕获“隐藏”的图片

我们的核心思路是：绕过XSSFWorkbook提供的图片获取API，直接操作底层的OPCPackage对象，遍历包内所有部件（Part），通过其内容类型（ContentType）和关系（Relationships）来识别和提取所有可能的图片数据。

下面是一个增强版的ExcelWithWPSImageReader工具类的核心代码实现：

import org.apache.poi.openxml4j.opc.OPCPackage; import org.apache.poi.openxml4j.opc.PackagePart; import org.apache.poi.openxml4j.opc.PackageRelationship; import org.apache.poi.openxml4j.opc.PackageRelationshipCollection; import org.apache.poi.ss.usermodel.*; import org.apache.poi.xssf.usermodel.XSSFWorkbook; import org.apache.poi.xssf.usermodel.XSSFDrawing; import org.apache.poi.xssf.usermodel.XSSFPicture; import org.apache.poi.xssf.usermodel.XSSFShape; import org.apache.poi.xssf.usermodel.XSSFClientAnchor; import javax.imageio.ImageIO; import java.awt.image.BufferedImage; import java.io.*; import java.util.*; import java.util.regex.Pattern; /** * 增强版Excel读取器，支持读取WPS嵌入的图片 */ public class ExcelWithWPSImageReader { /** * 读取Excel文件，返回工作表数据及所有图片信息 * @param filePath Excel文件路径 * @return Map， key为工作表索引， value为该表的数据和图片列表 */ public static Map<Integer, SheetDataWithImages> readExcelWithImages(String filePath) throws Exception { Map<Integer, SheetDataWithImages> result = new HashMap<>(); // 1. 使用OPCPackage打开文件，保留底层包引用 OPCPackage pkg = OPCPackage.open(new File(filePath)); Workbook workbook = new XSSFWorkbook(pkg); try { int numberOfSheets = workbook.getNumberOfSheets(); for (int sheetIndex = 0; sheetIndex < numberOfSheets; sheetIndex++) { Sheet sheet = workbook.getSheetAt(sheetIndex); SheetDataWithImages sheetData = new SheetDataWithImages(); sheetData.setSheetName(sheet.getSheetName()); // 2. 读取单元格数据（标准POI方式） readSheetData(sheet, sheetData); // 3. 关键步骤：提取图片（增强方法） extractAllImages(pkg, sheet, sheetIndex, sheetData); result.put(sheetIndex, sheetData); } } finally { // 注意：关闭workbook也会关闭底层的pkg，无需重复关闭 workbook.close(); } return result; } /** * 读取工作表单元格数据 */ private static void readSheetData(Sheet sheet, SheetDataWithImages sheetData) { List<List<Object>> data = new ArrayList<>(); for (Row row : sheet) { List<Object> rowData = new ArrayList<>(); for (Cell cell : row) { rowData.add(getCellValue(cell)); } data.add(rowData); } sheetData.setCellData(data); } /** * 增强的图片提取方法：结合标准API和底层扫描 */ private static void extractAllImages(OPCPackage pkg, Sheet sheet, int sheetIndex, SheetDataWithImages sheetData) throws Exception { List<ExcelImage> images = new ArrayList<>(); // 3.1 方法A：使用标准POI API获取已知图片（对标准Excel有效） if (sheet instanceof org.apache.poi.xssf.usermodel.XSSFSheet) { XSSFSheet xssfSheet = (XSSFSheet) sheet; List<XSSFShape> shapes = xssfSheet.getDrawingPatriarch().getShapes(); for (XSSFShape shape : shapes) { if (shape instanceof XSSFPicture) { XSSFPicture pic = (XSSFPicture) shape; XSSFClientAnchor anchor = (XSSFClientAnchor) pic.getAnchor(); byte[] pictureData = pic.getPictureData().getData(); String format = pic.getPictureData().getSuggestFileExtension(); ExcelImage img = new ExcelImage(); img.setRowIndex(anchor.getRow1()); img.setColIndex(anchor.getCol1()); img.setImageData(pictureData); img.setFormat(format); img.setSource("POI_Standard_API"); images.add(img); } } } // 3.2 方法B：底层扫描OOXML包，查找所有可能的图片部件（关键！用于捕获WPS图片） // 定义常见的图片内容类型 Set<String> imageContentTypes = new HashSet<>(Arrays.asList( "image/png", "image/jpeg", "image/jpg", "image/gif", "image/bmp", "application/vnd.openxmlformats-officedocument.drawingml.picture", "application/vnd.openxmlformats-officedocument.oleObject" // 特别注意OLE对象类型 )); // 遍历包中的所有部件 for (PackagePart part : pkg.getParts()) { String contentType = part.getContentType(); // 判断是否为图片或可能的OLE对象（WPS可能将图片包装在OLE中） if (isImagePart(part, imageContentTypes)) { try (InputStream is = part.getInputStream()) { byte[] data = readAllBytes(is); if (data != null && data.length > 0) { // 尝试从部件名称或关系中推断其所属工作表及位置（这是一个难点） // 这里简化处理：先收集所有图片数据。实际项目中可能需要解析drawingXML来关联位置。 ExcelImage img = new ExcelImage(); img.setImageData(data); img.setFormat(guessImageFormat(contentType, part.getPartName().getName())); img.setSource("OOXML_Package_Scan"); img.setPartName(part.getPartName().toString()); // 关联位置信息（需要更复杂的解析，此处为示例） associateImageWithCell(part, pkg, sheetIndex, img); images.add(img); } } } } // 3.3 去重：基于图片数据的MD5或SHA哈希，避免同一图片因不同引用被多次添加 images = deduplicateImages(images); sheetData.setImages(images); } /** * 判断一个PackagePart是否为图片部分 * 增加了对WPS可能存储方式的判断 */ private static boolean isImagePart(PackagePart part, Set<String> imageContentTypes) { String contentType = part.getContentType(); String partName = part.getPartName().getName().toLowerCase(); // 1. 标准图片内容类型 if (imageContentTypes.contains(contentType)) { return true; } // 2. 通过部件路径名判断（常见于/media/目录） if (partName.contains("/media/") && (partName.endsWith(".png") || partName.endsWith(".jpg") || partName.endsWith(".jpeg") || partName.endsWith(".gif"))) { return true; } // 3. 针对WPS：处理可能是OLE包装的图片 // WPS有时会将图片存储为OLE对象，但其内容实为图片数据 if ("application/vnd.openxmlformats-officedocument.oleObject".equals(contentType)) { // 可以通过检查部件名称或尝试解析前几个字节的魔数来进一步确认 // 例如，检查partName是否包含“image”字样，或读取流的前几个字节判断是否为PNG/JPEG return mayContainImageData(part); } return false; } /** * 尝试判断一个OLE对象部件是否包含图片数据 */ private static boolean mayContainImageData(PackagePart part) { // 简易实现：读取前8个字节，检查常见图片文件的魔数（Magic Number） try (InputStream is = part.getInputStream()) { byte[] header = new byte[8]; if (is.read(header) == 8) { // PNG: 89 50 4E 47 0D 0A 1A 0A if (header[0] == (byte)0x89 && header[1] == 'P' && header[2] == 'N' && header[3] == 'G') { return true; } // JPEG: FF D8 FF if (header[0] == (byte)0xFF && header[1] == (byte)0xD8 && header[2] == (byte)0xFF) { return true; } } } catch (Exception e) { // 忽略读取错误，返回false } return false; } /** * 尝试将图片与单元格关联（简化示例，实际逻辑复杂） * 需要解析 drawingX.xml 和其关系文件，建立“图片资源”与“单元格锚点”的映射。 */ private static void associateImageWithCell(PackagePart part, OPCPackage pkg, int sheetIndex, ExcelImage img) { // 这是一个复杂且易出错的部分。 // 基本思路： // 1. 找到当前工作表对应的 /xl/drawings/drawing{sheetIndex+1}.xml // 2. 解析该XML，找到所有 <xdr:twoCellAnchor> 元素，里面包含了图片引用(r:embed)和位置坐标(col, row)。 // 3. 根据图片引用ID，在 /xl/drawings/_rels/drawing{sheetIndex+1}.xml.rels 中找到对应的目标URI。 // 4. 将目标URI与当前图片部件的PartName进行匹配。 // 5. 如果匹配成功，则将坐标设置到img对象中。 // 由于代码较长，此处仅示意。在实际项目中，你可能需要借助XPath或DOM解析XML。 // img.setRowIndex(inferredRow); // img.setColIndex(inferredCol); img.setRowIndex(-1); // -1 表示位置未知 img.setColIndex(-1); } /** * 根据内容类型或文件名猜测图片格式 */ private static String guessImageFormat(String contentType, String fileName) { if (contentType.contains("png")) return "png"; if (contentType.contains("jpeg") || contentType.contains("jpg")) return "jpg"; if (contentType.contains("gif")) return "gif"; if (contentType.contains("bmp")) return "bmp"; if (fileName.endsWith(".png")) return "png"; if (fileName.endsWith(".jpg") || fileName.endsWith(".jpeg")) return "jpg"; if (fileName.endsWith(".gif")) return "gif"; if (fileName.endsWith(".bmp")) return "bmp"; return "unknown"; } /** * 基于图片二进制数据去重 */ private static List<ExcelImage> deduplicateImages(List<ExcelImage> images) { Map<String, ExcelImage> map = new LinkedHashMap<>(); // 用LinkedHashMap保持顺序 for (ExcelImage img : images) { String key = calculateHash(img.getImageData()); // 例如用MD5 if (!map.containsKey(key)) { map.put(key, img); } else { // 如果已存在，优先保留有位置信息的那个 ExcelImage existing = map.get(key); if (existing.getRowIndex() == -1 && img.getRowIndex() != -1) { map.put(key, img); } } } return new ArrayList<>(map.values()); } private static String calculateHash(byte[] data) { // 简化的哈希计算，实际应用请使用MessageDigest生成MD5或SHA-1 return Integer.toHexString(Arrays.hashCode(data)); } private static byte[] readAllBytes(InputStream is) throws IOException { ByteArrayOutputStream buffer = new ByteArrayOutputStream(); byte[] data = new byte[4096]; int nRead; while ((nRead = is.read(data, 0, data.length)) != -1) { buffer.write(data, 0, nRead); } return buffer.toByteArray(); } private static Object getCellValue(Cell cell) { // ... 标准的单元格值获取逻辑，根据CellType处理字符串、数字、公式等 ... switch (cell.getCellType()) { case STRING: return cell.getStringCellValue(); case NUMERIC: if (DateUtil.isCellDateFormatted(cell)) { return cell.getDateCellValue(); } return cell.getNumericCellValue(); case BOOLEAN: return cell.getBooleanCellValue(); case FORMULA: return cell.getCellFormula(); case BLANK: return ""; default: return null; } } /** * 封装工作表数据及图片 */ public static class SheetDataWithImages { private String sheetName; private List<List<Object>> cellData; private List<ExcelImage> images; // getters and setters ... } /** * 封装图片信息 */ public static class ExcelImage { private int rowIndex; // 图片左上角所在行（0-based） private int colIndex; // 图片左上角所在列（0-based） private byte[] imageData; private String format; // png, jpg等 private String source; // 标识来源，用于调试 private String partName; // OOXML中的部件名 // getters and setters ... } }

4. 关键难点与避坑指南：不只是读出来，还要放对地方

实现“读取”只是第一步。在实际业务中，我们通常需要知道这张图片属于哪个单元格，以便将图片与对应的业务数据（如产品ID、名称）关联起来。这正是整个需求中最棘手的地方，也是很多开源方案语焉不详的部分。

难点一：位置信息（Anchor）的丢失WPS存储的图片，其位置锚点信息（XSSFClientAnchor， 包含起始行、列、结束行、列以及偏移像素）可能在转换或存储过程中变得不标准，或者POI无法正确解析WPS生成的对应XML结构。这导致即使你通过底层扫描拿到了图片二进制数据，也无法确定它该放在表格的哪个位置。

避坑经验：不要完全依赖POI的XSSFPicture.getAnchor()。在底层扫描到图片后，必须尝试主动去解析当前工作表对应的drawingX.xml文件。你需要手动处理XML，寻找<xdr:twoCellAnchor>或<xdr:oneCellAnchor>元素，并解析其中的<xdr:from>子元素来获取行(row)、列(col)索引。这个过程非常繁琐，且XML命名空间和结构可能因WPS版本而异，需要强大的容错处理。

难点二：图片与位置的关联关系断裂在OOXML中，图片文件（如/xl/media/image1.png）与它在工作表上的位置形状是分开存储的，通过关系（Relationship）文件链接。WPS可能创建非标准的关系类型（Relationship Type），或者使用自定义的属性，导致POI的标准关系解析器无法建立这个链接。

实操技巧：在associateImageWithCell方法中，我们的匹配逻辑不能只依赖标准的r:embed。可以尝试以下策略：

1. 路径匹配：将drawingX.xml.rels中Target属性的值（如../media/image1.png）与扫描到的图片部件的PartName进行字符串匹配。
2. ID回查：如果路径匹配失败，可以尝试提取图片部件的原始关系ID（这需要从包含该部件的上级部件的关系集中查找），再用这个ID去drawingX.xml中搜索对应的形状定义。
3. 模糊匹配：作为保底方案，如果无法建立精确关联，可以记录下“未定位图片”，并在界面上提供给用户进行手动关联。或者，如果业务逻辑允许，可以根据图片被发现的顺序（例如在OOXML包中的出现顺序）与数据行的顺序进行“软关联”，但这风险很高。

难点三：内存管理与性能使用OPCPackage.open(File)会一次性将整个ZIP包（可能包含大量高分辨率图片）加载到内存中。对于几十兆甚至上百兆的Excel文件，极易引发java.lang.OutOfMemoryError: Java heap space错误。

解决方案：

• 增加JVM堆内存：这是最简单的办法，通过启动参数-Xmx2048m或-Xmx4096m来调整，但治标不治本。
• 使用流式处理：POI提供了org.apache.poi.xssf.eventusermodel.XSSFReader和SAX解析器，可以按工作表流式读取，但对于图片的随机访问支持不佳。
• 分治策略：对于超大文件，最稳妥的方法是引导用户拆分文件，或者在后端处理时，采用“先解压到临时目录，再流式读取图片文件”的方式。可以使用ZipInputStream手动解压.xlsx文件到临时文件夹，然后只将xl/workbook.xml和xl/worksheets/下的XML文件用DOM或SAX解析，而xl/media/下的大图片文件则用FileInputStream按需读取。这样能极大降低内存峰值。处理完成后，务必清理临时目录。

5. 实战测试与结果验证：如何确保真的读到了WPS图片

理论再好，也需要实战检验。我们设计一个测试流程来验证我们的增强读取器是否有效。

测试文件准备：

1. 使用WPS Office新建一个.xlsx文件。
2. 在A1单元格输入“产品ID”， B1输入“产品名称”， C1输入“产品主图”。
3. 在C2单元格，使用WPS的“插入”->“图片”功能，嵌入一张本地图片。
4. 保存文件，命名为test_wps_image.xlsx。

测试代码：

public class TestWPSImageRead { public static void main(String[] args) { String filePath = "path/to/your/test_wps_image.xlsx"; try { Map<Integer, ExcelWithWPSImageReader.SheetDataWithImages> result = ExcelWithWPSImageReader.readExcelWithImages(filePath); for (Map.Entry<Integer, ExcelWithWPSImageReader.SheetDataWithImages> entry : result.entrySet()) { int sheetIndex = entry.getKey(); ExcelWithWPSImageReader.SheetDataWithImages sheetData = entry.getValue(); System.out.println("=== Sheet: " + sheetData.getSheetName() + " ==="); // 打印单元格数据 List<List<Object>> data = sheetData.getCellData(); for (List<Object> row : data) { System.out.println(row); } // 打印图片信息 List<ExcelWithWPSImageReader.ExcelImage> images = sheetData.getImages(); System.out.println("Found " + images.size() + " image(s)."); for (int i = 0; i < images.size(); i++) { ExcelWithWPSImageReader.ExcelImage img = images.get(i); System.out.println(" Image " + i + ":"); System.out.println(" Source: " + img.getSource()); System.out.println(" Format: " + img.getFormat()); System.out.println(" Size: " + (img.getImageData() != null ? img.getImageData().length + " bytes" : "N/A")); System.out.println(" Position: Row=" + img.getRowIndex() + ", Col=" + img.getColIndex()); System.out.println(" PartName: " + img.getPartName()); // 可选：将图片保存到本地验证 if (img.getImageData() != null && img.getFormat() != null) { String outputPath = "extracted_image_" + i + "." + img.getFormat(); try (FileOutputStream fos = new FileOutputStream(outputPath)) { fos.write(img.getImageData()); System.out.println(" Saved to: " + outputPath); } } } } } catch (Exception e) { e.printStackTrace(); } } }

预期结果与验证：

• 成功情况：控制台输出显示找到了至少一张图片，且Source字段包含OOXML_Package_Scan。将保存的图片文件用图片查看器打开，确认与WPS中嵌入的图片一致。单元格数据被正确读取。
• 失败情况：如果只找到0张图片，或图片数据为空，说明我们的扫描逻辑仍有遗漏。需要进一步调试：
  1. 打印出OPCPackage中所有PackagePart的ContentType和PartName，查看WPS图片到底被存成了什么类型、放在哪个路径下。
  2. 检查mayContainImageData方法中的魔数判断是否覆盖了你的图片格式。
  3. 用解压软件（如7-Zip）手动解压.xlsx文件，对比WPS生成的文件和Office生成的文件在xl/目录结构上的差异，特别是drawings和media文件夹。

一个常见的“坑”：测试时一切正常，一上生产环境就读取失败。很可能是因为生产环境的文件来自不同用户、不同版本的WPS，甚至可能是从网页或移动端导出的，其内部结构变异性更大。因此，在生产代码中，必须对isImagePart和associateImageWithCell方法添加更宽松的判断和更完善的异常捕获与日志记录，确保单一文件的解析失败不会导致整个导入任务中断。

6. 进阶优化与扩展思路

解决了基本读取问题后，我们可以从性能、功能和鲁棒性上进行优化。

6.1 性能优化：缓存与懒加载每次读取都全量扫描OOXML包是耗时的。如果同一个文件需要多次访问（例如分页预览数据），可以引入缓存。

• 元数据缓存：第一次解析时，将图片的PartName、哈希值、推断出的位置信息等元数据缓存起来。下次读取时，先检查文件哈希或最后修改时间，如果未变，则直接使用缓存的元数据，仅按需加载图片二进制数据。
• 图片懒加载：在ExcelImage对象中，不直接存储byte[] imageData，而是存储一个Supplier<byte[]>或类似引用，只有在真正需要图片内容（如展示、上传）时，才去读取对应的PackagePart的输入流。

6.2 功能扩展：支持更多对象类型我们的方案聚焦于图片，但WPS可能嵌入的其他对象（如图表、智能图形、甚至其他文档）原理类似。你可以扩展imageContentTypes集合和isImagePart判断逻辑，来支持检测和提取其他类型的嵌入式对象。

// 扩展内容类型判断 Set<String> embeddedObjectTypes = new HashSet<>(imageContentTypes); embeddedObjectTypes.add("application/vnd.openxmlformats-officedocument.drawingml.chart"); embeddedObjectTypes.add("application/vnd.ms-office.drawing"); // ... 其他类型

6.3 鲁棒性增强：防御性编程与降级策略

• 格式嗅探：guessImageFormat方法可以加强，使用javax.imageio.ImageIO的ImageReader来探测真实的图片格式，而不是仅依赖文件扩展名或ContentType。
• 降级策略：当我们的增强扫描器也无法定位图片时，可以提供降级方案。例如，记录一条警告日志，并将图片数据以“未关联”的状态返回给上层业务。业务层可以根据其他上下文（如固定列、文件名顺序）进行匹配，或者提供人工干预界面。
• 依赖管理：确保使用的POI版本足够新，以包含最新的兼容性修复。同时，注意POI相关依赖（如poi-ooxml、poi-ooxml-schemas）的版本一致性，避免因依赖冲突导致奇怪的解析错误。

实现一个健壮的、能处理WPS嵌入式图片的Excel读取器，是对开发者耐心和细心的考验。它要求我们不仅会使用高级API，还要愿意深入文件格式的细节，处理各种边界情况和兼容性问题。最终得到的这个组件，将成为处理来自“真实世界”的、杂乱无章的Excel数据源的可靠工具。