|
此版本仍在开发中，尚未视为稳定版。如需最新稳定版本，请使用 Spring Boot 4.0.4！ |
打包可执行归档文件
该插件可以创建可执行的归档文件（JAR 文件和 WAR 文件），其中包含应用程序的所有依赖项，然后可以通过 java -jar 命令运行。
打包可执行归档文件由 repackage 目标完成，如下例所示：
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>repackage 目标并非设计为在命令行上单独使用，因为它作用于由 jar 阶段生成的源 war（或 package）文件。
若要在命令行上使用此目标，必须包含 package 阶段：mvn package spring-boot:repackage。 |
如果你正在使用 spring-boot-starter-parent，则该执行已通过 repackage 执行 ID 预先配置好了，因此只需添加插件定义即可。 |
上面的示例会在 Maven 生命周期的 package 阶段重新打包生成的 jar 或 war 归档文件，包括项目中定义的所有 provided 依赖项。
如果需要排除其中某些依赖项，可以使用其中一个 exclude 选项；更多详细信息请参阅依赖排除。
原始（即非可执行）的构件默认会被重命名为 .original，但也可以通过使用自定义分类器来保留原始构件。
outputFileNameMapping 的 maven-war-plugin 功能目前不受支持。 |
spring-boot-devtools 和 spring-boot-docker-compose 模块默认会自动被排除（您可以使用 excludeDevtools 和 excludeDockerCompose 属性来控制此行为）。
为了使其与 war 打包方式兼容，必须将 spring-boot-devtools 和 spring-boot-docker-compose 依赖项设置为 optional，或指定 provided 作用域。
该插件会重写你的清单文件（manifest），特别是它会管理 Main-Class 和 Start-Class 条目。
如果默认配置不起作用，你必须在 Spring Boot 插件中配置这些值，而不是在 jar 插件中配置。
清单文件中的 Main-Class 由 Spring Boot 插件的 layout 属性控制，如下例所示：
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<mainClass>${start.class}</mainClass>
<layout>ZIP</layout>
</configuration>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>layout 属性的默认值由归档类型（jar 或 war）决定。以下是可用的布局：
-
JAR：标准的可执行 JAR 布局。 -
WAR：可执行 WAR 布局。provided依赖项会被放置在WEB-INF/lib-provided中，以避免在将war部署到 Servlet 容器时发生任何冲突。 -
ZIP（DIR的别名）：类似于使用JAR的PropertiesLauncher布局。 -
NONE：打包所有依赖项和项目资源。不包含引导加载器（bootstrap loader）。
分层 Jar 或 War
一个重新打包的 JAR 文件分别将应用程序的类和依赖项放在 BOOT-INF/classes 和 BOOT-INF/lib 目录中。
类似地，一个可执行的 WAR 文件将应用程序的类放在 WEB-INF/classes 中，依赖项则放在 WEB-INF/lib 和 WEB-INF/lib-provided 中。
在需要从 JAR 或 WAR 文件内容构建 Docker 镜像的情况下，能够进一步分离这些目录以便将它们写入不同的镜像层是非常有用的。
分层归档文件使用与常规重新打包的 JAR 或 WAR 相同的布局，但包含一个额外的元数据文件，用于描述每一层。
默认情况下，定义了以下层：
-
dependencies用于任何版本号中不包含SNAPSHOT的依赖项。 -
spring-boot-loader用于加载器类。 -
snapshot-dependencies用于任何版本号中包含SNAPSHOT的依赖项。 -
application用于本地模块依赖项、应用程序类和资源。
模块依赖项是通过检查当前构建中包含的所有模块来识别的。 如果某个模块依赖项仅因其已被安装到 Maven 的本地缓存中，而并非当前构建的一部分，则该依赖项将被识别为常规依赖项。
层的顺序非常重要，因为它决定了当应用程序的一部分发生变化时，先前的层有多大可能被缓存。
默认顺序为 dependencies、spring-boot-loader、snapshot-dependencies、application。
应首先添加最不可能发生变化的内容，然后依次添加更可能发生变更的层。
重新打包的归档文件默认包含 layers.idx 文件。
要禁用此功能，可以按以下方式操作：
<project>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<layers>
<enabled>false</enabled>
</layers>
</configuration>
</plugin>
</plugins>
</build>
</project>自定义层配置
根据您的应用程序需求，您可能希望调整图层的创建方式并添加新的图层。 这可以通过使用一个单独的配置文件来实现，该配置文件应按如下所示进行注册：
<project>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<layers>
<enabled>true</enabled>
<configuration>${project.basedir}/src/layers.xml</configuration>
</layers>
</configuration>
</plugin>
</plugins>
</build>
</project>配置文件描述了如何将一个归档文件划分为多个层，以及这些层的顺序。 以下示例展示了如何显式地定义上述默认的顺序：
<layers xmlns="http://www.springframework.org/schema/boot/layers"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/boot/layers
https://www.springframework.org/schema/boot/layers/layers-3.5.xsd">
<application>
<into layer="spring-boot-loader">
<include>org/springframework/boot/loader/**</include>
</into>
<into layer="application" />
</application>
<dependencies>
<into layer="application">
<includeModuleDependencies />
</into>
<into layer="snapshot-dependencies">
<include>*:*:*SNAPSHOT</include>
</into>
<into layer="dependencies" />
</dependencies>
<layerOrder>
<layer>dependencies</layer>
<layer>spring-boot-loader</layer>
<layer>snapshot-dependencies</layer>
<layer>application</layer>
</layerOrder>
</layers>layers XML 格式分为三个部分：
-
<application>块定义了应用程序类和资源应如何分层。 -
<dependencies>块定义了依赖项应如何分层。 -
<layerOrder>块定义了图层应被写入的顺序。
嵌套的 <into> 块用于 <application> 和 <dependencies> 部分中，以声明某一层的内容。
这些块按照其定义的顺序从上到下依次进行评估。
任何未被前面块声明的内容将保持可用，供后续块进行处理。
<into> 块通过嵌套的 <include> 和 <exclude> 元素来声明内容。
<application> 部分在 include/exclude 表达式中使用 Ant 风格的路径匹配。
<dependencies> 部分使用 group:artifact[:version] 模式。
它还提供了 <includeModuleDependencies /> 和 <excludeModuleDependencies /> 元素，可用于包含或排除本地模块依赖项。
如果没有定义 <include>，则所有内容（未被前面的块声明的部分）都会被考虑。
如果没有定义 <exclude>，则不会应用任何排除规则。
查看上面的 <dependencies> 示例，我们可以看到第一个 <into> 会将所有模块依赖分配给 application.layer 层。
下一个 <into> 会将所有 SNAPSHOT 依赖分配给 snapshot-dependencies 层。
最后一个 <into> 会将剩余的所有内容（在本例中，即所有非 SNAPSHOT 的依赖）分配给 dependencies 层。
<application> 块具有类似的规则。
首先将 org/springframework/boot/loader/** 内容分配给 spring-boot-loader 层。
然后将所有剩余的类和资源分配给 application 层。
<into> 块的定义顺序通常与层的书写顺序不同。
因此，必须始终包含 <layerOrder> 元素，并且该元素必须涵盖所有被 <into> 块引用的层。 |
spring-boot:repackage
org.springframework.boot:spring-boot-maven-plugin:3.5.13-SNAPSHOT
重新打包现有的 JAR 和 WAR 归档文件，使其可以通过命令行使用 java -jar 直接执行。当设置 layout=NONE 时，也可仅用于将嵌套的依赖项打包到一个 JAR 文件中（不包含主类，因此不可执行）。
可选参数
| 姓名 | 类型 | 默认 |
|---|---|---|
|
|
|
|
||
|
||
|
||
|
|
|
|
|
|
|
||
|
||
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
||
|
|
|
|
||
|
|
参数详情
attach
将重新打包的归档文件附加到本地 Maven 仓库以进行安装，或部署到远程仓库。如果未配置分类器（classifier），它将替换普通的 JAR 文件。如果已配置了 classifier，使得普通 JAR 文件与重新打包的 JAR 文件不同，则它将与普通 JAR 文件一同被附加。当该属性设置为 false 时，重新打包的归档文件将不会被安装或部署。
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
classifier
要添加到重新打包的归档文件中的分类器（classifier）。如果未指定，则主构件（main artifact）将被重新打包后的归档文件替换。如果指定了分类器，该分类器还将用于确定要重新打包的源归档文件：如果已存在具有该分类器的构件，则将其用作源文件并进行替换；如果不存在这样的构件，则使用主构件作为源文件，并将重新打包后的归档文件作为带有该分类器的附加构件（supplemental artifact）进行附加。附加构件可使其与原始构件一同部署，更多详情请参阅Maven 官方文档。
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
embeddedLaunchScript
如果 JAR 文件是完全可执行的，则要添加到 JAR 文件开头的内嵌启动脚本。如果未指定，将使用“Spring Boot”默认脚本。
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
embeddedLaunchScriptProperties
应在嵌入式启动脚本中展开的属性。
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
excludeDevtools
从重新打包的归档文件中排除 Spring Boot devtools。
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
excludeDockerCompose
从重新打包的归档文件中排除 Spring Boot 开发服务。
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
excludeGroupIds
要排除的 groupId 名称的逗号分隔列表（精确匹配）。
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
excludes
要排除的构件定义集合。Exclude 元素定义了必需的 groupId 和 artifactId 组件，以及一个可选的 classifier 组件。当将其配置为属性时，值应以逗号分隔，各组件之间用冒号分隔：
groupId:artifactId,groupId:artifactId:classifier
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
executable
通过在 JAR 文件前添加一个启动脚本，使其成为可在 *nix 系统上直接执行的完整可执行 JAR。目前，某些工具尚不支持此格式，因此你可能无法始终使用该技术。例如，jar -xf 在解压已设置为完全可执行的 JAR 或 WAR 文件时可能会静默失败。建议仅在你打算直接执行该文件（而非使用 java -jar 运行或将其部署到 Servlet 容器）时才启用此选项。
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
includes
要包含的构件定义集合。Include 元素定义了必需的 groupId 和 artifactId 组件，以及一个可选的 classifier 组件。当配置为属性时，值应以逗号分隔，各组件之间用冒号分隔：
groupId:artifactId,groupId:artifactId:classifier
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
layout
归档文件的类型（对应于其中依赖项的布局方式）。可能的取值有 JAR、WAR、ZIP、DIR、NONE。默认值根据归档文件的类型自动推断。
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
mainClass
主类的名称。如果未指定，则将使用找到的第一个包含 main 方法的已编译类。
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
outputDirectory
包含生成的归档文件的目录。
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
outputTimestamp
用于生成可重现输出归档条目的时间戳，可以采用 ISO 8601 格式（yyyy-MM-dd’T’HH:mm:ssXXX）或一个表示自 Unix 纪元以来秒数的 int 值。
姓名 |
|
|---|---|
类型 |
|
默认值 |
|
用户属性 |
|
Since |
|
<h1>示例</h1>
自定义分类器
默认情况下，repackage 目标会用重新打包后的构件替换原始构件。
对于代表应用程序的模块来说，这是一种合理的行为；但如果你的模块被用作另一个模块的依赖项，则需要为重新打包后的构件提供一个分类器（classifier）。
原因在于，应用程序类被打包在 BOOT-INF/classes 目录下，导致依赖该模块的其他模块无法加载重新打包后的 JAR 文件中的类。
如果情况确实如此，或者您更倾向于保留原始构件，并将重新打包的构件以不同的分类器（classifier）附加，请按以下示例所示配置该插件：
<project>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<id>repackage</id>
<goals>
<goal>repackage</goal>
</goals>
<configuration>
<classifier>exec</classifier>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>如果你使用的是 spring-boot-starter-parent，那么 repackage 目标会在 ID 为 repackage 的执行中自动运行。
在这种配置下，只需指定相关配置即可，如下例所示：
<project>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<id>repackage</id>
<configuration>
<classifier>exec</classifier>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>此配置将生成两个构件：原始构件以及由 repackage 目标生成的重新打包后的对应构件。 两者都将被透明地安装/部署。
如果你希望以与主构件相同的方式重新打包一个次要构件，也可以使用相同的配置。
以下配置会安装/部署一个带有 task 分类器的构件，其中包含重新打包后的应用程序：
<project>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>jar</goal>
</goals>
<phase>package</phase>
<configuration>
<classifier>task</classifier>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<id>repackage</id>
<goals>
<goal>repackage</goal>
</goals>
<configuration>
<classifier>task</classifier>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>由于 maven-jar-plugin 和 spring-boot-maven-plugin 在同一阶段执行，因此必须先定义 jar 插件（以确保它在 repackage 目标之前运行）。
同样，如果您使用的是 spring-boot-starter-parent，则可以简化如下：
<project>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<executions>
<execution>
<id>default-jar</id>
<configuration>
<classifier>task</classifier>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<id>repackage</id>
<configuration>
<classifier>task</classifier>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>自定义名称
如果你需要重新打包的 JAR 文件具有与项目 artifactId 属性所定义的名称不同的本地名称，请使用标准的 finalName，如下例所示：
<project>
<build>
<finalName>my-app</finalName>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<id>repackage</id>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>此配置将在 target/my-app.jar 中生成重新打包的构件。
本地重新打包的构件
默认情况下，repackage 目标会用可执行的构件替换原始构件。
如果你只需要部署原始的 jar 文件，同时又希望使用常规文件名来运行你的应用程序，请按如下方式配置该插件：
<project>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<id>repackage</id>
<goals>
<goal>repackage</goal>
</goals>
<configuration>
<attach>false</attach>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>此配置会生成两个构件：原始构件和由 repackage 目标生成的可执行构件。
只有原始构件会被安装/部署。
自定义布局
Spring Boot 使用在附加的 jar 文件中定义的自定义布局工厂（该 jar 文件作为构建插件的依赖项提供）来重新打包此项目的 jar 文件：
<project>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<executions>
<execution>
<id>repackage</id>
<goals>
<goal>repackage</goal>
</goals>
<configuration>
<layoutFactory implementation="com.example.CustomLayoutFactory">
<customProperty>value</customProperty>
</layoutFactory>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.example</groupId>
<artifactId>custom-layout</artifactId>
<version>0.0.1.BUILD-SNAPSHOT</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project>布局工厂（layout factory）是通过在 pom 文件中显式指定的 LayoutFactory（来自 spring-boot-loader-tools）实现提供的。
如果插件类路径上仅存在一个自定义的 LayoutFactory，并且它已在 META-INF/spring.factories 中列出，则无需在插件配置中显式设置它。
如果显式设置了 布局（layout），则布局工厂（layout factories）将始终被忽略。
依赖排除
默认情况下，repackage 和 run 目标都会包含项目中定义的所有 provided 依赖项。
Spring Boot 项目应将 provided 依赖项视为运行应用程序所需的“容器”依赖项。
一般来说，Spring Boot 项目不会被用作其他项目的依赖项，因此通常不太可能包含任何 optional 依赖项。
当项目确实包含可选依赖项时，这些依赖项也会被 repackage 和 run 目标一并包含。
其中一些依赖项可能完全不需要，应从可执行 JAR 文件中排除。 为了保持一致性，在运行应用程序时也不应包含这些依赖项。
有两种方式可以将某个依赖项排除在运行时的打包/使用之外：
-
排除一个由
groupId和artifactId标识的特定构件，如有需要，可选择性地指定classifier。 -
排除属于指定
groupId的任何构件。
以下示例排除了 com.example:module1，且仅排除该构件：
<project>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<excludes>
<exclude>
<groupId>com.example</groupId>
<artifactId>module1</artifactId>
</exclude>
</excludes>
</configuration>
</plugin>
</plugins>
</build>
</project>此示例排除了属于 com.example 组的所有构件：
<project>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<excludeGroupIds>com.example</excludeGroupIds>
</configuration>
</plugin>
</plugins>
</build>
</project>JAR 工具
创建分层的 JAR 或 WAR 文件时，spring-boot-jarmode-tools JAR 将作为依赖项添加到您的归档文件中。
当该 JAR 位于类路径上时，您可以以一种特殊模式启动应用程序，该模式允许引导代码运行与您的应用程序完全不同的内容，例如用于提取各层的工具。
如果您希望排除此依赖项，可以按以下方式操作：
<project>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<includeTools>false</includeTools>
</configuration>
</plugin>
</plugins>
</build>
</project>自定义层配置
默认配置会将依赖项划分为快照（snapshot）和非快照（non-snapshot）两类，但你可能需要更复杂的规则。
例如，你可能希望将项目中公司特定的依赖项隔离到一个专用层中。
以下 layers.xml 配置展示了一种此类设置：
<layers xmlns="http://www.springframework.org/schema/boot/layers"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/boot/layers
https://www.springframework.org/schema/boot/layers/layers-3.5.xsd">
<application>
<into layer="spring-boot-loader">
<include>org/springframework/boot/loader/**</include>
</into>
<into layer="application" />
</application>
<dependencies>
<into layer="snapshot-dependencies">
<include>*:*:*SNAPSHOT</include>
</into>
<into layer="company-dependencies">
<include>com.acme:*</include>
</into>
<into layer="dependencies"/>
</dependencies>
<layerOrder>
<layer>dependencies</layer>
<layer>spring-boot-loader</layer>
<layer>snapshot-dependencies</layer>
<layer>company-dependencies</layer>
<layer>application</layer>
</layerOrder>
</layers>上述配置创建了一个额外的 company-dependencies 层，其中包含所有 groupId 为 com.acme 的库。