后台管理系统里十张报表八张要导出 Excel，其中至少有一张得带多级表头——“订单信息”底下挂“订单编号”“下单时间”，“客户信息”底下挂“客户名称”“联系方式”，然后同一个客户的订单行还要在“客户名称”这一列纵向合并成一个大格子。我第一次接到 EasyExcel 导出 Excel 合并表头和数据这个需求时，心里想的是“不就导个表嘛”，结果真上手才发现，多级表头拼接、数据行纵向合并、合并后边框样式消失、几万行数据导出直接把内存打爆，这几个坑一个不落全踩了一遍。这篇文章就按我实际项目的落地过程来写，从需求拆解、方案选型、核心机制，到完整可跑的代码、参数调优和踩坑记录，一次性讲透。它适合正在做报表导出、被合并单元格折磨过的后端和全栈同学；哪怕你之前只写过最简单的单表头导出，跟着走也能把带合并的复杂报表啃下来。
1. 需求拆解与选型：多级表头合并到底卡在哪
1.1 什么样的报表需要合并表头和数据
先把需求讲清楚，不然后面的选型都是空中楼阁。带合并的导出，通常出现在“分组统计型”报表里。比如你要导出一份“客户订单明细”，逻辑结构是这样的：每个客户下面挂着若干个订单，每个订单下面又挂着若干商品明细。如果平铺成一行行导出，客户名和订单号就会大量重复，看起来极其臃肿，业务方根本没法一眼看出层级关系。
这种场景在 Excel 里最自然的表达方式就是合并：把“客户名称”这一列里连续的相同客户合并成一个纵向大格，“订单编号”这一列里同一个订单的多条商品明细合并成一个格。同时表头也往往是有层级的——“客户信息”作为一个大的父标题，横跨“客户名称”“联系方式”两列。这就是典型的“合并表头 + 合并数据”双合并需求。
很多人一开始会低估它，觉得 EasyExcel 注解写几个数组就完事了。多级表头确实能用注解拼出来，而且 EasyExcel 会自动把相同父标题合并，这个能力很好用。但数据行的纵向合并，EasyExcel 官方并没有直接提供一个“按列相同值自动合并”的开关，需要你自定义合并策略。这一步才是真正的分水岭，也是绝大多数人卡住的地方。所以第一件事，就是明确你到底要不要合并数据行，以及合并的判定维度是什么，是按客户合并还是按订单合并，还是两者都要。
1.2 POI、EasyExcel、模板导出三种路线怎么选
选型之前，先看清自己手里有多少种工具。最底层的是原生 Apache POI，功能最全，合并、样式、公式、图表样样能写，但代码极其啰嗦，一个简单表格就能写上百行，而且它对内存非常不友好，XSSFWorkbook 在内存里构建整棵树，几万行数据上百万个单元格对象，堆内存分分钟溢出。它的优势是“什么都能干”，劣势是“什么都得自己干”。
路线二是模板导出，先把表头、合并区域、样式在 Excel 模板里画好，程序只负责往里塞数据，用{}占位符或者列表填充。这条路的优点是样式和合并完全由模板管着，代码干净，特别适合“表头固定、样式复杂”的报表。缺点是动态性差，如果表头列会随着筛选条件变化，模板就废了。
路线三就是 EasyExcel。它在 POI 基础上做了一层封装，核心卖点是把读写拆成了 SAX 模式，读的时候不把整个文件加载进内存，写的时候也做了很多优化，配合注解和回调，开发效率高。它的定位很清晰：面向“结构相对固定、数据量大”的报表场景。我们最终选它，是因为项目里的报表已经用了 EasyExcel 做基础导出，多级表头用注解直接拼出来，数据合并虽然要自己写策略，但比起原生 POI 还是省了大量样板代码。如果你的报表样式极度复杂、合并区域完全手工定制，那 POI 或模板可能更合适；但如果是常规业务报表，EasyExcel 是性价比最高的选择。
提示：不要一上来就纠结“哪个最快”，先看你的核心约束是内存、开发效率还是样式自由度，不同的约束会指向完全不同的工具。
1.3 版本与依赖的取舍
版本这块有个必须提的坑。EasyExcel 在 3.x 版本做了较大的 API 调整，比如CellWriteHandler里afterCellDispose的参数从早期的CellData变成了List<WriteCellData<?>>，一些网上的老示例直接拿到新版本里跑会编译不过。所以选版本时，要么统一用 3.x（推荐，2023 年之后新项目基本都是 3.x），要么锁定一个稳定的 2.x，别混着抄代码。
我个人项目的依赖是这样的：
<dependency> <groupId>com.alibaba</groupId> <artifactId>easyexcel</artifactId> <version>3.3.4</version> </dependency>需要注意，EasyExcel 内部依赖了 POI 和 ehcache，如果你的项目里已经引了不同版本的 POI，很容易出现NoSuchMethodError。做法是在父 pom 里用dependencyManagement把 POI 版本统一锁死，比如 4.1.2 或 5.2.x，让 EasyExcel 和你的其他依赖用同一个 POI，冲突基本就没了。这个点在多人协作项目里非常关键，我见过好几次“本地能跑、服务器报错”最后都栽在 POI 版本冲突上。
2. 核心机制：注解、表头结构与合并策略
2.1 @ExcelProperty 如何拼出多级表头
EasyExcel 的多级表头，靠的是@ExcelProperty注解里传一个字符串数组。数组的每一个元素对应一层，从最外层父标题到最内层子标题依次排列。比如：
@ExcelProperty({"客户信息", "客户名称"}) private String customerName;这就表示“客户信息”是第一级表头，“客户名称”是第二级。如果多个字段的第一级名称完全相同，EasyExcel 在生成表头时会自动把这一级横向合并成一个格子。也就是说，“客户信息”横跨“客户名称”和“联系方式”两列，你不需要自己调addMergedRegion，框架帮你做了。这是个很容易被忽略的便利点——很多人以为多级表头也得自己合并，其实表头合并在 EasyExcel 里是自动的，你只要保证父标题字符串一致即可。
字段的导出顺序默认按注解数组的书写顺序，如果你想精确控制列序，还可以配合@ExcelProperty(value = {...}, index = 0)指定索引。但这里有个坑：一旦你用了 index，所有需要导出的字段都得显式指定 index，否则没指定的字段顺序会变得不可预测。我的习惯是干脆全部用书写顺序，不写 index，这样后期增删字段时不会因为漏改 index 而错位。另外，导出实体里尽量只放需要导出的字段，别为了省事把业务实体直接拿来当导出对象，字段一多容易误导出敏感信息。
2.2 表头合并与数据合并是两套机制
这是全文最需要划重点的一句话：表头合并是框架自动完成的，数据纵向合并是要你自己写策略的，两者完全不是一回事，千万别混在一个思路里。
表头合并靠的是相同父标题字符串自动触发，你几乎零成本。而数据行合并，本质上是“把同一列里连续的、值相同的单元格合并成一个区间”，这个“连续相同”的判断逻辑 EasyExcel 不认识你的业务，它不知道你希望按哪一列合并、哪些列要合并、相同值怎么定义。所以它只给你一个扩展点，也就是合并策略，让你自己去判断和调用 POI 的sheet.addMergedRegion(...)。
理解这一点后，整个实现思路就清晰了：表头部分我用注解拼好，交给框架自动合并父标题；数据部分我注册一个自定义合并策略，在数据写入过程中，对指定列做“相邻相同值合并”。两条线各走各的，互不干扰，这样代码结构也最干净。很多新手把两者搅在一起，试图在合并策略里连表头也管，结果要么把表头误合并，要么注解自带的多级表头被覆盖掉，问题就出在没分清这两套机制。
注意：数据合并有一个隐含前提——待合并的列必须是有序的，相同值一定要连续出现。如果同一个客户的订单被分散在不相邻的行里，你的合并逻辑会把它们识别成多段，合并出来是一堆碎格子。所以导出前务必对数据按合并维度排序，这一步做在数据库
ORDER BY里最稳。
2.3 合并策略的执行时机与选择
EasyExcel 里做合并，主要有几个入口，选错了要么合并不上，要么性能差。第一种是AbstractMergeStrategy，这是官方最推荐的扩展点，它的merge(Sheet sheet, Cell cell, Head head, Integer relativeRowIndex)方法会在数据行写入时对每个单元格回调一次，relativeRowIndex就是数据相对行号（从 0 开始，不含表头）。你可以在这里比较当前格和上一行同列值，决定是否合并。
第二种是OnceAbsoluteMergeStrategy，它适合“位置固定”的合并，比如固定把表头某几行某几列合并，构造时直接传四个参数（起始行、结束行、起始列、结束列）。这种适合同一位置永远要合并的场景，不适合按数据内容动态合并。
第三种是完整的CellWriteHandler，你可以在afterCellDispose里拿到单元格信息自己处理，灵活度最高但代码也最多，需要自己维护合并的起止状态。我的建议是：表头自动合并靠注解，按数据内容动态合并优先用AbstractMergeStrategy。它对数据行的回调时机刚刚好，拿得到 sheet 和 cell，逻辑也好写。
这里有个执行时机的细节要留意：合并回调是逐格触发的，也就是说你没法在“所有数据写完”后统一处理，只能在回调里即时判断。这带来一个典型问题——每一列的最后一段合并容易漏掉，因为后面没有下一个格子来触发“值变化”的判断。解决思路是把数据总数传进策略，当relativeRowIndex等于最后一行时，主动给每一列做一次收尾结算。这一点我在第 3 节的代码里会具体实现。
3. 完整实操：从实体类到导出接口
3.1 依赖与导出实体类定义
先定义导出实体。假设我们要导出一份客户订单明细，表头分三层：客户信息（客户名称、联系方式）、订单信息（订单编号、下单时间）、商品明细（商品名称、数量、金额）。注意，这里客户和订单的很多字段其实是一对多的结构，导出时会被平铺成多行，靠后续合并还原层级。
@Data public class OrderExportVO { @ExcelProperty({"客户信息", "客户名称"}) private String customerName; @ExcelProperty({"客户信息", "联系方式"}) private String contactPhone; @ExcelProperty({"订单信息", "订单编号"}) private String orderNo; @ExcelProperty({"订单信息", "下单时间"}) private String orderTime; @ExcelProperty({"商品明细", "商品名称"}) private String productName; @ExcelProperty({"商品明细", "数量"}) private Integer quantity; @ExcelProperty({"商品明细", "金额"}) private BigDecimal amount; }这份实体导出来后，表头会自动形成“客户信息 / 订单信息 / 商品明细”三个横向合并的父级区域，父级下再各挂子标题。我们打算合并的列是“客户名称”和“订单编号”，也就是第 0 列和第 2 列。注意，这两列必须是有序的，SQL 里要ORDER BY customer_name, order_no，保证相同值连续出现，否则合并逻辑会失效。实体类里我特意用了BigDecimal存金额，避免用double导致精度问题，导出时 EasyExcel 会按数值处理，但如果你需要保留两位小数，最好在数据层就格式化好，或者在单元格样式里设置dataFormat。
3.2 自定义合并策略：按列合并相邻相同值
这是全文的核心代码。我写一个继承自AbstractMergeStrategy的策略类，构造时传入两个参数：需要合并的列索引集合，以及数据总条数（用于最后一段收尾）。
import com.alibaba.excel.metadata.Head; import com.alibaba.excel.write.handler.AbstractMergeStrategy; import org.apache.poi.ss.usermodel.Cell; import org.apache.poi.ss.usermodel.DataFormatter; import org.apache.poi.ss.usermodel.Sheet; import org.apache.poi.ss.util.CellRangeAddress; import java.util.*; public class ColumnMergeStrategy extends AbstractMergeStrategy { private final Set<Integer> mergeColumns; private final int totalDataSize; private final Map<Integer, Integer> startRowMap = new HashMap<>(); private final DataFormatter dataFormatter = new DataFormatter(); public ColumnMergeStrategy(Set<Integer> mergeColumns, int totalDataSize) { this.mergeColumns = mergeColumns; this.totalDataSize = totalDataSize; } @Override protected void merge(Sheet sheet, Cell cell, Head head, Integer relativeRowIndex) { if (relativeRowIndex == null) { return; } int colIndex = cell.getColumnIndex(); if (!mergeColumns.contains(colIndex)) { return; } int rowIndex = cell.getRowIndex(); Integer start = startRowMap.get(colIndex); if (start == null) { startRowMap.put(colIndex, rowIndex); } else { String prevValue = getCellStringValue(sheet.getRow(rowIndex - 1).getCell(colIndex)); String currentValue = getCellStringValue(cell); if (!Objects.equals(prevValue, currentValue)) { if (rowIndex - start > 1) { sheet.addMergedRegion(new CellRangeAddress(start, rowIndex - 1, colIndex, colIndex)); } startRowMap.put(colIndex, rowIndex); } } if (relativeRowIndex == totalDataSize - 1) { int s = startRowMap.getOrDefault(colIndex, rowIndex); if (rowIndex - s + 1 > 1) { sheet.addMergedRegion(new CellRangeAddress(s, rowIndex, colIndex, colIndex)); } } } private String getCellStringValue(Cell cell) { if (cell == null) { return ""; } return dataFormatter.formatCellValue(cell); } }逻辑拆开看：每一列的合并状态用一个startRowMap记录“当前这段合并从哪一行开始”。当某个单元格的值和上一行同列不同时，说明上一段结束，结算范围[start, rowIndex-1]，如果长度大于 1 就调用addMergedRegion合并；然后把这一行设为新一段的起点。最后，当relativeRowIndex到达数据最后一行时，对每一列做一次收尾结算，把最后一段也合并上。
这里有几个细节值得说。第一，sheet.getRow(rowIndex - 1)拿的是上一行的物理行，必须保证它不为 null，正常数据连续写入不会有空行，但保险起见可以在取值前做空判断。第二，用DataFormatter转字符串来比较，是为了兼容数字、日期等类型，避免拿Cell对象直接equals出错——数字 1 和字符串 "1" 会判成不同，用格式化器统一成字符串更稳。第三，addMergedRegion区域不能重叠，我们的逻辑天然保证每段不重叠，所以安全。第四，数据总条数这里我假设是单次全量写入，如果是分页写入，这个totalDataSize就得换一种收尾判断方式，第 3.4 节会讲。
3.3 表头样式、列宽与导出接口
光有合并不够，导出的报表还得好看。合并之后有个副作用必须先处理——单元格一旦被合并，只有左上角那格保留样式，其余格子的边框会消失，看起来像被啃了一块。所以样式要在合并之前或统一设置好，通常用HorizontalCellStyleStrategy设置表头和内容的整体样式。
private HorizontalCellStyleStrategy buildStyleStrategy() { WriteCellStyle headStyle = new WriteCellStyle(); headStyle.setFillForegroundColor(IndexedColors.GREY_25_PERCENT.getIndex()); headStyle.setHorizontalAlignment(HorizontalAlignment.CENTER); headStyle.setVerticalAlignment(VerticalAlignment.CENTER); WriteFont headFont = new WriteFont(); headFont.setFontHeightInPoints((short) 11); headFont.setBold(true); headStyle.setWriteFont(headFont); WriteCellStyle contentStyle = new WriteCellStyle(); contentStyle.setHorizontalAlignment(HorizontalAlignment.CENTER); contentStyle.setVerticalAlignment(VerticalAlignment.CENTER); contentStyle.setWrapped(true); setBorder(contentStyle); return new HorizontalCellStyleStrategy(headStyle, contentStyle); } private void setBorder(WriteCellStyle style) { style.setBorderTop(BorderStyle.THIN); style.setBorderBottom(BorderStyle.THIN); style.setBorderLeft(BorderStyle.THIN); style.setBorderRight(BorderStyle.THIN); }边框样式我单独抽了个方法，因为四个方向都要设，写一起容易漏。表头用灰色填充加粗居中，内容居中且自动换行。列宽方面，EasyExcel 内置了LongestMatchColumnWidthStyleStrategy，能根据内容自动拉宽列，省得手工一个个设：
.registerWriteHandler(new LongestMatchColumnWidthStyleStrategy())不过要提醒，这个策略对纯中文的宽度估算在部分 POI 版本下不准确，可能出现一列内容“挤在一起”或“宽得离谱”的情况。我的处理是给它加个上限，或者干脆对关键列用sheet.setColumnWidth(colIndex, 20 * 256)手工定死。.xlsx里一列宽度的单位是字符宽，乘 256 是换算成 POI 用的单位。
导出接口就顺理成章了：
@GetMapping("/export/order") public void exportOrder(HttpServletResponse response) throws IOException { List<OrderExportVO> dataList = orderService.listForExport(); response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); response.setCharacterEncoding("utf-8"); String fileName = URLEncoder.encode("客户订单明细", "UTF-8").replaceAll("\\+", "%20"); response.setHeader("Content-Disposition", "attachment;filename*=utf-8''" + fileName + ".xlsx"); Set<Integer> mergeColumns = new HashSet<>(Arrays.asList(0, 2)); EasyExcel.write(response.getOutputStream(), OrderExportVO.class) .registerWriteHandler(buildStyleStrategy()) .registerWriteHandler(new LongestMatchColumnWidthStyleStrategy()) .registerWriteHandler(new ColumnMergeStrategy(mergeColumns, dataList.size())) .sheet("订单明细") .doWrite(dataList); }注意这里ColumnMergeStrategy的totalDataSize用的是dataList.size()，因为我们是一次性全量写入。文件名的中文必须用URLEncoder.encode处理，而且要把编码后的+替换成%20，否则中文文件名在某些浏览器里会变成一堆乱码或者空格。
3.4 大数据量分页导出与内存控制
数据量一大，上面那种一次性doWrite(dataList)就有问题了。虽然 EasyExcel 写内存比 POI 友好，但如果你把十万条数据先list()全查出来塞进一个 List，光这个 List 就够呛，更别提导出过程中框架还要构建单元格。正确姿势是分批查库、分批写入，用ExcelWriter手动控制。
ExcelWriter excelWriter = null; try { excelWriter = EasyExcel.write(response.getOutputStream(), OrderExportVO.class) .registerWriteHandler(buildStyleStrategy()) .build(); WriteSheet writeSheet = EasyExcel.writerSheet("订单明细").build(); int pageSize = 5000; int pageNo = 1; while (true) { List<OrderExportVO> page = orderService.pageForExport(pageNo, pageSize); if (CollectionUtils.isEmpty(page)) { break; } excelWriter.write(page, writeSheet); pageNo++; } } finally { if (excelWriter != null) { excelWriter.finish(); } }但分页写入和合并策略有一个天然矛盾：跨页的相同值合并会断掉。比如第 1 页最后一行和第 2 页第一行都是“张三”的订单，但它们被分成两次write，合并策略在页边界处看不到连续性，就会生成两个独立的合并段，中间断成两截。解决思路有三种：一是按“合并维度”来分页，保证同一个客户的订单不会被拆到两页；二是把页大小调大，减少边界出现概率，但不根治；三是记录上一页最后一行的值，在下一页第一行写入时用它做比较，实现跨页续接——这需要在策略里缓存上一页的收尾状态，代码复杂度会上升。
我的实际选择是第一种：分页查询时按客户或订单分组切分，保证同一分组的行落在同一页。这需要在查询层做点功课，比如先把分组的主键查出来，再按组批量拉明细。虽然麻烦一点，但合并结果最稳定，也不会因为导出逻辑的复杂度失控。另外那个totalDataSize的收尾判断在分页下也要调整，可以改成“每页写完时对当前页做一次收尾”，代价是页边界可能多合并一段，所以还是推荐按组切页。
提示：
ExcelWriter用完必须finish()，而且在finally里调用。如果中途抛异常没 finish，响应流可能被写了一半，前端下载到的是损坏文件。这个坑我在生产环境排查过一次，现象就是“偶尔下载的 Excel 打不开”。
4. 常见问题与排查技巧实录
4.1 合并后边框和样式丢失
这是最高频的反馈。改完合并逻辑，测试一看，合并的大格子里边框缺了一块。原因前面提过：POI 合并单元格后，只有左上角单元格的样式会保留并渲染，其余被合并掉的格子的样式就“看不见”了，尤其是边框，因为它本是画在单元格四边上的。
解决方式有两种。一种是让样式策略在合并之后依然生效——但HorizontalCellStyleStrategy是在写入单元格时设样式的，合并在其后，所以边框还是丢。更靠谱的做法是在自定义合并策略里，合并完成后，把合并区域左上角那个单元格的样式重新设置一遍，特别是补上四边边框。可以在addMergedRegion之后，拿到sheet.getRow(start).getCell(colIndex)，给它设一个带边框的CellStyle。
private void resetBorder(Sheet sheet, int startRow, int endRow, int colIndex) { CellStyle style = sheet.getWorkbook().createCellStyle(); style.setBorderTop(BorderStyle.THIN); style.setBorderBottom(BorderStyle.THIN); style.setBorderLeft(BorderStyle.THIN); style.setBorderRight(BorderStyle.THIN); Cell topLeft = sheet.getRow(startRow).getCell(colIndex); if (topLeft != null) { topLeft.setCellStyle(style); } }要注意createCellStyle创建的样式最好复用，别在循环里无限创建，否则样式数量会爆炸，Excel 打开时会报“样式过多”的警告。更优雅的方式是在合并策略里持有几个预建好的 CellStyle，反复使用。另一种更省事的方案是干脆不用 EasyExcel 的合并回调，导完后用 POI 打开文件重新画一遍边框，但那样又回到了 POI 的内存问题，得不偿失。
4.2 表头层级错位、列宽异常
表头错位通常有两类原因。一类是多级表头的父标题不一致——比如一处写“客户信息”，另一处写“客户资料”，框架就认为是两个不同的父级，合并自然对不上，还会出现该跨列的没跨。排查办法是盯着实体类注解，把相同父级的字符串逐字对齐，包括空格和标点。
另一类是表头层级深度不一致。比如大部分字段是两级表头，个别字段只写了一级，EasyExcel 在拼接时会按最大深度补齐，短的那些会在顶部留空，看起来像表头少了一块、整体下沉。解决办法就是所有导出字段的表头层级保持统一，要么全两级，要么该补的父级补上。
列宽异常的元凶通常是LongestMatchColumnWidthStyleStrategy对中文的估算。中文一个字占用约两个字符宽度，但 POI 的估算模型偏西文，容易出现中文列被算窄、内容“鼓”出来换行的情况。我的做法是给这个策略配合一个列宽上限，同时给那些明显偏窄的列手工setColumnWidth。还有一个细节是自动换行setWrapped(true)开了之后，如果列宽不够，单元格会换行把行高撑高，表头和内容对不齐，所以列宽要么给足，要么关掉换行。
注意：表头合并区域和列宽是两码事，父标题虽然横跨多列，但它的显示宽度是它所占各列宽度之和，单列太窄会显得父标题“挤”。合并表头的报表，列宽宁可宽一点。
4.3 大量数据导出 OOM 与超时
几万行以上，最怕的就是OutOfMemoryError: Java heap space，或者前端一直转圈等到网关超时。先厘清一个误区：EasyExcel 写模式并不是完全不占内存，它只是比 POI 全量构建要省，但你一次性塞几十万行，照样爆。所以第一步就是别全量list()，改成分页write，这一点在 3.4 节已经做了。
第二步是控制 JVM 堆。如果导出是偶发的大任务，可以在导出接口所在的服务上调大堆内存，比如-Xmx1g到-Xmx2g，但这不是根治手段，只是给缓冲。第三步是排查有没有别的地方在“撑”内存，最典型的是把EasyExcel.write(response.getOutputStream(), OrderExportVO.class)写成了EasyExcel.write(某个 ByteArrayOutputStream, ...)，然后再把字节数组写到响应流——这样一来整个 Excel 的字节全都堆在内存里，白瞎了 EasyExcel 的流式设计。正确做法是直接把response.getOutputStream()交给 EasyExcel。
超时问题则往往和网关、反向代理的响应超时配置有关。导出几万行可能要几十秒，如果网关设了 30 秒超时，请求就被掐断，用户看到“下载失败”。这类问题要么把导出做成异步任务（先返回任务 ID，前端轮询下载），要么调大相关超时。涉及具体环境的超时参数，我这里就不展开了，原则是“链路每一跳都要确认超时阈值”。
4.4 文件名乱码与下载失败
文件名乱码几乎是每个做导出的人都会遇到的。核心是响应头Content-Disposition的编码规范。浏览器对中文文件名有filename=和filename*=两套规范，前者用 ISO-8859-1，后者用 RFC 5987 规定的 UTF-8 编码。稳妥写法就是前面代码里的：
response.setHeader("Content-Disposition", "attachment;filename*=utf-8''" + URLEncoder.encode(fileName, "UTF-8").replaceAll("\\+", "%20") + ".xlsx");URLEncoder默认把空格编码成+，所以要把+换回%20，否则文件名里带空格就会显示成加号。
下载失败还有一类隐蔽原因：响应流已经被写过一部分，此时再抛异常。比如文件写到一半，某个单元格处理报错，异常抛出去被全局异常处理器接住，它又试图往同一个响应里写 JSON 错误信息，结果响应体就变成“前半段 xlsx 二进制 + 后半段 JSON”，前端下载下来打不开。规避办法是在导出接口里先把要用的数据、样式、策略都准备好，确保进入写文件阶段后尽量不抛业务异常；同时全局异常处理里对导出类接口做特判，一旦响应已提交就不要再写东西。这个坑我踩过一次，表现是“大部分时候正常，个别数据触发异常时下载到坏文件”。
把上面这些问题整理成一张速查表，排查时对照着看会快很多：
| 现象 | 可能原因 | 排查方向与处理 |
|---|---|---|
| 合并后边框消失 | 合并只保留左上角样式 | 在合并回调里重置左上角单元格边框样式 |
| 表头该合并的没合并 | 父标题字符串不一致 | 逐字对齐注解里的相同父级名称 |
| 表头整体下沉 | 表头层级深度不统一 | 统一各字段的层级，补齐父级标题 |
| 合并后出现碎格子 | 待合并列未排序，相同值不连续 | 导出 SQL 增加按合并维度的 ORDER BY |
| 最后一段没合并 | 逐格回调缺少收尾触发 | 用数据总数判断最后一行，主动收尾 |
| 分页导出合并断开 | 相同值被拆到两页 | 按分组切页，保证同组数据同页 |
| 导出 OOM | 全量 list 后一次性写入 | 改分页 write，直接用响应流写入 |
| 请求超时 | 网关或代理响应超时过短 | 改异步导出或调大超时阈值 |
| 文件名乱码 | Content-Disposition 编码不对 | 用 filename* 加 URLEncoder 编码 |
5. 参数调优与可复用工具类设计
5.1 合并性能与内存相关参数
合并本身是有成本的，每调用一次addMergedRegion都会在 sheet 上维护一个区域列表，合并区域越多，POI 在后续渲染和写出时的开销就越大。所以能减少合并次数就减少。最直接的一招是合理选择合并列：只合并真正需要的列，别把每一列都拿去合并。有些报表为了好看，把明细里其实每条都不同的列也纳入合并，结果是每次都在“新建一段”，白白增加开销。
第二个调优点是批量写入的页大小。页太小，write调用次数多，跨页合并断裂概率高；页太大，单页内存占用上升，收尾判断也更容易吃力。我实测下来，页大小设在 3000 到 5000 之间是个比较舒服的区间，既不至于频繁跨页，也不会一次性占用太多内存。具体值要结合单行数据的字段数量来调，字段多、单元格多，页就该小一点。
第三个点是避免在合并策略里做重活。比如有人图省事，在merge回调里每次去查一次数据库或者做复杂的正则，这会让本来 O(n) 的合并退化成灾难。策略里只做“读上一行值、比较、合并”这三件事，任何业务查询都放在数据准备阶段完成。还有，DataFormatter建议在策略里只 new 一次然后复用，别每个单元格都 new 一个，虽然它本身不重，但回调次数是行数乘以列数量级，积少成多。
5.2 把合并逻辑抽成通用工具类
一个项目里往往不止一张报表要合并，如果每张报表都复制一份合并策略，后期改起来会很痛苦。我的做法是把“按列合并相邻相同值”抽成一个通用策略类，只暴露两个配置入口：合并列索引集合、数据总数（或分页模式）。前面写的ColumnMergeStrategy基本就是通用形态，不同报表只是构造参数不同。
再进一步，还可以把整个导出流程封装成一个模板方法，比如ExcelExportTemplate.export(response, fileName, sheetName, clazz, styleStrategy, mergeColumns, dataProvider)，把响应头设置、writer 构建、分页循环、异常收尾都收进去。这样业务代码只剩“查数据、指定合并列、调用导出”三步，新人接手也不会把响应头写错。这里要强调的是，工具类里不要写死任何业务字段，合并列用索引传入，样式用策略对象传入，保持足够的中立性，才能真正复用。
另外分享一下我做样式时的经验：表头样式和内容样式各建一次，然后缓存成静态常量，不要每次导出都new WriteCellStyle()。POI 对工作簿内的样式数量是有上限的（.xls约 4000，.xlsx宽松很多但也有代价），如果导出批量大或者单元格巨多，反复创建样式会拖慢生成甚至触发样式超限的告警。样式对象一旦建好就复用，既省内存又省时间。这些看起来是小事，但在动辄几万行的导出任务里，累积效应很明显。
最后再补一个我实际调试用的小技巧：合并是否正确，别每次都启动整个项目去点导出看结果，那样反馈太慢。可以写一个单元测试，直接在本地FileOutputStream里导出一小批构造好的假数据，输出到本地文件，用 Excel 打开检查合并区域。假数据里特意造几组“连续相同”和“交叉不同”的值，专门用来验证边界——比如一整列全是同一个值、一整列全不重复、以及“A A B B A”这种带回跳的序列，能一次性把合并逻辑的漏洞暴露出来。调通之后再把数据源换成真实查询，效率高很多。
