尧图网页设计 
简介这是Apache POI 3.17版本的完整Java开发包面向需要读写Excel、Word等Office文档的Java开发者解决在项目中操作.xls与.xlsx格式文件时的依赖配置和API调用问题。压缩包内共2000个文件以13个核心及依赖jar包为主包括poi-3.17.jar、xmlbeans-2.6.0.jar、curvesapi-1.04.jar、commons-codec-1.10.jar、commons-collections4-4.1.jar等其中xmlbeans用于XML文档解析curvesapi提供曲线图表支持commons-codec负责常用编解码commons-collections4则增强集合处理能力共同保证POI功能的完整运行。另有大量html帮助文档、png/jpg示例图片和css样式文件覆盖各子模块的类说明、方法索引与界面示意便于离线查阅API并理解展示效果压缩包整体约28.82MB。目前已有489人学习下载特别适合希望快速引入POI依赖进行Excel报表生成、数据导入导出及公式处理的初中级Java工程师。通过该资源读者可一步到位获得全量jar及相关依赖省去逐个查找下载的麻烦包内齐全的API页面与示例图片也有助于深入理解HSSF、XSSF、SXSSF等核心接口的用法方便二次开发与排错。 如果你是在用 Java 处理 Excel、Word、PPT 这类 Office 文档那对 poi.jar 这个名字一定不陌生。作为 Apache 基金会下的老牌开源库Apache POI 在 Java 领域的地位基本等同于操作 Office 文档的事实标准。而 3.17 这个版本虽然发布时间已经有些年头了但它至今仍是很多生产环境里跑得最稳、被引用最多、也最常被讨论的版本之一。这篇文章我不会去念 API 文档而是从一个实际维护过大量 POI 相关代码的开发者视角聊一聊 poi.jar 3.17 到底适合什么场景、怎么把它用好、以及那些官方文档里不会写明白的坑。无论你是刚接触 POI 的新手还是被老项目里 Excel 导出功能困扰许久的维护者这篇文章应该都能给你一些实实在在的参考。1. 为什么到现在还有人在找 poi.jar 3.171.1 3.17 版本的历史定位与不可替代性Apache POI 3.17 是 2017 年年中发布的版本但我观察到直到今天仍然有大量项目在主动锁定这个版本而不是升级到 4.x 甚至 5.x。原因并不复杂3.17 是最后一个支持 Java 6/7 的稳定版本。从 4.0 开始POI 的最低运行环境直接提升到了 Java 8。对于许多金融、传统企业、制造业的老系统来说JDK 版本受制于历史包袱很难说升就升于是 3.17 就成了这些环境里最合理的“天花板”。另一方面3.17 在稳定性上确实口碑不错。它处在 POI 从 OOXML 支持逐步成熟的过渡期XSSF 和 SXSSF 两种 Excel 处理模式都已经能够应付绝大多数生产场景而某些 API 还没有经历后面大版本重构带来的改动。简单来说这个版本“能打的活都打了该稳的地方也稳了”所以很多团队宁可继续使用它也不愿意冒着兼容性风险去做升级。1.2 老项目的真实困境不是不想升而是升不动我自己就遇到过类似的情况。一个运行了快十年的报表系统核心导出的代码全部基于 3.17 编写的整套代码里用了大量 HSSFWorkbook、XSSFWorkbook、CellStyle 缓存、FormulaEvaluator 这套老 API。如果升级到 4.x至少需要处理几类问题org.apache.poi.ss.usermodel包下的部分接口签名有调整直接编译不通过。依赖的xmlbeans、commons-collections4等传递依赖版本变化容易和项目里其他框架冲突。升级后某些样式和公式的渲染行为会和原来不一样需要回归测试。这三条每一条都足够劝退。所以如果你的项目也是类似情况别纠结先把手头的事做好3.17 在 Java 6/7 和旧版 JDK 环境里依然是一个非常靠谱的选择。2. poi.jar 3.17 核心结构与应用场景2.1 一套 Jar 包两种文档模型poi.jar 并不是一个单一功能的类库它内部针对 Excel 的不同格式提供了完全不同的实现模型。这一点很多新手一开始容易混。简单来说类名对应格式包位置内存占用适用场景HSSFWorkbook.xlsExcel 97-2003org.apache.poi.hssf.usermodel较低老格式文件读写XSSFWorkbook.xlsxExcel 2007org.apache.poi.xssf.usermodel较高常规 Excel 导出SXSSFWorkbook.xlsx流式写入org.apache.poi.xssf.streaming低滑动窗口大数据量导出HSSF 处理的是二进制格式的 .xls虽然格式老但性能其实很好适合处理小规模文件或者兼容旧系统。XSSF 处理的是 OOXML 格式的 .xlsx本质上是把 Excel 文件当作一个 ZIP 包来解析所以功能最强但 Workbook 对象会把整个文档结构加载到内存里文件一大就容易 OutOfMemory。SXSSF 是 3.17 里非常值得关注的能力它基于 XSSF 做了流式处理只保留滑动窗口内的行数据在内存非常适合生成上万甚至十万行的导出文件。我自己的经验是如果是做日常的报表导出优先想清楚数据量级再选模型。十行和十万行方案完全是两回事。3.17 时代 SXSSF 已经比较成熟没必要非抱着 XSSF 死撑大文件。2.2 除了 Excel3.17 还能干什么除了最常见的 Excel3.17 中还有几个模块容易被忽略poi-ooxml包含对 .docx、.xlsx、.pptx 等 OOXML 格式的支持。poi-scratchpad处理 .doc、.ppt、.vsdx 等老格式。poi-ooxml-schemasOOXML 格式所需的 XML Schema 定义处理 .xlsx 时必须的依赖之一。实际工作中用 POI 从 Word 文档里提取正文、读取 PowerPoint 里的备注文字也都是很常见的需求。不过最核心的使用场景仍然是围绕 Excel 展开的这也是 3.17 被讨论最多的地方。3. 实操一个完整的 Excel 读写导出案例3.1 工程依赖配置与版本锁定用 Maven 管理依赖的工程里3.17 的坐标配置大概是这样的dependency groupIdorg.apache.poi/groupId artifactIdpoi/artifactId version3.17/version /dependency dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version3.17/version /dependency这里有一个隐藏的细节只引入poi-ooxml是会自动带入poi和poi-ooxml-schemas的但如果你的项目里同时还需要写.xls老格式只依赖poi-ooxml可能会有覆盖不全的情况。最稳妥的做法是显式声明poi和poi-ooxml两个 jar让版本号完全一致避免 Maven 依赖仲裁时拉取到不同版本。我见过不少异常比如NoClassDefFoundError: org/apache/poi/ss/usermodel/Workbook排查到最后都是因为poi和poi-ooxml版本不一致导致的。这个问题在 3.17 上尤其常见因为那个时代很多依赖传递链设计的还不像现在这么规范。3.2 写 Excel从创建 Workbook 到写出文件直接看一个相对完整的例子这里实现的是一个“员工信息报表”导出包含表头样式、日期格式化、单元格合并、自动列宽这几个常见需求import org.apache.poi.ss.usermodel.*; import org.apache.poi.xssf.streaming.SXSSFWorkbook; import java.io.FileOutputStream; import java.util.Date; public class EmployeeReportExport { public static void main(String[] args) throws Exception { // SXSSFWorkbook 适合数据量较大的导出场景参数 100 表示滑动窗口大小 Workbook workbook new SXSSFWorkbook(100); Sheet sheet workbook.createSheet(员工信息); sheet.setDefaultColumnWidth(18); CellStyle headerStyle workbook.createCellStyle(); Font headerFont workbook.createFont(); headerFont.setBold(true); headerFont.setFontHeightInPoints((short) 12); headerStyle.setFont(headerFont); headerStyle.setAlignment(HorizontalAlignment.CENTER); headerStyle.setVerticalAlignment(VerticalAlignment.CENTER); CellStyle dateStyle workbook.createCellStyle(); CreationHelper createHelper workbook.getCreationHelper(); dateStyle.setDataFormat(createHelper.createDataFormat().getFormat(yyyy-MM-dd)); String[] headers {工号, 姓名, 部门, 入职日期, 月薪}; Row headerRow sheet.createRow(0); for (int i 0; i headers.length; i) { Cell cell headerRow.createCell(i); cell.setCellValue(headers[i]); cell.setCellStyle(headerStyle); } Object[][] data { {E001, 张三, 研发部, new Date(), 15000.0}, {E002, 李四, 产品部, new Date(), 18000.0}, }; for (int i 0; i data.length; i) { Row row sheet.createRow(i 1); for (int j 0; j data[i].length; j) { Cell cell row.createCell(j); if (data[i][j] instanceof Date) { cell.setCellValue((Date) data[i][j]); cell.setCellStyle(dateStyle); } else if (data[i][j] instanceof Number) { cell.setCellValue(((Number) data[i][j]).doubleValue()); } else { cell.setCellValue(String.valueOf(data[i][j])); } } } // 合并第一行表头下的某些单元格这里示例为把第3行前两列合并 // sheet.addMergedRegion(new CellRangeAddress(2, 2, 0, 1)); try (FileOutputStream fos new FileOutputStream(员工信息.xlsx)) { workbook.write(fos); } // 流式写入模式下需要显式关闭以清空临时文件 workbook.close(); System.out.println(导出完成); } }这段代码里我想强调几个点。第一SXSSFWorkbook(100)中的 100 是窗口大小意思是在内存里只保留最近 100 行更早的行会被刷入临时文件。这个数字并不是越大越好太大会造成内存浪费太小又会影响某些需要随机访问行的操作。第二workbook.close()在 SXSSF 模式下是必须的因为它会在临时目录里生成中间文件不关闭就会留下垃圾文件。如果用的是 XSSFWorkbook 则不一定需要但为了习惯一致都关掉总没错。另外单元格宽度方面setColumnWidth的单位是 1/256 个字符宽度。如果要让列宽根据内容自适应可以用sheet.autoSizeColumn(i)但这个方法在数据量大时性能很差我建议只在小文件或者样式要求高的场景用。3.3 读 Excel处理日期、公式与数值格式读 Excel 比写 Excel 的坑多得多尤其是你根本不知道用户会在单元格里塞什么类型的数据时。下面是一个读取 .xlsx 文件的完整示例重点展示了日期单元格、公式单元格、数字单元格的处理方式import org.apache.poi.ss.usermodel.*; import org.apache.poi.xssf.usermodel.XSSFWorkbook; import java.io.FileInputStream; public class EmployeeReportReader { public static void main(String[] args) throws Exception { try (Workbook workbook new XSSFWorkbook(new FileInputStream(员工信息.xlsx))) { Sheet sheet workbook.getSheetAt(0); DataFormatter formatter new DataFormatter(); for (Row row : sheet) { for (Cell cell : row) { switch (cell.getCellType()) { case Cell.CELL_TYPE_STRING: System.out.print(cell.getStringCellValue() \t); break; case Cell.CELL_TYPE_NUMERIC: if (DateUtil.isCellDateFormatted(cell)) { System.out.print(cell.getDateCellValue() \t); } else { System.out.print(cell.getNumericCellValue() \t); } break; case Cell.CELL_TYPE_FORMULA: // 拿公式的缓存值 System.out.print(cell.getCachedFormulaResultType() \t); break; default: // 空单元格也统一输出一个占位 System.out.print(-\t); } } System.out.println(); } } } }读 Excel 时最经典的坑就是日期列读出的是数字。Excel 内部的日期本质上是距 1900 年 1 月 1 日的天数序列所以如果你的单元格是日期格式getNumericCellValue()拿到的就是 40000 这种数字。用DateUtil.isCellDateFormatted(cell)可以判断单元格格式化规则是否为日期格式如果是再调用getDateCellValue()转换。DataFormatter是另一个神器它能按照单元格的显示格式把值转成字符串。比如数字 1234.5 如果设置了两位小数格式用 DataFormatter 拿到的就是 1234.50而不是原始 double。这在做报表数据核对时非常实用可以避免那些“数据对不上”的诡异问题。还有一个 3.17 里很经典的缺失功能DataFormatter默认不会对公式单元格触发重新计算需要配合FormulaEvaluator使用。如果你需要拿到公式的最新计算结果建议在读取前主动调用workbook.getCreationHelper().createFormulaEvaluator().evaluateAll()。4. 高频踩坑与排查经验4.1 找不到类、依赖冲突与 NoClassDefFoundError这个问题出现的频率远高于其他任何异常。典型的报错是java.lang.NoClassDefFoundError: org/apache/poi/ss/usermodel/Workbook或者java.lang.ClassNotFoundException: org.apache.xmlbeans.XmlObject。大部分情况下这都是因为项目里有多个版本甚至多个来源的 POI 相关 jar 同时出现在 classpath 中。比方说 A 模块引了 3.17B 模块的框架又传递依赖了 3.9最终运行时加载到的类可能来自 3.9然后调用 3.17 才有的 API 就炸了。解决思路如下用mvn dependency:tree找出所有 poi 相关依赖及其最终版本。在根 POM 的dependencyManagement里显式锁死poi、poi-ooxml、poi-ooxml-schemas、xmlbeans的版本。如果某个第三方框架捆绑了旧版 poi用exclusion排除掉。4.2 导出大文件内存溢出用XSSFWorkbook导出 5 万行数据堆内存 512MB 的话基本是必炸的。原因我已经提过XSSFWorkbook 会把所有的行、单元格、样式全部构建成对象图放在内存里。而SXSSFWorkbook通过滑动窗口机制将行数据写入了临时文件内存里只保留窗口内的行能稳定扛住十万行级别。但我还要提醒一个实际使用中的性能细节不要每行都创建新的 CellStyle。样式对象是走共享池的创建大量重复样式不仅内存暴涨写出的文件体积也会变大甚至可能导致打开文件变慢。正确做法是把样式对象提前创建好然后在行循环里复用。4.3 日期显示成数字、科学计数法、Excel 打开乱码日期列变成数字原因我上面已经讲过。科学计数法的问题则通常出在大数字上比如身份证号、订单号原本应该是字符串但如果你直接setCellValue(long)Excel 会把它当数字显示超过一定长度就会变成科学计数法。解决办法有两种要么在写入时明确调用setCellType(Cell.CELL_TYPE_STRING)然后传入字符串要么设置单元格格式为文本格式再用setCellValue(String)。我个人的习惯是凡是不需要参与计算的字段统一按字符串写省得后期再去处理格式问题。还有一个容易被忽略的导出细节文件名中的中文和空格在 HTTP 下载时会出现乱码或无法打开的问题。这里建议在设置 Content-Disposition 时做 URL 编码处理而不是直接拼原生字符串。4.4 常见问题速查表现象可能原因解决思路NoClassDefFoundErrorpoi 与 poi-ooxml 版本不一致在 dependencyManagement 固定统一版本30MB 以上 xlsx 读取 OOMXSSFWorkbook 全量加载内存改用 XSSFReader 或 SAX 事件模型单元格读出科学计数法长数字被当作 double 写入按字符串写入或设置文本格式日期单元格显示为数字dateStyle 未设置通过 CellStyle 设置 DataFormat导出文件行数几百行但很大每行重复创建样式复用 CellStyle 对象下载文件中文名乱码Content-Disposition 未编码用 URLEncoder 编码文件名文件无法打开且提示损坏未正常 close 流或写入未完成确保 OutputStream 刷新并关闭我在实际维护 3.17 版本项目的过程中最大的体会就是POI 这个库本身很强大但它更像一个“工具箱”用得好不好全看使用者对文档结构、数据模型、内存模型的理解。3.17 虽然版本老但只要把上面这些关键场景理清楚它在生产环境里的稳定程度和可维护性真的不比新版差多少。最后再分享一个小技巧如果你在 3.17 上遇到 API 相关的问题网上搜索时可以把关键词从“POI 3.17”换成“POI 3.17 源码”优先看源码。3.17 的源码阅读难度不大而且没有 4.x 里那些复杂的模块拆分追根溯源往往比到处翻博客更高效。本文还有配套的精品资源点击获取 poi.jar 3.17实战：Java处理Excel的稳定之选与避坑指南
简介这是Apache POI 3.17版本的完整Java开发包面向需要读写Excel、Word等Office文档的Java开发者解决在项目中操作.xls与.xlsx格式文件时的依赖配置和API调用问题。压缩包内共2000个文件以13个核心及依赖jar包为主包括poi-3.17.jar、xmlbeans-2.6.0.jar、curvesapi-1.04.jar、commons-codec-1.10.jar、commons-collections4-4.1.jar等其中xmlbeans用于XML文档解析curvesapi提供曲线图表支持commons-codec负责常用编解码commons-collections4则增强集合处理能力共同保证POI功能的完整运行。另有大量html帮助文档、png/jpg示例图片和css样式文件覆盖各子模块的类说明、方法索引与界面示意便于离线查阅API并理解展示效果压缩包整体约28.82MB。目前已有489人学习下载特别适合希望快速引入POI依赖进行Excel报表生成、数据导入导出及公式处理的初中级Java工程师。通过该资源读者可一步到位获得全量jar及相关依赖省去逐个查找下载的麻烦包内齐全的API页面与示例图片也有助于深入理解HSSF、XSSF、SXSSF等核心接口的用法方便二次开发与排错。 如果你是在用 Java 处理 Excel、Word、PPT 这类 Office 文档那对 poi.jar 这个名字一定不陌生。作为 Apache 基金会下的老牌开源库Apache POI 在 Java 领域的地位基本等同于操作 Office 文档的事实标准。而 3.17 这个版本虽然发布时间已经有些年头了但它至今仍是很多生产环境里跑得最稳、被引用最多、也最常被讨论的版本之一。这篇文章我不会去念 API 文档而是从一个实际维护过大量 POI 相关代码的开发者视角聊一聊 poi.jar 3.17 到底适合什么场景、怎么把它用好、以及那些官方文档里不会写明白的坑。无论你是刚接触 POI 的新手还是被老项目里 Excel 导出功能困扰许久的维护者这篇文章应该都能给你一些实实在在的参考。1. 为什么到现在还有人在找 poi.jar 3.171.1 3.17 版本的历史定位与不可替代性Apache POI 3.17 是 2017 年年中发布的版本但我观察到直到今天仍然有大量项目在主动锁定这个版本而不是升级到 4.x 甚至 5.x。原因并不复杂3.17 是最后一个支持 Java 6/7 的稳定版本。从 4.0 开始POI 的最低运行环境直接提升到了 Java 8。对于许多金融、传统企业、制造业的老系统来说JDK 版本受制于历史包袱很难说升就升于是 3.17 就成了这些环境里最合理的“天花板”。另一方面3.17 在稳定性上确实口碑不错。它处在 POI 从 OOXML 支持逐步成熟的过渡期XSSF 和 SXSSF 两种 Excel 处理模式都已经能够应付绝大多数生产场景而某些 API 还没有经历后面大版本重构带来的改动。简单来说这个版本“能打的活都打了该稳的地方也稳了”所以很多团队宁可继续使用它也不愿意冒着兼容性风险去做升级。1.2 老项目的真实困境不是不想升而是升不动我自己就遇到过类似的情况。一个运行了快十年的报表系统核心导出的代码全部基于 3.17 编写的整套代码里用了大量 HSSFWorkbook、XSSFWorkbook、CellStyle 缓存、FormulaEvaluator 这套老 API。如果升级到 4.x至少需要处理几类问题org.apache.poi.ss.usermodel包下的部分接口签名有调整直接编译不通过。依赖的xmlbeans、commons-collections4等传递依赖版本变化容易和项目里其他框架冲突。升级后某些样式和公式的渲染行为会和原来不一样需要回归测试。这三条每一条都足够劝退。所以如果你的项目也是类似情况别纠结先把手头的事做好3.17 在 Java 6/7 和旧版 JDK 环境里依然是一个非常靠谱的选择。2. poi.jar 3.17 核心结构与应用场景2.1 一套 Jar 包两种文档模型poi.jar 并不是一个单一功能的类库它内部针对 Excel 的不同格式提供了完全不同的实现模型。这一点很多新手一开始容易混。简单来说类名对应格式包位置内存占用适用场景HSSFWorkbook.xlsExcel 97-2003org.apache.poi.hssf.usermodel较低老格式文件读写XSSFWorkbook.xlsxExcel 2007org.apache.poi.xssf.usermodel较高常规 Excel 导出SXSSFWorkbook.xlsx流式写入org.apache.poi.xssf.streaming低滑动窗口大数据量导出HSSF 处理的是二进制格式的 .xls虽然格式老但性能其实很好适合处理小规模文件或者兼容旧系统。XSSF 处理的是 OOXML 格式的 .xlsx本质上是把 Excel 文件当作一个 ZIP 包来解析所以功能最强但 Workbook 对象会把整个文档结构加载到内存里文件一大就容易 OutOfMemory。SXSSF 是 3.17 里非常值得关注的能力它基于 XSSF 做了流式处理只保留滑动窗口内的行数据在内存非常适合生成上万甚至十万行的导出文件。我自己的经验是如果是做日常的报表导出优先想清楚数据量级再选模型。十行和十万行方案完全是两回事。3.17 时代 SXSSF 已经比较成熟没必要非抱着 XSSF 死撑大文件。2.2 除了 Excel3.17 还能干什么除了最常见的 Excel3.17 中还有几个模块容易被忽略poi-ooxml包含对 .docx、.xlsx、.pptx 等 OOXML 格式的支持。poi-scratchpad处理 .doc、.ppt、.vsdx 等老格式。poi-ooxml-schemasOOXML 格式所需的 XML Schema 定义处理 .xlsx 时必须的依赖之一。实际工作中用 POI 从 Word 文档里提取正文、读取 PowerPoint 里的备注文字也都是很常见的需求。不过最核心的使用场景仍然是围绕 Excel 展开的这也是 3.17 被讨论最多的地方。3. 实操一个完整的 Excel 读写导出案例3.1 工程依赖配置与版本锁定用 Maven 管理依赖的工程里3.17 的坐标配置大概是这样的dependency groupIdorg.apache.poi/groupId artifactIdpoi/artifactId version3.17/version /dependency dependency groupIdorg.apache.poi/groupId artifactIdpoi-ooxml/artifactId version3.17/version /dependency这里有一个隐藏的细节只引入poi-ooxml是会自动带入poi和poi-ooxml-schemas的但如果你的项目里同时还需要写.xls老格式只依赖poi-ooxml可能会有覆盖不全的情况。最稳妥的做法是显式声明poi和poi-ooxml两个 jar让版本号完全一致避免 Maven 依赖仲裁时拉取到不同版本。我见过不少异常比如NoClassDefFoundError: org/apache/poi/ss/usermodel/Workbook排查到最后都是因为poi和poi-ooxml版本不一致导致的。这个问题在 3.17 上尤其常见因为那个时代很多依赖传递链设计的还不像现在这么规范。3.2 写 Excel从创建 Workbook 到写出文件直接看一个相对完整的例子这里实现的是一个“员工信息报表”导出包含表头样式、日期格式化、单元格合并、自动列宽这几个常见需求import org.apache.poi.ss.usermodel.*; import org.apache.poi.xssf.streaming.SXSSFWorkbook; import java.io.FileOutputStream; import java.util.Date; public class EmployeeReportExport { public static void main(String[] args) throws Exception { // SXSSFWorkbook 适合数据量较大的导出场景参数 100 表示滑动窗口大小 Workbook workbook new SXSSFWorkbook(100); Sheet sheet workbook.createSheet(员工信息); sheet.setDefaultColumnWidth(18); CellStyle headerStyle workbook.createCellStyle(); Font headerFont workbook.createFont(); headerFont.setBold(true); headerFont.setFontHeightInPoints((short) 12); headerStyle.setFont(headerFont); headerStyle.setAlignment(HorizontalAlignment.CENTER); headerStyle.setVerticalAlignment(VerticalAlignment.CENTER); CellStyle dateStyle workbook.createCellStyle(); CreationHelper createHelper workbook.getCreationHelper(); dateStyle.setDataFormat(createHelper.createDataFormat().getFormat(yyyy-MM-dd)); String[] headers {工号, 姓名, 部门, 入职日期, 月薪}; Row headerRow sheet.createRow(0); for (int i 0; i headers.length; i) { Cell cell headerRow.createCell(i); cell.setCellValue(headers[i]); cell.setCellStyle(headerStyle); } Object[][] data { {E001, 张三, 研发部, new Date(), 15000.0}, {E002, 李四, 产品部, new Date(), 18000.0}, }; for (int i 0; i data.length; i) { Row row sheet.createRow(i 1); for (int j 0; j data[i].length; j) { Cell cell row.createCell(j); if (data[i][j] instanceof Date) { cell.setCellValue((Date) data[i][j]); cell.setCellStyle(dateStyle); } else if (data[i][j] instanceof Number) { cell.setCellValue(((Number) data[i][j]).doubleValue()); } else { cell.setCellValue(String.valueOf(data[i][j])); } } } // 合并第一行表头下的某些单元格这里示例为把第3行前两列合并 // sheet.addMergedRegion(new CellRangeAddress(2, 2, 0, 1)); try (FileOutputStream fos new FileOutputStream(员工信息.xlsx)) { workbook.write(fos); } // 流式写入模式下需要显式关闭以清空临时文件 workbook.close(); System.out.println(导出完成); } }这段代码里我想强调几个点。第一SXSSFWorkbook(100)中的 100 是窗口大小意思是在内存里只保留最近 100 行更早的行会被刷入临时文件。这个数字并不是越大越好太大会造成内存浪费太小又会影响某些需要随机访问行的操作。第二workbook.close()在 SXSSF 模式下是必须的因为它会在临时目录里生成中间文件不关闭就会留下垃圾文件。如果用的是 XSSFWorkbook 则不一定需要但为了习惯一致都关掉总没错。另外单元格宽度方面setColumnWidth的单位是 1/256 个字符宽度。如果要让列宽根据内容自适应可以用sheet.autoSizeColumn(i)但这个方法在数据量大时性能很差我建议只在小文件或者样式要求高的场景用。3.3 读 Excel处理日期、公式与数值格式读 Excel 比写 Excel 的坑多得多尤其是你根本不知道用户会在单元格里塞什么类型的数据时。下面是一个读取 .xlsx 文件的完整示例重点展示了日期单元格、公式单元格、数字单元格的处理方式import org.apache.poi.ss.usermodel.*; import org.apache.poi.xssf.usermodel.XSSFWorkbook; import java.io.FileInputStream; public class EmployeeReportReader { public static void main(String[] args) throws Exception { try (Workbook workbook new XSSFWorkbook(new FileInputStream(员工信息.xlsx))) { Sheet sheet workbook.getSheetAt(0); DataFormatter formatter new DataFormatter(); for (Row row : sheet) { for (Cell cell : row) { switch (cell.getCellType()) { case Cell.CELL_TYPE_STRING: System.out.print(cell.getStringCellValue() \t); break; case Cell.CELL_TYPE_NUMERIC: if (DateUtil.isCellDateFormatted(cell)) { System.out.print(cell.getDateCellValue() \t); } else { System.out.print(cell.getNumericCellValue() \t); } break; case Cell.CELL_TYPE_FORMULA: // 拿公式的缓存值 System.out.print(cell.getCachedFormulaResultType() \t); break; default: // 空单元格也统一输出一个占位 System.out.print(-\t); } } System.out.println(); } } } }读 Excel 时最经典的坑就是日期列读出的是数字。Excel 内部的日期本质上是距 1900 年 1 月 1 日的天数序列所以如果你的单元格是日期格式getNumericCellValue()拿到的就是 40000 这种数字。用DateUtil.isCellDateFormatted(cell)可以判断单元格格式化规则是否为日期格式如果是再调用getDateCellValue()转换。DataFormatter是另一个神器它能按照单元格的显示格式把值转成字符串。比如数字 1234.5 如果设置了两位小数格式用 DataFormatter 拿到的就是 1234.50而不是原始 double。这在做报表数据核对时非常实用可以避免那些“数据对不上”的诡异问题。还有一个 3.17 里很经典的缺失功能DataFormatter默认不会对公式单元格触发重新计算需要配合FormulaEvaluator使用。如果你需要拿到公式的最新计算结果建议在读取前主动调用workbook.getCreationHelper().createFormulaEvaluator().evaluateAll()。4. 高频踩坑与排查经验4.1 找不到类、依赖冲突与 NoClassDefFoundError这个问题出现的频率远高于其他任何异常。典型的报错是java.lang.NoClassDefFoundError: org/apache/poi/ss/usermodel/Workbook或者java.lang.ClassNotFoundException: org.apache.xmlbeans.XmlObject。大部分情况下这都是因为项目里有多个版本甚至多个来源的 POI 相关 jar 同时出现在 classpath 中。比方说 A 模块引了 3.17B 模块的框架又传递依赖了 3.9最终运行时加载到的类可能来自 3.9然后调用 3.17 才有的 API 就炸了。解决思路如下用mvn dependency:tree找出所有 poi 相关依赖及其最终版本。在根 POM 的dependencyManagement里显式锁死poi、poi-ooxml、poi-ooxml-schemas、xmlbeans的版本。如果某个第三方框架捆绑了旧版 poi用exclusion排除掉。4.2 导出大文件内存溢出用XSSFWorkbook导出 5 万行数据堆内存 512MB 的话基本是必炸的。原因我已经提过XSSFWorkbook 会把所有的行、单元格、样式全部构建成对象图放在内存里。而SXSSFWorkbook通过滑动窗口机制将行数据写入了临时文件内存里只保留窗口内的行能稳定扛住十万行级别。但我还要提醒一个实际使用中的性能细节不要每行都创建新的 CellStyle。样式对象是走共享池的创建大量重复样式不仅内存暴涨写出的文件体积也会变大甚至可能导致打开文件变慢。正确做法是把样式对象提前创建好然后在行循环里复用。4.3 日期显示成数字、科学计数法、Excel 打开乱码日期列变成数字原因我上面已经讲过。科学计数法的问题则通常出在大数字上比如身份证号、订单号原本应该是字符串但如果你直接setCellValue(long)Excel 会把它当数字显示超过一定长度就会变成科学计数法。解决办法有两种要么在写入时明确调用setCellType(Cell.CELL_TYPE_STRING)然后传入字符串要么设置单元格格式为文本格式再用setCellValue(String)。我个人的习惯是凡是不需要参与计算的字段统一按字符串写省得后期再去处理格式问题。还有一个容易被忽略的导出细节文件名中的中文和空格在 HTTP 下载时会出现乱码或无法打开的问题。这里建议在设置 Content-Disposition 时做 URL 编码处理而不是直接拼原生字符串。4.4 常见问题速查表现象可能原因解决思路NoClassDefFoundErrorpoi 与 poi-ooxml 版本不一致在 dependencyManagement 固定统一版本30MB 以上 xlsx 读取 OOMXSSFWorkbook 全量加载内存改用 XSSFReader 或 SAX 事件模型单元格读出科学计数法长数字被当作 double 写入按字符串写入或设置文本格式日期单元格显示为数字dateStyle 未设置通过 CellStyle 设置 DataFormat导出文件行数几百行但很大每行重复创建样式复用 CellStyle 对象下载文件中文名乱码Content-Disposition 未编码用 URLEncoder 编码文件名文件无法打开且提示损坏未正常 close 流或写入未完成确保 OutputStream 刷新并关闭我在实际维护 3.17 版本项目的过程中最大的体会就是POI 这个库本身很强大但它更像一个“工具箱”用得好不好全看使用者对文档结构、数据模型、内存模型的理解。3.17 虽然版本老但只要把上面这些关键场景理清楚它在生产环境里的稳定程度和可维护性真的不比新版差多少。最后再分享一个小技巧如果你在 3.17 上遇到 API 相关的问题网上搜索时可以把关键词从“POI 3.17”换成“POI 3.17 源码”优先看源码。3.17 的源码阅读难度不大而且没有 4.x 里那些复杂的模块拆分追根溯源往往比到处翻博客更高效。本文还有配套的精品资源点击获取