月初和同事聊起要不要把项目里的Excel导入导出模块重写，起因是看到群里有人贴了一段NoSuchFieldError: factory的堆栈，下面一群人回复“EasyExcel老毛病又犯了”。当时我心里咯噔一下，知道这个“老朋友”怕是真到了该告别的时候。后来把核心导出导入功能整体迁到了 Apache Fesod——也就是 EasyExcel 进入 Apache 基金会之后的继任项目，熟练之后发现，迁移成本真的比想象中低，但收益比想象中高。这篇文章把我这一路踩过的坑、换库的决策过程、以及复杂表头、嵌套List、模板填充这些高频场景的落地方法都整理出来，给还在 EasyExcel 泥潭里挣扎的朋友一个参考。
1. 先从那个让我崩溃的 NoSuchFieldError: factory 说起
事情发生在一个普通的发版日。升级完依赖后，某个导入接口在读取Excel的一瞬间直接抛出NoSuchFieldError: factory。这个报错的诡异之处在于：项目平时启动、新增、修改、导出都好好的，但只要走到某一个特定格式的单元格解析分支，就会炸。
我第一反应是POI版本冲突，但当时项目里已经统一过POI版本，理论上不该有问题。后来用mvn dependency:tree一层层查，发现某个内部组件通过传递依赖带进来一份旧POI，而代码里同时存在两份不同版本的POI类。JVM加载类的时候，按照类加载器顺序加载了旧版本，运行期访问新版本字段时自然就找不到。这个问题最恶心的地方在于，它完全看类加载顺序、看具体解析路径，有时候换一台机器、换一个JDK版本就复现不了。
排查过程很枯燥：先在POM里把可疑传递依赖全部排除，再手动固定所有POI相关坐标到同一个版本。但这也让我彻底对 EasyExcel 的“稳定”产生了怀疑——底层和POI深度耦合，一旦POI升级、JDK升级，就可能出现这种潜伏性故障。
1.1 为什么EasyExcel留下了这么多“烂摊子”
EasyExcel 当年确实解决了 POI 的一个大痛点：默认的 XSSF 会把整个Excel读到内存，稍微大一点的文件就 OOM。EasyExcel 用 SAX 模式逐行解析，内存占用低，读写速度也快，这几年在国内 Java 生态里几乎是导入导出事实标准。
但问题在于，这个项目进入维护停滞状态后，很多已知问题不再修复，社区里的 issue 越堆越多。我遇到过的几个痛点包括：
- 骨架还在，但没人做“大保养”：核心API多年没演进，遇到复杂场景只能自己造轮子。
- POI 版本敏感：稍微动一下依赖版本，就可能触发各种诡异报错，比如我遇到的
NoSuchFieldError: factory。 - 高级功能文档匮乏：复杂表头、嵌套List、模板填充合并单元格，这些场景的官方文档信息量极少，很多靠社区文章拼凑。
- 新的社区PR没人合：明明有人提交了修复方案，但长时间挂着不处理，给人的信号就是“别指望了”。
1.2 触发我迁移的3个具体痛点
真正让我下决心迁移的不是某一次单个问题，而是这些问题反复出现，每次都要靠“改依赖版本 + 清缓存 + 重新打包”这种玄学手段才能绕过。
第一个痛点是复杂表头导入。业务方经常发来一张多级表头的Excel，比如第一行是“部门”，第二行是“2025年”，第三行是“计划/实际”。这种表头是人看得懂，程序很痛苦。EasyExcel 的注解方式写起来极其啰嗦，动态表头又缺少可以直接抄的示例。
第二个痛点是单元格换行。业务人员在备注、地址、描述里随手加个换行，导入导出之后要么被截断，要么整个字段错位。看起来是小问题，但几乎每个业务系统都会遇到，而且特别难解释给非技术同事听。
第三个痛点是模板填充。我们用模板导出订单数据，遇到“一个用户多条订单记录”的结构，模板里的占位符和合并单元格总是对不上，导出来的Excel经常出现数据堆叠、合并错乱的情况。
2. Apache Fesod 是什么，为什么值得换
先说明一下，我这里说的 Apache Fesod 就是 EasyExcel 进入 Apache 基金会之后的继任项目。项目在孵化阶段，不同渠道可能叫法不一，但API设计上尽量保持了 EasyExcel 的原有思路：基于注解映射、SAX模式读取、低内存占用。对我来说，最直观的感受是“还是那套玩法，但是有人管了”。
选择 Fesod 做迁移目标，主要看中三点：一是API兼容性高，原有代码的改动量能控制住；二是项目活跃，issue 响应和修复速度比老项目好了不止一个量级；三是底层依赖重新梳理过，POI 版本冲突这类老问题少了很多。
2.1 API兼容性，迁移成本到底有多低
先说结论：如果你的项目只用 EasyExcel 的基础读写功能，迁移成本几乎可以忽略。
旧代码是这样写的：
List<DemoData> list = EasyExcel.read(file) .head(DemoData.class) .sheet("Sheet1") .doReadSync();换到 Fesod 之后，代码长这样：
List<DemoData> list = Fesod.read(file) .head(DemoData.class) .sheet("Sheet1") .doReadSync();导出也是一样的套路：
Fesod.write(outputStream) .head(DemoData.class) .sheet("Sheet1") .doWrite(dataList);所以大部分情况下，迁移就是“换一个入口类、改一下import包名”。但如果你用了比较深的功能，比如自定义拦截器、复杂监听器、动态表头、模板填充，那还是需要花点时间看新版的API和示例，不能无脑全局替换。
2.2 底层哪些地方确实“开窍”了
我在迁移过程中重点翻了一下新版的核心代码，有几个改进是比较明显的。
首先是依赖整理。老 EasyExcel 对 POI 版本的约束非常严格，但项目停更后又跟不上 POI 新版本，导致升级 JDK 或者升级 POI 都容易踩雷。Fesod 在底层重新梳理了依赖树，把容易冲突的坐标做了隔离，我在迁移后的项目里统一POI版本就顺利多了。
其次是渲染相关优化。之前我们在 Linux 服务器上导出带图片的Excel，经常遇到字体、系统库方面的问题，比如libfreetype6缺失导致图片或图表渲染异常。新版在渲染链路里做了更多容错处理，遇到系统字体缺失时不再直接崩溃，而是有更明确的错误提示和降级策略。
第三是复杂场景的支持更明确。复杂表头、嵌套对象、模板填充这些用法，在新项目里都有对应的API和例子，不再像之前那样靠“试错 + 搜索 + 猜”来推进。
3. 实际迁移：复杂表头导入，一次说清楚
先还原一个真实场景：业务方每季度会发来一张“月度经营计划表”，表头长这样：
- 第一行：部门
- 第二行：1月、2月、3月……
- 第三行：每个月份下面有“计划”和“实际”两列
这种表从第二行开始才是真正的数据表头，而且是三级表头，列数会随着月份动态变化。处理这种表，核心就是两个字：拆表头。
3.1 注解方式：多级表头怎么映射
当表头结构固定、列不动态变化时，用注解是最快的。关键在于@ExcelProperty的value数组要严格按“从大类到子类”的顺序写全。
public class MonthPlanImport { @ExcelProperty(value = {"部门", "部门", "部门"}, index = 0) private String dept; @ExcelProperty(value = {"2025年", "1月", "计划"}, index = 1) private BigDecimal janPlan; @ExcelProperty(value = {"2025年", "1月", "实际"}, index = 2) private BigDecimal janActual; }这里有个细节：value数组里的每个元素对应表头的一级，比如{"2025年", "1月", "计划"}就表示三级表头的完整路径。如果表头的合并单元格处理不当，value数组里会出现空字符串，导致解析错位。因此，在处理真正复杂的模板时，我更推荐先写一个小工具把表头打印出来，确认每一列的完整路径，再写注解。
3.2 动态表头：运行期才能确定的列怎么办
很多时候列是动态的，比如“根据业务选择的月份生成对应列”，这时候注解写死就没法用了。Fesod 支持直接从List<List<String>>构建表头：
List<List<String>> headList = new ArrayList<>(); // 固定列 headList.add(Arrays.asList("部门", "部门", "部门")); // 动态月份列 for (String month : selectedMonths) { headList.add(Arrays.asList("2025年", month, "计划")); headList.add(Arrays.asList("2025年", month, "实际")); } List<List<Object>> rows = Fesod.read(file) .head(headList) .sheet("Sheet1") .doReadSync();这种方式的优点是很灵活，动态生成的列可以直接映射到数据结构里。缺点是拿到的每行数据是List<Object>，需要按下标转换为业务对象。我的建议是：先定一个列下标常量或枚举，别在业务代码里到处写魔法数字，否则后面维护的人会骂人。
3.3 三个隐藏比较深的坑
动态表头跑通容易，跑得稳难。我在测试阶段踩了三个坑：
第一，表头合并单元格带来的空值。多级表头里，如果某个单元格被合并了，比如“部门”跨了三行，读到的表头字符串可能只有第一行有值，后面全是空字符串。动态构建headList时，必须把这种空字符串补成上一级的值，否则映射会整体错位。
第二，表头单元格内换行。有的Excel模板在表头文字里直接按了 Alt+Enter 换行，导致表头字符串判断出错。读取后最好统一做一次清理，把表头里的换行符去掉再参与匹配。
第三，headList 与实际表头不一致时不会立刻报错。如果手工构建的表头和Excel真实表头对不上，Fesod 大概率不会抛异常，而是静默地返回一堆错位数据。所以用动态表头方案时，务必加一个断言或校验逻辑，确保读取的表头行和你构建的表头一致。
4. 单元格换行、嵌套List与模板填充，三个高频场景复盘
这部分内容很多，我把迁移过程中遇到频率最高的三个场景合并在一起复盘，因为它们之间其实有关联：都是“Excel 呈现方式”和“Java 对象结构”不一致导致的。
4.1 单元格换行被截断：几乎每个业务系统都会踩
业务人员特别习惯在备注、地址、描述字段里按 Alt+Enter 换行。导出的时候如果没做处理，用户看到的是所有文字挤在一行；导入的时候如果不处理换行符，字段内容会变少甚至错位。
解决思路是自定义一个 Converter，把读取和写入时的换行符都显式处理掉：
public class NewLineConverter implements Converter<String> { @Override public String convertToJavaData(ReadCellData<?> cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) { return cellData.getStringValue().replace("\n", "\n"); } @Override public WriteCellData<?> convertToExcelData(String value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) { return new WriteCellData<>(value); } }读取端的关键是不要用默认的“一行一条”逻辑去理解单元格内容，而是把单元格当作文本块整体读取。写入端则要注意，导出后Excel需要设置wrapText样式，也就是自动换行，否则虽然数据里有换行符，用户在界面上也看不到换行的效果，容易误以为数据丢了。
4.2 嵌套List渲染：一对多导出不再靠“手动拼接”
业务场景很典型：导出用户列表，每个用户下面跟着一张订单列表。二维表格里要表达一对多，常规做法是“用户一行，下面若干订单行，用户字段在首列”。
EasyExcel 时代，官方推荐用模板填充来实现这种结构，但很多人卡在“嵌套对象怎么在模板里写”这一步。Fesod 延续了模板填充的思路，普通字段用{user.name}这种方式，列表字段则需要在模板里画出一行“循环行”，并在这行里写子对象的字段占位符。
用户姓名：{user.name} | 订单号 | 商品名称 | 金额 | | {order.orderNo} | {order.goodsName} | {order.amount} |这里的order就是 List 里的元素对象。填充时，Fesod 会识别出这行是循环行，然后根据集合大小自动扩容，生成N行数据。
嵌套List渲染最核心的一点是：模板里必须先画好循环行的结构。如果你只写了{order.orderNo}却忘记把这行标记为可循环，最终输出的数据只会有一行，其余数据全都丢失。
4.3 模板填充的合并单元格：那些年我们手动拼过的Merge
一开始我们用模板填充导出一张“部门费用汇总表”，模板里把部门名称的单元格做了纵向合并。老写法是：先用 EasyExcel 填充数据，再用 POI 手工addMergedRegion处理合并。这个方案的痛点是行列号需要自己算，数据一多，合并区域就错位，调试成本非常高。
Fesod 对模板合并单元格的处理更接近“保留模板原样”。也就是说，你在模板里提前画好合并区域，填充的时候只要数据行数不超过模板预设区域，合并效果就能保留下来。
实际操作中的建议是：
- 模板合并区域要预留足够多的行，尽量覆盖数据量的上限。
- 如果数据量不确定，填充前先做一次统计，超过模板区域就拆分Sheet或分页导出。
- 填充完成后，对最后一列或最后一行的合并区域做一次自动校正，避免因为数据行数变化导致合并边界不对齐。
5. 常见问题与排查技巧实录（速查表）
我把这段时间遇到的高频问题整理成一张速查表，方便遇到问题时直接对号入座。
| 问题现象 | 根本原因 | 排查与解决建议 |
|---|---|---|
启动正常，解析某些Excel时抛NoSuchFieldError: factory | 依赖树中存在多个不同版本的POI，类加载器加载到旧版本 | 用mvn dependency:tree排查，排除传递依赖，统一POI版本 |
| Linux环境导出带图片/图表的Excel报错或渲染异常 | 系统缺少字体渲染相关库，如libfreetype6 | 安装系统依赖库；或者升级到新版，利用渲染容错处理 |
| 复杂表头导入后字段全部错位 | 表头合并单元格导致空值，或动态headList和真实表头不一致 | 读取表头后做归一化处理，补全合并单元格空值，校验表头一致性 |
| 单元格内换行导致文本截断或错位 | 默认解析逻辑把换行符当作行分隔处理 | 自定义 Converter，读/写显式保留换行符 |
| 模板填充后合并单元格错乱 | 模板预设合并区域与数据行数不匹配 | 预留足够合并行，填充前统计行数，必要时填充后重建合并区域 |
| 嵌套List渲染只有一行数据 | 模板中缺少循环行，占位符没有放入循环区域 | 在模板中画出循环行，将子对象字段占位符放在循环行内 |
5.1 排查思路：先分读取和写入
遇到Excel相关的问题，我一般会先区分“数据读不进来”和“数据写不出去”两条线。
如果是读取问题，优先检查依赖树、表头定义、单元格格式、换行符处理。尤其是用了老版本POI的项目，先把POI版本统一到和新版Fesod匹配的版本，很多神秘报错就消失了。
如果是写入问题，优先检查模板里的占位符、循环行、合并区域、系统字体这四样。模板填充出问题时，最快的方法是把模板文件用文本编辑器打开，看清楚占位符到底写没写对，别在Excel可视化界面上凭感觉猜测。
5.2 我在迁移中总结的几条避坑经验
这几条是实操中觉得最值钱的经验，分享给准备迁移的朋友：
第一，所有涉及Excel的项目，统一用 dependencyManagement 把POI版本锁死。不要在子模块里各写各的版本，否则迟早会遇到类加载器的问题。
第二，给所有导入接口加一个统一的数据清洗层。不要在每个监听器里写重复的“去空格、处理换行、转换类型”逻辑，做成公共组件，后面能省很多事。
第三，模板类导出必须做回归测试。我见过太多模板文件被无意改动一个空格、一个占位符，导致整批数据错位的案例。给核心模板建立一份固定的测试用例，每次改模板都跑一遍。
第四，Linux环境部署前，先确认字体和系统库。如果业务里有图片导出、图表生成，提前在测试环境把libfreetype6这类依赖装好，别等到生产环境发版后才发现。
第五，别一次迁移所有接口。先挑一个最常出问题的模块（比如复杂表头导入）做试点，跑通后再批量推进，风险会小很多。
6. 一些迁移建议与个人体会
在我接触过的技术选型里，从 EasyExcel 迁到 Fesod 属于“收益明显、成本偏低”的类型，但前提是别一上来就想着全局替换。
6.1 什么样的项目建议立刻迁移
判断标准很简单：如果你现在的项目里，EasyExcel 只用来做简单的单表头读写，运行一直很稳定，那不用着急，可以继续观察。但如果你的项目里出现了以下任意一种情况，建议尽早启动迁移评估：
- 频繁出现 POI 版本冲突、类加载异常，靠排除依赖才能跑通；
- 需要支持复杂表头、动态表头、嵌套对象导出；
- 经常使用模板填充，并且被合并单元格问题困扰；
- 出现了
NoSuchFieldError: factory这类底层兼容性报错，且排查成本越来越高。
6.2 迁移落地步骤和验收标准
我的落地步骤大致是这样：
- 先替换依赖：把 EasyExcel 相关坐标替换为 Fesod，固定POI版本。
- 跑一遍基础读写用例：确认简单读写没有问题，重点看原有
@ExcelProperty注解是否兼容。 - 逐个迁移高级场景：按“简单导入 -> 简单导出 -> 动态表头 -> 模板填充”的顺序推进。
- 回归测试：为每个接口准备一份测试Excel，覆盖正常数据、空表、复杂表头、单元格换行这几类情况。
验收标准就一条：和旧逻辑输出结果完全一致，且没有因为换库引入新增的运行时异常。
最后再分享一个小技巧：不管用哪个库，Excel导入导出最大的成本从来不是“怎么写代码”，而是“把Excel规则搞清楚”。先和业务方对齐表头结构、合并规则、数据格式，再动手写代码，你会发现换库这件事，比你想象中轻松得多。
