SpringBoot项目导出Excel报错？Unexpected record signature 0X9的两种修复方案-CSDN博客

SpringBoot项目导出Excel报错？Unexpected record signature 0X9的深度剖析与根治方案

最近在重构一个老项目的报表导出模块时，我又一次遇到了那个熟悉的“老朋友”——Unexpected record signature: 0X9。这已经不是第一次了，每次接手一个基于Maven构建的SpringBoot项目，只要涉及到从resources目录读取Excel、PDF等二进制模板文件进行导出，这个错误就像个定时炸弹，总会在某个不经意的打包时刻被引爆。表面上看，这是一个文件损坏的错误，但深究下去，你会发现它直指Maven资源处理机制的核心。对于追求交付稳定性的团队来说，这类问题不彻底解决，就如同在代码里埋下了隐雷。今天，我们就来彻底拆解这个问题的成因，并给出几种不仅治标、更能治本的解决方案，让你从此告别这类令人头疼的构建期“幽灵错误”。

1. 问题根源：当Maven的“好心”办了坏事

要解决问题，首先得理解问题是如何产生的。很多开发者第一次遇到 Unexpected record signature: 0X9 时，第一反应往往是：我的Excel模板文件是不是损坏了？于是反复替换文件，但问题依旧。实际上，问题的罪魁祸首很可能不是你，而是项目的构建工具——Maven。

在SpringBoot项目中，我们习惯将各种配置文件、静态模板（如Excel、Word）放在 src/main/resources 目录下。Maven在构建项目（执行 mvn compile 或 mvn package）时，默认会对 resources 目录下的资源文件进行处理，这个过程称为资源过滤（Resource Filtering）。

资源过滤的本意是什么？ 它的设计初衷非常有用：允许你在资源文件（如 .properties, .yml, .xml）中使用Maven属性（例如 ${project.version}）或环境变量（例如 ${DB_URL}），在构建时，Maven会自动将这些占位符替换为实际的值。这对于实现不同环境的配置差异化至关重要。

然而，这个机制对所有资源文件一视同仁。当它遇到一个二进制文件（比如 .xlsx、.pdf、.jar、图片等）时，它依然会尝试打开文件，解析其中的内容，寻找 ${...} 这类占位符。问题就出在这里：

二进制文件被误读为文本：Maven以文本方式读取二进制文件，会破坏文件原有的字节结构。
无意义的“替换”：即使文件中没有占位符，这个读取过程本身也可能引入编码错误或改变特定字节。
签名损坏：对于Excel（.xlsx）文件，其本质是一个ZIP压缩包，文件头部有特定的魔数（Magic Number）或签名。Maven的过滤操作可能会意外修改文件开头的几个字节，导致签名从预期的 0X504B0304（PK头）变成了 0X9 或其他无效值，从而在Java代码（使用Apache POI等库）读取时抛出 Unexpected record signature: 0X9 异常。

注意：0X9 只是一个常见报错值，实际可能遇到 0X3C、0XEF 等，其本质都是文件头部的关键字节被篡改。

简单来说，Maven的资源过滤功能“污染”了你的二进制资源文件。理解了这一点，我们的解决思路就非常清晰了：告诉Maven，哪些资源文件需要过滤，哪些需要“原样”复制，保持字节级完整。

2. 方案一：精细化控制Maven资源目录（推荐）

这是最直接、最符合Maven设计哲学的方式。通过在 pom.xml 中显式配置 <resources>，我们可以对 src/main/resources 目录下的文件进行精细化管理。

2.1 基础配置：排除特定文件类型

核心思想是配置两个资源规则：

规则一：处理大多数需要过滤的文本资源（如 .properties, .yml），但排除二进制文件。
规则二：单独处理二进制文件，并明确关闭过滤。

以下是详细的 pom.xml 配置示例：

<build>
    <resources>
        <!-- 规则一：处理除二进制文件外的所有资源，并开启过滤 -->
        <resource>
            <directory>src/main/resources</directory>
            <includes>
                <include>**/*</include> <!-- 包含所有文件 -->
            </includes>
            <excludes>
                <!-- 排除所有不需要过滤的二进制文件扩展名 -->