在使用Apache POI操作Excel文件时，很多开发者都会遇到一个棘手的报错：org.apache.poi.poifs.filesystem.NotOLE2FileException: Invalid header signature; read 0x6D78206C6D74683C, expected 0xE11AB1A1E011CFD0 - Your file appears not to be a valid OLE2 document。
初次遇到这个报错，很容易陷入“文件损坏”“依赖缺失”的误区，其实它的核心原因非常明确，今天就带大家彻底搞懂这个报错，一步到位解决问题，避免重复踩坑。
一、报错核心原因（一句话看懂）
这个报错的本质只有一个：你用了处理「旧版Excel（.xls）」的代码，去读取「新版Excel（.xlsx）」，或者你操作的文件根本不是标准Excel文件。
先给大家普及两个关键概念，理解后就不会再用错代码：
- OLE2格式：对应旧版Excel（.xls），是Excel 97-2003版本的文件格式，POI中用HSSF相关类处理；
- OOXML格式：对应新版Excel（.xlsx），是Excel 2007及以上版本的文件格式，POI中用XSSF相关类处理。
报错信息中的关键提示的含义：
- expected 0xE11AB1A1E011CFD0：这是标准.xls文件的头部签名，是POI识别旧版Excel的标志；
- read 0x6D78206C6D74683C：这是程序实际读取到的文件头部信息，不是合法的Excel文件签名，说明文件格式不匹配或文件本身有问题。
二、3种最常见的报错场景（对号入座）
场景1：代码混用（90%的开发者都会踩的坑）
这是最常见的原因，简单说就是“用错了工具”。比如：
用处理.xls的HSSFWorkbook、POIFSFileSystem类，去读取.xlsx文件，代码示例如下（错误示范）：
// 错误代码：用HSSF处理.xlsx文件
FileInputStream fis = new FileInputStream("test.xlsx");
HSSFWorkbook workbook = new HSSFWorkbook(fis); // 此处必报NotOLE2FileException核心问题：HSSF系列类仅支持.xls，无法识别.xlsx格式，二者不能混用。
场景2：文件后缀名“造假”
很多人图方便，把.csv文件、普通文本文件，或者.xlsx文件，强行修改后缀名为.xls，导致POI识别失败。
比如：将“data.csv”改成“data.xls”，虽然文件图标变成了Excel，但本质还是CSV文件，POI读取时会因为头部签名不匹配报错。
场景3：文件本身不合法（损坏/非Excel文件）
这种情况也很常见，主要包括：
- 文件下载不完整（比如浏览器下载中断、传输过程中损坏）；
- 文件是网页、图片、加密Excel，或者被修改过后缀的非Excel文件；
- Excel文件本身损坏，用Office打开时会提示“修复文件”。
三、终极解决方案（3种方案，按需选择）
方案1：使用WorkbookFactory（最省心，推荐首选）
POI提供了WorkbookFactory类，能够自动识别Excel文件格式（.xls/.xlsx），无需手动区分，一行代码解决所有版本适配问题，彻底避免报错。
正确代码示例（可直接复制使用）：
import org.apache.poi.ss.usermodel.Workbook;
import org.apache.poi.ss.usermodel.WorkbookFactory;
import java.io.FileInputStream;
public class ExcelReadDemo {
public static void main(String[] args) {
// 替换为你的Excel文件路径（支持.xls和.xlsx）
String filePath = "D:\\test.xlsx";
try (FileInputStream fis = new FileInputStream(filePath);
// 自动识别文件格式，无需区分.xls和.xlsx
Workbook workbook = WorkbookFactory.create(fis)) {
// 后续读取Excel的逻辑（通用，无需修改）
System.out.println("Excel读取成功，工作表数量：" + workbook.getNumberOfSheets());
} catch (Exception e) {
e.printStackTrace();
}
}
}优点：兼容性强，无需关注文件格式，代码简洁，后续维护成本低；
注意：使用该方法，必须确保依赖包完整（下文会讲）。
方案2：手动区分文件格式（精准控制，适合特殊场景）
如果需要对不同格式的Excel做差异化处理，可以手动区分后缀名，分别使用对应的处理类：
import org.apache.poi.hssf.usermodel.HSSFWorkbook;
import org.apache.poi.xssf.usermodel.XSSFWorkbook;
import java.io.FileInputStream;
public class ExcelReadDemo2 {
public static void main(String[] args) {
String filePath = "D:\\test.xlsx";
try (FileInputStream fis = new FileInputStream(filePath)) {
Workbook workbook;
// 手动判断文件后缀，区分格式
if (filePath.endsWith(".xls")) {
// 处理旧版.xls文件
workbook = new HSSFWorkbook(fis);
} else if (filePath.endsWith(".xlsx")) {
// 处理新版.xlsx文件
workbook = new XSSFWorkbook(fis);
} else {
throw new RuntimeException("不支持的文件格式，请使用.xls或.xlsx");
}
System.out.println("读取成功，工作表名称：" + workbook.getSheetAt(0).getSheetName());
} catch (Exception e) {
e.printStackTrace();
}
}
}方案3：排查文件本身问题（解决非代码原因）
如果代码没问题，还是报错，就需要排查文件本身：
- 验证文件：用Office或WPS手动打开文件，看是否能正常打开，是否提示“文件损坏”；
- 核对后缀：确认文件后缀是真实的.xls或.xlsx，不要强行修改后缀；
- 重新获取文件：如果是下载的文件，重新下载，确保下载完整；如果是他人传输的，让对方重新发送。
四、必做检查：依赖包配置（缺一不可）
很多人用了正确的代码，还是报错，原因是POI依赖包不完整。操作Excel需要同时引入两个核心依赖：poi（支持.xls）和poi-ooxml（支持.xlsx）。
以下是Maven依赖配置（推荐版本5.2.5，稳定无bug）：
<!-- 旧版.xls格式支持 -->
<dependency>
<groupId>org.apache.poi</groupId>
<artifactId>poi</artifactId>
<version>5.2.5</version>
</dependency>
<!-- 新版.xlsx格式支持 -->
<dependency>
<groupId>org.apache.poi</groupId>
<artifactId>poi-ooxml</artifactId>
<version>5.2.5</version>
</dependency>如果是Gradle项目，对应依赖配置：
implementation 'org.apache.poi:poi:5.2.5'
implementation 'org.apache.poi:poi-ooxml:5.2.5'注意：两个依赖的版本必须一致，否则会出现版本冲突，导致报错。
五、快速排查步骤（5分钟定位问题）
如果遇到报错，按照以下步骤排查，高效解决问题：
- 看后缀：确认Excel文件后缀是.xls还是.xlsx，是否被修改过；
- 验文件：用Office打开文件，确认文件能正常打开、无损坏；
- 查代码：检查是否用了HSSF类处理.xlsx文件，替换为WorkbookFactory或XSSF类；
- 核依赖：确认poi和poi-ooxml两个依赖都已引入，版本一致；
- 换文件：用一个已知正常的Excel文件测试，排除文件本身问题。
六、总结
其实NotOLE2FileException报错并不复杂，核心就是「文件格式与处理代码不匹配」，记住以下3点，就能彻底避免：
- 优先使用WorkbookFactory，自动适配.xls和.xlsx，省心又高效；
- 不要强行修改文件后缀，确保文件是标准Excel格式；
- 依赖包必须完整，poi和poi-ooxml缺一不可，版本保持一致。
按照本文的方案修改，基本上能100%解决这个报错。如果还有其他POI操作Excel的问题，欢迎在评论区留言讨论~
