Spring Boot Maven 插件如何构建可执行 JAR 的核心配置

前言

在 Java 生态中，Spring Boot 以其“约定优于配置”的理念和开箱即用的特性，成为现代应用开发的首选框架。而 spring-boot-maven-plugin 作为 Spring Boot 的核心插件，承担着将应用打包为可执行 JAR/WAR 的关键角色。

一、插件的核心功能与目标

1.1 插件的定位

spring-boot-maven-plugin 是 Spring Boot 提供的 Maven 插件，其核心目标是：

• 可执行包生成：将应用及其依赖打包为独立的 JAR/WAR 文件，支持通过 java -jar 直接运行。
• 生命周期管理：在集成测试阶段启动/停止应用，支持自动化测试。
• 构建信息管理：生成 build-info.properties 文件，供 Actuator 等组件使用。
• 热部署支持：与 Spring Boot DevTools 集成，实现代码修改后的自动重启。

1.2 插件的 Goals（目标）

该插件定义了 5 个核心目标（Goal），分别对应不同的构建阶段：

1.3 插件定位

spring-boot-maven-plugin 是 Spring Boot 提供的官方 Maven 插件，其核心目标是将 Spring Boot 应用程序打包为可独立运行的 JAR 或 WAR 文件。与传统 Maven 打包方式不同，该插件生成的可执行文件内置了嵌入式服务器（如 Tomcat、Jetty），无需依赖外部容器即可运行，极大简化了部署流程。

1.4 核心功能

• 可执行文件打包：将应用及其所有依赖打包为单一 JAR/WAR，支持 java -jar 直接运行。
• 生命周期管理：支持集成测试阶段的应用启动与停止。
• 开php发者工具集成：结合 Spring Boot DevTools 实现热部署。
• 构建信息生成：生成 build-info.properties 文件，记录项目元数据。

二、核心配置详解

2.1 <mainClass>：指定入口类

<configuration>
    <mainClass>com.example.Application</mainClass>
</configuration>

• 作用：定义应用的主类（包含 @SpringBootApplication 注解的类）。
• 原理：插件会在生成的 JAR 包的 MANIFEST.MF 中写入以下内容：

  Main-Class: org.springframework.boot.loader.JarLauncher
  Start-Class: com.example.Application

• 注意事项：
  • 若未显式配置，插件会自动扫描项目中带有 @SpringBootApplication 的类。
  • 对于多模块项目，需确保主类路径正确，避免冲突。

2.2 <skip>：跳过插件执行

<configuration>
    <skip>true</skip>
</configuration>

• 作用：控制是否跳过 repackage 等操作。
• 适用场景：
  • 快速构建时仅生成普通 JAR（如 mvn package 后直接部署）。
  • 调试阶段避免重复打包。
• 默认值：false。

2.3 <includeSystemScope>：包含系统依赖

<configuration>
    <includeSystemScope>true</includeSystemScope>
</configuration>

• 作用：是否将 system 作用域的依赖（通过 <systemPath> 引入的本地 JAR）包含到最终包中。
• 风险提示：
  • 系统依赖依赖于本地路径，可能导致构建不可移植。
  • 建议：优先使用 file 或 maven 仓库管理依赖。

2.4 <layout>：定义打包格式

<configuration>
    <layout>JAR</layout>
</configuration>

• 支持的值：

  值	描述
  JAR	可执行 JAR，使用 JarLauncher 启动（默认值）。
  WAR	可执行 WAR，使用 WarLauncher 启动，需配置 servlet 容器。
  ZIP	类似 JAR 的 ZIP 包，使用 PropertiesLauncChina编程her 启动。
  NONE	仅打包依赖，不包含 Spring Boot 启动器（不可执行）。
  MODULE	打包依赖库（排除 provided 作用域），不包含启动器。

• 选择策略：

  • Web 应用优先使用 WAR。
  • 微服务或独立应用使用 JAR。
  • 高度定制化场景选择 NONE 或 MODULE。

2.5 <executions>：绑定构建生命周期

(1) repackage 目标

<executions>
    <execution>
        <id>repackage</id>
        <goals>
            <goal>repackage</goal>
        </goals>
    </execution>
</executions>

• 作用：将 repackage 目标绑定到 package 阶段。
• 结果：执行 mvn package 后，插件会自动生成可执行包，并覆盖原始包（保留为 .origin 文件）。
• 生成结构：

  your-app.jar
  ├── META-INF/
  │   └── MANIFEST.MF
  ├── org/springframework/boot/loader/  # 启动类
  └── BOOT-INF/
      ├── classes/  # 项目编译后的类文件
      └── lib/      # 所有依赖的 .jar 文件

• 执行命令：

  mvn clean package
  java -jar target/your-app.jar

(2) run 目标

mvn spring-boot:run

• 作用：直接运行 Spring Boot 应用，无需打包。
• 适用场景：快速调试或开发阶段。

(3) start 与 stop 目标

<execution>
    <id>start</id>
    <goals>
        <goal>start</goal>
    </goals>
</execution>
<execution>
    <id>stop</id>
    <goals>
        <goal>stop</goal>
    </goals>
</execution>

• 作用：在集成测试阶段启动/停止应用。
• 典型流程：

  mvn integration-test  # 启动应用
  mvn verify            # 停止应用

(4) build-info 目标

<execution>
    <goals>
        <goal>build-info</goal>
    </goals>
</execution>

• 作用：生成 build-info.properties 文件，记录项目版本、构建时间等元数据。
• 文件内容示例：

  build.artifact=your-app
  build.name=your-app
  build.version=1.0.0
  build.time=2025-07-13T18:14:03Z

三、高级配置与最佳实践

3.1 多环境配置

通过 php<profiles> 动态切换配置文件：

<profiles>
    <profile>
        <id>dev</id>
        <properties>
            <env>dev</env>
        </properties>
    </profile>
    <profile>
        <id>prod</id>
        <properties>
            <env>prod</env>
        </properties>
    </profile>
</profiles>

结合资源过滤（resources 配置）实现不同环境的配置分离。

3.2 与 Spring Boot DevTools 集成

启用热部署（HotSwap）：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

• 效果：代码修改后，应用会自动重启（无需手动执行 mvn package）。

3.3 自定义构建信息

通过 build-info 目标生成元数据：

<execution>
    <id>generate-build-info</id>
    <goals>
        <goal>build-info</goal>
    </goals>
    <phase>process-resources</phase>
</execution>

生成的 build-info.properties 示例：

build.artifact=example-app
build.name=example-app
build.version=1.0.0
build.time=2025-07-13T22:00:09Z

四、典型配置示例

4.1 基础配置

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <version>${spring-boot.version}</version>
    <configuration>
        <mainClass>com.example.Application</mainClass>
        <skip>false</skip>
        <includeSystemScope>false</includeSystemScope>
        <layout>JAR</layout>
    </configuration>
    <executions>
        <execution>
            <id>repackage</id>
            <goals>
                <goal>repackage</goal>
            </goals>
        </execution>
    </executions>
</plugin>

4.2 高级配置（集成 DevTools 与多环境）

<profChina编程iles>
    <profile>
        <id>dev</id>
        <properties>
            <env>dev</env>
        </properties>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                    <configuration>
                        <mainClass>com.example.Application</mainClphpass>
                        <layout>JAR</layout>
                    </configuration>
                    <executions>
                        <execution>
                            <id>repackage</id>
                            <goals>
                                <goal>repackage</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

五、常见问题与解决方案

5.1 启动类未正确识别

• 现象：运行 java -jar app.jar 报错 No main manifest attribute。
• 原因：未正确配置 <mainClass> 或自动扫描失败。
• 解决方案：
  1. 显式配置 <mainClass>。
  2. 确保主类路径正确（src/main/java/com/example/Application.java）。
  3. 检查 @SpringBootApplication 注解是否缺失。

5.2 依赖冲突

• 现象：运行时报错 java.lang.NoSuchMethodError。
• 原因：依赖版本不一致或存在多个同名 JAR。
• 解决方案：
  • 使用 mvn dependency:tree 分析依赖树。
  • 通过 <exclusions> 排除冲突依赖。
  • 升级 Spring Boot 版本以获取最新依赖管理。

5.3 打包后体积过大

• 现象：生成的 JAR 文件体积异常庞大。
• 原因：包含大量未使用的依赖或重复资源。
• 解决方案：
  • 使用 spring-boot-maven-plugin 的 exclude 配置过滤无用依赖。
  • 启用 spring-boot:repackage 的 skip 模式，仅打包必要依赖。

六、总结

spring-boot-maven-plugin 是 Spring Boot 项目构建的基石，其配置直接影响应用的打包效率、运行性能及维护成本。通过合理配置 <mainClass>、<layout>、<executions> 等参数，开发者可以灵活控制构建流程，适配不同场景需求。同时，结合 DevTools、多环境配置等高级特性，能够显著提升开发效率与部署灵活性。

到此这篇关于Spring Boot Maven 插件如何构建可执行 JAR 的核心配置的文章就介绍到这了,更多相关Spring Boot Maven可执行jar内容请搜索China编程(www.chinasem.cn)以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程China编程(www.chinasem.cn)！