Packaging Executable Archives (Packaging Executable Archives) _ Spring Boot3.4.0-SNAPSHOT中文文档(官方文档中文翻译)|Spring 教程 —

This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Boot 3.3.4!spring-doc.cn

The plugin can create executable archives (jar files and war files) that contain all of an application’s dependencies and can then be run with java -jar.spring-doc.cn

Packaging an executable archive is performed by the repackage goal, as shown in the following example:spring-doc.cn

<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>

The repackage goal is not meant to be used alone on the command-line as it operates on the source jar (or war) produced by the package phase. To use this goal on the command-line, you must include the package phase: mvn package spring-boot:repackage.

If you are using spring-boot-starter-parent, such execution is already pre-configured with a repackage execution ID so that only the plugin definition should be added.

The example above repackages a jar or war archive that is built during the package phase of the Maven lifecycle, including any provided dependencies that are defined in the project. If some of these dependencies need to be excluded, you can use one of the exclude options; see the dependency exclusion for more details.spring-doc.cn

The original (that is non-executable) artifact is renamed to .original by default but it is also possible to keep the original artifact using a custom classifier.spring-doc.cn

The outputFileNameMapping feature of the maven-war-plugin is currently not supported.

The spring-boot-devtools and spring-boot-docker-compose modules are automatically excluded by default (you can control this using the excludeDevtools and excludeDockerCompose properties). In order to make that work with war packaging, the spring-boot-devtools and spring-boot-docker-compose dependencies must be set as optional or with the provided scope.spring-doc.cn

The plugin rewrites your manifest, and in particular it manages the Main-Class and Start-Class entries. If the defaults don’t work you have to configure the values in the Spring Boot plugin, not in the jar plugin. The Main-Class in the manifest is controlled by the layout property of the Spring Boot plugin, as shown in the following example:spring-doc.cn

<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>

The layout property defaults to a value determined by the archive type (jar or war). The following layouts are available:spring-doc.cn

JAR: regular executable JAR layout.spring-doc.cn
WAR: executable WAR layout. provided dependencies are placed in WEB-INF/lib-provided to avoid any clash when the war is deployed in a servlet container.spring-doc.cn
ZIP (alias to DIR): similar to the JAR layout using PropertiesLauncher.spring-doc.cn
NONE: Bundle all dependencies and project resources. Does not bundle a bootstrap loader.spring-doc.cn

If you are using spring-boot-starter-parent, such execution is already pre-configured with a repackage execution ID so that only the plugin definition should be added.

The outputFileNameMapping feature of the maven-war-plugin is currently not supported.

Layered Jar or War

A repackaged jar contains the application’s classes and dependencies in BOOT-INF/classes and BOOT-INF/lib respectively. Similarly, an executable war contains the application’s classes in WEB-INF/classes and dependencies in WEB-INF/lib and WEB-INF/lib-provided. For cases where a docker image needs to be built from the contents of a jar or war, it’s useful to be able to separate these directories further so that they can be written into distinct layers.spring-doc.cn

Layered archives use the same layout as a regular repackaged jar or war, but include an additional meta-data file that describes each layer.spring-doc.cn

By default, the following layers are defined:spring-doc.cn

dependencies for any dependency whose version does not contain SNAPSHOT.spring-doc.cn
spring-boot-loader for the loader classes.spring-doc.cn
snapshot-dependencies for any dependency whose version contains SNAPSHOT.spring-doc.cn
application for local module dependencies, application classes, and resources.spring-doc.cn

Module dependencies are identified by looking at all of the modules that are part of the current build. If a module dependency can only be resolved because it has been installed into Maven’s local cache and it is not part of the current build, it will be identified as regular dependency.spring-doc.cn

The layers order is important as it determines how likely previous layers can be cached when part of the application changes. The default order is dependencies, spring-boot-loader, snapshot-dependencies, application. Content that is least likely to change should be added first, followed by layers that are more likely to change.spring-doc.cn

The repackaged archive includes the layers.idx file by default. To disable this feature, you can do so in the following manner:spring-doc.cn

<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>

Custom Layers Configuration

Depending on your application, you may want to tune how layers are created and add new ones. This can be done using a separate configuration file that should be registered as shown below:spring-doc.cn

<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>

The configuration file describes how an archive can be separated into layers, and the order of those layers. The following example shows how the default ordering described above can be defined explicitly:spring-doc.cn

<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
	                      layers-xsd: https://www.springframework.org/schema/boot/layers/layers-3.4.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>

The layers XML format is defined in three sections:spring-doc.cn

The <application> block defines how the application classes and resources should be layered.spring-doc.cn
The <dependencies> block defines how dependencies should be layered.spring-doc.cn
The <layerOrder> block defines the order that the layers should be written.spring-doc.cn

Nested <into> blocks are used within <application> and <dependencies> sections to claim content for a layer. The blocks are evaluated in the order that they are defined, from top to bottom. Any content not claimed by an earlier block remains available for subsequent blocks to consider.spring-doc.cn

The <into> block claims content using nested <include> and <exclude> elements. The <application> section uses Ant-style path matching for include/exclude expressions. The <dependencies> section uses group:artifact[:version] patterns. It also provides <includeModuleDependencies /> and <excludeModuleDependencies /> elements that can be used to include or exclude local module dependencies.spring-doc.cn

If no <include> is defined, then all content (not claimed by an earlier block) is considered.spring-doc.cn

If no <exclude> is defined, then no exclusions are applied.spring-doc.cn

Looking at the <dependencies> example above, we can see that the first <into> will claim all module dependencies for the application.layer. The next <into> will claim all SNAPSHOT dependencies for the snapshot-dependencies layer. The final <into> will claim anything left (in this case, any dependency that is not a SNAPSHOT) for the dependencies layer.spring-doc.cn

The <application> block has similar rules. First claiming org/springframework/boot/loader/** content for the spring-boot-loader layer. Then claiming any remaining classes and resources for the application layer.spring-doc.cn

The order that <into> blocks are defined is often different from the order that the layers are written. For this reason the <layerOrder> element must always be included and must cover all layers referenced by the <into> blocks.

`spring-boot:repackage`

org.springframework.boot:spring-boot-maven-plugin:3.4.0-SNAPSHOTspring-doc.cn

Repackage existing JAR and WAR archives so that they can be executed from the command line using java -jar. With layout=NONE can also be used simply to package a JAR with nested dependencies (and no main class, so not executable).spring-doc.cn

Required parameters

Name Type Default

Name	Type	Default
outputDirectory spring-doc.cn	`File`spring-doc.cn	`${project.build.directory}`spring-doc.cn

outputDirectory spring-doc.cn

Filespring-doc.cn

${project.build.directory}spring-doc.cn

Optional parameters

Name Type Default

Name	Type	Default
attach spring-doc.cn	`boolean`spring-doc.cn	`true`spring-doc.cn
classifier spring-doc.cn	`String`spring-doc.cn
embeddedLaunchScript spring-doc.cn	`File`spring-doc.cn
embeddedLaunchScriptProperties spring-doc.cn	`Properties`spring-doc.cn
excludeDevtools spring-doc.cn	`boolean`spring-doc.cn	`true`spring-doc.cn
excludeDockerCompose spring-doc.cn	`boolean`spring-doc.cn	`true`spring-doc.cn
excludeGroupIds spring-doc.cn	`String`spring-doc.cn
excludes spring-doc.cn	`List`spring-doc.cn
executable spring-doc.cn	`boolean`spring-doc.cn	`false`spring-doc.cn
includeSystemScope spring-doc.cn	`boolean`spring-doc.cn	`false`spring-doc.cn
includeTools spring-doc.cn	`boolean`spring-doc.cn	`true`spring-doc.cn
includes spring-doc.cn	`List`spring-doc.cn
layers spring-doc.cn	`Layers`spring-doc.cn
layout spring-doc.cn	`LayoutType`spring-doc.cn
layoutFactory spring-doc.cn	`LayoutFactory`spring-doc.cn
loaderImplementation spring-doc.cn	`LoaderImplementation`spring-doc.cn
mainClass spring-doc.cn	`String`spring-doc.cn
outputTimestamp spring-doc.cn	`String`spring-doc.cn	`${project.build.outputTimestamp}`spring-doc.cn
requiresUnpack spring-doc.cn	`List`spring-doc.cn
skip spring-doc.cn	`boolean`spring-doc.cn	`false`spring-doc.cn

attach spring-doc.cn

booleanspring-doc.cn

truespring-doc.cn

classifier spring-doc.cn

Stringspring-doc.cn

embeddedLaunchScript spring-doc.cn

Filespring-doc.cn

embeddedLaunchScriptProperties spring-doc.cn

Propertiesspring-doc.cn

excludeDevtools spring-doc.cn

booleanspring-doc.cn

truespring-doc.cn

excludeDockerCompose spring-doc.cn

booleanspring-doc.cn

truespring-doc.cn

excludeGroupIds spring-doc.cn

Stringspring-doc.cn

excludes spring-doc.cn

Listspring-doc.cn

executable spring-doc.cn

booleanspring-doc.cn

falsespring-doc.cn

includeSystemScope spring-doc.cn

booleanspring-doc.cn

falsespring-doc.cn

includeTools spring-doc.cn

booleanspring-doc.cn

truespring-doc.cn

includes spring-doc.cn

Listspring-doc.cn

layers spring-doc.cn

Layersspring-doc.cn

layout spring-doc.cn

LayoutTypespring-doc.cn

layoutFactory spring-doc.cn

LayoutFactoryspring-doc.cn

loaderImplementation spring-doc.cn

LoaderImplementationspring-doc.cn

mainClass spring-doc.cn

Stringspring-doc.cn

outputTimestamp spring-doc.cn

Stringspring-doc.cn

${project.build.outputTimestamp}spring-doc.cn

requiresUnpack spring-doc.cn

Listspring-doc.cn

skip spring-doc.cn

booleanspring-doc.cn

falsespring-doc.cn

Parameter details

`attach`

Attach the repackaged archive to be installed into your local Maven repository or deployed to a remote repository. If no classifier has been configured, it will replace the normal jar. If a classifier has been configured such that the normal jar and the repackaged jar are different, it will be attached alongside the normal jar. When the property is set to false, the repackaged archive will not be installed or deployed.spring-doc.cn

Namespring-doc.cn	`attach`spring-doc.cn
Typespring-doc.cn	`boolean`spring-doc.cn
Default valuespring-doc.cn	`true`spring-doc.cn
User propertyspring-doc.cn
Sincespring-doc.cn	`1.4.0`spring-doc.cn

Layered Jar or War

Custom Layers Configuration

spring-boot:repackage

Required parameters

Optional parameters

Parameter details

attach

classifier

embeddedLaunchScript

embeddedLaunchScriptProperties

excludeDevtools

excludeDockerCompose

excludeGroupIds

excludes

executable

includeSystemScope

includeTools

includes

layers

layout

layoutFactory

loaderImplementation

mainClass

outputDirectory

outputTimestamp

requiresUnpack

skip

Examples

Custom Classifier

Custom Name

Local Repackaged Artifact

Custom Layout

Dependency Exclusion

JAR Tools

Custom Layers Configuration

`spring-boot:repackage`

`attach`

`classifier`

`embeddedLaunchScript`

`embeddedLaunchScriptProperties`

`excludeDevtools`

`excludeDockerCompose`

`excludeGroupIds`

`excludes`

`executable`

`includeSystemScope`

`includeTools`

`includes`

`layers`

`layout`

`layoutFactory`

`loaderImplementation`

`mainClass`

`outputDirectory`

`outputTimestamp`

`requiresUnpack`

`skip`