先交代一下背景，最近我在维护一个内部报表服务时又踩了 EasyExcel 的坑：客户提交了一个带多层表头的 Excel，结果代码跑了几分钟就报数组越界，查了半天才发现问题出在 EasyExcel 解析复杂表头时的索引错位。这已经不是第一次因为这类问题被拖住节奏了，于是团队内部讨论后，我决定把部分导入导出链路从 EasyExcel 迁移到 Apache Fesod（也就是 Apache FastExcel 的社区叫法）。这篇文章就来讲讲为什么做这个决定、迁移过程里哪些工作量被高估、哪些坑又确实存在，以及如果你也在纠结要不要换，该怎么判断。
1. EasyExcel 停止维护之后，社区的焦虑都写在搜索词里
1.1 一条“不维护”的消息，凭什么牵动这么多人
EasyExcel 在国内 Java 开发者群体里的地位，不需要我过多渲染。简洁的 API、基于注解的导入导出模型、相对 POI 更低的内存占用，让它一度成为 Spring Boot 项目里处理 Excel 的默认选项。我见过不少公司的报表中心、履约系统、对账系统，整个文件处理链路都长在 EasyExcel 上。
但这里有个一直存在却很少被正视的问题：EasyExcel 本质上是一个“个人英雄主义”色彩很重的开源项目。它背后确实有公司资源支持，但项目的走向、排期、issue 响应速度，高度依赖核心维护者的精力和时间。一旦维护节奏放缓，社区就会迅速进入“有 bug 没人修、提 PR 没人看、新版 JDK 兼容没人管”的尴尬状态。
再直白一点，依赖一个更新频率明显下降的第三方库，不只是一个技术选型问题，也是一个风险控制问题。你用 EasyExcel 写出的代码越稳定，反而越容易在环境升级时炸开——JDK 版本一升、POI 版本一变，原本一年都不出问题的链路突然变成定时炸弹。
1.2 从高频搜索词看真实痛点
我看了一下最近“easyexcel”相关的高频搜索词，很有意思，几乎每个词背后都是一类真实的开发场景：
| 高频搜索词 | 真实场景 | 本质问题 |
|---|---|---|
| easyexcel 复杂的表头导入 | 财务、运营数据上报，多层表头映射 | 表头层级解析和 Java 模型映射困难 |
| easyexcel 单元格换行 | 描述文本里带\n，导出换行不生效 | 样式处理与数据处理的边界模糊 |
| easyexcel 使用模板填充的合并 | 模板预置合并单元格，填充后错乱 | 模板引擎与 POI 合并区域逻辑冲突 |
| java + easyexcel 如何渲染嵌套 list | 订单主表和明细子表的层级导出 | 模板数据模型设计不清晰 |
| easyexcel libfreetype6 | Linux 服务器生成图片/水印报错 | 系统字体库缺失，依赖环境问题 |
| easyexcel nosuchfielderror factory | 升级 POI 后运行时报错 | 类库版本冲突，POI 反射调用链断裂 |
这些搜索词有一个共同点：它们都不是特别冷门的需求。复杂表头、嵌套明细、模板合并、单元格内换行，这些在真实业务里太常见了。当这些高频问题无法在项目里得到及时修复时，用户自然会去搜索，也自然会开始考虑替代方案。
2. Apache Fesod 是什么，它凭什么接得住这波迁移
2.1 Fesod 与 FastExcel：先把这个名字讲清楚
先纠正一个名字问题。很多人看到“Apache Fesod”会愣一下，我也是，第一反应是“这又是什么新库”。实际上，Fesod 就是 Apache FastExcel 在社区传播过程中被叫出来的另一个名字，准确说项目目前对外公开的名称是 Apache FastExcel。你如果直接按 Fesod 去搜文档，大概率搜不到官方主页，但按 FastExcel 去查，就能看到它在 Apache 孵化器里的进展。
这个名字混乱其实也反映了这个项目目前的状态：它还没有完全“毕业”，处在从社区项目向 Apache 顶级项目过渡的阶段。不过代码已经在开源仓库里可用，API 也相对稳定，所以用来做实操没问题，只要你别在生产环境直接跟踪 SNAPSHOT 版本就行。
2.2 它和 EasyExcel、POI 的“血脉关系”
Apache FastExcel 本质上延续了 EasyExcel 的核心设计思路：基于注解定义 Excel 模型，通过监听器逐行读取数据，写入时支持流式模式降低内存峰值。它在底层仍然依赖 Apache POI 来操作真实的.xlsx文件，但帮开发者屏蔽掉了大量 POI 的复杂性。
你可以把它理解成 EasyExcel 的“精神续作”：保留了 EasyExcel 那套让人舒服的声明式 API，同时针对 POI 版本兼容、旧 JDK 支持、模板填充逻辑等问题做了重构。这也是为什么很多 EasyExcel 迁移过来的项目会发现，核心代码改动量并不像想象中那么大。
如果画一条技术脉络会更好理解：
- Apache POI是地基，负责最底层的 OOXML 解析和写入，功能最全但 API 晦涩；
- EasyExcel在 POI 之上做了一层封装，主打“简单好用”，但在后期维护停滞；
- Apache FastExcel / Fesod保留 EasyExcel 的封装思路，把维护节奏和生态治理交给 Apache 基金会，同时适配更新的 POI 版本和 JDK 环境。
所以它并不是凭空出现的库，而是迎着 EasyExcel 用户群的迁移需求长出来的新一代表现。
2.3 什么项目适合切到它，什么项目还得留在 POI
任何技术选型都不能只看优点，还得看匹配度。我的判断很简单：
适合切换的场景：
- 正在用 EasyExcel，且已经遇到 issue 无人处理的阻点；
- 新项目需要 Excel 导入导出，不想再踩 EasyExcel 停止维护的坑；
- 项目 JDK 已经升级到 17 或 21，旧版 EasyExcel 在模块化环境下出现反射告警或类型错误；
- 主要场景是常规导入、导出、模板填充，不需要过度定制 OOXML 底层结构。
暂时不适合的场景：
- 项目完全稳定、没有新增需求，也没有人员愿意承担迁移验证成本；
- 你需要对 Excel 做精细的样式控制、公式引擎操作、复杂数据验证，这些还是得回到 POI 甚至直接用底层 XML 操作；
- 你不仅要处理 Excel，还要处理 Word、PPT、Visio 等格式，这种场景直接上 Apache POI 全家桶更稳妥。
说白了，FastExcel 替代的是 EasyExcel 的位置，不是替代 POI 的位置。你要把它当“更省心的 POI 封装”来用，而不是当万能工具。
3. 迁移实录：报表服务如何从 EasyExcel 切到 FastExcel
3.1 依赖替换与代码改造
我迁移的是一个定时报表服务，核心功能是根据业务库数据生成汇总 Excel，再通过模板填充输出给运营团队。原来用 EasyExcel 的部分主要有三个：数据模型注解、Write 调用、模板填充。
先说依赖。Maven 坐标从com.alibaba:easyexcel换成 FastExcel 的坐标，注意不同版本包的命名空间不一样，建议直接看官方仓库的最新文档，不要照抄网上旧帖子的坐标。这样做的原因很简单：FastExcel 还在快速迭代期，旧文章的坐标很可能已经过期。
替换完依赖后，代码层面的改动比我预期的小。核心 API 风格保持了一致：
// 旧写法：EasyExcel EasyExcel.write(fileName, OrderReport.class) .sheet("订单汇总") .doWrite(orderList); // 新写法：FastExcel FastExcel.write(fileName, OrderReport.class) .sheet("订单汇总") .doWrite(orderList);模型类上的注解基本可以保留，@ExcelProperty这类声明式映射在新库里依然是主流用法。真正需要留意的是自定义 Listener 和拦截器接口的包名变化，以及部分回调方法签名调整。这部分在换依赖后编译阶段就会暴露出来，按编译错误逐个改就好。
3.2 双跑与灰度验证
迁移最怕的不是改代码，而是改完之后行为不一致。所以我做了一件事：把新旧两条导出链路暂时并存，通过配置开关切换，然后批量对比输出结果。
具体操作分三步：
- 用同一批订单数据分别调用新旧接口，生成两份 Excel 文件；
- 用脚本读取两份文件的 sheet 数量、行列数、关键单元格文本，做逐项对比；
- 重点检查合并单元格区域、日期格式、数字精度这三个最容易出差异的地方。
对比下来大部分内容是一致的，模板填充场景出现过一次差异：新库对于模板中合并单元格的处理方式更“保守”，数据区域扩展时不会主动覆盖合并区域，这在旧版本里是有可能自动帮你“摊平”的。这个差异不能算 bug，反而更安全，但对依赖旧行为的代码来说确实是破坏性变更，需要单独验证。
3.3 大并发导出时的内存观察
我们的报表服务是多个任务并行执行的，原来用 EasyExcel 时，我在 JVM 监控里见过比较明显的老年代波动。换成 FastExcel 后，我用同样的任务量对比了内存曲线：
- 小文件（几百行）场景下没有明显差别；
- 中等文件（几万行）场景下，FastExcel 的流式写入表现与 EasyExcel 相当；
- 大文件（几十万行）场景下，FastExcel 的临时文件管理更干脆，内存峰值略低。
但注意，这只是单次观察，不是严谨的基准测试。真正影响内存的还是你是否开启了流式写、是否复用了 Workbook 实例、写入后是否及时释放资源。不要指望换个库就能解决所有内存问题，该优化的代码结构还是得优化。
4. 六类高频报错与重灾区场景的排查笔记
4.1 复杂表头导入：多级表头如何映射
复杂表头导入一直是 EasyExcel 社区的高频问题，尤其财务系统和人力资源系统里，一张 Excel 的顶部经常有两三层的合并表头。EasyExcel 官方文档其实支持多级表头，通过注解里的父子结构来声明层级关系，但实际用起来很别扭：表头层级和 Java 对象层级需要一一对应，稍微错位就导入出空值。
从实践角度，我给两个建议：
第一，能改模板就不要硬编码。如果导入模板由业务方提供且频繁变动，优先将表头行加入“动态解析”逻辑：读取前几行判断表头结构，再生成对应的列映射，而不是把映射关系写死在 Java 类里。
第二，对于相对固定的复杂表头，可以用注解方式声明两级表头，但一定要给每个字段指定明确的列索引。不要依赖字段顺序去匹配表头顺序，因为 Excel 的列顺序一旦调整，按顺序映射的代码就会静默出错。
4.2 单元格内换行数据读崩了
“easyexcel 单元格换行”这个搜索词，反映的其实是两个问题：一个是导入时单元格内的换行符被误判成行分隔符，另一个是导出时字符串里的\n没有触发 Excel 单元格自动换行样式。
先说导入。读取单元格文本时要区分真正的行分隔符和单元格内部换行。代码逻辑上要做到这一点并不复杂：先把整行数据读出来，再对单元格内部文本按\r\n或\n做保留处理，而不是提前按行拆分。
再说导出。字符串内容里的\n要显示为换行，必须同时设置单元格样式wrapText。很多人在 POI 时代就有这个经验，但在 EasyExcel 的注解式 API 下容易忽略——注解能映射字段，不代表能自动推断样式。FastExcel 同样遵循这个规则，导出包含多行文本的字段时，记得手动配置换行样式，而不是期望库帮你做好。
4.3 模板合并单元格填充后格式错乱
模板填充是最让我头疼的一类问题，因为它的表现千奇百怪：有的明明设置了合并区域，填充后却只显示第一行；有的是数据多出来几行，合并区域没有跟着扩展；有的更诡异，填充完整个 sheet 的边框都丢了。
根因在于：模板填充的底层逻辑是先解析模板中的占位符，再按数据量扩展行，最后才重新计算合并区域。如果模板里把合并区域和数据占位行放在同一个范围内，数据行数一变化，合并区域就全乱套。
我的处理经验是：模板设计时就给“动态数据区域”留出独立空间，合并区域放在数据区之外，或者放到数据区内的最右侧列，避免纵向合并和数据行扩展冲突。如果你实在需要在数据区内合并，那就不要指望模板一次性填充完成，而是在生成后通过代码重新设置合并区域，这样最可控。
4.4 嵌套 List 到底怎么在模板里渲染
“java + easyexcel 如何渲染嵌套 list”是另一个高频搜索词，典型的业务场景是“一个订单下面有多条商品明细”，导出时希望订单占一行主数据，明细子表在旁边或下方展开。
这个问题的关键不是怎么写代码，而是怎么设计模板的数据模型。嵌套渲染通常要求模板占位符支持层级引用，比如外层是订单对象，里层是订单下的商品列表：
{order.id} {order.customer} {order.items[].productName} {order.items[].quantity}有些模板引擎要求内层必须放到新行，且缩进层级和占位符路径要能体现父子关系。如果你在严格模式下渲染，某个字段在对应的 List 元素里不存在，就会直接抛错。所以我的建议是：在模板堆叠占位符之前，先在代码里构造好完整的嵌套数据结构，确保每个层级都有值，再交给模板引擎。
如果 FastExcel 的能力不足以支持特别复杂的嵌套布局，不要硬刚模板。优先把数据打平成“主表明细行”的二维 List，用普通数据模型导出，最后再用样式调整视觉层级。这个方案虽然没那么“优雅”，但可维护性高得多。
4.5 libfreetype6 报错：Linux 服务器的“字体关”
这个报错在 Windows 本地开发时基本不会出现，一到 Linux 服务器部署就原形毕露。它的典型场景是：项目里要用 POI 或 Excel 组件生成带文字的图片，比如把图表导出成图片塞进 Excel，或者给单元格设置图片背景，结果服务器上找不到字体渲染库，直接抛libfreetype6.so相关的加载错误。
这不是 FastExcel 或者 EasyExcel 的代码问题，而是系统环境缺少字体相关的底层库。排查思路也很直接：先确认当前系统是否装了 FreeType 库，再确认是否有可用中文字体。以 Ubuntu/Debian 为例，可以安装：
sudo apt-get install -y libfreetype6-dev fontconfig fonts-dejavu-core fonts-wqy-zenhei安装完后建议再用fc-list检查一下中文字体是否被识别。如果字体缺失，Excel 里图片上的中文字符会全部变成方块。这个坑和用哪个 Excel 库无关，换到 FastExcel 依然存在，所以环境准备阶段最好就补上。
4.6 NoSuchFieldError factory：一次典型的 POI 版本冲突
NoSuchFieldError: factory是我在多个项目里见过的问题，它比 libfreetype6 更隐蔽，因为它发生在类加载阶段，不熟悉 JVM 类加载机制的话很难一眼定位。
简单解释一下原因：Java 项目里同一个类可以被多个 jar 包提供，如果 A 库依赖 POI 4.x，B 库依赖 POI 5.x，运行时类加载器只加载其中一个版本，当代码通过反射访问不存在的字段或方法时，就会抛出NoSuchFieldError或NoSuchMethodError。factory这个字段在 POI 不同版本间的包结构不同，新旧版本混用必然中招。
排查步骤我建议按这个顺序：
- 先看完整堆栈，确认报错的类属于哪个 jar 包；
- 用
mvn dependency:tree -Dincludes=org.apache.poi查看当前项目依赖的 POI 版本树； - 找出所有引入 POI 的依赖，排除掉不需要的传递依赖，统一收敛到同一个版本；
- 在 pom 中用
<exclusion>排除冲突项。
这个问题的根源不在 Excel 库本身，但在迁移到 FastExcel 时尤其容易触发，因为新库要求更新的 POI 版本，老项目里的其他组件可能还在用旧版本。我的经验是先锁定 POI 版本，再切 Excel 库，否则两件事混在一起排错会相当痛苦。
5. 迁移后我最后想说的话
5.1 不要为“赶潮流”迁移
我理解很多人看到“再见了 EasyExcel”这类标题，容易产生“别人都换了我也得换”的焦虑。但迁移一定是有成本的：代码改造只是一小部分，更多成本在回归测试、兼容性对比、历史模板的重新验证上。如果你的 EasyExcel 链路两年没有出过问题，团队也没有业务压力要求升级依赖，那你完全可以继续用。技术选型不是追新，而是为了减少长期的维护成本。
5.2 新建项目的选择
如果是在 2025 年的当下开一个全新的 Java 项目，我的个人结论是：表格数据处理需求很常规，不想直接用 POI 那套繁琐 API，又不想再赌一个维护节奏不稳定的个人项目，那 FastExcel / Fesod 这类对 EasyExcel 继承性好的封装库是一个合理选择。至少在生态治理这件事上，Apache 基金会模式比单个维护者更可持续，遇到问题也有人能接手。
5.3 一个保险做法
最后分享一个我个人觉得很实用的做法：迁移不要“一刀切”，而是先在项目里留一个切换开关，新旧实现并存一段时间，通过实际业务流量慢慢验证。我这边的做法是让一部分任务走新库，一部分任务继续走旧库，对比运行日志、输出文件和监控指标，跑了大概两周才把所有流量切过去。虽然多占了一些代码空间，但换来的确定性和从容感是值得的。
那句话怎么说来着，最好的迁移不是发布会式的一夜换新，而是不动声色地把风险降到最低。希望这篇记录能给正在纠结要不要换 Excel 处理库的朋友一点参考。
