**Unable to open nested entry 'BOOT-INF/lib/city_pass_test-1.0.jar'. It has be** **问题：嵌套JAR无法打开，如何修复Spring Boot打包中的非法字符或损坏引用？**

Question

在Spring Boot项目构建过程中，有时会出现“Unable to open nested entry 'BOOT-INF/lib/city_pass_test-1.0.jar'. It has be”这类错误。该问题通常由JAR包路径中的非法字符、文件损坏或打包方式不当引起。Spring Boot默认使用嵌套JAR结构，若依赖JAR文件名存在特殊字符或损坏引用，会导致解压或运行失败。解决方法包括：检查依赖构建过程，确保JAR文件完整性；使用`spring-boot-maven-plugin`时配置``排除问题依赖；或改用`war`打包方式避免嵌套JAR问题。此外，升级Spring Boot版本也有助于修复此类兼容性缺陷。

Answer 1

一、问题概述

在Spring Boot项目的构建和运行过程中，开发者可能会遇到如下错误：

Unable to open nested entry 'BOOT-INF/lib/city_pass_test-1.0.jar'. It has be

该错误提示表明Spring Boot在尝试读取嵌套JAR中的某个依赖包时失败。这类问题通常由以下几种原因引起：

• JAR文件名中包含非法字符（如空格、特殊符号等）
• 依赖JAR文件损坏或构建过程中出错
• Maven依赖打包方式不兼容Spring Boot默认的嵌套JAR机制

由于Spring Boot默认采用嵌套JAR结构（即一个JAR中包含多个内嵌JAR），若其中某个依赖存在问题，整个应用将无法正常启动。

二、深入分析：Spring Boot嵌套JAR机制

Spring Boot使用“嵌套JAR”技术来打包项目及其依赖，使得应用可以作为一个独立的可执行JAR运行。其结构如下：

myapp.jar
├── BOOT-INF/
│   ├── classes/         # 项目编译后的类文件
│   └── lib/             # 所有依赖JAR包
├── META-INF/
└── org.springframework.boot.loader.JarLauncher

这种结构依赖于Spring Boot的自定义类加载机制，若其中某个依赖JAR文件名存在非法字符、路径过长或文件本身损坏，会导致类加载器在尝试访问该文件时抛出异常。

此外，部分依赖包在运行时需要被解压才能访问其内容（如本地库文件），这些依赖若未被正确配置，也会导致嵌套JAR机制失效。

三、常见原因与排查流程

原因类型	描述	排查方式
非法字符	JAR文件名中包含空格、特殊符号或中文字符	检查BOOT-INF/lib/目录下的文件名
文件损坏	依赖JAR文件在构建过程中损坏或未正确生成	重新下载依赖，使用mvn dependency:purge-local-repository清理本地仓库
打包方式不当	依赖未按标准Maven方式构建，或包含非标准结构	检查依赖项目的pom.xml配置
需要解压运行	某些依赖必须在运行时解压后才能使用（如JNI库）	配置<requiresUnpack>排除该依赖

四、解决方案详解

1. 检查依赖完整性

确保所有依赖JAR文件完整且无损坏。可以通过以下方式验证：

• 删除本地Maven仓库缓存：rm -rf ~/.m2/repository/
• 重新执行构建：mvn clean install

2. 使用<requiresUnpack>配置

若某个依赖在运行时必须被解压，可在pom.xml中配置spring-boot-maven-plugin插件：

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <requiresUnpack>
            <dependency>
                <groupId>com.example</groupId>
                <artifactId>city_pass_test</artifactId>
            </dependency>
        </requiresUnpack>
    </configuration>
</plugin>

此配置会将指定依赖从嵌套JAR中提取出来，避免加载失败。

3. 改用WAR打包方式

若希望完全避免嵌套JAR的问题，可将项目打包方式改为WAR：

<packaging>war</packaging>

并确保主类继承SpringBootServletInitializer：

public class Application extends SpringBootServletInitializer {
    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
        return builder.sources(Application.class);
    }
}

4. 升级Spring Boot版本

某些Spring Boot版本存在已知的嵌套JAR处理缺陷，升级到最新稳定版可有效修复兼容性问题。例如：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.12</version>
    <relativePath/>
</parent>

五、流程图：错误排查与解决流程

graph TD
A[启动Spring Boot应用] --> B{是否出现嵌套JAR错误?}
B -- 是 --> C[检查BOOT-INF/lib目录]
C --> D{是否存在非法字符或损坏文件?}
D -- 是 --> E[重命名依赖或重新构建]
D -- 否 --> F[配置requiresUnpack排除依赖]
B -- 否 --> G[应用正常运行]
F --> H[或改用WAR打包方式]
H --> I[或升级Spring Boot版本]
I --> J[重新构建并验证]

六、扩展建议与最佳实践

• 定期清理Maven本地仓库，避免因缓存导致的依赖问题
• 避免使用中文或空格命名依赖JAR文件
• 对于包含原生库（native库）的依赖，务必使用<requiresUnpack>配置
• 使用CI/CD工具自动验证构建结果，防止构建失败被忽略
• 启用Spring Boot的debug日志输出，便于快速定位问题根源