easyExcel导出图片为byte[]时WPS显示空白

Question

使用EasyExcel导出包含图片（以byte[]形式存储）的Excel文件时，部分图片在WPS中显示为空白，而在Microsoft Excel中正常显示。该问题常见于通过ImageUtils插入的图片未正确适配WPS对图像格式或尺寸的解析逻辑，尤其当图片分辨率过高或未设置合适的列宽行高时，WPS易出现渲染异常。同时，EasyExcel默认使用的PNG格式在WPS中兼容性较弱，可能导致图像加载失败。需调整图片压缩策略、显式设置单元格大小并优先采用JPEG格式以提升WPS兼容性。

Answer 1

一、问题现象与背景分析

在使用EasyExcel导出包含图片（以byte[]形式存储）的Excel文件时，开发者普遍反馈：部分图片在WPS Office中显示为空白区域，而在Microsoft Excel中则正常渲染。这一兼容性问题直接影响了企业级报表系统的用户体验，尤其在国产办公软件推广背景下显得尤为突出。

经过初步排查，该问题并非源于EasyExcel本身的数据写入错误，而是与WPS对图像嵌入机制的解析差异密切相关。具体表现为：

• 图片分辨率过高导致WPS渲染超时或跳过绘制；
• 未显式设置单元格行高列宽，造成图像溢出或压缩异常；
• EasyExcel默认采用PNG格式嵌入图片，而WPS对PNG支持存在兼容性缺陷；
• 图像插入位置与单元格坐标未精确对齐，引发布局错乱。

二、技术原理深度剖析

EasyExcel底层基于Apache POI进行Excel文件生成，其图像插入逻辑依赖于Drawing Patriarch和ClientAnchor机制将byte[]数据写入工作表。不同的是，Microsoft Excel与WPS在处理这些二进制图像对象时采用了不同的解码策略。

以下为图像插入的核心流程图：

graph TD
    A[Java对象含byte[]图片] --> B(EasyExcel Write)
    B --> C{判断图片格式}
    C -->|PNG| D[调用ImageUtils.writeWithImage]
    C -->|JPEG| E[压缩并转换格式]
    D & E --> F[创建HSSFClientAnchor]
    F --> G[写入DrawingPatriarch]
    G --> H[生成.xls/.xlsx]
    H --> I{打开方式?}
    I -->|Microsoft Excel| J[正常解析PNG/JPEG]
    I -->|WPS Office| K[部分跳过PNG/高分辨率图]
    K --> L[显示空白]
    

三、常见排查路径与验证方法

排查项	验证方式	预期结果	工具建议
图片是否成功写入	重命名.xlsx为.zip，解压查看xl/media/目录	存在image1.png等文件	7-Zip / WinRAR
图片格式类型	通过POI读取Workbook获取PictureData	确认为PNG或JPEG	Apache POI API
行列尺寸适配	检查Sheet.setColumnWidth()和Row.setHeightInPoints()	宽度≥图片像素/7	Excel公式换算
WPS版本兼容性	测试WPS 2019 vs WPS 2023	新版支持更好	多环境实测
图像分辨率	使用BufferedImage获取getWidth/getHeight	<=2000px推荐	ImageIO.read()

四、解决方案体系构建

1. 优先使用JPEG格式：将原始图片转换为JPEG以提升WPS兼容性。
2. 限制图片分辨率：对大于1500px的图片进行等比压缩。
3. 显式设置单元格大小：根据图片尺寸动态调整列宽和行高。
4. 优化图像插入锚点：确保ClientAnchor精准定位。
5. 启用缓存压缩中间态：避免重复编码开销。

五、代码实现示例

public class ImageExportHandler {

    public static byte[] compressToJpeg(byte[] original, int maxWidth) throws IOException {
        BufferedImage img = ImageIO.read(new ByteArrayInputStream(original));
        int width = img.getWidth();
        int height = img.getHeight();

        // 等比缩放
        if (width > maxWidth) {
            double ratio = (double) maxWidth / width;
            width = maxWidth;
            height = (int) (height * ratio);
        }

        BufferedImage resized = new BufferedImage(width, height, BufferedImage.TYPE_INT_RGB);
        Graphics2D g = resized.createGraphics();
        g.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BILINEAR);
        g.drawImage(img, 0, 0, width, height, null);
        g.dispose();

        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        ImageIO.write(resized, "jpeg", baos); // 强制输出JPEG
        return baos.toByteArray();
    }

    public void writeImageToSheet(Sheet sheet, byte[] imageBytes, int rowIndex, int colIndex) throws IOException {
        // 设置行高（单位：1/20 pt）
        Row row = sheet.getRow(rowIndex);
        if (row == null) row = sheet.createRow(rowIndex);
        row.setHeightInPoints(120); // 建议根据图片高度动态计算

        // 设置列宽（单位：1/256 字符宽度）
        sheet.setColumnWidth(colIndex, 30 * 256);

        // 插入图片
        int pictureIdx = sheet.getWorkbook().addPicture(imageBytes, Workbook.PICTURE_TYPE_JPEG);
        CreationHelper helper = sheet.getWorkbook().getCreationHelper();
        Drawing drawing = sheet.createDrawingPatriarch();
        ClientAnchor anchor = helper.createClientAnchor();
        anchor.setCol1(colIndex);
        anchor.setRow1(rowIndex);
        anchor.setCol2(colIndex + 1);
        anchor.setRow2(rowIndex + 1);
        anchor.setAnchorType(ClientAnchor.MOVE_AND_RESIZE);

        drawing.createPicture(anchor, pictureIdx);
    }
}

六、生产环境最佳实践建议

在实际项目中，应建立统一的图像处理管道，涵盖如下环节：

• 上传阶段：强制校验图片MIME类型与扩展名一致性；
• 服务端预处理：统一转码为JPEG+最大边≤1500px；
• 模板设计：预留足够单元格空间，避免自动拉伸；
• 日志监控：记录每次图像插入的尺寸与格式信息；
• A/B测试：定期对比WPS与Excel渲染效果差异。

此外，可结合Spring Boot配置化管理图像策略：

# application.yml
easyexcel:
  image:
    format: jpeg
    max-width: 1500
    max-height: 1500
    quality: 0.85
    enable-compression: true