Maven - Spring Boot 项目打包本地 jar 的 3 种方法

Pre

Maven - Manual Maven JAR Installation：用 mvn install:install-file 安装本地 JAR 的实用指南

概述

在 Spring Boot 项目中，通常依赖包会从 Maven 中央仓库或私有仓库获取，并由 spring-boot-maven-plugin 自动打包进最终的可执行 fat jar（BOOT-INF/lib 目录）。
但在实际开发中，有时会遇到无法从公共或私有仓库获取的第三方 jar，例如厂商提供的 SDK、本地编译生成的工具包、未开源的内部依赖等。

如果直接使用 <scope>system</scope> 引入本地 jar，虽然能在编译时解析，但 Maven 默认不会将 system scope 依赖打入 Spring Boot 的 fat jar 中，导致部署后运行时找不到该类。

为了解决这一问题，需要在打包阶段显式将这些 jar 文件复制到 BOOT-INF/lib 目录，确保它们随 Spring Boot 应用一起分发与运行。

这个场景尤其适用于：

• 快速集成：临时引入无法上传至私服的第三方 jar。
• 离线部署：运行环境无法访问外部仓库。
• 封闭式交付：需要将全部依赖打包成一个独立可运行的 jar 文件。

方案思路

1. 编译期：使用 <scope>system</scope> 让本地 jar 参与编译。
2. 打包期：通过 maven-resources-plugin 在 process-resources 阶段将本地 jar 文件复制到 target/classes/BOOT-INF/lib，这样 spring-boot-maven-plugin 在 repackage 时会将其一并打入 fat jar。
3. 运行期：由于 jar 已进入 BOOT-INF/lib，Spring Boot 的类加载器会自动加载。

构建流程图

工作机制说明

1. 资源复制阶段
   maven-resources-plugin 在 process-resources 阶段，将 src/main/resources/lib 中的所有 jar 文件复制到 target/classes/BOOT-INF/lib。
2. 打包阶段
   spring-boot-maven-plugin 在 repackage 阶段会打包所有在 BOOT-INF/lib 的 jar 到最终可执行 jar 中。
3. 运行阶段
   Spring Boot 启动时会用自带的类加载器加载 BOOT-INF/lib 中的所有 jar，使它们在运行时可用。

目录结构示例

my-project/
├── src/
│   ├── main/
│   │   ├── java/...         # 源码
│   │   ├── resources/
│   │   │   ├── application.yml
│   │   │   └── lib/
│   │   │       └── your.jar  # 本地 jar
├── pom.xml

POM 配置模板

<dependency>
    <groupId>com.xxx</groupId>
    <artifactId>your-artifact</artifactId>
    <version>1.0.0</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/src/main/resources/lib/your.jar</systemPath>
</dependency>

<build>
    <plugins>
        <!-- 复制本地 jar 到 BOOT-INF/lib -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-resources-plugin</artifactId>
            <version>3.3.0</version>
            <executions>
                <execution>
                    <id>copy-system-jars</id>
                    <phase>process-resources</phase>
                    <goals>
                        <goal>copy-resources</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>${project.build.outputDirectory}/BOOT-INF/lib</outputDirectory>
                        <resources>
                            <resource>
                                <directory>${project.basedir}/src/main/resources/lib</directory>
                                <includes>
                                    <include>*.jar</include>
                                </includes>
                            </resource>
                        </resources>
                    </configuration>
                </execution>
            </executions>
        </plugin>

        <!-- Spring Boot 打包插件 -->
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <includeSystemScope>true</includeSystemScope>
            </configuration>
        </plugin>
    </plugins>
</build>

构建与验证

mvn clean package

验证 jar 是否被打入：

jar tf target/my-project-0.0.1-SNAPSHOT.jar | grep BOOT-INF/lib

应能看到 your.jar 记录。

注意事项

• system scope 在 Maven 官方中不推荐长期使用，不具备依赖冲突检测功能，适合临时方案。

• 如果 jar 需要长期维护，建议安装到本地仓库：

  mvn install:install-file \
    -Dfile=src/main/resources/lib/your.jar \
    -DgroupId=com.xxx \
    -DartifactId=your-artifact \
    -Dversion=1.0.0 \
    -Dpackaging=jar
  

• 团队协作建议使用私服（Nexus / Artifactory）管理。

方案优缺点