1. 为什么越来越多人想跟 EasyExcel 说再见群里有人转了一条动态再见了EasyExcel我决定用Apache Fesod。底下马上炸出一串追问Fesod 是什么好用吗在哪能下载说实话我第一反应也是去查可 Apache 官网项目列表翻了一圈GitHub 的 apache 组织里也没找到对应的仓库等了几天也没看到正式的 release 通告。以我自己的判断这多半是圈子里某个博主起的新代号或者干脆就是标题党。与其去追一个来历不明的名字不如把 EasyExcel 到底哪里让人受不了、换的话能换谁、复杂表头和模板填充这些真正的硬骨头一次理清楚。这篇文章就是干这个的适合所有写 Java 后端、天天跟 Excel 导入导出打交道的人。1.1 EasyExcel 的功与过好用是真的难受也是真的先讲公道话。EasyExcel 能火起来核心就三个字省心。你用 ExcelProperty 注解标一下字段write 和 read 一行调用就能把 POI 那一大坨样板代码盖住。它的读取默认走 SAX 模式不会把整本 Excel 一次吞进内存这对动辄几十万行的大文件非常友好。国内很多项目选它不是因为大家懒得学 POI而是因为它解决了一个真问题让 Excel 读写变成日常 CRUD而不是每次都要开一个工具类写到凌晨。但用得越深越能摸到它的边界。第一个点是复杂表头导入。像三级表头、斜线表头、跨行跨列合并、动态追加列这些需求落在注解上就会非常拧巴。EasyExcel 对“固定表头、整整齐齐一行一个对象”这种场景很舒服可一旦表头是树形结构字段映射就没法用一行注解讲清楚你得手动去处理合并单元格信息等于又回到了 POI 的思路。第二个痛点是模板填充尤其是带合并单元格、嵌套列表的模板。EasyExcel 的 fill 接口可以按占位符填值但遇到同一行里既有普通字段又有列表字段或者模板里有大量合并单元格时样式错位和覆盖问题就会冒出来而且报错信息还不一定看得懂。第三个问题集中在依赖和升级上。EasyExcel 底层基于 POI可项目里往往还直接引了 POI 做其他功能。两边版本对不上经常冒出 NoSuchFieldError、NoSuchMethodError 这类诡异报错。热词里出现的 easyexcel nosuchfielderror factory、easyexcel libfreetype6基本都属于这一类要么是 POI 版本冲突要么是服务器缺字体库。版本一升级旧代码可能编译不过新代码的 API 又变了社区里又缺少一份足够清晰的迁移文档于是很多人对它的热情慢慢从“真香”变成了“再看看”。1.2 从“阿里 EasyExcel”到“Apache 生态”Fesod 到底是什么关于 EasyExcel 的去向很多人的印象还停留在“阿里开源”。后来社区里一直有消息说它会捐给 Apache 基金会未来会以 Apache 项目的名义继续演进坐标和包名都可能调整。无论这条线最终走到哪一步一个不争的事实是很多人在升级到新坐标或者改引用时遇到了各种兼容性问题。这也是“再见了EasyExcel”这类标题能引起共鸣的原因——当旧组件不再按预期更新或者更新带来一堆麻烦时大家的第一反应就是找一个新替代品。但“Apache Fesod”这个名字按我目前的核查结果并不是一个可以验证的正式项目。Apache 官方项目列表里查不到Maven 中央仓库里也搜不到对应坐标GitHub 的 apache 组织下没有对应的公开仓库。它更像是某位博主为了表达“我放弃 EasyExcel 了”这种情绪顺手造的代号甚至可能是某个未开源项目的预热。我不建议任何人仅凭一个名字就开始重构线上系统。遇到这种新名词正确做法是先做三件事第一去 Apache 官网项目列表确认它是不是顶级项目第二去 Maven 中央仓库搜坐标看有没有 release 版本第三去 GitHub 看仓库的 Star、commit 活跃度和 issue 响应速度。三关都过了再谈选型不迟。2. 如果不用 EasyExcel现在有哪些真实可选的路线既然要跟 EasyExcel 说再见总得有地方可以去。我把目前主流的路线分成三类回到 Apache POI 自己写、用封装类库、在 POI 之上做一层轻量自研。很多人第一反应是找“下一个 EasyExcel”但我更建议先回到底层重新理解一遍问题因为只有理解了 POI你才看得懂其他所有封装库到底帮你省了什么。2.1 Apache POI 才是真正绕不开的底层事实标准这句话可能有点绝对但在 Java 生态里做 Excel 处理最终几乎都会落到 Apache POI 头上。EasyExcel 也好FastExcel 也好底层走的都是 POI。POI 提供的是完整能力读取单元格、写样式、合并区域、公式计算、数据校验、图表几乎 Excel 能做的它都能做只是代码写起来繁琐对新手不友好。用 POI 做复杂表头导入时你能拿到最底层的控制力。比如通过 sheet.getMergedRegions() 拿到所有合并区域通过 CellRangeAddress 判断某个单元格是否在合并范围内写模板时你可以精确定位到某个命名单元格把值写进去而不影响周围样式。这些能力在高层封装里会被“简化”掉一部分遇到特殊需求反而更难绕过去。POI 的坑也很明确。常见的有两个一是 XSSF 模式把整个工作簿放进内存文件稍大就容易 OOM所以大批量导出要换 SXSSF 流式写入但 SXSSF 的文档频率、自动 flush 时机又需要调参二是版本差异大不同版本之间有些 API 标记了废弃但还没移除有些新方法在老版本里根本不存在一旦项目里出现两个 POI 版本直接爆炸。我的建议是如果决定回 POI先锁定一个主流版本把项目里所有传递依赖的 POI 统一掉再开始写代码。2.2 FastExcel看起来最像 EasyExcel 的替代品FastExcel 是最近社区里讨论比较多的一个封装层。它的定位很聪明底层还是 POI但 API 参考了 EasyExcel 的使用习惯让熟悉 EasyExcel 的人切过去成本低很多。比如注解驱动、一行读写、流式处理大文件这些理念都保留了同时又尝试规避 EasyExcel 在模板填充和复杂表头上的短板。不过在选它之前我建议先冷静看一下它的成熟度。它的问题在于生态沉淀时间不够网上能搜到的案例和问题排查文档比 EasyExcel 少一个量级。真到了生产环境遇到一个诡异的合并单元格错位或者样式丢失问题你能依赖的资料就少很多。我用过它的 demo写起来确实顺手但大型项目的复杂报表我暂时不敢直接压上去。如果你是评估新项目可以用一个非核心模块先跑一个月看看稳定性如果是存量系统我不建议就为了追新而迁移。2.3 自研封装什么时候才值得动这个手在很多公司里Excel 需求其实高度重复导入模板就那几张导出报表也就那几种格式。这种情况下与其每次引一个重型框架不如在 POI 上做一层几十行的小工具。我自己就维护过一套内部组件核心功能只有三个按命名区域写入值、按占位符填充普通字段、解析列表区域并循环写入行。这套东西满足了两三个系统的报表需求代码量不大出了 bug 也容易排查。自研封装最重要的一点是控制边界。只封装你用得着的场景不要想着做一个通用的 Excel 框架。一旦开始支持任意表头、任意模板、任意合并规则你就等于重新造了一个 EasyExcel而且大概率造得不如它。自研的另一个前提是团队里有人真的懂 POI并且愿意维护这个内部库。如果团队只会调 API那出了问题可能比引第三方库更麻烦。3. 复杂表头导入与模板填充所有轮子的分水岭说实话普通 Excel 读写用什么库区别不大真正的分水岭在复杂表头导入和模板填充。这两块做不好再好看的技术选型都是白搭。接下来我拆一下这两个场景的难点和我的处理思路顺便把嵌套列表、单元格换行这些“最后一公里”的坑也一起说了。3.1 复杂表头导入难在哪合并区域、表头树、动态列复杂表头之所以难是因为 Excel 的一行无法表达层级关系。比如“个人信息”下面挂“姓名、年龄”“成绩”下面挂“语文、数学、英语”视觉上是一个二维表格底层却是一堆合并单元格。读取的时候如果按普通行遍历你会发现第二行某些单元格是空的因为这些位置属于上一层的合并区域。想要正确解析核心是先把表头区域构建成树。我的做法分三步。第一步扫描表头区域把每个单元格的行号、列号、值、是否处于合并区域、合并范围都记录下来。关键代码是遍历合并区域集合判断一个坐标是否在某个 CellRangeAddress 范围内如果有就从 range.getFirstRow() 和 range.getFirstColumn() 拿左上角的值作为这一格的有效值。第二步根据列区间构建表头树。每一层的列跨度决定了它的子节点分布比如“成绩”占两列那它的子节点“语文”“数学”就分配在这两列上。第三步数据行从表头结束的下一行开始读按表头树的叶子节点列索引去取字段值动态列则需要额外准备一个“列名到字段名”的映射配置。这里有个容易踩的坑表头行数不能写死。不同模板的表头层数不一样我会用一个扫描逻辑去找“最后一个非空子表头单元格”所在的行把它作为表头结束行。另外合并单元格的值只在左上角存在其他位置的单元格读出来是 null如果不做“合并区域补全”表头树会直接短路。调试时我习惯把行列号打印出来先看原始读取有没有问题再做映射。3.2 模板填充与合并单元格从能导出到能对齐模板填充的场景通常是业务方给了一份设计好的 Excel 模板里面已经写好了标题、样式、合并区域、公式我们只要在指定位置填数据。最稳妥的做法是先把模板做好代码里不重建样式只往目标单元格写值。定位目标位置可以用命名区域也可以在代码里写死行列号但命名区域可读性更好、后续模板调整时不用改代码逻辑。写入合并单元格时有一个非常关键的细节必须写到合并区域的左上角单元格否则看起来像是写进去了实际数据并不会显示或者会破坏合并结构。POI 里可以通过 sheet.getMergedRegions() 拿到所有合并区域判断目标位置是否落在某个区域内如果落在里面就定位到 range.getFirstRow()、range.getFirstColumn() 再写入。填充列表数据时还要注意不要破坏模板里已有的行样式。我习惯的做法是先复制模板中某一行的样式再在下面插入新行插入后重新设置样式否则新行会变成默认样式一眼就能看出来是程序导出的。3.3 嵌套列表、单元格换行这几个“最后一公里”细节嵌套列表是模板填充里最容易让人崩溃的需求。比如一个订单模板上半部分是订单号、客户名、下单时间中间是一张订单明细表明细表下面还有汇总字段。这类模板不能简单地一次 fill 完我的处理方式是分阶段填充先填充普通字段再扩展明细区域最后填充汇总。如果明细行数不确定必须提前算好要插入多少行再从明细区域的最后一行开始往上扩展否则前面的数据会被推走。单元格换行是另一个小但烦人的问题。在 POI 里往单元格写字符串时字符串里的 \n 不会自动生效必须把单元格样式里的 wrapText 设为 true否则换行符会被当成空白符吞掉。设置完 wrapText 之后还要手动调整行高因为 POI 不会根据内容自动撑高行。实测中导出的 Excel 在 Windows 上打开时行高偶尔会比内容矮一截这时可以按内容行数估算一个最小行高或者干脆把行高设成一个保守的值。4. 常见报错与排查技巧实录选型是一回事真到了写代码和跑生产的时候问题永远比想象中多。我把这几年在 Excel 导入导出上踩过的典型问题整理成了速查表后面再补一些排查思路都是实打实能直接拿去用的经验。4.1 依赖与运行时报错速查表报错关键字常见原因排查方向NoSuchFieldError: factoryPOI 版本冲突某个类字段在新版本中被移除用 mvn dependency:tree 查 POI 版本并统一NoSuchMethodError传递依赖把 POI 版本拉低了锁定 POI 版本排除旧传递依赖java.lang.NoClassDefFoundError缺包或类被隔离检查依赖范围确认 jar 是否完整libfreetype6 相关错误服务器缺少字体渲染库安装字体库或换更轻量的导入导出方式java.lang.OutOfMemoryError读取/写入模式选择不当读用 SAX/流式写考虑 SXSSF遇到 NoSuchFieldError 这类问题最直接的手段是跑一下mvn dependency:tree -Dincludesorg.apache.poi看项目里到底引了几个 POI 版本。很多冲突不是直接依赖造成的而是 A 库带 poi-ooxml 3.16B 库带 poi-ooxml 4.1.2两个 jar 在 classpath 里打架。统一版本之后大概率就好了。不要在报错信息里看到一行 factory 就以为是被劫持或者代码写错了先查依赖树。4.2 数据写入和样式表现层的疑难杂症数据写进去没问题但打开 Excel 后发现各种“不对”这类问题往往比报错更磨人。数字变成科学计数法多半是单元格默认格式的问题解决办法是在创建单元格时把 cellType 设为 STRING或者通过 setDataFormat 指定纯文本格式。日期显示成一串数字是因为日期实际上是一个序列值必须把单元格格式设为日期格式或者用 DataFormatter 统一处理后再展示。复杂表头导入时第一行被误当成数据行也是高频问题。我遇到过几次后来发现是表头结束行的判断条件写得太简单比如只看某一列是否为空而那一列恰好整个表头区域都为空。正确做法是扫描完整行判断整行是否所有业务列都为空再把这一行作为表头结束标志。模板填充后合并单元格错位也一样要先打印行列号定位看看是不是填到了不是左上角的位置。4.3 我的选型结论和踩坑清单如果项目已经在用 EasyExcel而且用得好好的我建议别动。技术选型最忌讳“别人说不好我也要换”没有足够的收益就承担迁移成本不划算。如果确实被某些场景卡住了比如复杂表头和模板填充实在搞不定那就回到底层 POI把关键模块用 POI 重写其他模块继续沿用旧方案渐进替换比一次性重写稳得多。关于 Fesod 这类名字我的态度很明确等它真的有了可下载的 jar、可跑的 demo、可看的 issue 记录再考虑接手。不要因为一个标题就去重构也不要因为一次升级失败就去否定一个还在维护的项目。技术选型选的是稳定性、可控性和团队熟悉度不是一时情绪。真正稳的方案往往是那个你愿意读源码、改得动 bug 的方案。