Java POI多级表头Excel导出：树形模型、动态布局与SXSSF性能优化

1. 项目概述与核心痛点

最近在做一个后台管理系统的报表模块，产品经理拿着原型图过来，指着那个密密麻麻、层层嵌套的Excel表头问我：“这个能导出来吗？”我一看，好家伙，典型的“多级表头”需求，比如一个销售报表，第一行是“部门”，下面分出“A组”和“B组”，“A组”下面又分出“Q1销售额”、“Q2销售额”……这种结构在POI的基础教程里可找不到现成答案。网上搜了一圈，要么是简单的两三级合并，要么代码写得又臭又长，耦合度高到没法复用。所以，我花了点时间，沉淀出了一套清晰、可扩展的Java POI多级表头导出方案。这篇文章，我就把这个从设计思路到代码落地的完整过程，包括那些容易踩的坑和性能优化的细节，毫无保留地分享给你。无论你是正在被复杂报表折磨的开发，还是想深入学习POI高级用法的朋友，这篇内容都能让你直接“抄作业”，快速搞定这个棘手的场景。

简单说，我们要解决的核心问题是：如何用Apache POI库，动态、灵活地生成具有任意层级和跨列合并关系的Excel表头，并保证代码的维护性和导出性能。这不仅仅是调用几个mergeCells接口那么简单，它涉及到表头数据结构的抽象、单元格合并策略的计算以及样式管理的复杂性。

2. 核心设计思路与数据结构抽象

直接上手写合并单元格的代码，很快就会陷入泥潭。我的经验是，先把“多级表头”这个业务概念，翻译成程序能理解的数据结构。这是最关键的一步，设计好了，后面代码写起来行云流水；设计差了，就得不停地打补丁。

2.1 为什么需要抽象表头模型？

POI的SXSSFWorkbook或XSSFWorkbook只提供了操作单元格（Cell）和行（Row）的底层API。它不知道什么是“部门”、“季度”。如果我们直接把业务字段名（如deptName,q1Sales）硬编码到循环里，那么一旦表头结构发生变化（这在业务系统中太常见了），就需要重写大量逻辑。因此，我们必须建立一个中间层——一个能描述表头层级、跨度和标题的模型。

2.2 树形结构：最自然的映射

多级表头本质上就是一个树形结构。最顶层的根节点可以理解为整个表格的标题（有时不需要），第一级表头是树的第二层节点，它们可能有子节点，以此类推。树的叶子节点，对应的是最终数据列的表头，也是我们需要填充数据的列。

我设计了一个HeaderNode类来承载这个模型：

import lombok.Data; import java.util.ArrayList; import java.util.List; /** * 表头节点模型 */ @Data public class HeaderNode { /** * 表头显示名称 */ private String title; /** * 对应的数据字段名（用于数据填充，叶子节点必备） */ private String fieldName; /** * 子节点列表 */ private List<HeaderNode> children; /** * 节点层级（根节点为0，从1开始计算实际表头层级） */ private int level; /** * 在Excel中的起始列索引（0-based） */ private int startCol; /** * 在Excel中的结束列索引（0-based） */ private int endCol; /** * 在Excel中的行索引（0-based） */ private int rowIndex; public HeaderNode(String title) { this.title = title; this.children = new ArrayList<>(); } public HeaderNode(String title, String fieldName) { this.title = title; this.fieldName = fieldName; this.children = new ArrayList<>(); } /** * 添加子节点 */ public HeaderNode addChild(HeaderNode child) { if (this.children == null) { this.children = new ArrayList<>(); } this.children.add(child); return this; } /** * 判断是否为叶子节点（即最终的数据列） */ public boolean isLeaf() { return children == null || children.isEmpty(); } }

这个模型的核心字段是title,children,startCol,endCol。fieldName是叶子节点特有的，用于后续绑定数据。startCol和endCol会在后续的布局计算中自动填充，它们定义了单元格合并的范围。

2.3 构建一个真实的表头树例子

光看模型可能有点抽象，我们用一个具体的销售报表来构建这棵树：

// 构建一个三级表头 // 第一级：部门 HeaderNode deptHeader = new HeaderNode("部门"); // 第二级：A组、B组 HeaderNode groupA = new HeaderNode("A组"); HeaderNode groupB = new HeaderNode("B组"); // 第三级：A组下的季度销售额（叶子节点，关联数据字段） HeaderNode aQ1 = new HeaderNode("Q1销售额", "aQ1Sales"); HeaderNode aQ2 = new HeaderNode("Q2销售额", "aQ2Sales"); HeaderNode bQ1 = new HeaderNode("Q1销售额", "bQ1Sales"); HeaderNode bQ2 = new HeaderNode("Q2销售额", "bQ2Sales"); // 组装树形结构 groupA.addChild(aQ1).addChild(aQ2); groupB.addChild(bQ1).addChild(bQ2); deptHeader.addChild(groupA).addChild(groupB); // 还可以有另一个一级表头，如“人员信息” HeaderNode infoHeader = new HeaderNode("人员信息"); HeaderNode nameCol = new HeaderNode("姓名", "name"); HeaderNode empIdCol = new HeaderNode("工号", "empId"); infoHeader.addChild(nameCol).addChild(empIdCol); // 根节点列表（可以没有实际的根，用List<HeaderNode>表示第一级表头） List<HeaderNode> rootHeaders = new ArrayList<>(); rootHeaders.add(deptHeader); rootHeaders.add(infoHeader);

通过这样的结构，我们就把“部门-A组-Q1销售额”这样的业务关系，用程序对象清晰地表达出来了。后续所有的操作，都基于这个树形结构展开。

实操心得：在定义HeaderNode时，我强烈建议使用Lombok的@Data注解来减少getter/setter的样板代码。同时，fieldName的设计至关重要，它是连接表头和数据实体的桥梁。确保叶子节点的fieldName与你的数据对象属性名一致，或者可以通过反射、Map键值对等方式匹配。

3. 表头布局计算与单元格合并算法

有了表头树，下一步就是把这棵树“画”到Excel的网格上。这需要解决两个核心问题：1. 每个节点应该占据多少列？2. 每个节点应该在哪一行？

3.1 深度优先遍历计算列跨度

一个节点的列跨度（endCol - startCol + 1），等于它所有叶子节点后代的数量。因为叶子节点才对应最终的数据列。计算这个值，需要一个递归的深度优先遍历（DFS）。

我为HeaderNode增加一个计算方法：

/** * 计算并设置当前节点及其所有子节点的列跨度信息 * @param startColIndex 当前节点起始的列索引 * @return 当前节点占据的最后一列的索引 */ public int calculateLayout(int startColIndex) { this.startCol = startColIndex; // 如果是叶子节点，只占据一列 if (this.isLeaf()) { this.endCol = startColIndex; return startColIndex; } // 非叶子节点，遍历子节点 int currentCol = startColIndex; for (HeaderNode child : this.children) { // 递归计算子节点的布局，并更新当前列指针 currentCol = child.calculateLayout(currentCol); currentCol++; // 移动到下一列 } // 因为循环最后多加了1，需要减回来，才是当前节点的结束列 this.endCol = currentCol - 1; return this.endCol; }

这个方法需要从根节点（或第一级节点）开始调用，并传入起始列索引（通常是0）。

int colIndex = 0; for (HeaderNode header : rootHeaders) { colIndex = header.calculateLayout(colIndex); colIndex++; // 处理完一个根节点，移动到下一列开始 } // 循环结束后colIndex-1就是总列数

执行完这个计算后，树中每个节点的startCol和endCol就都被正确赋值了。例如，“A组”节点会计算出它的startCol和endCol，正好覆盖了“Q1销售额”和“Q2销售额”两列。

3.2 层级与行索引分配

表头的层级决定了行索引。第一级表头在第0行，第二级在第1行，以此类推。我们需要知道整棵树的最大深度，以确定需要创建多少行表头。

/** * 计算节点的层级（相对于根） * @param node 当前节点 * @param currentLevel 当前层级 */ public static void calculateLevel(HeaderNode node, int currentLevel) { node.setLevel(currentLevel); if (!node.isLeaf()) { for (HeaderNode child : node.children) { calculateLevel(child, currentLevel + 1); } } } // 计算最大深度，用于确定表头行数 public static int getMaxDepth(List<HeaderNode> rootNodes) { int maxDepth = 0; for (HeaderNode node : rootNodes) { maxDepth = Math.max(maxDepth, getDepth(node)); } return maxDepth; } private static int getDepth(HeaderNode node) { if (node.isLeaf()) { return node.getLevel(); } int maxChildDepth = node.getLevel(); for (HeaderNode child : node.children) { maxChildDepth = Math.max(maxChildDepth, getDepth(child)); } return maxChildDepth; }

在渲染时，我们遍历所有节点，如果节点的level等于当前正在处理的行号rowIndex，就在该行的[startCol, endCol]区间创建单元格并设置值。对于非叶子节点（startCol<endCol），就需要进行单元格合并。

3.3 递归渲染表头到Sheet

这是将计算好的布局应用到POISheet对象的关键步骤。我们采用按行渲染的策略：

/** * 渲染表头到指定的Sheet * @param sheet POI Sheet对象 * @param rootNodes 根节点列表 * @param startRowIndex 表头开始的行索引（通常为0） */ public static void renderHeader(Sheet sheet, List<HeaderNode> rootNodes, int startRowIndex) { int maxDepth = getMaxDepth(rootNodes); // 1. 创建表头行 Row[] headerRows = new Row[maxDepth]; for (int i = 0; i < maxDepth; i++) { headerRows[i] = sheet.createRow(startRowIndex + i); } // 2. 递归渲染每个节点 for (HeaderNode node : rootNodes) { renderNode(sheet, headerRows, node, startRowIndex); } } private static void renderNode(Sheet sheet, Row[] headerRows, HeaderNode node, int baseRowIndex) { int targetRowIndex = baseRowIndex + node.getLevel() - 1; // 计算在headerRows中的实际索引 Row targetRow = headerRows[targetRowIndex]; // 创建单元格并设置值 Cell cell = targetRow.createCell(node.getStartCol()); cell.setCellValue(node.getTitle()); // 应用样式（下一节详述） // cell.setCellStyle(headerStyle); // 如果需要合并单元格（非叶子节点且跨越多列） if (!node.isLeaf() && node.getStartCol() < node.getEndCol()) { CellRangeAddress region = new CellRangeAddress( targetRowIndex, // 起始行 targetRowIndex, // 结束行（同一行） node.getStartCol(), // 起始列 node.getEndCol() // 结束列 ); sheet.addMergedRegion(region); // 注意：合并后，只有第一个单元格（startCol）有值，需要居中显示 } // 递归渲染子节点 if (!node.isLeaf()) { for (HeaderNode child : node.children) { renderNode(sheet, headerRows, child, baseRowIndex); } } }

这个renderNode方法会遍历整棵树，在合适的行和列位置创建单元格、赋值、合并。注意，CellRangeAddress的参数是包含性的，即(0,0,0,2)表示合并第0行的第0、1、2列。

注意事项：POI的合并单元格(addMergedRegion)有一个重要的特性：合并后，只有区域左上角那个原始单元格（在我们的代码里就是startCol对应的Cell）的内容和样式会被保留。其他被合并的单元格即使之前创建并设置了内容，也会被忽略。因此，我们的逻辑是先创建所有单元格并赋值，然后再添加合并区域，这样逻辑最清晰。有些教程先合并再赋值，容易导致索引错乱。

4. 样式管理、性能优化与边界处理

表头画出来了，但如果全是默认样式，黑体白底，那也太丑了。而且，当数据量大了以后，性能和内存都是挑战。这一部分，我们聊聊怎么把表头做得既美观又高效。

4.1 集中式样式管理

在POI中，CellStyle对象是绑定到Workbook的，而不是Cell。创建大量重复的CellStyle是内存浪费。最佳实践是创建一个样式工厂（或工具类），在整个导出过程中复用样式。

public class CellStyleUtil { private final Workbook workbook; private Map<String, CellStyle> styleCache = new HashMap<>(); public CellStyleUtil(Workbook workbook) { this.workbook = workbook; initDefaultStyles(); } private void initDefaultStyles() { // 1. 默认表头样式 CellStyle headerStyle = workbook.createCellStyle(); Font headerFont = workbook.createFont(); headerFont.setBold(true); headerFont.setFontHeightInPoints((short) 11); headerStyle.setFont(headerFont); headerStyle.setAlignment(HorizontalAlignment.CENTER); headerStyle.setVerticalAlignment(VerticalAlignment.CENTER); headerStyle.setFillForegroundColor(IndexedColors.GREY_25_PERCENT.getIndex()); headerStyle.setFillPattern(FillPatternType.SOLID_FOREGROUND); headerStyle.setBorderTop(BorderStyle.THIN); headerStyle.setBorderBottom(BorderStyle.THIN); headerStyle.setBorderLeft(BorderStyle.THIN); headerStyle.setBorderRight(BorderStyle.THIN); styleCache.put("HEADER", headerStyle); // 2. 数据行样式 CellStyle dataStyle = workbook.createCellStyle(); dataStyle.setAlignment(HorizontalAlignment.LEFT); dataStyle.setVerticalAlignment(VerticalAlignment.CENTER); dataStyle.setBorderTop(BorderStyle.THIN); // ... 设置其他边框 styleCache.put("DATA", dataStyle); // 可以创建更多样式，如“货币格式”、“日期格式”等 } public CellStyle getHeaderStyle() { return styleCache.get("HEADER"); } public CellStyle getDataStyle() { return styleCache.get("DATA"); } // 获取其他样式的方法... }

在渲染表头时，直接从CellStyleUtil获取样式并设置：

// 在renderNode方法中 cell.setCellStyle(styleUtil.getHeaderStyle());

对于合并的单元格，为了让内容真正居中，我们需要在合并后，对那个唯一的单元格再次应用居中对齐的样式（尽管创建时已经应用了，但有些情况下显式设置更安全）。

4.2 使用SXSSFWorkbook应对大数据量

如果导出的数据行数可能上万，甚至几十万，使用传统的XSSFWorkbook（.xlsx）或HSSFWorkbook（.xls）很容易导致内存溢出（OutOfMemoryError）。POI提供了SXSSFWorkbook，它是一个流式版本的实现，原理是在内存中只保持一定数量的行（一个滑动窗口），将之前的行写入临时文件。

// 创建SXSSFWorkbook，并指定在内存中保留的行数（例如100行） SXSSFWorkbook workbook = new SXSSFWorkbook(100); Sheet sheet = workbook.createSheet("销售报表"); // ... 使用前面同样的方法渲染表头和数据 // 写入文件 try (FileOutputStream out = new FileOutputStream("large_report.xlsx")) { workbook.write(out); // 重要：清理临时文件 workbook.dispose(); }

重要提示：

1. SXSSFWorkbook的dispose()方法必须调用，用于删除临时文件，否则会堆积在磁盘上（通常是系统临时目录）。
2. SXSSFWorkbook不支持某些特性，如公式求值、复制单元格样式到新行等。但对于纯数据导出和格式化的表头，它完全胜任。
3. 滑动窗口大小（构造函数参数）需要权衡。太小会增加IO频率，影响速度；太大会占用更多内存。100-1000是一个常见范围。

4.3 处理复杂边界情况

在实际开发中，你肯定会遇到一些“奇怪”的需求，下面是我踩过坑后总结的解决方案：

情况一：表头层级深度不一致（非满树）比如，“部门”下面有三级，“人员信息”只有一级。我们的树形模型和calculateLayout算法天然支持这种情况。getMaxDepth会返回最大深度（例如3），渲染时，较浅的节点只会在其存在的层级渲染，更深层的行对应位置就是空的，这符合预期。

情况二：动态表头有时表头结构需要根据查询条件动态生成。这要求我们的HeaderNode构建过程也是动态的。可以将表头配置存储在数据库或JSON中，导出时解析配置并构建树。核心算法（布局计算、渲染）完全不用变，只需改变树的构建源。

// 伪代码：从JSON配置动态构建 String headerConfigJson = "..."; // 从数据库或接口获取 List<HeaderNode> dynamicHeaders = parseJsonToHeaderTree(headerConfigJson); // 后续的calculateLayout和renderHeader照旧

情况三：超宽表头（列数超过Excel限制）Excel不同版本有列数限制（.xls是256列，.xlsx是16384列）。在计算完布局后，可以检查endCol是否超过限制。如果超过，需要在设计阶段就与产品经理沟通，拆分报表或调整表头结构。

情况四：单元格样式继承与覆盖你可能希望不同层级的表头有不同的背景色。可以在HeaderNode中增加一个styleKey字段，在renderNode时根据这个key从CellStyleUtil获取不同的样式。或者在renderNode方法中，根据node.getLevel()来动态决定样式。

5. 数据填充、导出流与完整示例

表头渲染好了，接下来就是把数据填进去，并完成最终的导出流程。

5.1 基于字段名的数据填充

我们之前为叶子节点定义了fieldName。现在假设我们有一组数据对象List<SalesData>。填充数据的核心是根据列索引找到对应的fieldName，再从数据对象中取出值。

首先，我们需要一个从列索引到fieldName的映射。在布局计算完成后，遍历所有叶子节点即可构建：

/** * 构建列索引到字段名的映射 * @param rootNodes 根节点列表 * @return Map<列索引, 字段名> */ public static Map<Integer, String> getColumnFieldMapping(List<HeaderNode> rootNodes) { Map<Integer, String> mapping = new HashMap<>(); traverseLeaves(rootNodes, mapping); return mapping; } private static void traverseLeaves(List<HeaderNode> nodes, Map<Integer, String> mapping) { for (HeaderNode node : nodes) { if (node.isLeaf()) { mapping.put(node.getStartCol(), node.getFieldName()); } else { traverseLeaves(node.getChildren(), mapping); } } }

然后，在数据填充循环中使用这个映射：

public static void fillData(Sheet sheet, List<?> dataList, Map<Integer, String> fieldMapping, int headerRowCount) { CellStyleUtil styleUtil = new CellStyleUtil(sheet.getWorkbook()); int startRowIndex = headerRowCount; // 表头占用的行数之后开始数据行 for (int i = 0; i < dataList.size(); i++) { Object data = dataList.get(i); Row row = sheet.createRow(startRowIndex + i); // 遍历所有有定义的列 for (Map.Entry<Integer, String> entry : fieldMapping.entrySet()) { int colIndex = entry.getKey(); String fieldName = entry.getValue(); Cell cell = row.createCell(colIndex); // 使用反射或工具类（如BeanUtils、Map）获取字段值 Object value = getFieldValue(data, fieldName); setCellValue(cell, value); // 根据值类型（String, Number, Date）设置 cell.setCellStyle(styleUtil.getDataStyle()); } } } // 一个简单的反射取值方法（需处理异常和性能，生产环境建议缓存Field或使用BeanUtils） private static Object getFieldValue(Object obj, String fieldName) { try { Field field = obj.getClass().getDeclaredField(fieldName); field.setAccessible(true); return field.get(obj); } catch (Exception e) { // 日志记录 return null; } }

对于更复杂的场景，数据对象可能是Map<String, Object>，那么取值就简化为map.get(fieldName)。使用反射时要注意性能，如果数据量极大，可以考虑预编译Field对象或使用MethodHandle。

5.2 使用Response流进行Web导出

在Web应用中，我们通常需要将Excel直接写入HttpServletResponse的输出流，让用户下载。

@GetMapping("/exportSalesReport") public void exportSalesReport(HttpServletResponse response) { // 1. 准备数据 List<SalesData> dataList = salesService.getReportData(); List<HeaderNode> header = buildSalesHeader(); // 构建表头 // 2. 创建工作簿（使用SXSSF应对大数据） SXSSFWorkbook workbook = new SXSSFWorkbook(100); try { Sheet sheet = workbook.createSheet("销售报表"); // 3. 计算表头布局并渲染 int colIndex = 0; for (HeaderNode node : header) { colIndex = node.calculateLayout(colIndex); colIndex++; } int maxDepth = getMaxDepth(header); renderHeader(sheet, header, 0); // 4. 构建字段映射并填充数据 Map<Integer, String> fieldMapping = getColumnFieldMapping(header); fillData(sheet, dataList, fieldMapping, maxDepth); // 5. 可选：自动调整列宽（大数据时慎用，耗性能） for (int i = 0; i < fieldMapping.size(); i++) { sheet.autoSizeColumn(i); } // 6. 设置响应头，触发浏览器下载 String fileName = URLEncoder.encode("销售报表.xlsx", "UTF-8").replaceAll("\\+", "%20"); response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); response.setHeader("Content-Disposition", "attachment;filename*=UTF-8''" + fileName); // 7. 写入响应流 workbook.write(response.getOutputStream()); response.getOutputStream().flush(); } catch (Exception e) { // 异常处理，记录日志，可能返回错误信息 throw new RuntimeException("导出Excel失败", e); } finally { // 8. 重要：清理SXSSF临时文件 if (workbook != null) { workbook.dispose(); } } }

关键点：

• 文件名编码：使用URLEncoder并处理空格（+号）是兼容各种浏览器的好习惯。
• Content-Type：.xlsx文件对应MIME类型是application/vnd.openxmlformats-officedocument.spreadsheetml.sheet。
• Content-Disposition：attachment表示下载，filename*使用RFC 5987编码支持中文。
• 流关闭：确保输出流正确关闭，但通常response.getOutputStream()由Servlet容器管理，我们只需flush，不要close它。
• 异常处理：导出失败时，如果响应已部分提交，再想返回JSON错误信息就难了。一种做法是在操作前进行预检查，另一种是捕获异常后尝试重置响应（response.reset()），但这在某些情况下可能无效。最稳妥的是做好日志记录和前端超时、断点续传的兼容设计。

5.3 完整工具类与使用示例

将上述所有步骤封装成一个工具类ExcelExporter，可以让导出功能变得非常简单：

public class ExcelExporter { private Workbook workbook; private Sheet sheet; private CellStyleUtil styleUtil; private List<HeaderNode> headers; private Map<Integer, String> fieldMapping; public ExcelExporter(List<HeaderNode> headers) { this.headers = headers; // 默认使用SXSSF this.workbook = new SXSSFWorkbook(100); this.styleUtil = new CellStyleUtil(this.workbook); this.sheet = workbook.createSheet("Sheet1"); initialize(); } private void initialize() { // 1. 计算布局 int colIndex = 0; for (HeaderNode node : this.headers) { colIndex = node.calculateLayout(colIndex); colIndex++; } // 2. 渲染表头 int maxDepth = getMaxDepth(this.headers); renderHeader(this.sheet, this.headers, 0, styleUtil); // 3. 构建字段映射 this.fieldMapping = getColumnFieldMapping(this.headers); } public void fillData(List<?> dataList) { int headerRowCount = getMaxDepth(headers); // ... 调用之前实现的fillData方法 internalFillData(sheet, dataList, fieldMapping, headerRowCount, styleUtil); } public void writeToStream(OutputStream outputStream) throws IOException { workbook.write(outputStream); } public void dispose() { if (workbook instanceof SXSSFWorkbook) { ((SXSSFWorkbook) workbook).dispose(); } } // ... 其他辅助方法 }

使用这个工具类，业务代码变得非常简洁：

public void export(HttpServletResponse response) { List<HeaderNode> header = buildHeader(); // 构建表头 List<MyData> data = getData(); // 获取数据 ExcelExporter exporter = new ExcelExporter(header); exporter.fillData(data); response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); response.setHeader("Content-Disposition", "attachment;filename=report.xlsx"); try (OutputStream out = response.getOutputStream()) { exporter.writeToStream(out); } catch (IOException e) { log.error("导出失败", e); } finally { exporter.dispose(); } }

6. 常见问题排查与性能调优实录

即使按照上面的步骤操作，在实际项目中你还是可能会遇到一些棘手的问题。下面是我在多次实践中总结出来的“避坑指南”。

6.1 表头错位或合并区域异常

现象：表头文字没有出现在合并后的单元格中央，或者合并区域覆盖了不该覆盖的单元格。排查步骤：

1. 检查startCol和endCol计算：在calculateLayout方法后，打印或调试查看每个非叶子节点的startCol和endCol。确保endCol - startCol + 1等于其所有叶子子孙的数量。
2. 验证合并区域坐标：在addMergedRegion之前，打印CellRangeAddress的四个参数。确保起始行和结束行相同（因为我们只做同行合并），且起始列小于等于结束列。
3. 确认渲染顺序：必须是先创建所有单元格并设置值，再执行合并。如果顺序反了，或者试图在合并区域内的非首个单元格设置值，值是无效的。
4. 检查行创建：确保表头的每一行（Row对象）都已正确创建。如果某一行没创建，却试图在其上合并单元格，会抛出NullPointerException。

一个简单的调试方法是在renderNode里加入日志：

private static void renderNode(..., HeaderNode node, ...) { // ... if (!node.isLeaf() && node.getStartCol() < node.getEndCol()) { CellRangeAddress region = ...; System.out.println(String.format("Merging [%d,%d,%d,%d] for node '%s'", region.getFirstRow(), region.getLastRow(), region.getFirstColumn(), region.getLastColumn(), node.getTitle())); sheet.addMergedRegion(region); } }

6.2 导出速度慢或内存溢出（OOM）

对于速度慢：

1. 禁用自动调整列宽：sheet.autoSizeColumn(i)是一个非常耗时的操作，它会计算每列所有单元格内容的宽度。对于上万行数据，这个操作可能占导出总时间的80%以上。如果对列宽要求不严格，可以移除这行代码，或者只对前N行（如100行）进行估算后设置固定列宽。
2. 检查样式创建：确保CellStyle和Font是复用的，而不是在每个单元格处都创建新的。使用前面提到的CellStyleUtil缓存样式。
3. 使用SXSSFWorkbook：对于大数据量，这是必须的。但注意滑动窗口大小，太小（如10）会导致频繁的磁盘IO，反而降低速度。通常设置100-500是一个平衡点。
4. 优化数据获取：数据查询本身可能是瓶颈。确保数据库查询有合适的索引，避免N+1查询问题。考虑分页查询并流式写入，但这对业务逻辑改动较大。

对于内存溢出：

1. 首要原因：未使用SXSSF。这是最经典的OOM场景。立即切换到SXSSFWorkbook。
2. SXSSF滑动窗口设置过大。如果数据有100万行，窗口设为10000，内存压力依然很大。根据你的JVM堆大小调整，通常100-1000足够。
3. 内存中持有过多数据对象。即使使用了SXSSF，如果你的List<Data>一次性从数据库加载了100万条记录到内存，同样会OOM。解决方案是使用分页查询+流式写入：

   int pageSize = 1000; int pageNum = 0; while (true) { List<Data> page = dataService.getDataPage(pageNum, pageSize); if (page.isEmpty()) { break; } fillData(sheet, page, fieldMapping, currentRowIndex); currentRowIndex += page.size(); pageNum++; // 重要：及时清空对当前页数据的引用，帮助GC page = null; }

4. 忘记调用dispose()。SXSSFWorkbook产生的临时文件会一直堆积，直到磁盘空间耗尽，虽然这不直接导致JVM OOM，但会影响系统。

6.3 样式丢失或不生效

现象：设置了单元格样式（如背景色、边框），但导出的Excel里看不到。可能原因和解决：

1. 样式对象被覆盖：POI的CellStyle是有限的（早期版本有数量限制）。如果你不断workbook.createCellStyle()，超过限制后，新创建的样式可能会覆盖旧的。务必使用缓存复用。
2. 合并单元格的样式：记住，合并后只有第一个单元格的样式有效。如果你需要整个合并区域有边框，必须对合并区域所有原始单元格（而不仅仅是第一个）在合并前设置边框样式。或者，一个更常见的做法是：先合并，然后获取合并后区域左上角那个单元格，对其设置样式，这个样式会应用到整个区域（但边框有时有例外，为保险起见，可以遍历区域设置每个单元格的边框）。
3. 字体问题：中文字体显示为方框。确保服务器环境安装了中文字体，或者在创建Font时使用支持的字体名，如Font font = workbook.createFont(); font.setFontName("SimSun");（宋体）。

6.4 在Web导出中响应已提交的错误

现象：导出过程中发生异常，尝试在Controller里返回一个JSON错误信息，但前端收到的是乱码或下载提示。原因：在调用workbook.write(response.getOutputStream())时，一旦有数据写入输出流，HTTP响应头就已经提交了。此时再想通过@RestControllerAdvice返回JSON或设置不同的状态码，为时已晚。解决方案：

1. 预校验：在开始写入流之前，尽可能完成所有可能失败的操作（如数据查询、权限校验、参数验证）。
2. 使用缓冲：可以先写入一个ByteArrayOutputStream，确认全部操作成功后，再将其写入HttpServletResponse。

   try (ByteArrayOutputStream baos = new ByteArrayOutputStream()) { workbook.write(baos); // 一切顺利，再设置响应头并写入 response.setContentType(...); response.setHeader(...); response.getOutputStream().write(baos.toByteArray()); } catch (Exception e) { // 这里还可以返回错误JSON，因为响应头还未提交 response.reset(); // 重置响应 response.setContentType("application/json"); // ... 写入错误信息JSON }

   注意：这种方法会将整个Excel文件先加载到内存（ByteArrayOutputStream），不适用于超大文件导出。对于大文件，预校验是更可行的方案。
3. 前端配合：前端做好超时和错误处理。如果后端导出失败，流可能会提前关闭，前端可以通过监听fetch或XMLHttpRequest的error/abort事件来提示用户。

6.5 关于公式、图表与更复杂格式

本文聚焦于多级表头和数据导出，这是最常见的需求。如果你还需要：

• 公式：使用cell.setCellFormula("SUM(A2:A10)")。注意，在SXSSF中，公式求值可能需要额外的处理。
• 图表：POI支持创建图表，但API非常复杂。对于复杂的报表，更常见的做法是使用模板引擎（如JXLS、EasyExcel的模板功能）或直接使用Excel模板文件，在预留的位置用POI填充数据。这比完全用代码“画”出整个报表要简单和灵活得多。
• 条件格式、数据验证等：POI都支持，但代码会比较冗长。评估需求，如果非常复杂，模板可能是更好的选择。

最后，再分享一个我个人的小技巧：在开发阶段，尤其是调试表头布局时，可以不直接写文件到响应流，而是先写到一个本地文件，然后用Excel打开检查。这样能更直观地看到问题所在，比看日志打印的列索引要高效得多。