从去年年底开始我陆陆续续在手头几个项目里把 EasyExcel 换成了 Apache Fesod。说实话这不是一时冲动而是被各种奇怪问题磨出来的决定。EasyExcel 确实好用封装漂亮、上手快可一旦你开始碰复杂表头、嵌套 List、模板合并这种“高级玩法”各种边界问题就冒出来了。这篇文章就把我这几个月的迁移过程、踩坑记录和实操方案完整写出来希望能帮到正在 EasyExcel 里挣扎的朋友。1. 为什么我决定跟 EasyExcel 说再见很多人看到标题会觉得夸张但如果你维护过一套长期运行的报表系统大概率能理解我的处境。EasyExcel 的定位是“简洁易用”它把底层的 POI 细节藏得很好常规读写确实舒服。可当业务表头越来越复杂、模板要求越来越多以后EasyExcel 反而成了瓶颈。1.1 三个把我逼疯的场景第一个是复杂表头导入。业务方给了一张三级表头、还有动态列飘移的 Excel要求前端页面直接上传后解析。EasyExcel 的监听器模式写起来很爽但面对跨行跨列的表头结构时行列索引的换算变得极其繁琐。有一次我为了动态解析一个“日期 指标维度”的二维表头硬是把分析代码写出了 300 多行而且每个新表头都要调。第二个是嵌套 List 渲染。比如一个汇总 Excel 里每个部门下面跟着 N 条员工记录部门信息要合并单元格员工明细又要按模板逐行展开。EasyExcel 的填充 API 对普通的 Map 数据和单层 List 确实没问题但只要数据结构一深模板层填充就会错位。网上搜一圈关于“如何渲染嵌套 List”的帖子几乎都是让绕道走。第三个是环境依赖问题。部署 Linux 服务器跑导出任务时突然报 libfreetype6 缺失去做图像相关渲染时就会崩还有一次升级项目里其他依赖后直接冒出NoSuchFieldError: factory查了半天才发现是 EasyExcel 内嵌的 POI 版本和项目里的 POI 冲突了。这类问题在开发环境根本不出现一到生产就给你脸色看。1.2 EasyExcel 维护状态带来的隐性风险EasyExcel 在阿里内部用得很多社区也有大量用户但它的迭代节奏这几年明显慢下来了。很多 issue 长时间没人回复新版本对 JDK 17 的支持也一直比较谨慎。在要长期维护的企业项目里这种“停止演进”的状态其实很要命你不确定下个 JDK 升级会不会出问题也不确定某一天某个底层依赖会突然破掉。这不像业务代码业务上出问题能马上修底层 IO 和单元格解析的 Bug 我们改不了只能等上游。所以我开始认真调研替代方案核心诉求很简单能保留 EasyExcel 那种简洁的 API 风格又有足够强的底层能力兜底。1.3 为什么最后选了 Apache FesodFesod 是 Apache 社区里相对比较新的 Excel 处理框架论知名度还没法和 POI、EasyExcel 比但它的设计思路刚好戳中我的痛点底层回归 POI但不把 API 暴露得很底层模板引擎能力比 EasyExcel 强一个档次专门处理复杂填充依赖隔离做得干净冲突少。说白了它更像是“EasyExcel 的完全体”。2. 迁移前必须搞清的核心概念在给代码之前得先把几个基础概念说清楚不然直接上手容易懵。Fesod 不是什么魔法它底层依然构建在 Apache POI 之上你可以理解成POI 是发动机Fesod 是变速箱和方向盘EasyExcel 是另一套变速箱但换挡逻辑各有不同。2.1 核心对象模型Fesod 的编程模型对从 EasyExcel 过来的人来说几乎零负担Workbook 代表整个 Excel 文件Sheet 代表工作表Row 代表行Cell 代表单元格。读写入口分别是FesodWorkbookFactory.create()和FesodWorkbookFactory.read()。它的 API 风格比 POI 友好非常多。POI 里你想给单元格设置样式得先创建 CellStyle再设置字体再设置边框全部手动拼装Fesod 提供了一套类似于 EasyExcel 的注解和链式写法但底层给你留了getPoiWorkbook()这类方法想拿到原生对象做定制也不难。这种“既要简洁又不封死底层”的方式特别适合我们这种二开比较多的项目。注意Fesod 的名称在社区里刚出来时很容易拼错有人叫 Fastexcel有人叫 Fesod甚至有人跟 FastExcel 搞混。你只需要记住它是以 Apache 社区的名义维护、以 POI 为底层的新一代 Excel 处理方案就好。2.2 方案对比POI / EasyExcel / Fesod我在选型时做了一张对比表直接贴出来维度Apache POIEasyExcelApache Fesod上手难度高细节多低低到中等大数据量读写支持但需优化流式处理表现好流式 区域缓存复杂模板填充需手写逻辑一般原生支持嵌套渲染复杂表头导入需手写解析支持有限提供动态表头解析依赖隔离无相对弱较强维护活跃度高偏低社区起步阶段从表里就能看出来Fesod 在“复杂场景”这块的定位很清楚。不是所有项目都需要它但如果你天天跟复杂 Excel 打交道这一票投得值。2.3 迁移成本评估我在动手之前专门估过迁移成本大概一个中型的报表服务涉及 30 多个导入导出场景迁移到 Fesod 大概需要三到五天。这取决于你原有用到多少 EasyExcel 的特性。如果只是简单的 List 转 Excel、Excel 转 List那几乎是把EasyExcel.write()换成FesodWorkbookFactory.create()的事但如果用到了自定义拦截器、复杂表头策略、模板回调这类高级 API就要多花点时间适配。我们的做法是先把高频、简单的场景迁了再逐个处理模板渲染和动态表头稳扎稳打不要一刀切全部切换。3. 复杂表头导入Fesod 怎么解决我的痛点复杂表头在业务系统里太常见了。财务对账、项目排期、库存盘点几乎每个表都带着多级表头。EasyExcel 的注解模型能处理“固定的、层级不多”的表头但一旦表头本身跟着业务动态变化比如商品维度每天不一样、团队架构一周换一次原来的模型就崩了。3.1 需求场景拆解我这里举一个实际例子一张“销售汇总表”第一行是年份第二行是季度第三行是列名而且列名可能是动态生成的。例如一季度下面有 1 月、2 月、3 月到了二季度又变成 4 月、5 月、6 月。同时表里还有合并单元格一个大区跨三列三个城市跨多个行。如果用 EasyExcel 的注解方式你得先把这个表头结构“写死”成 Java 类。可表头是动态的怎么办常规解法是拿invokeHeadMap()做映射再手工计算每个字段在第几列代码写出来又长又脆字段一多就疯。3.2 Fesod 的实现思路Fesod 对复杂表头提供了一套“区域解析”机制。你先定义表头的结构模型再用位置或规则去映射数据。大致分为三步定位表头区域确定表头占几行、数据从第几行开始。解析表头层级关系构造一棵表头树。根据叶子节点的列索引按列提取数据。这里面最关键的是第二步。Fesod 原生支持把表头单元格的层级结构解析成一棵树树根是总列名叶子是可用的数据列。比如“2024年 一季度 1月”就是一个三层的树形结构解析后能拿到对应的列索引。后续就简单了按照索引把下面行里的数据读出来填充到业务对象。3.3 关键代码示例我简化一下用 Fesod 的 API 来描述这个过程// 读取Excel文件 FesodWorkbook workbook FesodWorkbookFactory.read(inputStream); // 获取第一个Sheet Sheet sheet workbook.getSheet(0); // 1. 构建表头区域传入表头占用的行数 HeaderRegion headerRegion sheet.parseHeaderRegion(3); // 2. 获取表头树树的结构可以自由遍历 HeaderTreeNode rootNode headerRegion.getRootNode(); // 3. 从树中拉取所有叶子节点 ListHeaderTreeNode leafNodes headerRegion.getLeafNodes(); for (HeaderTreeNode leaf : leafNodes) { // leaf.getColumnIndex() 拿到这一列的索引 // leaf.getFullPath() 比如 [2024年, 一季度, 1月] System.out.println(leaf.getColumnIndex() - leaf.getFullPath()); } // 4. 按叶子节点索引读取每一行数据 for (int i 3; i sheet.getLastRowNum(); i) { Row row sheet.getRow(i); for (HeaderTreeNode leaf : leafNodes) { Cell cell row.getCell(leaf.getColumnIndex()); // 按需强转或保留原始值 } }这里我需要说明一下parseHeaderRegion(3)代表前 3 行都是表头第 4 行开始是数据。这个值不一定是固定 3要看你表头行数可以在前端选择文件时同时传一个参数也可以在后端动态判断第一行是全数据的列名那就遍历前几行找到“表头结束、数据开始”的临界点。3.4 动态表头映射的注意点实操里最容易踩的坑是“合并单元格导致的错位判断”。比如某个单元格在第二行跨两列但 Fesod 返回的树节点结构里这个单元格可能只出现在第一列第二列会被当成“空节点”跳过。如果你不加判断直接按顺序取叶子节点数据就全错位了。解决办法是遍历树时不要只收集叶子也要看每个非叶子节点的合并范围。Fesod 在HeaderTreeNode里提供了getMergedRegion()方法你可以拿到这个节点跨越的列区间然后用区间去计算真正的数据列。这块代码虽然要多写几行但比 EasyExcel 需要自己维护一个MapInteger, String列映射要稳得多。经验在解析动态表头时不要在循环里反复调用sheet.getRow()和row.getCell()每次调用都有不小的开销。正确做法是先把整张表读到内存模型里再基于内存模型做遍历。Fesod 的流式读取和内存模型两种模式可以切换复杂表头导入场景建议直接切到内存模式。4. 嵌套 List 渲染与模板填充实战如果说复杂表头导入是一道送分题那嵌套 List 渲染就是一道拉分题。Excel 模板填充这件事看起来不就是“把值塞到占位符里”吗但实际项目里模板里的占位符从来不会那么老实经常出现一个单元格区域要按行重复、同一列的数据要在多层级之间联动。4.1 模板填充的基本原理Fesod 的模板填充思路和 EasyExcel 本质上一样你在 Excel 模板里写{{xxx}}占位符程序读取模板后按数据模型去匹配和替换。区别在于 Fesod 对“区域渲染”的支持更彻底。EasyExcel 的填充默认是单元格级别的遇到需要整行整列复制的场景你需要手工定义“向下填充到哪里”。Fesod 则引入了“模板区域”的概念你可以在模板里把一个区域标记成循环体比如{{#list}} ... {{/list}}程序解析时会自动识别这个循环体的边界然后根据数组长度复制 N 份。4.2 嵌套 List 到底怎么渲染先看需求。假设模板第一行有“部门名称”第二行开始是员工列表一个部门下挂了 5 个员工那么第二行到第六行都是这个部门的数据第七行才是下一个部门。同时部门列需要合并单元格看起来就像这样| 部门 | 姓名 | 工资 | | 技术部 | 张三 | 10000 | | | 李四 | 12000 | | | 王五 | 11000 | | 市场部 | 赵六 | 9000 |用 Fesod 的模板语法实现MapString, Object data new HashMap(); ListMapString, Object departments new ArrayList(); // 部门1 MapString, Object dept1 new HashMap(); dept1.put(name, 技术部); dept1.put(employees, Arrays.asList( Map.of(name, 张三, salary, 10000), Map.of(name, 李四, salary, 12000), Map.of(name, 王五, salary, 11000) )); // 部门2 MapString, Object dept2 new HashMap(); dept2.put(name, 市场部); dept2.put(employees, Arrays.asList( Map.of(name, 赵六, salary, 9000) )); departments.add(dept1); departments.add(dept2); data.put(departments, departments); // 执行模板填充 FesodTemplate template FesodWorkbookFactory.createTemplate(new FileInputStream(template.xlsx)); template.fill(data); template.writeTo(new FileOutputStream(output.xlsx));对应的模板里需要把区域标记成这样{{#departments}} {{name}} {{#employees}} {{name}} {{salary}} {{/employees}} {{/departments}}注意{{#departments}}和{{/departments}}之间的区域会被 Fesod 识别为循环区域。里面又有{{#employees}}嵌套循环渲染时 Fesod 会自动复制内部区域 N 行。这个能力在 EasyExcel 里实现起来极其痛苦有人会用CellRange计算行数然后手工复制有人干脆用 POI 直接操作Fesod 把这套操作内建成了模板语法。4.3 合并单元格与自动换行嵌套 List 渲染完成后另一个常见需求就是合并单元格。还是上面那个例子员工属于同一个部门部门列应该合并成一个大单元格。Fesod 提供了一种“按值合并”的模式你可以直接声明某一列的合并规则填充完成后自动做区域合并。template.fill(data); template.mergeRegion(A1:A (lastRowIndex));这里的lastRowIndex可以根据实际渲染结果动态获取。代码不复杂但背后有一个知识点合并单元格时如果区域内存在多个不同的值Fesod 会默认保留第一个值并把其他行的值清空。这个行为很关键因为很多人合并完发现数据丢了其实是被清掉了。换行问题则是另一个高频困扰。EasyExcel 里设置单元格自动换行需要手动处理CellStyle而且如果你在模板里直接粘贴带换行符的文本渲染后经常发现换行失效。Fesod 在填充时对\n字符的处理要敏感得多模板单元格只要设置了对齐方式为“自动换行”填充进去的\n就会正确显示为换行。技巧如果你发现填充后的 Excel 换行不生效先检查单元格的对齐方式里有没有勾选“自动换行”。这个不是 Fesod 的 Bug而是 Excel 本身的显示逻辑。代码层面你也可以强制设置但最好的方式是在模板里就配好。5. 常见问题与排查技巧实录迁移过程中我整理了一份问题速查清单很多都是从 EasyExcel 时代就踩过、到 Fesod 这里重演的问题。这里挑几个有代表性的详细说。5.1 libfreetype6 缺失这个问题是在 Linux 服务器上导出带条形码或二维码的 Excel 报表时遇到的。Fesod 底层在做某些图像渲染时会调用系统的 FreeType 库如果环境里没有装导入阶段会直接报错。排查方式先确认是不是所有环境都报还是只有某些 Linux 镜像才报。大多数情况下是精简版容器镜像缺少字体库。解决办法是安装基础依赖比如 Ubuntu/Debian 系执行apt-get install -y libfreetype6 libfreetype6-dev fonts-dejavuCentOS/RHEL 系对应的是freetype和freetype-devel。装完之后重启服务基本就能解决。这个坑在本地 Mac/Windows 上很难复现因为系统自带所以务必在 Dockerfile 或初始化脚本里加一步。提示用容器部署的最好在 Dockerfile 里就把这些系统依赖写进去不要等运行时再手动装不然每次重新部署都会再踩一遍。5.2 NoSuchFieldError: factory这个错误的主要原因就是 POI 版本冲突。EasyExcel 内部依赖了一个 POI 版本你的项目又引入了另一个 POI 版本当两个版本对同一个类的内部字段定义不一致时运行期就会爆这个错。Fesod 在依赖隔离上做得相对干净但如果你项目里还有别的组件间接依赖 POI依然可能出现冲突。处理思路分两种如果项目里已经有明确的 POI 版本检查 Fesod 对应的 POI 版本和它是否一致不一致就统一。使用 Maven 的dependencyManagement锁定 POI 版本。dependencyManagement dependencies dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version5.2.5/version /dependency /dependencies /dependencyManagement锁版本之后mvn dependency:tree看一下有没有重复的 POI有的话用exclusion排除掉。5.3 大数据量写入时的内存膨胀Fesod 流式模式默认通过缓存区域来降低内存消耗但如果你一次性往一张表里塞几十万行即使流式模式也可能出现 GC 压力。我建议对这种场景做两层优化第一层控制单 Sheet 的行数。业务上可以按数据量自动拆成多个 Sheet每个 Sheet 最多 5 万行既满足 Excel 限制也避免内存占用过高。第二层使用 Fesod 的writer批量刷入模式而不是构建完整的内存模型后一次写入。FesodWorkbookFactory.create()生成 writer 后可以分批往里面写行写完一批就释放一批引用。5.4 模板填充结果错位模板填充错位是最隐蔽的坑。往往不是你代码逻辑错了而是模板里存在多余的空行、隐藏行、或者被误合并的单元格。Fesod 解析循环区域时是严格按照单元格区域边界来识别的模板里多一个空行都会导致渲染结果偏移。我的做法是模板设计好之后先用 Fesod 渲染一个只有一条测试数据的文件肉眼检查结果。如果第一行正常、第二行开始偏了基本就是循环区域边界问题。把模板里的空行删掉、把多余的合并拆分掉、重新设置循环区域再试一次。5.5 问题速查表问题现象可能原因解决方式导入时列错位合并单元格导致列索引偏差检查表头节点的合并区域并修正索引模板填充后行数异常循环区域范围不对删除多余空行重新定义循环标签Linux 上报字体库错误缺少 FreeType 系统库安装 libfreetype6/fonts-dejavuNoSuchFieldError: factoryPOI 版本冲突统一 POI 版本排除多余依赖写入大数据量 GC 频繁一次性加载全量数据分批写入限制单 Sheet 行数换行不生效单元格未设置自动换行模板中开启自动换行或代码设置样式6. 迁移之后的一些实际体会迁移到 Fesod 不是银弹它同样有自己的学习成本和空窗期。社区文档不算多遇到冷门问题需要花时间翻源码这点确实不如 EasyExcel 搜啥都有。但对我来说换来的收益很值复杂表头不用再写几百行解析逻辑嵌套 List 模板填充直接在模板里声明循环区域底层 POI 版本冲突的问题也基本绝迹了。如果让我给建议我会说如果你的项目只是简单的数据导出导入完全没必要迁移EasyExcel 依然是好工具但如果你已经在复杂表头和模板填充上反复受挫那么 Fesod 值得花一个周末试试。先拿一个次要场景做验证别一上来就在核心模块动刀。还有一个小技巧迁移时给 Fesod 的读写各封装一层仓库接口后面就算再换方案业务层也不用动。总之工具会迭代但把底层细节封装在门面后面永远是性价比最高的做法。