如果你在 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 上挂了很久官方一直没有特别好的解法。社区里等不及的人开始自己 forkFastExcel 就是这么出来的。1.2 我在真实项目里踩过的五个大坑我在一个订单管理后台里负责导入导出模块功能不算复杂但需求很典型导入客户发的对账单、导出订单明细、用模板生成报价单。就这几个场景我把 EasyExcel 的坑踩了个遍。第一个坑是复杂表头导入。客户给的对账单表头有三行第一行是总标题第二行是分组第三行才是真正的字段名而且很多单元格是合并的。EasyExcel 的ExcelProperty虽然支持多级表头但它是把表头层级写死在类上的字段多了、表头结构变了注解就得跟着改一遍维护成本非常高。更不能接受的是遇到动态列或者客户临时加列的情况注解方案几乎没法处理。第二个坑是模板填充的合并单元格。我们有个报价单模板模板里已经画好了表格样式包括一系列合并单元格比如“产品信息”这个单元格竖向合并三行。用 EasyExcel 的 fill 功能往里塞数据时问题就来了fill 是流式按行写的模板里的合并区域是静态的数据行一多合并区域不会跟着扩展最后导出的文件要么合并范围不对要么数据把合并单元格冲散。这个问题让我加班到凌晨两点。第三个坑是单元格换行。需求是导出时单元格内容有换行比如收货地址分三行显示。EasyExcel 默认写字符串时字符串里虽然有\n但单元格样式没有开启WrapTextExcel 里看就是不换行只有编辑栏能看到内容。你得自己拿到 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. 替代方案选型不是所有“替代”都叫 Apache2.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 的运行环境。我把三个方案放在一张表里对比了一下维度EasyExcelApache POIFastExcel社区分支上手难度低高低读大文件内存占用低SAX高user model低同 EasyExcel复杂表头控制有限灵活有限同 EasyExcel模板填充合并单元格支持差自己实现有改进复杂仍要手工底层版本冲突风险存在自己控制同 EasyExcel维护状态迭代放缓Apache 活跃社区活跃真实的情况是我现在既没用纯粹的 EasyExcel也不是纯 POI而是“FastExcel 关键场景直接操作 POI”的组合。简单导出用 FastExcel导入解析和复杂模板用自己封装的 POI 工具类。这样两边都不折腾。3. 实战拿下复杂表头、模板填充与合并单元格3.1 解决复杂表头导入POI 拆表头 数据行逐行读先说复杂表头导入。我的做法是彻底放弃注解绑定表头改成动态解析。核心思路分三步先把表头行数读出来解析每个单元格的值和层级关系然后处理合并单元格把合并区域的值复制到该区域覆盖的所有坐标上最后从表头结束的下一行开始按列号读取数据列名作为 Map 的 key。下面这段代码是我工具类的核心表头占几行可以从 Excel 的样式特征判断也可以由一个配置项传进来。public ListMapString, String parseSheet(InputStream in, int headerRowCount) throws IOException { Workbook workbook WorkbookFactory.create(in); try { Sheet sheet workbook.getSheetAt(0); // 第一步根据表头行数构建列名映射 MapInteger, String headerMap buildHeaderMap(sheet, headerRowCount); // 第二步数据行从表头下一行开始 ListMapString, String rows new ArrayList(); for (int rowIdx headerRowCount; rowIdx sheet.getLastRowNum(); rowIdx) { Row row sheet.getRow(rowIdx); if (row null) { continue; } MapString, 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 MapInteger, String buildHeaderMap(Sheet sheet, int headerRowCount) { // 第一步合并单元格值扩展到覆盖范围 ListCellRangeAddress mergedRegions sheet.getMergedRegions(); MapString, 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); } } } // 第二步取最后一行的表头作为列名 MapInteger, 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) { // 先保存原始合并区域注意要新建列表避免引用的是同一个集合 ListCellRangeAddress 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 都只支持单层列表。我的做法很务实先把嵌套结构拍平成单层结构每条明细一行订单头信息在明细的第一行复制一份然后在模板里用普通列表填充。ListMapString, Object flatRows new ArrayList(); for (Order order : orderList) { boolean isFirst true; for (OrderItem item : order.getItems()) { MapString, 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 groupIdorg.apache.poi/groupId artifactIdpoi/artifactId version5.2.5/version /dependency dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.5/version /dependency /dependencies /dependencyManagement第二步在引入 EasyExcel 时排除掉它内部依赖的 POI。否则即使 dependencyManagement 锁了版本有些组件还是会因为传递依赖把旧版本带进来。dependency groupIdcom.alibaba/groupId artifactIdeasyexcel/artifactId version3.3.4/version exclusions exclusion groupIdorg.apache.poi/groupId artifactIdpoi/artifactId /exclusion exclusion groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId /exclusion exclusion groupIdorg.apache.poi/groupId artifactIdpoi-ooxml-schemas/artifactId /exclusion /exclusions /dependency如果你已经切换到 FastExcel思路完全一样。排查时先用这个命令看依赖树mvn dependency:tree -Dincludesorg.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 问题速查表把前面遇到的坑整理成一张速查表方便后续排查对照。问题现象根因处理方案java.lang.NoSuchFieldError: factoryclasspath 存在多个 POI 版本或 POI 版本与 EasyExcel 不匹配统一 POI 版本排除 EasyExcel 自带 POIjava.lang.NoClassDefFoundError: sun/font/FontManagerFactoryLinux 服务器缺少字体渲染库安装 libfreetype6、fontconfig、中文字体模板填充后合并单元格错位fill 按行写数据静态合并区域不自动扩展填充后手动重算 CellRangeAddress 并重建模板里嵌套 List 渲染不出来模板填充只支持单层 list把嵌套结构拍平成单层结构导出的单元格有换行符但不换行没有设置 WrapText 或行高不够设置 setWrapText(true)并手动设置行高读 Excel 时中文乱码或者字体宽度显示异常缺少字体库或字体未缓存安装字体后执行 fc-cache -f这六类问题占了 Excel 处理模块日常故障的绝大部分。如果你也在维护类似系统建议直接把这几个检查项写进团队的排查文档能省不少事。4.2 一次 NoSuchFieldError 的完整排查过程有一次升级项目依赖后导出功能突然挂掉报错堆栈指向org.apache.poi.ss.usermodel.CellStyle的某个字段。我第一反应就是 POI 版本冲突于是执行mvn dependency:tree -Dincludesorg.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而是难在封装层和底层之间的信息不对称。把这一层想透了比换任何库都管用。