版本：4.0.2

本站内所有文档均为中英对照文档，点击中文可以显示英文。此提醒连续关闭5次后，将不再显示。

文档内容来源于 spring.io，由 springdoc.tech 翻译，版权归属于 SPRING.IO (Broadcom. Inc)。可供个人学习、研究，未经许可，不得进行转载或用于商业行为。

打包 OCI 镜像

QWen Max 中英对照 Packaging OCI Images

打包 OCI 镜像

Docker Daemon
Docker Registry
Image Customizations
Tags Format
spring-boot:build-image
Required parameters
Optional parameters
Parameter details
spring-boot:build-image-no-fork
Required parameters
Optional parameters
Parameter details
Examples
Custom Image Builder
Builder Configuration
Runtime JVM Configuration
Custom Image Name
Buildpacks
Image Publishing
Builder Cache and Workspace Configuration
Docker Configuration

该插件可以使用 Cloud Native Buildpacks（CNB）从 jar 或 war 文件创建 OCI 镜像。可以通过命令行使用 build-image 目标来构建镜像。这可确保在创建镜像之前，package 生命周期阶段已经执行完毕。

备注

出于安全原因，镜像以非 root 用户身份构建和运行。更多详情请参见 CNB 规范。

最简单的入门方式是在项目上执行 mvn spring-boot:build-image。可以在每次调用 package 阶段时自动创建镜像，如下例所示：

<build>
	<plugins>
		<plugin>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-maven-plugin</artifactId>
			<executions>
				<execution>
					<goals>
						<goal>build-image-no-fork</goal>
					</goals>
				</execution>
			</executions>
		</plugin>
	</plugins>
</build>

备注

在将目标绑定到 package 生命周期时，请使用 build-image-no-fork。该目标与 build-image 类似，但不会 fork 生命周期以确保 package 已经执行。在本节其余部分中，build-image 用于指代 build-image 或 build-image-no-fork 目标。

提示

尽管 buildpack 从一个可执行归档文件运行，但无需先执行 repackage 目标，因为如果需要，可执行归档文件会自动生成。当 build-image 重新打包应用程序时，它会应用与 repackage 目标相同的设置，即可以使用某个排除选项来排除依赖项。默认情况下，spring-boot-devtools 和 spring-boot-docker-compose 模块会被自动排除（你可以通过 excludeDevtools 和 excludeDockerCompose 属性来控制此行为）。还需注意，默认情况下不会包含可选依赖项。如果你将这些模块定义为可选的，则还需要将 includeOptional 属性设置为 true。

Docker Daemon

build-image goal 需要访问 Docker daemon。该 goal 会检查本地 Docker CLI 的配置文件，以确定当前的 context，并使用该 context 的连接信息与 Docker daemon 通信。如果无法确定当前 context，或者该 context 没有连接信息，则该 goal 将使用默认的本地连接。这种方式在所有受支持的平台上均可与 Docker Engine 配合使用，无需额外配置。

可以设置环境变量来配置 build-image goal，以使用替代的本地或远程连接。下表列出了环境变量及其值：

环境变量	描述
`DOCKER_CONFIG`	Docker CLI 配置文件的位置，用于确定当前上下文（默认为 `$HOME/.docker`）
`DOCKER_CONTEXT`	应使用的上下文名称，用于从 Docker CLI 配置文件中获取主机信息（会覆盖 `DOCKER_HOST`）
`DOCKER_HOST`	包含 Docker 守护进程主机和端口的 URL，例如 `tcp://192.168.99.100:2376`
`DOCKER_TLS_VERIFY`	当设置为 `1` 时，启用安全的 HTTPS 协议（可选）
`DOCKER_CERT_PATH`	HTTPS 证书和密钥文件的路径（当 `DOCKER_TLS_VERIFY=1` 时必需，否则忽略）

Docker daemon 的连接信息也可以通过插件配置中的 docker 参数提供。下表总结了可用的参数：

参数	说明
`context`	应用于从 Docker CLI 配置文件中检索主机信息的上下文名称
`host`	包含 Docker 守护进程主机和端口的 URL，例如 `tcp://192.168.99.100:2376`
`tlsVerify`	当设置为 `true` 时，启用安全的 HTTPS 协议（可选）
`certPath`	HTTPS 证书和密钥文件的路径（当 `tlsVerify` 为 `true` 时必填，否则忽略）
`bindHostToBuilder`	当为 `true` 时，`host` 属性的值将提供给为 CNB builder 创建的容器（可选）

更多详情，请参见示例。

Docker Registry

如果 builder 或 runImage 参数指定的 Docker 镜像存储在需要身份验证的私有 Docker 镜像仓库中，则可以使用 docker.builderRegistry 参数提供身份验证凭据。

如果要将生成的 Docker 镜像发布到 Docker 镜像仓库，可以使用 docker.publishRegistry 参数提供身份验证凭据。

参数用于用户认证或身份令牌（identity token）认证。有关所支持的认证方法的更多信息，请参阅用于存储镜像的 Docker registry 的相关文档。

下表总结了 docker.builderRegistry 和 docker.publishRegistry 的可用参数：

Parameter	Description
`username`	Docker 镜像仓库用户的用户名。用户认证时必需。
`password`	Docker 镜像仓库用户的密码。用户认证时必需。
`url`	Docker 镜像仓库的地址。用户认证时可选。
`email`	Docker 镜像仓库用户的电子邮件地址。用户认证时可选。
`token`	Docker 镜像仓库用户的身份令牌。令牌认证时必需。

更多详情，请参见示例。

备注

如果未提供凭证，该插件会读取用户现有的 Docker 配置文件（通常位于 $HOME/.docker/config.json）以确定认证方法。插件将使用这些方法，为所请求的镜像提供认证凭证。

该插件支持以下认证方法：

Credential Helpers：在 Docker 配置文件中配置的外部工具，用于为特定的 registry 提供凭证。例如，osxkeychain 或 ecr-login 等工具可处理某些 registry 的认证。
Credential Store：一种默认的后备机制，用于安全地存储和检索凭证（例如，Docker Desktop 使用的 desktop）。
Static Credentials：直接存储在 Docker 配置文件 auths 部分中的凭证。

镜像定制

该插件调用一个 builder 来协调生成镜像。该 builder 包含多个 buildpacks，可以检查应用程序以影响所生成的镜像。默认情况下，插件会选择一个 builder 镜像。所生成镜像的名称由项目属性推断得出。

image 参数允许配置构建器及其在项目上的操作方式。下表总结了可用的参数及其默认值：

Parameter / (User Property)	描述	默认值
`builder` (`spring-boot.build-image.builder`)	要使用的构建器镜像的名称。	`paketobuildpacks/builder-noble-java-tiny:latest`
`trustBuilder` (`spring-boot.build-image.trustBuilder`)	是否将该 builder 视为 trusted。	`true` if the builder is one of `paketobuildpacks/builder-noble-java-tiny`, `paketobuildpacks/builder-jammy-java-tiny`, `paketobuildpacks/builder-jammy-tiny`, `paketobuildpacks/builder-jammy-base`, `paketobuildpacks/builder-jammy-full`, `paketobuildpacks/builder-jammy-buildpackless-tiny`, `paketobuildpacks/builder-jammy-buildpackless-base`, `paketobuildpacks/builder-jammy-buildpackless-full`, `gcr.io/buildpacks/builder`, `heroku/builder`; `false` otherwise.
`imagePlatform` (`spring-boot.build-image.imagePlatform`)	所拉取的任何 builder 镜像、运行镜像和 buildpack 镜像的平台（操作系统和架构）。必须采用 `OS[/architecture[/variant]]` 的形式，例如 `linux/amd64`、`linux/arm64` 或 `linux/arm/v5`。请参考所使用 builder 的文档，以确定可用的镜像操作系统和架构选项。	无默认值，表示应使用主机平台。
`runImage` (`spring-boot.build-image.runImage`)	要使用的运行镜像的名称。	无默认值，表示应使用 Builder 元数据中指定的运行时镜像。
`name` (`spring-boot.build-image.imageName`)	生成镜像的 Image name。	`docker.io/library/` `${project.artifactId}:${project.version}`
`pullPolicy` (`spring-boot.build-image.pullPolicy`)	用于确定何时从注册表拉取 builder 镜像和 run 镜像的 Policy。可接受的值为 `ALWAYS`、`NEVER` 和 `IF_NOT_PRESENT`。	`ALWAYS`
`env`	应传递给构建器的环境变量。
`buildpacks`	构建器在构建镜像时应使用的 Buildpacks。仅会使用指定的 Buildpacks，从而覆盖构建器中包含的默认 Buildpacks。Buildpack 引用必须采用以下形式之一： - 构建器中的 Buildpack - `[urn:cnb:builder:]<buildpack ID>[@<version>]` - 文件系统目录中的 Buildpack - `[file://]<path>` - 文件系统中 gzip 压缩的 tar（.tgz）文件中的 Buildpack - `[file://]<path>/<file name>` - OCI 镜像中的 Buildpack - `[docker://]<host>/<repo>[:<tag>][@<digest>]`	None，表示构建器应使用其中包含的 buildpacks。
`bindings`	构建镜像时应挂载到构建器容器的卷绑定挂载（Volume bind mounts）。这些绑定将在创建构建器容器时以未经解析和验证的形式直接传递给 Docker。绑定必须采用以下形式之一： - `<host source path>:<container destination path>[:<options>]` - `<host volume name>:<container destination path>[:<options>]` 其中 `<options>` 可包含以下内容： - `ro`：将卷以只读方式挂载到容器中 - `rw`：将卷以可读写方式挂载到容器中 - `volume-opt=key=value`：指定由选项名称及其值组成的键值对
`network` + (`spring-boot.build-image.network`)	构建器容器将配置为使用的网络驱动。所提供的值在创建构建器容器时会未经验证地直接传递给 Docker。
`cleanCache` + (`spring-boot.build-image.cleanCache`)	是否在构建前清理缓存。	`false`
`verboseLogging`	启用构建器操作的详细日志记录。	`false`
`publish` + (`spring-boot.build-image.publish`)	是否将生成的镜像发布到 Docker registry。	`false`
`tags`	一个或多个要应用于生成镜像的附加标签。提供给 `tags` 选项的值应为完整的镜像引用。更多详情请参见标签部分。
`buildWorkspace`	一个临时工作区，将由 builder 和 buildpacks 在镜像构建过程中用于存储文件。该值可以是一个命名卷（named volume）或绑定挂载（bind mount）位置。	Docker 守护进程中一个命名卷，其名称源自镜像名称。
`buildCache`	一个包含由 buildpacks 创建的层并被镜像构建过程使用的缓存。该值可以是一个命名卷或绑定挂载位置。	Docker 守护进程中一个命名卷，其名称源自镜像名称。
`launchCache`	一个包含由 buildpacks 创建的层并被镜像启动过程使用的缓存。该值可以是一个命名卷或一个绑定挂载位置。	Docker 守护进程中一个命名卷，其名称源自镜像名称。
`createdDate` (`spring-boot.build-image.createdDate`)	一个用于设置生成镜像元数据中 `Created` 字段的日期。该值必须是 ISO 8601 即时格式的字符串，或者使用 `now` 表示当前日期和时间。	一个固定的日期，用于实现构建可重现性。
`applicationDirectory` (`spring-boot.build-image.applicationDirectory`)	应用程序内容将被上传到构建器镜像中的目录路径。在生成的镜像中，应用程序内容也将位于此位置。	`/workspace`
`securityOptions`	安全选项，将应用于构建器容器，以字符串值数组的形式提供	`["label=disable"]` on Linux and macOS, `[]` on Windows

备注

该插件通过编译器的插件配置或 maven.compiler.target 属性来检测项目的目标 Java 兼容性。当使用默认的 Paketo builder 和 buildpacks 时，该插件会指示 buildpacks 安装相同的 Java 版本。你可以按照 builder 配置示例中所示的方式覆盖此行为。

更多详情，请参见示例。

标签格式

提供给 tags 选项的值应为完整的镜像引用。可接受的格式为 [domainHost:port/][path/]name[:tag][@digest]。

如果域名缺失，则默认为 docker.io。如果路径缺失，则默认为 library。如果标签缺失，则默认为 latest。

一些示例：

my-image 对应的镜像引用为 docker.io/library/my-image:latest
my-repository/my-image 对应的镜像引用为 docker.io/my-repository/my-image:latest
example.com/my-repository/my-image:1.0.0 将按原样使用

`spring-boot:build-image`

org.springframework.boot:spring-boot-maven-plugin:4.0.2

使用 buildpack 将应用程序打包为 OCI 镜像，并 fork 生命周期以确保 package 已运行。此目标适用于命令行调用。如果需要在构建中配置目标 execution，请改用 build-image-no-fork。

必需参数

名称	类型	默认值
sourceDirectory	`File`	`${project.build.directory}`

可选参数

名称	类型	默认值
applicationDirectory	`String`
classifier	`String`
cleanCache	`Boolean`
createdDate	`String`
docker	`[Docker](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Docker.html)`
excludeDevtools	`boolean`	`true`
excludeDockerCompose	`boolean`	`true`
excludeGroupIds	`String`
excludes	`List`
image	`[Image](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Image.html)`
imageBuilder	`String`
imageName	`String`
imagePlatform	`String`
includeOptional	`boolean`	`false`
includeSystemScope	`boolean`	`false`
includeTools	`boolean`	`true`
includes	`List`
layers	`[Layers](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Layers.html)`
layout	`[LayoutType](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/AbstractPackagerMojo.LayoutType.html)`
layoutFactory	`[LayoutFactory](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/loader/tools/LayoutFactory.html)`
mainClass	`String`
network	`String`
publish	`Boolean`
pullPolicy	`[PullPolicy](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/buildpack/platform/build/PullPolicy.html)`
runImage	`String`
skip	`boolean`	`false`
trustBuilder	`Boolean`

参数详情

`applicationDirectory`

Image#applicationDirectory 的别名，用于支持通过命令行属性进行配置。

`applicationDirectory`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.applicationDirectory`
起始版本	`3.1.0`

`classifier`

查找源代码归档文件时使用的分类器。

`classifier`
类型	`java.lang.String`
默认值
用户属性
自	`2.3.0`

`cleanCache`

Image#cleanCache 的别名，用于支持通过命令行属性进行配置。

`cleanCache`
类型	`java.lang.Boolean`
默认值
用户属性	`spring-boot.build-image.cleanCache`
起始版本	`2.4.0`

`createdDate`

Image#createdDate 的别名，用于支持通过命令行属性进行配置。

`createdDate`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.createdDate`
起始版本	`3.1.0`

`docker`

Docker 配置选项。

`docker`
类型	`[org.springframework.boot.maven.Docker](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Docker.html)`
默认值
用户属性
自	`2.4.0`

`excludeDevtools`

从重新打包的归档文件中排除 Spring Boot devtools。

`excludeDevtools`
类型	`boolean`
默认值	`true`
用户属性	`spring-boot.repackage.excludeDevtools`
起始版本	`1.3.0`

`excludeDockerCompose`

从重新打包的归档文件中排除 Spring Boot 开发服务。

`excludeDockerCompose`
类型	`boolean`
默认值	`true`
用户属性	`spring-boot.repackage.excludeDockerCompose`
自版本	`3.1.0`

`excludeGroupIds`

要排除的 groupId 名称的逗号分隔列表（精确匹配）。

`excludeGroupIds`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.excludeGroupIds`
起始版本	`1.1.0`

`excludes`

要排除的构件定义集合。Exclude 元素定义了必需的 groupId 和 artifactId 组件，以及一个可选的 classifier 组件。当配置为属性时，值应以逗号分隔，各组件之间用冒号分隔：groupId:artifactId,groupId:artifactId:classifier

`excludes`
类型	`java.util.List`
默认值
用户属性	`spring-boot.excludes`
起始版本	`1.1.0`

`image`

镜像配置，包含 builder、runImage、name、env、cleanCache、verboseLogging、pullPolicy 和 publish 选项。

`image`
类型	`[org.springframework.boot.maven.Image](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Image.html)`
默认值
用户属性
自	`2.3.0`

`imageBuilder`

Image#builder 的别名，用于支持通过命令行属性进行配置。

`imageBuilder`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.builder`
起始版本	`2.3.0`

`imageName`

Image#name 的别名，用于支持通过命令行属性进行配置。

`imageName`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.imageName`
起始版本	`2.3.0`

`imagePlatform`

Image#imagePlatform 的别名，用于支持通过命令行属性进行配置。

`imagePlatform`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.imagePlatform`
起始版本	`3.4.0`

`includeOptional`

包含可选依赖项。

`includeOptional`
类型	`boolean`
默认值	`false`
用户属性
自	`3.5.7`

`includeSystemScope`

包含系统作用域的依赖项。

`includeSystemScope`
类型	`boolean`
默认值	`false`
用户属性
自版本	`1.4.0`

`includeTools`

包含 JAR 工具。

`includeTools`
类型	`boolean`
默认值	`true`
用户属性
自	`3.3.0`

`includes`

要包含的构件定义集合。Include 元素定义了必需的 groupId 和 artifactId 组件，以及一个可选的 classifier 组件。当配置为属性时，值应以逗号分隔，各组件之间用冒号分隔：groupId:artifactId,groupId:artifactId:classifier

`includes`
类型	`java.util.List`
默认值
用户属性	`spring-boot.includes`
起始版本	`1.2.0`

`layers`

层配置，包含禁用层创建、排除层工具 JAR 包，以及提供自定义层配置文件的选项。

`layers`
类型	`[org.springframework.boot.maven.Layers](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Layers.html)`
默认值
用户属性
起始版本	`2.3.0`

`layout`

归档文件的类型（对应于其中依赖项的布局方式）。可能的值有 JAR、WAR、ZIP、DIR、NONE。默认值根据归档文件类型进行推测。

`layout`
类型	`[org.springframework.boot.maven.AbstractPackagerMojo$LayoutType](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/AbstractPackagerMojo.LayoutType.html)`
默认值
用户属性
自	`2.3.11`

`layoutFactory`

如果未显式设置布局，将使用此布局工厂来创建可执行归档文件。第三方可以提供替代的布局实现。

`layoutFactory`
类型	`[org.springframework.boot.loader.tools.LayoutFactory](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/loader/tools/LayoutFactory.html)`
默认值
用户属性
起始版本	`2.3.11`

`mainClass`

主类的名称。如果未指定，则将使用找到的第一个包含 main 方法的已编译类。

`mainClass`
类型	`java.lang.String`
默认值
用户属性
起始版本	`1.0.0`

`network`

Image#network 的别名，用于支持通过命令行属性进行配置。

`network`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.network`
起始版本	`2.6.0`

`publish`

Image#publish 的别名，用于支持通过命令行属性进行配置。

`publish`
类型	`java.lang.Boolean`
默认值
用户属性	`spring-boot.build-image.publish`
起始版本

`pullPolicy`

Image#pullPolicy 的别名，用于支持通过命令行属性进行配置。

`pullPolicy`
类型	`[org.springframework.boot.buildpack.platform.build.PullPolicy](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/buildpack/platform/build/PullPolicy.html)`
默认值
用户属性	`spring-boot.build-image.pullPolicy`
自

`runImage`

Image#runImage 的别名，用于支持通过命令行属性进行配置。

`runImage`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.runImage`
起始版本	`2.3.1`

`skip`

跳过执行。

`skip`
类型	`boolean`
默认值	`false`
用户属性	`spring-boot.build-image.skip`
自	`2.3.0`

`sourceDirectory`

包含源代码归档文件的目录。

`sourceDirectory`
类型	`java.io.File`
默认值	`${project.build.directory}`
用户属性
自	`2.3.0`

`trustBuilder`

Image#trustBuilder 的别名，用于支持通过命令行属性进行配置。

`trustBuilder`
类型	`java.lang.Boolean`
默认值
用户属性	`spring-boot.build-image.trustBuilder`
自

`spring-boot:build-image-no-fork`

org.springframework.boot:spring-boot-maven-plugin:4.0.2

使用 buildpack 将应用程序打包为 OCI 镜像，但不 fork lifecycle。在构建中配置 goal execution 时应使用此 goal。若要在命令行上调用该 goal，请改用 build-image。

必需参数

名称	类型	默认值
sourceDirectory	`File`	`${project.build.directory}`

可选参数

名称	类型	默认值
applicationDirectory	`String`
classifier	`String`
cleanCache	`Boolean`
createdDate	`String`
docker	`[Docker](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Docker.html)`
excludeDevtools	`boolean`	`true`
excludeDockerCompose	`boolean`	`true`
excludeGroupIds	`String`
excludes	`List`
image	`[Image](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Image.html)`
imageBuilder	`String`
imageName	`String`
imagePlatform	`String`
includeOptional	`boolean`	`false`
includeSystemScope	`boolean`	`false`
includeTools	`boolean`	`true`
includes	`List`
layers	`[Layers](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Layers.html)`
layout	`[LayoutType](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/AbstractPackagerMojo.LayoutType.html)`
layoutFactory	`[LayoutFactory](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/loader/tools/LayoutFactory.html)`
mainClass	`String`
network	`String`
publish	`Boolean`
pullPolicy	`[PullPolicy](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/buildpack/platform/build/PullPolicy.html)`
runImage	`String`
skip	`boolean`	`false`
trustBuilder	`Boolean`

参数详情

`applicationDirectory`

Image#applicationDirectory 的别名，用于支持通过命令行属性进行配置。

`applicationDirectory`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.applicationDirectory`
起始版本	`3.1.0`

`classifier`

查找源代码归档文件时使用的分类器。

`classifier`
类型	`java.lang.String`
默认值
用户属性
自	`2.3.0`

`cleanCache`

Image#cleanCache 的别名，用于支持通过命令行属性进行配置。

`cleanCache`
类型	`java.lang.Boolean`
默认值
用户属性	`spring-boot.build-image.cleanCache`
起始版本	`2.4.0`

`createdDate`

Image#createdDate 的别名，用于支持通过命令行属性进行配置。

`createdDate`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.createdDate`
起始版本	`3.1.0`

`docker`

Docker 配置选项。

`docker`
类型	`[org.springframework.boot.maven.Docker](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Docker.html)`
默认值
用户属性
自	`2.4.0`

`excludeDevtools`

从重新打包的归档文件中排除 Spring Boot devtools。

`excludeDevtools`
类型	`boolean`
默认值	`true`
用户属性	`spring-boot.repackage.excludeDevtools`
起始版本	`1.3.0`

`excludeDockerCompose`

从重新打包的归档文件中排除 Spring Boot 开发服务。

`excludeDockerCompose`
类型	`boolean`
默认值	`true`
用户属性	`spring-boot.repackage.excludeDockerCompose`
自版本	`3.1.0`

`excludeGroupIds`

要排除的 groupId 名称的逗号分隔列表（精确匹配）。

`excludeGroupIds`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.excludeGroupIds`
起始版本	`1.1.0`

`excludes`

要排除的构件定义集合。Exclude 元素定义了必需的 groupId 和 artifactId 组件，以及一个可选的 classifier 组件。当将其配置为属性时，值应以逗号分隔，各组件之间用冒号分隔：groupId:artifactId,groupId:artifactId:classifier

`excludes`
类型	`java.util.List`
默认值
用户属性	`spring-boot.excludes`
起始版本	`1.1.0`

`image`

镜像配置，包含 builder、runImage、name、env、cleanCache、verboseLogging、pullPolicy 和 publish 选项。

`image`
类型	`[org.springframework.boot.maven.Image](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Image.html)`
默认值
用户属性
自	`2.3.0`

`imageBuilder`

Image#builder 的别名，用于支持通过命令行属性进行配置。

`imageBuilder`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.builder`
起始版本	`2.3.0`

`imageName`

Image#name 的别名，用于支持通过命令行属性进行配置。

`imageName`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.imageName`
起始版本	`2.3.0`

`imagePlatform`

Image#imagePlatform 的别名，用于支持通过命令行属性进行配置。

`imagePlatform`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.imagePlatform`
起始版本	`3.4.0`

`includeOptional`

包含可选依赖项。

`includeOptional`
类型	`boolean`
默认值	`false`
用户属性
自	`3.5.7`

`includeSystemScope`

包含 system 作用域的依赖项。

`includeSystemScope`
类型	`boolean`
默认值	`false`
用户属性
自	`1.4.0`

`includeTools`

包含 JAR 工具。

`includeTools`
类型	`boolean`
默认值	`true`
用户属性
自版本	`3.3.0`

`includes`

`includes`
类型	`java.util.List`
默认值
用户属性	`spring-boot.includes`
起始版本	`1.2.0`

`layers`

层配置，包含禁用层创建、排除层工具 JAR 以及提供自定义层配置文件的选项。

`layers`
类型	`[org.springframework.boot.maven.Layers](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/Layers.html)`
默认值
用户属性
自	`2.3.0`

`layout`

归档文件的类型（对应于其中依赖项的布局方式）。可能的值有 JAR、WAR、ZIP、DIR、NONE。默认值根据归档文件类型进行推测。

`layout`
类型	`[org.springframework.boot.maven.AbstractPackagerMojo$LayoutType](https://docs.spring.io/spring-boot/maven-plugin/api/java/org/springframework/boot/maven/AbstractPackagerMojo.LayoutType.html)`
默认值
用户属性
起始版本	`2.3.11`

`layoutFactory`

如果未显式设置布局，将用于创建可执行归档文件的布局工厂。第三方可以提供替代的布局实现。

`layoutFactory`
类型	`[org.springframework.boot.loader.tools.LayoutFactory](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/loader/tools/LayoutFactory.html)`
默认值
用户属性
起始版本	`2.3.11`

`mainClass`

主类的名称。如果未指定，则将使用找到的第一个包含 main 方法的已编译类。

`mainClass`
类型	`java.lang.String`
默认值
用户属性
起始版本	`1.0.0`

`network`

Image#network 的别名，用于支持通过命令行属性进行配置。

`network`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.network`
起始版本	`2.6.0`

`publish`

Image#publish 的别名，用于支持通过命令行属性进行配置。

`publish`
类型	`java.lang.Boolean`
默认值
用户属性	`spring-boot.build-image.publish`
起始版本

`pullPolicy`

Image#pullPolicy 的别名，用于支持通过命令行属性进行配置。

`pullPolicy`
类型	`[org.springframework.boot.buildpack.platform.build.PullPolicy](https://docs.spring.io/spring-boot/api/java/org/springframework/boot/buildpack/platform/build/PullPolicy.html)`
默认值
用户属性	`spring-boot.build-image.pullPolicy`
起始版本

`runImage`

Image#runImage 的别名，用于支持通过命令行属性进行配置。

`runImage`
类型	`java.lang.String`
默认值
用户属性	`spring-boot.build-image.runImage`
自	`2.3.1`

`skip`

跳过执行。

`skip`
类型	`boolean`
默认值	`false`
用户属性	`spring-boot.build-image.skip`
起始版本	`2.3.0`

`sourceDirectory`

包含源代码归档文件的目录。

`sourceDirectory`
类型	`java.io.File`
默认值	`${project.build.directory}`
用户属性
自	`2.3.0`

`trustBuilder`

Image#trustBuilder 的别名，用于支持通过命令行属性进行配置。

`trustBuilder`
类型	`java.lang.Boolean`
默认值
用户属性	`spring-boot.build-image.trustBuilder`
起始版本

示例

Custom Image Builder

如果你需要自定义用于创建镜像的 builder，或用于启动构建后镜像的 run 镜像，请按以下示例配置该插件：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<builder>mine/java-cnb-builder</builder>
						<runImage>mine/java-cnb-run</runImage>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

此配置将使用名称为 mine/java-cnb-builder、标签为 latest 的构建器镜像，以及名称为 mine/java-cnb-run、标签为 latest 的运行镜像。

构建器镜像和运行镜像也可以在命令行中指定，如下例所示：

$ mvn spring-boot:build-image -Dspring-boot.build-image.builder=mine/java-cnb-builder -Dspring-boot.build-image.runImage=mine/java-cnb-run

Builder 配置

如果构建器使用环境变量暴露配置选项，则可以使用 env 属性进行设置。

以下是在构建时配置 Paketo Java buildpack 所使用的 JVM 版本的示例：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<env>
							<BP_JVM_VERSION>17</BP_JVM_VERSION>
						</env>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

如果在运行构建器（builder）的 Docker 守护进程与 buildpacks 下载制品（artifacts）的网络位置之间存在网络代理，则需要配置构建器以使用该代理。当使用 Paketo 构建器时，可以通过设置 HTTPS_PROXY 和/或 HTTP_PROXY 环境变量来实现，如下例所示：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<env>
							<HTTP_PROXY>http://proxy.example.com</HTTP_PROXY>
							<HTTPS_PROXY>https://proxy.example.com</HTTPS_PROXY>
						</env>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

运行时 JVM 配置

Paketo Java buildpack 通过设置 JAVA_TOOL_OPTIONS 环境变量来配置 JVM 运行时环境。当应用镜像在容器中启动时，可以修改 buildpack 提供的 JAVA_TOOL_OPTIONS 值，以自定义 JVM 运行时行为。

应存储在镜像中并应用于每次部署的环境变量修改，可以按照 Paketo 文档中所述进行设置，如下例所示：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<env>
							<BPE_DELIM_JAVA_TOOL_OPTIONS xml:space="preserve"> </BPE_DELIM_JAVA_TOOL_OPTIONS>
							<BPE_APPEND_JAVA_TOOL_OPTIONS>-XX:+HeapDumpOnOutOfMemoryError</BPE_APPEND_JAVA_TOOL_OPTIONS>
						</env>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

自定义镜像名称

默认情况下，镜像名称是从项目的 artifactId 和 version 推断出来的，类似于 docker.io/library/${project.artifactId}:${project.version}。你可以像下面的例子一样控制镜像名称：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<name>example.com/library/${project.artifactId}</name>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

备注

此配置未显式指定标签，因此使用 latest。也可以指定一个标签，可以使用 ${project.version}、构建中可用的任意属性，或硬编码的版本。

镜像名称也可以在命令行中指定，如下例所示：

$ mvn spring-boot:build-image -Dspring-boot.build-image.imageName=example.com/library/my-app:v1

Buildpacks

默认情况下，builder 将使用 builder 镜像中包含的 buildpack，并按照预定义的顺序应用它们。也可以提供一组替代的 buildpack，以应用未包含在 builder 中的 buildpack，或更改已包含 buildpack 的顺序。当提供一个或多个 buildpack 时，将仅应用所指定的 buildpack。

以下示例指示 builder 使用一个打包在 .tgz 文件中的自定义 buildpack，然后使用 builder 中包含的 buildpack。

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<buildpacks>
							<buildpack>file:///path/to/example-buildpack.tgz</buildpack>
							<buildpack>urn:cnb:builder:paketo-buildpacks/java</buildpack>
						</buildpacks>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Buildpacks 可以以如下任意一种形式指定。

位于 CNB Builder 中的 buildpack（如果 builder 中仅有一个 buildpack 与 buildpack-id 匹配，则版本号可省略）：

urn:cnb:builder:buildpack-id
urn:cnb:builder:buildpack-id@0.0.1
buildpack-id
buildpack-id@0.0.1

指向包含 buildpack 内容的目录的路径（在 Windows 上不受支持）：

file:///path/to/buildpack/
/path/to/buildpack/

一个指向包含 buildpack 内容的 gzip 压缩 tar 文件的路径：

file:///path/to/buildpack.tgz
/path/to/buildpack.tgz

一个包含打包的 buildpack 的 OCI 镜像：

docker://example/buildpack
docker:///example/buildpack:latest
docker:///example/buildpack@sha256:45b23dee08…
example/buildpack
example/buildpack:latest
example/buildpack@sha256:45b23dee08…

镜像发布

通过启用 publish 选项，可以将生成的镜像发布到 Docker registry。

如果 Docker registry 需要身份验证，可以使用 docker.publishRegistry 参数配置凭据。如果 Docker registry 不需要身份验证，则可以省略 docker.publishRegistry 配置。

备注

镜像将被发布到的 registry 由镜像名称中的 registry 部分决定（在这些示例中为 docker.example.com）。如果配置了 docker.publishRegistry 凭据并包含 url 参数，则该值会传递给 registry，但不会用于确定发布 registry 的位置。

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<name>docker.example.com/library/${project.artifactId}</name>
						<publish>true</publish>
					</image>
					<docker>
						<publishRegistry>
							<username>user</username>
							<password>secret</password>
						</publishRegistry>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

publish 选项也可以在命令行中指定，如以下示例所示：

$ mvn spring-boot:build-image -Dspring-boot.build-image.imageName=docker.example.com/library/my-app:v1 -Dspring-boot.build-image.publish=true

在命令行中使用 publish 选项并进行身份验证时，你可以像下面这个示例一样，通过属性提供凭据：

$ mvn spring-boot:build-image \
      -Ddocker.publishRegistry.username=user \
      -Ddocker.publishRegistry.password=secret \
      -Ddocker.publishRegistry.url=docker.example.com \
      -Dspring-boot.build-image.publish=true \
      -Dspring-boot.build-image.imageName=docker.example.com/library/my-app:v1

并在 XML 配置中引用这些属性：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<docker>
						<publishRegistry>
							<url>${docker.publishRegistry.url}</url>
							<username>${docker.publishRegistry.username}</username>
							<password>${docker.publishRegistry.password}</password>
						</publishRegistry>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

构建器缓存与工作区配置

CNB 构建器在构建和启动镜像时会缓存所使用的层。默认情况下，这些缓存以命名卷的形式存储在 Docker 守护进程中，其名称由目标镜像的完整名称派生而来。如果镜像名称频繁变动（例如在镜像名称中使用项目版本作为标签），那么缓存可能会频繁失效。

缓存卷可以配置为使用替代名称，以对缓存生命周期提供更精细的控制，如下例所示：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<buildCache>
							<volume>
								<name>cache-${project.artifactId}.build</name>
							</volume>
						</buildCache>
						<launchCache>
							<volume>
								<name>cache-${project.artifactId}.launch</name>
							</volume>
						</launchCache>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

构建器（Builders）和 buildpacks 在构建镜像时需要一个位置来存储临时文件。默认情况下，这个临时构建工作区存储在一个命名卷（named volume）中。

缓存和构建工作区可以配置为使用绑定挂载（bind mounts）而不是命名卷（named volumes），如下例所示：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<image>
						<buildWorkspace>
							<bind>
								<source>/tmp/cache-${project.artifactId}.work</source>
							</bind>
						</buildWorkspace>
						<buildCache>
							<bind>
								<source>/tmp/cache-${project.artifactId}.build</source>
							</bind>
						</buildCache>
						<launchCache>
							<bind>
								<source>/tmp/cache-${project.artifactId}.launch</source>
							</bind>
						</launchCache>
					</image>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

Docker 配置

minikube 的 Docker 配置

该插件可以与 minikube 提供的 Docker daemon 通信，而不是使用默认的本地连接。

在 Linux 和 macOS 上，启动 minikube 后，可以使用命令 eval $(minikube docker-env) 来设置环境变量。

该插件也可以通过提供类似于以下示例所示的连接详细信息，配置为使用 minikube daemon：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<docker>
						<host>tcp://192.168.99.100:2376</host>
						<tlsVerify>true</tlsVerify>
						<certPath>/home/user/.minikube/certs</certPath>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

用于 podman 的 Docker 配置

该插件可以与 podman 容器引擎通信。

该插件可以通过提供类似以下示例所示的连接详细信息，配置为使用 podman 本地连接：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<docker>
						<host>unix:///run/user/1000/podman/podman.sock</host>
						<bindHostToBuilder>true</bindHostToBuilder>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

提示

安装了 colima CLI 后，可以使用命令 podman info --format='{{.Host.RemoteSocket.Path}}' 来获取本例中 docker.host 配置属性的值。

Colima 的 Docker 配置

该插件可以与 Colima 提供的 Docker daemon 通信。可以通过以下命令设置 DOCKER_HOST 环境变量：

$ export DOCKER_HOST=$(docker context inspect colima -f '{{.Endpoints.docker.Host}}')

该插件也可以通过提供类似于以下示例所示的连接详细信息，配置为使用 Colima 守护进程：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<docker>
						<host>unix:///${user.home}/.colima/docker.sock</host>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

用于身份验证的 Docker 配置

如果 builder 镜像或 run 镜像存储在支持用户认证的私有 Docker registry 中，则可以使用 docker.builderRegistry 参数提供认证信息，如下例所示：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<docker>
						<builderRegistry>
							<username>user</username>
							<password>secret</password>
							<url>https://docker.example.com/v1/</url>
							<email>user@example.com</email>
						</builderRegistry>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

如果 builder 镜像或 run 镜像存储在支持令牌认证的私有 Docker registry 中，则可以使用 docker.builderRegistry 参数提供令牌值，如下例所示：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<docker>
						<builderRegistry>
							<token>9cbaf023786cd7...</token>
						</builderRegistry>
					</docker>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

打包 OCI 镜像
Docker Daemon
Docker Registry
镜像定制
- 标签格式
spring-boot:build-image
spring-boot:build-image-no-fork
示例

打包 OCI 镜像​

Docker Daemon​

Docker Registry​

镜像定制​

标签格式​

spring-boot:build-image​

必需参数​

可选参数​

参数详情​

applicationDirectory​

classifier​

cleanCache​

createdDate​

docker​

excludeDevtools​

excludeDockerCompose​

excludeGroupIds​

excludes​

image​

imageBuilder​

imageName​

imagePlatform​

includeOptional​

includeSystemScope​

includeTools​

includes​

layers​

layout​

layoutFactory​

mainClass​

network​

publish​

pullPolicy​

runImage​

skip​

sourceDirectory​

trustBuilder​

spring-boot:build-image-no-fork​

必需参数​

可选参数​

参数详情​

applicationDirectory​

classifier​

cleanCache​

createdDate​

docker​

excludeDevtools​

excludeDockerCompose​

excludeGroupIds​

excludes​

image​

imageBuilder​

imageName​

imagePlatform​

includeOptional​

includeSystemScope​

includeTools​

includes​

layers​

layout​

layoutFactory​

mainClass​

network​

publish​

pullPolicy​

runImage​

skip​

sourceDirectory​

trustBuilder​

示例​

Custom Image Builder​

Builder 配置​

运行时 JVM 配置​

自定义镜像名称​

Buildpacks​

镜像发布​

构建器缓存与工作区配置​

Docker 配置​

minikube 的 Docker 配置​

用于 podman 的 Docker 配置​

打包 OCI 镜像

Docker Daemon

Docker Registry

镜像定制

标签格式

`spring-boot:build-image`

必需参数

可选参数

参数详情

`applicationDirectory`

`classifier`

`cleanCache`

`createdDate`

`docker`

`excludeDevtools`

`excludeDockerCompose`

`excludeGroupIds`

`excludes`

`image`

`imageBuilder`

`imageName`

`imagePlatform`

`includeOptional`

`includeSystemScope`

`includeTools`

`includes`

`layers`

`layout`

`layoutFactory`

`mainClass`

`network`

`publish`

`pullPolicy`

`runImage`

`skip`

`sourceDirectory`

`trustBuilder`

`spring-boot:build-image-no-fork`

必需参数

可选参数

参数详情

`applicationDirectory`

`classifier`

`cleanCache`

`createdDate`

`docker`

`excludeDevtools`

`excludeDockerCompose`

`excludeGroupIds`

`excludes`

`image`

`imageBuilder`

`imageName`

`imagePlatform`

`includeOptional`

`includeSystemScope`

`includeTools`

`includes`

`layers`

`layout`

`layoutFactory`

`mainClass`

`network`

`publish`

`pullPolicy`

`runImage`

`skip`

`sourceDirectory`

`trustBuilder`

示例

Custom Image Builder

Builder 配置

运行时 JVM 配置

自定义镜像名称

Buildpacks

镜像发布

构建器缓存与工作区配置

Docker 配置

minikube 的 Docker 配置

用于 podman 的 Docker 配置