告别EasyExcel复杂场景痛点：Apache POI+FastExcel组合实战

如果你在 Java 后端跟 Excel 打过交道，大概率用过或者至少听说过 EasyExcel。这个库确实帮很多人摆脱了 Apache POI 那套繁琐的 API，读大文件时内存占用控制得也不错。但当我真正在做复杂业务导入导出时，情况就开始变了：复杂表头、模板填充合并单元格、嵌套 List、POI 版本冲突、Linux 服务器缺字体库，这些事一件接一件冒出来，EasyExcel 用起来越来越不“easy”。最近社区里聊得比较多的替代方案是 FastExcel，还有朋友把名字记成了 Apache Fesod。我这边已经把核心模块从 EasyExcel 迁到了一个以 Apache POI 为底座的组合方案上，这篇文章就把我的完整思路、踩坑过程、还有能直接抄的代码整理出来。

先别急着问 Apache Fesod 是什么，我先把结论说了：Apache 基金会官方目前并没有叫 Fesod 的项目。大家最近在说的“Fesod”，大概率是 FastExcel 这个社区分支被念串了，或者是把 Apache POI 生态里的某个工具名记混了。所以这篇文章里我不会虚构一个不存在的库，而是以真实存在、社区还比较活跃的 FastExcel 和 Apache POI 为主线，讲讲我是怎么从 EasyExcel 迁移过来，以及那些让 EasyExcel 用户崩溃的问题到底怎么解决。

1. 为什么我要跟 EasyExcel 说再见

1.1 先给 EasyExcel 一个客观评价

EasyExcel 最大的贡献，是把 Apache POI 的 user model 模式做了一层更友好的封装。以前用 POI 写导出，要自己创建 Workbook、Sheet、Row、Cell，还要处理样式和合并单元格，代码量很大。EasyExcel 用注解加一行调用就能搞定，比如读文件只需要EasyExcel.read(file, DemoData.class, listener).sheet().doRead()，写文件也类似。这让大量 CRUD 项目的 Excel 处理门槛一下子降了下来，再加上 SAX 模式的流式读，内存表现确实比 POI 的 DOM 模式好很多。

但问题也出在这层封装上。EasyExcel 帮我把 80% 的简单场景变得很简单，剩下 20% 的复杂场景，封装的抽象反而成了阻碍。尤其是碰到多级表头、模板填充合并单元格、嵌套列表渲染这类需求时，注解和模板表达式覆盖不住，你必须绕过 EasyExcel 直接操作底层 POI 对象。而一旦走到这步，EasyExcel 的封装就有点像个半透明的壳，改起来既别扭又容易踩版本坑。

更现实的问题是迭代节奏。这几年 EasyExcel 的更新明显放缓，不少长期存在的 issue 一直没人处理。比如模板填充时合并单元格错位的问题，在 GitHub 上挂了很久，官方一直没有特别好的解法。社区里等不及的人开始自己 fork，FastExcel 就是这么出来的。

1.2 我在真实项目里踩过的五个大坑

我在一个订单管理后台里负责导入导出模块，功能不算复杂，但需求很典型：导入客户发的对账单、导出订单明细、用模板生成报价单。就这几个场景，我把 EasyExcel 的坑踩了个遍。

第一个坑是复杂表头导入。客户给的对账单表头有三行，第一行是总标题，第二行是分组，第三行才是真正的字段名，而且很多单元格是合并的。EasyExcel 的@ExcelProperty虽然支持多级表头，但它是把表头层级写死在类上的，字段多了、表头结构变了，注解就得跟着改一遍，维护成本非常高。更不能接受的是，遇到动态列或者客户临时加列的情况，注解方案几乎没法处理。

第二个坑是模板填充的合并单元格。我们有个报价单模板，模板里已经画好了表格样式，包括一系列合并单元格，比如“产品信息”这个单元格竖向合并三行。用 EasyExcel 的 fill 功能往里塞数据时，问题就来了：fill 是流式按行写的，模板里的合并区域是静态的，数据行一多，合并区域不会跟着扩展，最后导出的文件要么合并范围不对，要么数据把合并单元格冲散。这个问题让我加班到凌晨两点。

第三个坑是单元格换行。需求是导出时单元格内容有换行，比如收货地址分三行显示。EasyExcel 默认写字符串时，字符串里虽然有\n，但单元格样式没有开启WrapText，Excel 里看就是不换行，只有编辑栏能看到内容。你得自己拿到 CellStyle 去设置，等于绕过了 EasyExcel 的封装。

第四个坑是嵌套 List 渲染。模板里要渲染订单和订单明细，大概是“订单头一行，明细若干行，下一个订单头一行”这种结构。EasyExcel 的模板填充只支持一层list，你想在模板里写类似{{order.items}}这种嵌套语法，它根本解析不了。网上搜“java + easyexcel 如何渲染嵌套 list”，能搜到一堆同病相怜的人。

第五个坑是版本冲突。项目里为了处理别的功能，引入了 Apache POI 5.x，结果 EasyExcel 内部依赖的 POI 版本和项目里的对不上，启动直接报java.lang.NoSuchFieldError: factory。这种问题定位起来特别费劲，因为报错堆栈根本不指向你的业务代码，而是指向 POI 内部类。还有一次在生产环境的 Linux 服务器上，导出功能突然报字体库相关错误，查了半天发现是系统缺libfreetype6，和代码一点关系都没有。

这五个坑每个单拎出来都能写一篇排查记录。它们的共同点是：问题都出在 EasyExcel 封装边界之外的 POI 层，或者是 EasyExcel 适配不好的边界场景。于是我开始认真评估替代方案。

2. 替代方案选型：不是所有“替代”都叫 Apache

2.1 关于“Apache Fesod”的澄清

先说标题这个事。不少人把 FastExcel 记成了“Apache Fesod”，我一开始也以为是某个新的 Apache 顶级项目，但去 Apache 官网翻了一圈，并没有这个名字。FastExcel 实际上是社区里基于 EasyExcel 做的优化分支，本质还是依赖 Apache POI 做底层解析和写入。它保留了 EasyExcel 的大部分 API 习惯，同时修了一些老 issue，在读写性能和模板填充上做了增强。

所以要理解“用 Apache Fesod”，正确的理解是：你用了 FastExcel，并且通过它调用底层的 Apache POI 能力。Apache 基金会真正提供的 Excel 处理库是 Apache POI，这是绕不开的地基。搞清楚这个关系之后，选型思路就清晰多了：要么继续在 EasyExcel 的封装层里挣扎，要么往下沉一层，直接掌握 POI 的灵活性。

2.2 一个本质认识：EasyExcel 本身就是 Apache POI 的封装

很多用 EasyExcel 的人可能没注意，EasyExcel 并不是从零实现的 Excel 解析，它的底层就是 Apache POI。读文件时用的是 POI 的 SAX 事件解析模型，写文件时用的也是 POI 的 XSSF 组件。也就是说，你在 EasyExcel 上遇到的大部分底层问题，本质上都是 POI 的问题。

这个认识帮我解决了很多困惑。比如NoSuchFieldError: factory，它其实是 POI 内部字段在不同版本间变化导致的，和 EasyExcel 的 API 没关系。比如 Linux 上缺字体库，那也是 POI 渲染字体时才依赖系统库，EasyExcel 只是个调用方。

所以选型的时候，不要只想着换一个封装库，而是要考虑：我需要的是封装，还是底层控制力？如果你的业务里全是简单表格，封装越薄越好用；一旦出现复杂模板、动态列、特殊样式，你需要的是直接操作 POI 的能力。FastExcel 的价值在于，它封住简单场景，同时不阻碍你访问底层 POI 对象。

2.3 从 EasyExcel 到 FastExcel：迁移成本最低的路线

如果你确定要换，最快的路线不是重写，而是切到 FastExcel。它是一个兼容 EasyExcel API 的社区分支，很多代码只需要改 import 就能跑起来，比如把com.alibaba.excel换成对应的fastexcel包名。注解、Listener、写 Excel 的基本套路都差不多，团队上手成本很低。

我实际迁移时比预想顺利。核心导出代码改了大约 10 分钟，主要工作是批量替换 import 和调整个别 API 参数。复杂表头导入那块我没有继续依赖注解，而是直接改成 POI 解析，这部分代码数量反而少了，因为不再需要维护@ExcelProperty的层级映射。

有一点要提醒：FastExcel 毕竟是社区项目，不是 Apache 官方维护的，选型前要评估你们的项目对第三方分支的依赖接受度。如果公司对开源组件有严格的合规要求，更稳妥的方案是直接用 Apache POI 自己封装一层读写的工具类，把复杂的逻辑掌握在自己手里。

2.4 什么时候值得换、什么时候别折腾

我自己总结了一套判断标准。如果你的项目只是简单导出列表、导入单层表头的数据，EasyExcel 完全够用，不要为了换而换，新依赖引入的风险和测试成本与收益不成正比。但如果你的项目里有以下情况，就可以考虑换了：

• 模板填充时经常遇到合并单元格扩展、嵌套数据结构的问题；
• 需要使用多级表头导入，而且表头结构在公司内部经常变化；
• 项目里已经引入了 Apache POI，且与 EasyExcel 自带 POI 版本冲突；
• 生产环境是 Linux，导出涉及字体渲染，需要精准控制 POI 的运行环境。

我把三个方案放在一张表里对比了一下：

真实的情况是，我现在既没用纯粹的 EasyExcel，也不是纯 POI，而是“FastExcel + 关键场景直接操作 POI”的组合。简单导出用 FastExcel，导入解析和复杂模板用自己封装的 POI 工具类。这样两边都不折腾。

3. 实战：拿下复杂表头、模板填充与合并单元格

3.1 解决复杂表头导入：POI 拆表头 + 数据行逐行读

先说复杂表头导入。我的做法是彻底放弃注解绑定表头，改成动态解析。核心思路分三步：先把表头行数读出来，解析每个单元格的值和层级关系；然后处理合并单元格，把合并区域的值复制到该区域覆盖的所有坐标上；最后从表头结束的下一行开始，按列号读取数据，列名作为 Map 的 key。

下面这段代码是我工具类的核心，表头占几行可以从 Excel 的样式特征判断，也可以由一个配置项传进来。

public List<Map<String, String>> parseSheet(InputStream in, int headerRowCount) throws IOException { Workbook workbook = WorkbookFactory.create(in); try { Sheet sheet = workbook.getSheetAt(0); // 第一步：根据表头行数构建列名映射 Map<Integer, String> headerMap = buildHeaderMap(sheet, headerRowCount); // 第二步：数据行从表头下一行开始 List<Map<String, String>> rows = new ArrayList<>(); for (int rowIdx = headerRowCount; rowIdx <= sheet.getLastRowNum(); rowIdx++) { Row row = sheet.getRow(rowIdx); if (row == null) { continue; } Map<String, String> rowData = new HashMap<>(); for (int colIdx = row.getFirstCellNum(); colIdx < row.getLastCellNum(); colIdx++) { Cell cell = row.getCell(colIdx); if (cell == null) { continue; } String header = headerMap.get(colIdx); if (header != null && !header.isBlank()) { rowData.put(header, getCellStringValue(cell)); } } rows.add(rowData); } return rows; } finally { workbook.close(); } }

buildHeaderMap是关键。它先扫一遍合并区域，把合并单元格左上角的值填充到整个合并区域；然后按表头行数逐行扫描，取最后一行的文本作为当前列的最终列名。如果业务中需要上层表头做分组，可以在这一步额外把第一行和第二行拼起来，比如“基本信息_客户名称”，这样后续数据校验时连列来源都知道。

private Map<Integer, String> buildHeaderMap(Sheet sheet, int headerRowCount) { // 第一步：合并单元格值扩展到覆盖范围 List<CellRangeAddress> mergedRegions = sheet.getMergedRegions(); Map<String, String> cellValueMap = new HashMap<>(); for (CellRangeAddress region : mergedRegions) { Cell firstCell = sheet.getRow(region.getFirstRow()).getCell(region.getFirstColumn()); String value = (firstCell == null) ? "" : getCellStringValue(firstCell); for (int r = region.getFirstRow(); r <= region.getLastRow(); r++) { for (int c = region.getFirstColumn(); c <= region.getLastColumn(); c++) { cellValueMap.put(r + "_" + c, value); } } } // 第二步：取最后一行的表头作为列名 Map<Integer, String> headerMap = new HashMap<>(); Row headerRow = sheet.getRow(headerRowCount - 1); if (headerRow == null) { return headerMap; } for (int colIdx = headerRow.getFirstCellNum(); colIdx < headerRow.getLastCellNum(); colIdx++) { String key = (headerRowCount - 1) + "_" + colIdx; String value = cellValueMap.getOrDefault(key, getCellStringValue(headerRow.getCell(colIdx))); headerMap.put(colIdx, value); } return headerMap; }

这个方案最直接的好处是：客户换表头结构时，我不需要改 Java 代码，只要调整配置里的表头行数，最多改一下列名映射规则。对比原来用 EasyExcel 注解一个字段一个字段绑定的方式，维护成本低了一个量级。

3.2 模板填充最头痛的合并单元格与嵌套 List

模板填充合并单元格的问题，根因是 fill 机制只负责按行写数据，不负责维护模板里的静态合并区域。你以为数据行扩展时合并区域会自动跟着扩展，实际上不会。我曾经导出的报价单，产品信息的合并单元格固定覆盖前三行，但数据有十几行，结果表格完全乱掉。

我的解法是：填充完数据后，自己手动重算合并区域。核心逻辑是先把模板里原有的合并区域保存下来，然后按数据行数重新创建CellRangeAddress。注意一个坑：Sheet.removeMergedRegion的参数是下标，而且移除一个后，后面的下标会往前移，所以必须从后往前移除，否则会越界或者移错区域。

private void expandMergedRegions(Sheet sheet, int headerRows, int totalDataRows, int rowsPerRecord) { // 先保存原始合并区域，注意要新建列表，避免引用的是同一个集合 List<CellRangeAddress> original = new ArrayList<>(); for (int i = 0; i < sheet.getNumMergedRegions(); i++) { original.add(sheet.getMergedRegion(i)); } // 从后往前移除动态区域的合并，避免下标错乱 for (int i = sheet.getNumMergedRegions() - 1; i >= 0; i--) { CellRangeAddress region = sheet.getMergedRegion(i); if (region.getLastRow() > headerRows) { sheet.removeMergedRegion(i); } } // 按扩展后的总行数重新添加合并区域 int newLastRow = headerRows + totalDataRows * rowsPerRecord - 1; for (CellRangeAddress region : original) { if (region.getLastRow() <= headerRows) { continue; } sheet.addMergedRegion(new CellRangeAddress( region.getFirstRow(), newLastRow, region.getFirstColumn(), region.getLastColumn())); } }

至于嵌套 List 渲染，我劝你别在模板表达式上死磕。EasyExcel 和 FastExcel 的内置 fill 都只支持单层列表。我的做法很务实：先把嵌套结构拍平成单层结构，每条明细一行，订单头信息在明细的第一行复制一份，然后在模板里用普通列表填充。

List<Map<String, Object>> flatRows = new ArrayList<>(); for (Order order : orderList) { boolean isFirst = true; for (OrderItem item : order.getItems()) { Map<String, Object> row = new HashMap<>(); if (isFirst) { row.put("orderId", order.getId()); row.put("customerName", order.getCustomerName()); row.put("orderDate", order.getCreateTime()); isFirst = false; } row.put("itemName", item.getName()); row.put("price", item.getPrice()); row.put("quantity", item.getQuantity()); flatRows.add(row); } }

拍平之后，模板里就剩一个普通列表，fill 解析没有任何压力。缺点是遇到“订单头占有独立一行，明细另起若干行”这种布局时，拍平方案会让订单头信息重复出现在每一行明细里。针对这种严格布局，我最后直接放弃模板，用 POI 代码生成整张表，反而更好控制。模板适合固定样式，动态结构模板管不住，这点要认清。

3.3 单元格换行与样式控制

单元格换行的坑前面提过，这里给一个完整的解法。Excel 单元格显示换行需要两个条件：单元格内容里有换行符，且单元格样式开启了 WrapText。用 FastExcel 写字符串时，即使字符串里有\n，默认样式也不会开启换行。解决办法是拿到底层 POI 的 CellStyle 自行设置。

CellStyle style = workbook.createCellStyle(); style.setWrapText(true); style.setAlignment(HorizontalAlignment.CENTER); style.setVerticalAlignment(VerticalAlignment.CENTER); Cell cell = row.createCell(colIndex); cell.setCellStyle(style); cell.setCellValue("第一行\n第二行\n第三行");

光设置 WrapText 还不够，行高也要够，否则少数行还是显示不全。Excel 里如果行高是自动的，WrapText 开启后会按内容自动撑高；但 POI 生成的文件里，行高默认值是固定的，所以需要手动估算行高。一个简单粗暴的经验值：行高 = 内容里最大换行数 × 单行高度（大约 15 到 16 磅），再加一点余量。

int lineCount = content.split("\n", -1).length; float rowHeight = lineCount * 15.0f + 5.0f; row.setHeightInPoints(rowHeight);

这里有个细节：从 Excel 复制的文本里也可能带着\r\n，读文件时最好统一处理掉\r，只保留\n，否则换行可能会异常。我在工具类里写了一个normalizeNewLine方法，所有进入导出流程的字符串都过一遍。

3.4 版本冲突 NoSuchFieldError factory 的根因与修复

NoSuchFieldError: factory是我见过最多的 EasyExcel 疑难杂症。这个报错的本质是 classpath 里有多个版本的 POI，或者 POI 版本和 EasyExcel 期望的版本不兼容。JVM 加载类时，某个字段在当前版本里被删了或者改了名字，就抛NoSuchFieldError。

处理思路分两步：先统一项目里的 POI 版本，再把 EasyExcel 自带的 POI 排除掉。第一步用 Maven 的 dependencyManagement 锁定版本。

<dependencyManagement> <dependencies> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi</artifactId> <version>5.2.5</version> </dependency> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>5.2.5</version> </dependency> </dependencies> </dependencyManagement>

第二步在引入 EasyExcel 时排除掉它内部依赖的 POI。否则即使 dependencyManagement 锁了版本，有些组件还是会因为传递依赖把旧版本带进来。

<dependency> <groupId>com.alibaba</groupId> <artifactId>easyexcel</artifactId> <version>3.3.4</version> <exclusions> <exclusion> <groupId>org.apache.poi</groupId> <artifactId>poi</artifactId> </exclusion> <exclusion> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> </exclusion> <exclusion> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml-schemas</artifactId> </exclusion> </exclusions> </dependency>

如果你已经切换到 FastExcel，思路完全一样。排查时先用这个命令看依赖树：

mvn dependency:tree -Dincludes=org.apache.poi

输出里如果出现 4.1.2、5.2.3、5.2.5 多个版本，基本就是这次报错的元凶。另外一个经验：不要为了迁就一个老组件把 POI 钉死在 3.x，现在很多新的 Excel 功能都依赖 4.x 以上 API，版本越老，字段兼容问题越难解。

3.5 Linux 下 libfreetype6 缺失

这个坑和 EasyExcel 没有直接关系，但用 POI 生态导出时会遇到。生产环境是 Linux，导出的 Excel 里如果涉及图表、字体宽度计算、或者某些样式渲染，可能抛java.lang.NoClassDefFoundError: sun/font/FontManagerFactory或者依赖 FreeType 的底层异常。原因是 JDK 在 Linux 上渲染字体时，需要系统提供 FreeType 字体库。

网上搜“easyexcel libfreetype6”，你会发现一堆人在生产环境遇到这个问题。解法其实很朴素，让 Linux 装好字体库和字体，尤其是中文字体，否则中文宽度计算也会异常。

apt-get update apt-get install -y libfreetype6 fontconfig fonts-wqy-zenhei fc-cache -f

如果你是 Docker 部署，记得把这些命令写进 Dockerfile，不要手动进容器装，否则镜像一重建又没了。还有一个更省心的办法：如果导出的文件不涉及图表，也没必要触发字体渲染，可以调整代码避免生成图片或图表，这样就不依赖系统字体库。但报表类系统往往绕不开图表，该装库还是装库。

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

4.1 问题速查表

把前面遇到的坑整理成一张速查表，方便后续排查对照。

这六类问题占了 Excel 处理模块日常故障的绝大部分。如果你也在维护类似系统，建议直接把这几个检查项写进团队的排查文档，能省不少事。

4.2 一次 NoSuchFieldError 的完整排查过程

有一次升级项目依赖后，导出功能突然挂掉，报错堆栈指向org.apache.poi.ss.usermodel.CellStyle的某个字段。我第一反应就是 POI 版本冲突，于是执行mvn dependency:tree -Dincludes=org.apache.poi，结果发现项目里同时有三个版本的 POI：一个是 EasyExcel 传递依赖的 4.1.2，一个是业务组件传递的 3.17，还有一个是我自己代码里显式引入的 5.2.5。

Maven 的依赖仲裁规则会选最近的版本，但问题是有些组件在编译时用的是旧版本的 API，运行时却被加载到新版本的类，新旧类的字段对不上，JVM 直接抛NoSuchFieldError。这种问题最难缠的地方在于：它不是每次都会报，可能在开发环境好的，部署到服务器才炸，因为 classpath 顺序不同。

修复过程就是上面说的两步：先锁定 POI 版本到 5.2.5，再把 EasyExcel 的 POI 依赖排除掉。改完后这个报错彻底消失。后来我把所有 Excel 相关模块都改成显式依赖 POI 版本，不依赖传递依赖的“巧合”，同类问题再没出现过。

4.3 关于选型的一点建议

我现在固定下来的组合是：简单列表导出用 FastExcel，复杂模板和动态合并直接操作 Apache POI，版本统一锁定在 5.2.x，生产环境镜像里预装字体库。说实话，这套组合并没有让代码量变少，但让问题变“透明”了。以前在 EasyExcel 封装层里排查底层问题，总像隔着一层雾；现在出了问题，我能直接定位到 POI 的哪个类、哪段逻辑在捣乱。

如果你刚开始做 Excel 处理模块，我的建议是别急着套模板或者找“万能库”，先把 Apache POI 的基础 API 摸一遍。知道 Workbook、Sheet、Row、Cell 是怎么一层层组织的，知道合并区域和样式是怎么生效的，后面无论用哪个封装库，出了问题都能快速定位。踩过几次坑之后你会慢慢发现，Excel 处理的很多问题不是难在 API，而是难在封装层和底层之间的信息不对称。把这一层想透了，比换任何库都管用。