简介：这是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.17
1.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 | .xls（Excel 97-2003） | org.apache.poi.hssf.usermodel | 较低 | 老格式文件读写 |
| XSSFWorkbook | .xlsx（Excel 2007+） | org.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 除了 Excel，3.17 还能干什么
除了最常见的 Excel，3.17 中还有几个模块容易被忽略：
poi-ooxml：包含对 .docx、.xlsx、.pptx 等 OOXML 格式的支持。poi-scratchpad：处理 .doc、.ppt、.vsdx 等老格式。poi-ooxml-schemas：OOXML 格式所需的 XML Schema 定义，处理 .xlsx 时必须的依赖之一。
实际工作中，用 POI 从 Word 文档里提取正文、读取 PowerPoint 里的备注文字，也都是很常见的需求。不过最核心的使用场景仍然是围绕 Excel 展开的，这也是 3.17 被讨论最多的地方。
3. 实操：一个完整的 Excel 读写导出案例
3.1 工程依赖配置与版本锁定
用 Maven 管理依赖的工程里，3.17 的坐标配置大概是这样的：
<dependency> <groupId>org.apache.poi</groupId> <artifactId>poi</artifactId> <version>3.17</version> </dependency> <dependency> <groupId>org.apache.poi</groupId> <artifactId>poi-ooxml</artifactId> <version>3.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.17，B 模块的框架又传递依赖了 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 常见问题速查表
| 现象 | 可能原因 | 解决思路 |
|---|---|---|
| NoClassDefFoundError | poi 与 poi-ooxml 版本不一致 | 在 dependencyManagement 固定统一版本 |
| 30MB 以上 xlsx 读取 OOM | XSSFWorkbook 全量加载内存 | 改用 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 里那些复杂的模块拆分，追根溯源往往比到处翻博客更高效。
本文还有配套的精品资源，点击获取
