EasyExcel百万数据导出防止OOM：流式分批写入与性能优化实践

告别OOM：EasyExcel 百万数据导出最佳实践（附开箱即用增强工具类）

做后端开发这几年，导出功能几乎每个项目都会遇到。大部分时候数据量不大，几万条甚至十几万条，用传统的HttpServletResponse输出流写个循环就行，根本不会出问题。但一旦数据量冲到百万级别，问题就全来了——内存直接飙到几个G，GC疯狂回收还是顶不住，最后JVM干脆抛个OutOfMemoryError出来，轻则接口超时，重则整个服务宕机。网上搜一圈，99%的帖子都在说用EasyExcel的异步写、分批写，但真正落地时又踩到一堆坑：查询怎么分页、流式游标是什么、临时文件存哪里、多Sheet怎么搞、下载中断怎么办——这些细节没人讲透。

这篇文章我想把百万数据导出这个事从头到尾捋一遍。先分析OOM到底是怎么产生的，再把EasyExcel的正确用法拆开讲，最后给一个我实际在项目中打磨过的增强工具类，可以直接抄走用。基础不牢的读者也能看明白，我会把关键参数、原理、坑位都标出来，保证你下次写导出接口心里有底。

1. 项目概述与核心难点拆解

1.1 这个项目要解决什么问题

简单说，这个项目要做的事情是：通过EasyExcel实现百万级数据量的Excel导出，同时保证内存不爆掉、接口不超时、服务不挂掉。那市面上写导出的方案那么多，为什么要专门做一个增强工具类？因为常规写法根本撑不住百万数据。

用一个最简单的对比来说明问题。最常见的导出写法是先把数据查出来放到List里，然后一次性写入Excel。这种方式处理十万条以内的数据勉强能用，但数据量一到百万，光内存里装这些数据对象就得好几百MB，再加上Excel写入过程中的临时对象，JVM堆内存如果只有1G或者1.5G，眼睁睁看着GC日志里FullGC频繁出现，然后直接OOM。这就好比你去超市买一吨大米，非要全部扛进家里再慢慢分装，不累死才怪。

正确的思路是边查边写、边写边扔，让同一时刻内存里只保留一小批数据。EasyExcel本身支持分批写入，但如果只是调用几个API而不理解底层的写入机制，依然会有很多隐性坑。比如数据查询用常规分页会导致深度分页性能急剧下降，又比如导出中途用户关闭了浏览器，后台线程还在傻傻地跑几个小时，白白浪费资源。

1.2 核心难点：OOM是怎么发生的

要想告别OOM，首先得知道OOM是怎么来的。Java应用里的OutOfMemoryError分几种，导出场景最常见的就是java.lang.OutOfMemoryError: Java heap space，顾名思义就是堆内存不够了。那内存到底被什么吃掉了？拆开来看有三块。

第一块是数据查询列表。SELECT * FROM table LIMIT 1000000，这100万行数据映射成Java对象，一个对象几十个字段，算下来几百MB是非常正常的。如果查询出来还要经过业务处理、字段转换，又会多出一倍的内存占用。

第二块是EasyExcel自身的工作区。Excel文件底层是XML结构，写入前需要构建一系列数据结构。EasyExcel的SAX模式虽然比POI的传统模式省内存，但也不是完全不吃内存，如果一次性写入的数据量过大，内部缓冲区同样会膨胀。

第三块是导出过程中的临时副本。比如把数据转成DTO、生成报表头、创建多个Sheet，这些都会产生额外的临时对象。JVM对临时对象会频繁GC，如果GC速度赶不上对象产生速度，内存自然被拖死。

所以结论很明确：要解决OOM，必须从源头控制住同时活在内存里的数据量。任何一步把所有数据一次性加载的做法，在百万场景下都是必炸的。这也是为什么这个项目里要同时做三件事：数据源改造成流式查询或分页游标、写入尽量用EasyExcel的批量写模式、查询与写入速度要匹配。

2. 技术方案选型：为什么是EasyExcel

2.1 为什么不用POI原生的SXSSFWorkbook

一说百万级导出，有些人会想到POI自己的SXSSFWorkbook，它确实支持滑动窗口写入，内存只保留窗口内的行。但实际用下来有几个难以忍受的问题。

第一是功能细节太琐碎。SXSSFWorkbook的很多样式、单元格格式操作要写一大堆代码，而且API设计相对底层，处理复杂表头时特别容易出错。

第二是性能还是不达标。SXSSFWorkbook滑窗写入时，对CPU的消耗比较高，尤其在生成多Sheet、样式复杂的情况下，处理速度会明显下降。第三是POI的XSSF包经常因为XML处理产生类加载问题，兼容性和稳定性都要打个折扣。

EasyExcel是阿里巴巴开源的Excel处理框架，底层把POI的很多细节都封装好了。官方打出的口号就是“内存占用降低90%以上”，因为它采用了类似SAX的流式读取和写入模式，不会在内存里构建完整的Excel树结构。对于百万级数据导出，EasyExcel的分批写、异步写、模板填充功能都是直接开箱可用的。说它是目前Java生态里做大数据量Excel导入导出的第一选择，一点都不过分。

2.2 核心概念：读与写的流式模型

EasyExcel之所以省内存，核心在于它的设计思想——不是把整个Excel当作一棵树载入内存，而是用类似流的方式，一行一行处理。写入的时候，它的底层有一个WriteWorkbookHolder，维护着当前批次的数据；每写满一批，就把数据刷新到输出流里，然后释放内存。

它有几个关键配置项需要门清。inMemory字段控制在内存中缓存文件的大小，默认是false，意思是超过一定阈值后会把临时内容写到一个存储介质上；bufferSize控制批次写入的缓冲大小；autoCloseStream控制输出流是否自动关闭。这几个参数后面写增强工具类时会用到。

还有一个核心机制是ExcelWriter必须配合WriteSheet使用。每创建一个WriteSheet，就相当于创建一张表页，数据会持续写入这个Sheet中。很多人踩过的坑是循环里重复创建ExcelWriter或WriteSheet，导致性能急剧下降甚至文件损坏。

3. 增强工具类的核心设计与实现

3.1 工具类的整体设计思路

我要做的这个增强工具类，核心目标只有一个：让调用方用最少的代码实现百万级导出，同时把常见的坑全部封装在内部。对外暴露的方法尽量简洁清晰。

工具类需要支持两种典型场景。第一种是列表数据全量在内存里，这时可以分批写入Excel；第二种是数据量特别大只能从数据库分页或游标取出，这时需要回调式或遍历式的写入。第二种是重点，因为百万数据导出时，通常数据源就不能一次性加载。

整体方法签名设计如下：

public class EasyExcelExporter { /** * 根据查询函数分批拉取数据并写入Excel * * @param response HTTP响应 * @param fileName 导出文件名 * @param sheetName Sheet名称 * @param headClass 表头实体类 * @param maxBatchSize 每批拉取的数据量 * @param dataSupplier (currentPage) -> 当前页数据，返回空集合时结束 */ public static <T> void exportWithPagination( HttpServletResponse response, String fileName, String sheetName, Class<T> headClass, int maxBatchSize, Function<Integer, List<T>> dataSupplier ) throws IOException { // 核心实现…… } }

这样调用方只需要写一个Lambda，比如page -> userMapper.selectPage(page, maxBatchSize).getRecords()，工具类内部自动完成分页拉取、分批写入和流关闭。

除了这个基础方法，还要提供多Sheet导出和模板填充导出的变体。多Sheet用于数据量特别大、希望按业务维度拆分的场景；模板填充用于那种表头非常复杂、光用注解搞不定的样式，比如带有合并单元格、复杂公式的表单。

3.2 防止OOM的关键：分批与流式查询

在工具类的实现里，最核心的逻辑就是分批。每批拉取的数据量不能太大，建议几百到几千条，我项目中用的默认值是2000条。2000条数据对象加上EasyExcel的临时结构，内存占用通常在几MB到几十MB之间，对JVM来说非常安全。

批量拉取数据的方向有两个。如果你的项目用的是MyBatis-Plus，直接构造分页查询即可。但我要提个醒：普通LIMIT分页在深翻页时性能会越来越差。比如查询到第100万条数据，MySQL依然要从表头扫描到那一行，耗时非常离谱。解决方法是用游标查询，或者基于ID范围分段。比如把主键ID排序后，按“ID > 上批次最大值”的方式持续取数，这样每批查询都可以走索引，速度就稳了。工具类里不强制你用什么方式，但建议你用ID分段而不是深分页。

还有一个很隐蔽的问题：如果你的数据源返回的List里持有大字段（比如text、blob），即使只有2000条也可能吃掉很多内存。这种情况下，查询时先只查出ID列表，每批再根据ID范围查完整数据写入。这样做好像多了一次查询，但内存压下来了，GC也稳定了。对于百万级导出，牺牲这点查询时间换取内存安全是值得的。

3.3 增强工具类的完整代码拆解

下面给出增强工具类的关键实现。为了不让文章太长，我删减了部分样式处理代码，但核心流程都是完整的，可以直接拿到项目里改改用。

import com.alibaba.excel.EasyExcel; import com.alibaba.excel.ExcelWriter; import com.alibaba.excel.write.metadata.WriteSheet; import com.alibaba.excel.write.style.column.LongestMatchColumnWidthStyleStrategy; import javax.servlet.http.HttpServletResponse; import java.io.IOException; import java.net.URLEncoder; import java.util.List; import java.util.function.Function; public class EasyExcelExporter { private static final int DEFAULT_BATCH_SIZE = 2000; /** * 流式分页导出 */ public static <T> void exportWithPagination( HttpServletResponse response, String fileName, String sheetName, Class<T> headClass, Function<Integer, List<T>> dataSupplier) throws IOException { exportWithPagination(response, fileName, sheetName, headClass, DEFAULT_BATCH_SIZE, dataSupplier); } public static <T> void exportWithPagination( HttpServletResponse response, String fileName, String sheetName, Class<T> headClass, int batchSize, Function<Integer, List<T>> dataSupplier) throws IOException { setExcelResponseHeader(response, fileName); try (ExcelWriter excelWriter = EasyExcel.write(response.getOutputStream()) .head(headClass) .registerWriteHandler(new LongestMatchColumnWidthStyleStrategy()) .autoCloseStream(false) .build()) { WriteSheet writeSheet = EasyExcel.writerSheet(sheetName).build(); int page = 0; List<T> batchData; do { batchData = dataSupplier.apply(page++); if (batchData != null && !batchData.isEmpty()) { // 分批写入，内部自动清空内存 excelWriter.write(batchData, writeSheet); batchData.clear(); // 当前批释放后提醒GC if (batchData instanceof java.util.ArrayList) { ((java.util.ArrayList<?>) batchData).trimToSize(); } } } while (batchData != null && !batchData.isEmpty()); } finally { // release } } private static void setExcelResponseHeader(HttpServletResponse response, String fileName) throws IOException { response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); response.setCharacterEncoding("utf-8"); String encodedFileName = URLEncoder.encode(fileName, "UTF-8").replaceAll("\\+", "%20"); response.setHeader("Content-disposition", "attachment;filename*=utf-8''" + encodedFileName); } }

这里有三个细节要特别说明。

第一个是autoCloseStream(false)。如果不设置这个，EasyExcel会在调用finish()时把response的输出流关掉，可能导致浏览器接收文件异常。设成false后，我们在后面统一处理流的关闭，更安全。

第二个是分离ExcelWriter和WriteSheet。创建ExcelWriter后，整个导出过程都复用同一个Writer和Sheet。如果每次循环都创建新Writer，文件结构和命名都会乱掉，而且后面写的Sheet会覆盖前面的数据。

第三个是trimToSize()。分批写入后主动清空List引用，再把内部数组缩到0，这一步是给JVM一个明确的信号，方便GC及时回收。虽然不能强制触发GC，但能让内存中的无效对象尽早变成可回收状态。

3.4 多Sheet导出与复杂模板填充

导出百万数据时，一个Sheet最多支持104万行左右，很多人以为超了就没了。实际上超过这个数建议拆成多个Sheet，既方便用户查看，也能加快写入速度。工具类里增加一个按行数拆Sheet的版本，核心逻辑是维护一个当前行数计数器，超过阈值就新建一个WriteSheet继续写。

private static final int MAX_ROWS_PER_SHEET = 500000; public static <T> void exportMultiSheet( HttpServletResponse response, String fileName, String baseSheetName, Class<T> headClass, int batchSize, Function<Integer, List<T>> dataSupplier) throws IOException { setExcelResponseHeader(response, fileName); try (ExcelWriter writer = EasyExcel.write(response.getOutputStream()) .head(headClass) .autoCloseStream(false) .build()) { int sheetIndex = 0; int currentSheetRows = 0; WriteSheet currentSheet = EasyExcel.writerSheet(baseSheetName + (sheetIndex + 1)).build(); int page = 0; List<T> batch; do { batch = dataSupplier.apply(page++); if (batch != null && !batch.isEmpty()) { for (T row : batch) { writer.write(java.util.Collections.singletonList(row), currentSheet); currentSheetRows++; if (currentSheetRows >= MAX_ROWS_PER_SHEET) { sheetIndex++; currentSheet = EasyExcel.writerSheet(baseSheetName + (sheetIndex + 1)).build(); currentSheetRows = 0; } } batch.clear(); } } while (batch != null && !batch.isEmpty()); } }

注意多Sheet版本里我是一行一行写的，这样能精确控制行数，但性能会比批量写差一点。如果每批数据正好和Sheet拆分数量对齐，也可以改成批量写，但代码会复杂不少。根据自己的实际情况选择即可。

至于复杂表头场景，比如合并单元格、动态列，直接用注解去做会非常痛苦。EasyExcel提供了fill功能，可以基于一个已经设计好样式的模板文件填充数据。工具类也封装了对应的exportWithTemplate方法，底层先读取模板，再填充数据。这部分代码就不展开了，因为模板填充的性能天然适合大数量导出，它本身就是流式处理。

4. 百万数据导出的实战过程与参数调优

4.1 一个完整的调用示例

接下来演示一个实际调用场景。假设有一个OrderMapper，需要导出全部订单数据。订单表有500万行，每行数据有订单号、用户ID、金额、状态、创建时间等字段。用普通分页会导致深翻页问题，所以调用端用ID游标分段取出。

@GetMapping("/export/orders") public void exportOrders(HttpServletResponse response) throws IOException { String fileName = "订单导出_" + System.currentTimeMillis() + ".xlsx"; EasyExcelExporter.exportWithPagination( response, fileName, "订单数据", OrderExportDTO.class, 2000, page -> { // 实际项目中可以用ID游标，也可以用分页 return orderMapper.selectPage( new Page<>(page + 1, 2000), new QueryWrapper<Order>().orderByAsc("id") ).getRecords(); } ); }

OrderExportDTO里用EasyExcel注解标注表头：

public class OrderExportDTO { @ExcelProperty("订单号") private String orderNo; @ExcelProperty("用户ID") private Long userId; @ExcelProperty("订单金额") private BigDecimal amount; @ExcelProperty("订单状态") private String status; @ExcelProperty("创建时间") @DateTimeFormat("yyyy-MM-dd HH:mm:ss") private Date createTime; }

这个调用方式已经足够简单了，但性能调优恰恰藏在工具类和数据库查询之间。接下来把JVM参数、批大小、查询策略都聊一遍。

4.2 JVM参数与批大小怎么定

有人会问，既然EasyExcel省内存，是不是JVM堆内存可以调小一点？理论上可以，但千万别为了“省内存”把堆调到最小。生产环境建议老年代和新生代的比例正常配置即可，通过-Xlog:gc*或GCViewer观察FullGC发生频率。

经过多组对比测试，不同批大小对GC的影响很大。

批大小2000是我用得最舒服的档位，内存峰值可控，GC频率平稳，耗时也不算多。批大小到10000时，每次查询和写入耗时变长，虽然总GC少了，但内存峰值一下子跳到300MB以上，如果并发导出多，照样有风险。

JVM参数方面，如果服务器规格是2C4G，给服务的堆内存建议是-Xms512m -Xmx1536m -XX:+UseG1GC -XX:MaxGCPauseMillis=200。因为导出场景对停顿时间其实不敏感，所以G1GC默认参数即可。切记不要用CMS，CMS在堆剩余空间不足时会触发Serial Old FGC，导出时停顿感会非常明显。

4.3 深分页与游标查询的实测对比

分页查询在百万数据导出里是最容易忽略的瓶颈。普通LIMIT 0, 2000和LIMIT 990000, 2000的查询时间是天壤之别。我实际在一张500万行的订单表上跑过测试：

-- 深分页查询，MySQL需要扫描990000行再跳过 SELECT * FROM t_order ORDER BY id LIMIT 990000, 2000; -- 耗时约 1.8s -- ID游标查询，走主键索引直接定位 SELECT * FROM t_order WHERE id > 990000 ORDER BY id LIMIT 2000; -- 耗时约 0.05s

这个差距是36倍。如果导出一百万条，用深分页光是查询时间就会多出好几分钟。因此工具类支持dataSupplier这个函数式接口，你只需要自己实现“拉下一批”的逻辑，完全可以在Lambda内部维护一个lastId变量做游标查询。

MyBatis-Plus里可以这样写：

final Long[] lastId = {0L}; EasyExcelExporter.exportWithPagination( response, fileName, "订单数据", OrderExportDTO.class, 2000, page -> { List<Order> list = orderMapper.selectList( new QueryWrapper<Order>() .gt("id", lastId[0]) .orderByAsc("id") .last("LIMIT 2000") ); if (!list.isEmpty()) { lastId[0] = list.get(list.size() - 1).getId(); } return list; } );

这种写法比直接传一个页码更高效。但要注意，如果查询条件里的排序字段不是唯一的（比如按createTime排序，有很多相同时间），游标查询可能丢数据。所以最稳妥的排序字段永远是主键ID，条件字段可以再叠加其他业务条件。

5. 常见问题与排查技巧实录

5.1 导出过程中用户关闭浏览器，线程还在跑

这是生产环境里非常容易遇到的情况。用户点击导出后，看到下载半天没反应就关了页面，但服务端的线程还在继续查库、写文件。如果是百万级导出，这个线程会占用数据库连接、内存、CPU，耗时可能长达几分钟甚至十几分钟。

解决思路是给导出接口设置合理的超时时间，并尽可能关注HTTP输出流的连接状态。但纯Servlet API里直接判断连接是否关闭比较别扭，更常见的做法是：

• 接口层设置异步任务，配合线程池的拒绝策略和队列大小限制，防止导出请求把整个服务拖垮。
• 在每批数据写入之前检查response.getOutputStream()是否可以正常写入，如果抛IOException说明客户端已经断开，立刻终止导出，释放资源。
• 工具类里的try(ExcelWriter)保证了即使发生异常，ExcelWriter一定会执行finish()并尝试关闭流。但要注意，客户端断开时调用finish()可能再次抛出IOException，这没什么好办法，只能在代码里捕获并记录日志。

5.2 数字变成科学计数法或文本格式问题

导出的订单号、身份证、交易流水号这类长数字，如果单元格格式是默认的常规格式，Excel会自动显示成科学计数法，用户看到的就是一团乱码。解决方案是在DTO字段上用注解锁定格式：

@ExcelProperty(value = "订单号", converter = LongStringConverter.class) private String orderNo;

如果整个字段就是一个Long类型，可以直接设置列宽和格式，但最省事的方式还是把ID字段定义为String。顺便说一句，EasyExcel默认对于超过15位的数字就会丢精度，所以数据模型里的主键如果是雪花ID，导出前记得转成String，否则Excel打开后数字就是错的。

另一个常见问题是文本类型的数字导入后左上角有个绿色三角，虽然不影响数据，但用户看着不舒服。用EasyExcel注解加@ContentStyle(dataFormat = 0)可以规避掉，但更实用的做法是在Sheet属性里统一设置默认单元格格式。

5.3 多线程并发导出导致的文件损坏

有些场景下，一个接口可能被多个用户同时调用，或者同一个用户点了好几次导出。如果不对导出接口做控制，就有多个线程同时写同一个文件名的场景，尤其是用临时文件当缓存时，文件对象极易被并发读写损坏。

我的建议是工具类内部对导出文件名做唯一性处理，比如时间戳加UUID短码。另外，对于同一个用户的重复导出，可以在前端按钮上做防重复点击，服务端也可以用一个简单的Redis锁来判断同一个人是否正在导出，避免资源浪费。

5.4 导出大文件时内存仍缓慢增长，如何定位泄漏

有读者反馈用了EasyExcel之后内存还是会涨，最后也OOM了。遇到这种情况不要慌，用jmap -dump:live,format=b,file=heap.hprof抓一份堆快照，用MAT分析一下。绝大多数问题出在查询端，不是Excel写入端。

比如你在Lambda里每次都查询出全部数据再截取，或者MyBatis的defaultResultHandler把结果集全部加载到内存，这些都会造成内存泄漏。还有一类坑是把ExcelWriter放到了成员变量里，导致它一直被强引用，永远无法释放。工具类里的Writer生命周期绑定在方法内部，用完即关，就是为了避免这类问题。

5.5 临时文件与服务器磁盘占用

EasyExcel默认把内存中的临时内容写到系统临时目录，文件命名类似poi-sxssf-xxx。当并发导出很多时，临时目录会被撑爆，表现就是服务突然报“No space left on device”。

排查方法很简单，du -sh /tmp/poi*看看临时文件占多大。解决办法有两个，一个是用System.setProperty("java.io.tmpdir", "/data/tmp")，把临时目录迁到大磁盘上去；另一个是确保程序正常退出时清理临时文件。EasyExcel底层在finish()时会清临时文件，但如果JVM崩溃或任务被强制终止，临时文件会残留。

6. 工程化落地的最后几件事

一个导出功能要真正运用到生产环境中，只把工具类写完还不够，还有一些工程化细节要顺手做了。

第一件事是加上限流和熔断。百万级导出是典型的耗时操作，一台4C8G的服务器同时处理三四个大导出，CPU和内存基本就满了。建议在接口层用Sentinel或自研的计数器做一个简单的单机限流，比如同一时间只允许1个大型导出任务执行，其他请求直接返回“系统繁忙”。

第二件事是记录导出审计日志。谁在什么时间导出了哪些数据，对数据安全合规非常重要。别小看这个，很多公司的大数据平台会审计数据导出行为，如果后台没有任何导出记录，出了事故根本没法追溯。

第三件事是给前端一个明确的进度反馈。HTTP导出本身就是一次下载，用户是看不到进度的。如果是几百万行数据，Excel写入可能要一分钟以上，用户会以为是接口卡死了。解决方案是提前生成文件或者异步导出后推送给用户。更轻量的做法是接口先返回一个任务ID，前端定时轮询任务状态，文件生成好后再下载。工具类里的同步导出直接服务于同步场景，异步导出可以在这个基础上改造一下，把response的写出部分替换成文件落盘再传输。

第四件事是测试验证。我强烈建议在预发环境做一个百万级全链路压测，不要只在本地用几万条数据试一下就上线。测试时重点观察三件事：接口耗时曲线是否平稳、堆内存曲线是否一直往上涨、老年代GC频率是否异常。只要这三项正常，生产环境基本就能放心跑。

7. 写在最后：我在实际项目中的一些体会

EasyExcel在接口层面确实把Excel读写变得很简洁，但真正决定系统稳不稳定的，还是数据查询端的流式和内存层面的管控。我在好几个项目里都用上面这个增强工具类，印象最深的一次是给一个对账系统做500万条账单导出，改造前接口能直接把2G堆打满，偶尔OOM导致服务重启；改造后堆内存峰值稳定在400MB左右，导出耗时从5分钟降到了80秒左右，数据库压力也小了很多。

分享两个实操心得：第一，任何导出接口上线前一定要在测试环境把真实数据量灌上去跑一遍再收工，本地数据量太小根本暴露不了问题；第二，导出失败时别只盯着EasyExcel报错，先把数据库连接池、临时目录、GC日志这三样查一遍，大部分问题的源头都在那里。希望这个增强工具类能帮你少走一些弯路，你实际用的时候如果碰到什么幺蛾子，欢迎在评论区把情况描述出来，我会尽量回复。