前言适用场景后端开发中商品分类、订单台账、财务报表、渠道统计等 Excel 导出场景普遍存在多维度分组纵向合并需求一级大类、二级小类、规格价格多级联动要求上级分类不一致时下级字段即便数值相同也禁止合并。原生 EasyExcel 痛点官方ContentLoopMerge仅支持固定行数合并无法根据单元格值动态分层级合并网上通用合并处理器大多只支持单列合并多列联动需硬编码列下标新增字段全部失效逐行实时合并逻辑大批量导出极易出现合并区域重叠异常内存开销大数字、字符串、空值混合场景等值判断处理繁琐相同内容无法合并硬编码列索引耦合 VO 实体后期维护成本极高。核心业务合并规则本文方案标准VO 字段声明顺序AExcelColumnMerge→ BExcelColumnMerge→ C普通无注解若前置 A 列上下行数值不一致B 列哪怕连续相同禁止合并只有左侧所有标注合并注解的字段上下行完全一致当前列才允许纵向合并支持 N 级联动合并字段顺序决定合并层级无需手动配置层级参数。一、前置环境与 Maven 依赖版本说明EasyExcel3.1.1适配 SpringBoot 2.7.x/ 3.xLombok简化 VO 实体代码POIEasyExcel 内置依赖无需单独引入pom.xml 完整依赖!-- EasyExcel 3.1.1 核心导出包 -- dependency groupIdcom.alibaba/groupId artifactIdeasyexcel/artifactId version3.1.1/version /dependency !-- Lombok 简化实体get/set -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency二、全套源码分层解析可直接复制落地2.1 自定义合并标记注解 ExcelColumnMerge.java作用标记需要参与层级联动合并的实体字段无参数、零侵入仅运行期反射识别。package com.yzjyhp.excel.annotation; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * 列层级相同数据合并注解 * 前置依赖合并规则 * 假设字段顺序A (ExcelColumnMerge) → B (ExcelColumnMerge) → C (不合并) * 同一行区间如果 A 列没有形成合并段上下值不一样那么 B 列即使连续相同值禁止合并 * 只有前面所有标记合并的列连续值完全一致当前列才允许合并 * Date: 2026/7/9 18:00 * author: ekin.yuan * version 1.0.0 */ Target(ElementType.FIELD) Retention(RetentionPolicy.RUNTIME) Documented public interface ExcelColumnMerge { }注解核心说明Target(ElementType.FIELD)仅允许标注实体属性不支持类、方法RetentionPolicy.RUNTIME运行时保留注解处理器通过反射识别无自定义属性使用极简业务 VO 一行注解即可开启层级合并。2.2 核心批量合并处理器 MergeAnnotationBatchWriteHandler.java实现 EasyExcelCellWriteHandler采用先缓存、后批量合并设计区别于传统逐行实时合并解决大批量导出重叠报错问题。package com.yzjyhp.excel.handler; import com.alibaba.excel.write.handler.CellWriteHandler; import com.alibaba.excel.write.handler.context.CellWriteHandlerContext; import com.yzjyhp.excel.annotation.ExcelColumnMerge; import org.apache.poi.ss.usermodel.Cell; import org.apache.poi.ss.usermodel.CellType; import org.apache.poi.ss.usermodel.Sheet; import org.apache.poi.ss.util.CellRangeAddress; import java.lang.reflect.Field; import java.util.ArrayList; import java.util.Collections; import java.util.HashMap; import java.util.List; import java.util.Map; public class MergeAnnotationBatchWriteHandler implements CellWriteHandler { // XLSX单Sheet最大行下标边界保护防止POI越界异常 private static final int MAX_SHEET_ROW_INDEX 1048575; // 导出VO实体Class用于反射读取字段 private final Class? dataClass; // VO字段原始声明顺序 Excel表头从左到右顺序决定合并层级先后 private final ListField fieldOrderList; // 有序列表按表头从左到右存储所有带ExcelColumnMerge的列下标层级判断依据 private final ListInteger sortedMergeColList; // 缓存容器key行号 value该行所有合并列列下标,单元格值 private final MapInteger, MapInteger, Object rowAllMergeColValueMap new HashMap(); // 当前导出Sheet对象延迟初始化 private Sheet targetSheet; // 构造器传入VO实体Class自动解析合并列 public MergeAnnotationBatchWriteHandler(Class? dataClass) { this.dataClass dataClass; this.fieldOrderList getSortedFields(); this.sortedMergeColList getSortedMergeColumns(); } /** * 获取VO字段从上到下声明顺序对应Excel表头左右顺序 */ private ListField getSortedFields() { ListField list new ArrayList(); Field[] fields dataClass.getDeclaredFields(); for (Field field : fields) { field.setAccessible(true); list.add(field); } return list; } /** * 按表头从左至右顺序收集带合并注解的列下标有序层级判断核心 */ private ListInteger getSortedMergeColumns() { ListInteger mergeCols new ArrayList(); for (int i 0; i fieldOrderList.size(); i) { Field field fieldOrderList.get(i); if (field.isAnnotationPresent(ExcelColumnMerge.class)) { mergeCols.add(i); } } return mergeCols; } /** * 单元格写入完成后置钩子缓存所有合并列单元格值 */ Override public void afterCellDispose(CellWriteHandlerContext context) { // 延迟赋值Sheet if (targetSheet null) { targetSheet context.getWriteSheetHolder().getSheet(); } int rowIndex context.getRowIndex(); int colIndex context.getCell().getColumnIndex(); // 超过XLSX最大行直接丢弃 if (rowIndex MAX_SHEET_ROW_INDEX) { return; } // 跳过表头行rowIndex从0开始0为表头 if (rowIndex 1) { return; } // 当前列不参与合并无需缓存 if (!sortedMergeColList.contains(colIndex)) { return; } // 读取单元格原始值 Object cellVal getCellValue(context.getCell()); // 按行缓存列值 rowAllMergeColValueMap.computeIfAbsent(rowIndex, k - new HashMap()).put(colIndex, cellVal); } /** * 外部手动触发合并逻辑必须在writer.finish()前调用 * 核心合并主流程 */ public void executeMerge() { // 无数据/无合并列直接退出 if (targetSheet null || sortedMergeColList.isEmpty() || rowAllMergeColValueMap.isEmpty()) { return; } // 数据行升序排序保证从上至下遍历 ListInteger sortedRowList new ArrayList(rowAllMergeColValueMap.keySet()); Collections.sort(sortedRowList); // 仅1行数据无需合并 if (sortedRowList.size() 1) { return; } // 从左到右遍历每一个需要合并的列层级顺序不可颠倒 for (int colIdx : sortedMergeColList) { // 当前合并列在有序合并列表中的位置用于获取左侧所有合并列 int currMergeColPos sortedMergeColList.indexOf(colIdx); // 初始化合并起始行 int startRow sortedRowList.get(0); // 逐行对比上下行 for (int i 1; i sortedRowList.size(); i) { int currRow sortedRowList.get(i); int prevRow sortedRowList.get(i - 1); // 1. 核心规则校验当前列左侧所有合并列上下两行值是否全部相等 boolean allLeftColSame checkAllLeftMergeColSame(currMergeColPos, prevRow, currRow); if (!allLeftColSame) { // 左侧任意合并列值不同断开合并区间 if (startRow ! prevRow) { mergeSafe(targetSheet, startRow, prevRow, colIdx); } startRow currRow; continue; } // 2. 左侧全部相同再判断当前列自身值是否一致 MapInteger, Object prevRowValMap rowAllMergeColValueMap.get(prevRow); MapInteger, Object currRowValMap rowAllMergeColValueMap.get(currRow); Object prevVal prevRowValMap.get(colIdx); Object currVal currRowValMap.get(colIdx); if (!equals(prevVal, currVal)) { // 当前列值不同断开合并 if (startRow ! prevRow) { mergeSafe(targetSheet, startRow, prevRow, colIdx); } startRow currRow; } } // 处理循环结束后最后一段连续合并区间 int lastRow sortedRowList.get(sortedRowList.size() - 1); if (startRow ! lastRow) { mergeSafe(targetSheet, startRow, lastRow, colIdx); } } } /** * 校验当前列左侧所有合并列上下两行值是否全部相等 * param currMergeColPos 当前合并列在sortedMergeColList的下标 * param prevRow 上一行行号 * param currRow 当前行号 * return true左侧全部相同允许当前列合并false禁止合并 */ private boolean checkAllLeftMergeColSame(int currMergeColPos, int prevRow, int currRow) { MapInteger, Object prevRowMap rowAllMergeColValueMap.get(prevRow); MapInteger, Object currRowMap rowAllMergeColValueMap.get(currRow); // 遍历当前列左边所有合并列任意一列值不同直接返回false for (int i 0; i currMergeColPos; i) { int leftCol sortedMergeColList.get(i); Object v1 prevRowMap.get(leftCol); Object v2 currRowMap.get(leftCol); if (!equals(v1, v2)) { return false; } } return true; } // 工具私有方法 /** * 统一读取单元格值兼容字符串、数字、布尔、空单元格 */ private Object getCellValue(Cell cell) { if (cell null) return null; CellType type cell.getCellType(); switch (type) { case STRING: return cell.getStringCellValue().trim(); case NUMERIC: return cell.getNumericCellValue(); case BOOLEAN: return cell.getBooleanCellValue(); default: return ; } } /** * 通用值相等判断兼容空值、数字、字符串统一转字符串对比 */ private boolean equals(Object v1, Object v2) { if (v1 null v2 null) return true; if (v1 null || v2 null) return false; return v1.toString().equals(v2.toString()); } /** * 安全合并单元格增加行号边界保护防止POI数组越界 * addMergedRegionUnsafe不校验重叠批量合并性能更高前置逻辑保证无重叠 */ private void mergeSafe(Sheet sheet, int firstRow, int lastRow, int col) { if (firstRow MAX_SHEET_ROW_INDEX) return; lastRow Math.min(lastRow, MAX_SHEET_ROW_INDEX); if (firstRow lastRow) return; CellRangeAddress region new CellRangeAddress(firstRow, lastRow, col, col); sheet.addMergedRegionUnsafe(region); } }核心模块功能拆解构造器反射解析自动读取 VO 字段声明顺序按表头左右顺序收集带注解列无需手动写死列下标新增、删除导出字段无需修改处理器。afterCellDispose 缓存机制仅缓存单元格数据不实时合并大批量写入无频繁 POI 操作从根源规避合并重叠异常。executeMerge 批量合并入口所有数据写入完毕后统一执行合并一次性生成全部合并区域性能远高于逐行实时合并。checkAllLeftMergeColSame 层级校验核心严格落地业务规则前置所有合并列数值必须完全一致当前列才允许合并完美适配多级分类报表。mergeSafe 边界防护限制最大行 1048575规避 XLSX 文件规范限制导致的 POI 数组越界使用addMergedRegionUnsafe提升批量合并性能。通用 equals 工具方法兼容字符串、数字、空值、布尔类型统一转字符串对比解决数字与字符串等值无法合并问题。2.3 业务导出 VO 示例 ProductExcelVO2.javapackage com.yzjyhp.excel.vo; /** * Description: * Date: 2026/7/9 18:10 * author: ekin.yuan * version 1.0.0 */ import com.alibaba.excel.annotation.ExcelProperty; import com.yzjyhp.excel.annotation.ExcelColumnMerge; import lombok.Data; Data public class ProductExcelVO2 { // 第0列一级合并列最左侧最高优先级 ExcelColumnMerge ExcelProperty(商品大类) private String category1; // 第1列二级合并列依赖category1完全相同才合并 ExcelColumnMerge ExcelProperty(商品小类) private String category2; // 普通列不参与合并逻辑 ExcelProperty(商品名称) private String productName; // 第3列三级合并列依赖category1、category2全部相同才合并 ExcelColumnMerge private Double price; }VO 使用规范字段从上至下声明顺序 Excel 表头从左到右展示顺序层级越高的合并字段声明位置越靠前不需要合并的字段不添加ExcelColumnMerge注解。3.4 完整可运行 Demo复制直接执行import com.alibaba.excel.EasyExcel; import com.yzjyhp.excel.handler.MergeAnnotationBatchWriteHandler; import com.yzjyhp.excel.vo.ProductExcelVO2; import java.io.FileOutputStream; import java.util.ArrayList; import java.util.List; public class ExcelMergeDemo { public static void main(String[] args) throws Exception { // 1. 模拟业务数据重要数据必须按合并字段提前排序相同分组连续排列 ListProductExcelVO2 dataList new ArrayList(); // 数码-手机售价5999三行满足全部合并条件 ProductExcelVO2 p1 new ProductExcelVO2(); p1.setCategory1(数码); p1.setCategory2(手机); p1.setProductName(iPhone 16); p1.setPrice(5999.0); dataList.add(p1); ProductExcelVO2 p2 new ProductExcelVO2(); p2.setCategory1(数码); p2.setCategory2(手机); p2.setProductName(小米15); p2.setPrice(5999.0); dataList.add(p2); ProductExcelVO2 p3 new ProductExcelVO2(); p3.setCategory1(数码); p3.setCategory2(手机); p3.setProductName(华为Mate70); p3.setPrice(5999.0); dataList.add(p3); // 数码-耳机售价1999小类变更大类继续合并小类、售价断开 ProductExcelVO2 p4 new ProductExcelVO2(); p4.setCategory1(数码); p4.setCategory2(耳机); p4.setProductName(AirPods); p4.setPrice(1999.0); dataList.add(p4); // 家居-椅子售价299大类变更所有合并列全部断开 ProductExcelVO2 p5 new ProductExcelVO2(); p5.setCategory1(家居); p5.setCategory2(椅子); p5.setProductName(电竞椅); p5.setPrice(299.0); dataList.add(p5); // 2. 初始化合并处理器 MergeAnnotationBatchWriteHandler mergeHandler new MergeAnnotationBatchWriteHandler(ProductExcelVO2.class); // 3. 输出文件流 String filePath D:/商品导出层级合并.xlsx; try (FileOutputStream fos new FileOutputStream(filePath)) { // 构建EasyExcel写入器注册合并处理器 var writer EasyExcel.write(fos, ProductExcelVO2.class) .registerWriteHandler(mergeHandler) .sheet(商品列表) .build(); // 写入业务数据 writer.write(dataList); // 【核心必写】写入完成后执行批量合并逻辑必须在finish前调用 mergeHandler.executeMerge(); // 关闭写入器生成文件 writer.finish(); } System.out.println(Excel导出完成文件路径 filePath); } }Demo 关键注意事项业务数据必须提前按照合并层级字段排序相同分组连续排列否则合并分段错乱executeMerge()调用时机writer.write()之后、writer.finish()之前单 Sheet 仅需创建一个 Handler多 Sheet 场景每个 Sheet 单独实例化处理器。三、方案优缺点与可扩展优化点3.1 方案优势注解驱动零硬编码VO 添加注解即可开启合并无需手动维护列下标增减导出字段无需修改 Handler独家层级联动规则市面方案极少支持 “前置列不同当前列禁止合并” 多级联动逻辑批量合并性能优异先缓存后统一合并百万级数据无合并重叠报错减少 POI 底层调用全类型兼容统一处理字符串、数字、布尔、空单元格解决数字 / 字符串等值不合并问题内置边界安全防护限制 XLSX 最大行避免 POI 数组越界崩溃低侵入易集成仅新增注解 处理器原有导出业务代码改动极小兼容所有 SpringBoot 项目分层解耦设计单元格读取、数值对比、合并逻辑分层便于单独定制修改。3.2 现有局限与缺点仅支持纵向行合并不支持横向多列合并数据必须提前排序分散分组会出现分段合并多 Sheet 导出每个 Sheet 需要单独新建处理器实例仅支持实体写入导出不支持模板填充fill()模式全部数据缓存至内存超百万行极端场景内存占用偏高。3.3 可扩展优化方向生产环境落地改造注解增加 order 参数手动指定合并优先级打破字段声明顺序限制重写 equals 方法支持 BigDecimal 高精度金额对比适配财务报表封装工具类统一创建 Handler简化多 Sheet 重复代码添加日志输出打印合并区间起止行线上快速定位合并异常超大数据分段合并分批释放缓存降低内存占用适配 EasyExcel 模板填充模式合并后自动统一单元格居中、边框样式美化导出报表。四、高频踩坑总结报错日志 定位 修复方案坑 1合并重叠异常Cannot add merged region to sheet because it overlaps with an existing merged region报错原因传统逐行实时合并多次创建同一区域重复调用executeMerge()修复本方案仅在finish()前调用一次批量合并方法杜绝重复创建合并区域。坑 2上级分类不同下级相同数值依然合并层级规则失效原因 1VO 字段声明顺序错乱合并列有序列表颠倒修复VO 字段从上至下顺序与 Excel 表头左右顺序保持一致原因 2上级层级字段未添加ExcelColumnMerge注解修复所有参与层级判断的前置字段必须标记注解。坑 3数字 5000 与字符串 5000 无法合并原因原生对象 equals 对比类型不一致修复内置统一 toString 对比工具方法业务无需转换数据类型。坑 4表头行被合并首行数据丢失原因未过滤表头行 rowIndex0修复代码内置if(rowIndex 1) return;自动跳过表头无需额外处理。坑 5超 10 万行导出 POI 数组越界原因行号超出 XLSX 规范最大行 1048575修复mergeSafe 方法自动截断行号做边界保护。坑 6新增导出字段后合并全部错乱原因传统方案硬编码列下标修复本方案反射自动识别字段顺序调整 VO 字段顺序即可。五、EasyExcel 面试高频题 标准答案面试题 1原生 EasyExcel ContentLoopMerge 有什么缺陷本方案如何解决回答原生ContentLoopMerge只能固定行数合并无法根据单元格数值动态分层级合并无法实现上级分类不同下级禁止合并的业务需求原生需要手动指定 eachRow 固定行数动态不确定行数的报表完全无法适配本文自定义注解 反射处理器自动识别合并列内置前置列校验逻辑实现动态多级联动合并适配所有分组报表场景。面试题 2为什么不采用逐行实时合并而是全部写入完成后批量合并回答逐行实时合并会循环调用addMergedRegion大批量数据极易产生合并区域重叠异常每写入一行就执行判断逻辑频繁操作 POI 底层百万级导出性能差先缓存全部单元格数据、最后一次性合并仅单次遍历数据无重叠风险IO 开销更低性能更优。面试题 3多列层级合并的核心判断逻辑是什么回答所有标注ExcelColumnMerge的字段按照 VO 声明顺序生成有序合并列表遍历每一列时先校验该列左侧所有合并列上下行数值是否全部相等左侧任意一列数值不一致直接断开合并区间当前列不合并左侧全部数值一致再对比当前列单元格值相同则延长合并区间不同则断开。面试题 4使用该合并方案必须满足哪些前置条件回答导出数据必须按合并层级字段提前排序相同分组连续排列VO 实体字段声明顺序与 Excel 表头左右展示顺序保持一致多级前置层级字段全部添加ExcelColumnMerge注解executeMerge()必须在 writer.write () 之后、writer.finish () 之前执行。面试题 5如何扩展支持 BigDecimal 金额高精度合并对比回答修改处理器内 equals 工具方法增加 BigDecimal 类型判断使用 compareTo 高精度对比规避 toString 浮点精度丢失问题private boolean equals(Object v1, Object v2) { if (v1 null v2 null) return true; if (v1 null || v2 null) return false; // 高精度金额单独处理 if (v1 instanceof java.math.BigDecimal v2 instanceof java.math.BigDecimal) { return ((java.math.BigDecimal) v1).compareTo((java.math.BigDecimal) v2) 0; } return v1.toString().equals(v2.toString()); }六、结尾互动CSDN 引流本文完整落地 EasyExcel 3.1.1 多层级前置依赖单元格合并方案注解驱动零硬编码适配商品、订单、财务各类分组报表导出全套源码可直接复制投入生产。 你在 Excel 导出过程中是否遇到过层级合并错乱、大批量合并重叠、数字字符串无法合并等问题欢迎评论区留言交流点赞收藏本文后续开发报表导出直接复用这套完整解决方案