使用 Maven 运行你的应用程序

QWen Max 中英对照 Running your Application with Maven

该插件包含一个 run 目标，可用于从命令行启动你的应用程序，如下例所示：

$ mvn spring-boot:run

可以使用 arguments 参数指定应用程序参数，更多详情请参见 使用应用程序参数。

该应用程序在 fork 出的进程中执行，因此在命令行上设置的属性不会影响应用程序。如果你需要指定一些 JVM 参数（例如用于调试目的），可以使用 jvmArguments 参数，更多详情请参见 Debug the application。此外，还明确支持 system properties 和 environment variables。

由于启用 profile 非常常见，因此提供了一个专用的 profiles 属性，作为 -Dspring-boot.run.jvmArguments="-Dspring.profiles.active=dev" 的快捷方式，参见 指定激活的 profiles。

Spring Boot devtools 是一个模块，用于在开发 Spring Boot 应用程序时提升开发阶段的体验。要启用它，只需将以下依赖项添加到你的项目中：

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

当 devtools 运行时，它会在你重新编译应用程序时检测到变更，并自动刷新应用。这不仅适用于资源文件，也适用于代码。它还提供了一个 LiveReload 服务器，以便在内容发生变化时自动触发浏览器刷新。

Devtools 也可以配置为仅在静态资源发生变化时刷新浏览器（并忽略代码中的任何更改）。只需在你的项目中包含以下属性即可：

spring.devtools.remote.restart.enabled=false

在 devtools 之前，该插件默认支持资源的热刷新，但现在已禁用，转而采用上述描述的解决方案。你可以随时通过配置项目来恢复该功能：

<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<addResources>true</addResources>
				</configuration>
			</plugin>
		</plugins>
	</build>

当启用 addResources 时，运行应用程序时会将任何 src/main/resources 目录添加到应用程序的 classpath 中，并且会移除 classes 输出目录中发现的重复资源。这使得在开发 Web 应用程序时可以实现资源的热刷新。例如，你可以直接修改 HTML、CSS 或 JavaScript 文件，并立即看到更改效果，而无需重新编译应用程序。此外，这也是一种很有帮助的方式，允许前端开发人员无需下载和安装 Java IDE 即可开展工作。

备注

使用此功能的一个副作用是，在构建时对资源的过滤将无法生效。

为了与 repackage 目标保持一致，run 目标构建 classpath 的方式会使得插件配置中排除的任何依赖项也会从 classpath 中排除。更多细节请参见 专门的示例。

有时运行应用程序的测试变体非常有用。例如，如果你想在开发时 使用 Testcontainers 或利用某些测试桩（test stubs）。为此，可以使用 test-run 目标，它具备与 run 目标许多相同的功能和配置选项。

spring-boot:run

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

就地运行一个应用程序。

必需参数

名称	类型	默认值
classesDirectory	File	${project.build.outputDirectory}

可选参数

名称	类型	默认值
addResources	boolean	false
additionalClasspathElements	String[]
agents	File[]
arguments	String[]
commandlineArguments	String
environmentVariables	Map
excludeGroupIds	String
excludes	List
includes	List
jvmArguments	String
mainClass	String
noverify	boolean
optimizedLaunch	boolean	true
profiles	String[]
skip	boolean	false
systemPropertyVariables	Map
useTestClasspath	boolean	false
workingDirectory	File

参数详情

addResources

直接将 Maven 资源添加到 classpath 中，这样可以支持对资源进行实时的原地编辑。重复的资源会从 target/classes 中移除，以防止在调用 ClassLoader.getResources() 时出现重复。建议考虑改用向项目中添加 spring-boot-devtools，因为它不仅提供此功能，还包含许多其他特性。

addResources
类型	boolean
默认值	false
用户属性	spring-boot.run.addResources
起始版本	1.0.0

additionalClasspathElements

应添加到 classpath 的额外 classpath 元素。一个元素可以是包含类和资源的目录，也可以是一个 jar 文件。

additionalClasspathElements
类型	java.lang.String[]
默认值
用户属性	spring-boot.run.additional-classpath-elements
自版本	3.2.0

agents

Agent JAR 文件的路径。

agents
类型	java.io.File[]
默认值
用户属性	spring-boot.run.agents
起始版本	2.2.0

arguments

应传递给应用程序的参数。

arguments
类型	java.lang.String[]
默认值
用户属性
起始版本	1.0.0

classesDirectory

包含用于运行应用程序的类和资源文件的目录。

classesDirectory
类型	java.io.File
默认值	${project.build.outputDirectory}
用户属性
起始版本	1.0.0

commandlineArguments

应传递给应用程序的命令行参数。使用空格分隔多个参数，并确保将多个值用引号括起来。指定此选项时，将优先于 #arguments。

commandlineArguments
类型	java.lang.String
默认值
用户属性	spring-boot.run.arguments
自	2.2.3

environmentVariables

应与用于运行应用程序的 forked 进程关联的环境变量列表。

environmentVariables
类型	java.util.Map
默认值
用户属性
自版本	2.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

includes

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

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

jvmArguments

应与用于运行应用程序的 forked 进程关联的 JVM 参数。在命令行中，请确保将多个值用引号括起来。

jvmArguments
类型	java.lang.String
默认值
用户属性	spring-boot.run.jvmArguments
自版本	1.1.0

mainClass

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

mainClass
类型	java.lang.String
默认值
用户属性	spring-boot.run.main-class
起始版本	1.0.0

noverify

用于指示该 agent 需要 -noverify 的标志。

noverify
类型	boolean
默认值
用户属性	spring-boot.run.noverify
起始版本	1.0.0

optimizedLaunch

是否应优化 JVM 的启动。

optimizedLaunch
类型	boolean
默认值	true
用户属性	spring-boot.run.optimizedLaunch
起始版本	2.2.0

profiles

要激活的 Spring profiles。这是指定 spring.profiles.active 参数的便捷快捷方式。在命令行中使用逗号分隔多个 profiles。

profiles
类型	java.lang.String[]
默认值
用户属性	spring-boot.run.profiles
起始版本	1.3.0

skip

跳过执行。

skip
类型	boolean
默认值	false
用户属性	spring-boot.run.skip
起始版本	1.3.2

systemPropertyVariables

要传递给进程的 JVM 系统属性列表。

systemPropertyVariables
类型	java.util.Map
默认值
用户属性
自	2.1.0

useTestClasspath

运行时包含测试类路径的标志。

useTestClasspath
类型	boolean
默认值	false
用户属性	spring-boot.run.useTestClasspath
起始版本	1.3.0

workingDirectory

应用程序使用的当前工作目录。如果未指定，则将使用 basedir。

workingDirectory
类型	java.io.File
默认值
用户属性	spring-boot.run.workingDirectory
起始版本	1.5.0

spring-boot:test-run

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

使用测试运行时类路径（test runtime classpath）直接运行应用程序。用于启动应用程序的主类（main class）按以下顺序确定：

1. 如果配置了主类，则使用该配置的主类。
2. 否则，使用在测试类目录（test classes directory）中找到的主类（如果存在）。
3. 否则，使用在类目录（classes directory）中找到的主类（如果存在）。

必需参数

名称	类型	默认值
classesDirectory	File	${project.build.outputDirectory}
testClassesDirectory	File	${project.build.testOutputDirectory}

可选参数

名称	类型	默认值
addResources	boolean	false
additionalClasspathElements	String[]
agents	File[]
arguments	String[]
commandlineArguments	String
environmentVariables	Map
excludeGroupIds	String
excludes	List
includes	List
jvmArguments	String
mainClass	String
noverify	boolean
optimizedLaunch	boolean	true
profiles	String[]
skip	boolean	false
systemPropertyVariables	Map
workingDirectory	File

参数详情

addResources

直接将 Maven 资源添加到 classpath 中，这允许对资源进行实时原地编辑。重复的资源会从 target/classes 中移除，以防止在调用 ClassLoader.getResources() 时出现重复。建议考虑改用向项目中添加 spring-boot-devtools，因为它不仅提供此功能，还包含许多其他特性。

addResources
类型	boolean
默认值	false
用户属性	spring-boot.run.addResources
起始版本	1.0.0

additionalClasspathElements

应添加到 classpath 的额外 classpath 元素。一个元素可以是包含类和资源的目录，也可以是一个 jar 文件。

additionalClasspathElements
类型	java.lang.String[]
默认值
用户属性	spring-boot.run.additional-classpath-elements
自版本	3.2.0

agents

Agent JAR 文件的路径。

agents
类型	java.io.File[]
默认值
用户属性	spring-boot.run.agents
起始版本	2.2.0

arguments

应传递给应用程序的参数。

arguments
类型	java.lang.String[]
默认值
用户属性
起始版本	1.0.0

classesDirectory

包含用于运行应用程序的类和资源文件的目录。

classesDirectory
类型	java.io.File
默认值	${project.build.outputDirectory}
用户属性
起始版本	1.0.0

commandlineArguments

应传递给应用程序的命令行参数。使用空格分隔多个参数，并确保将多个值用引号括起来。当指定此选项时，其优先级高于 #arguments。

commandlineArguments
类型	java.lang.String
默认值
用户属性	spring-boot.run.arguments
起始版本	2.2.3

environmentVariables

应与用于运行应用程序的 forked 进程关联的环境变量列表。

environmentVariables
类型	java.util.Map
默认值
用户属性
自版本	2.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

includes

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

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

jvmArguments

应与用于运行应用程序的 forked 进程关联的 JVM 参数。在命令行中，请确保将多个值用引号括起来。

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

mainClass

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

mainClass
类型	java.lang.String
默认值
用户属性	spring-boot.run.main-class
起始版本	1.0.0

noverify

标志，用于表示该 agent 需要 -noverify。

noverify
类型	boolean
默认值
用户属性	spring-boot.run.noverify
起始版本	1.0.0

optimizedLaunch

是否应优化 JVM 的启动。

optimizedLaunch
类型	boolean
默认值	true
用户属性	spring-boot.test-run.optimizedLaunch
起始版本

profiles

要激活的 Spring 配置文件。这是指定 spring.profiles.active 参数的便捷快捷方式。在命令行中，使用逗号分隔多个配置文件。

profiles
类型	java.lang.String[]
默认值
用户属性	spring-boot.run.profiles
起始版本	1.3.0

skip

跳过执行。

skip
类型	boolean
默认值	false
用户属性	spring-boot.run.skip
起始版本	1.3.2

systemPropertyVariables

要传递给进程的 JVM 系统属性列表。

systemPropertyVariables
类型	java.util.Map
默认值
用户属性
自	2.1.0

testClassesDirectory

包含用于运行应用程序的测试类和资源文件的目录。

testClassesDirectory
类型	java.io.File
默认值	${project.build.testOutputDirectory}
用户属性
自

workingDirectory

应用程序使用的当前工作目录。如果未指定，则将使用 basedir。

workingDirectory
类型	java.io.File
默认值
用户属性	spring-boot.run.workingDirectory
起始版本	1.5.0

示例

调试应用程序

run 和 test-run 目标会在一个 fork 出的进程中运行你的应用程序。如果你需要调试它，应该添加必要的 JVM 参数以启用远程调试。以下配置会使进程挂起，直到调试器连接到 5005 端口：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<jvmArguments>
						-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005
					</jvmArguments>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

这些参数也可以在命令行中指定：

$ mvn spring-boot:run -Dspring-boot.run.jvmArguments=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005

使用系统属性

可以使用 systemPropertyVariables 属性指定系统属性。以下示例将 property1 设置为 test，将 property2 设置为 42：

<project>
	<build>
		<properties>
			<my.value>42</my.value>
		</properties>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<systemPropertyVariables>
						<property1>test</property1>
						<property2>${my.value}</property2>
					</systemPropertyVariables>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

如果该值为空或未定义（即 <my-property/>），系统属性将被设置为一个空字符串。Maven 会自动去除 pom 中指定的值的首尾空白，因此无法通过此机制指定需要以空格开头或结尾的系统属性；建议改用 jvmArguments。

任何 String 类型的 Maven 变量都可以作为系统属性传递。如果尝试传递其他类型的 Maven 变量（例如 List 或 URL 变量），则该变量表达式将被原样传递（不进行求值）。

jvmArguments 参数优先于使用上述机制定义的系统属性。在以下示例中，property1 的值为 overridden：

$ mvn spring-boot:run -Dspring-boot.run.jvmArguments="-Dproperty1=overridden"

使用环境变量

可以使用 environmentVariables 属性指定环境变量。以下示例设置了 'ENV1'、'ENV2'、'ENV3'、'ENV4' 环境变量：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<environmentVariables>
						<ENV1>5000</ENV1>
						<ENV2>Some Text</ENV2>
						<ENV3/>
						<ENV4></ENV4>
					</environmentVariables>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

如果该值为空或未定义（即 <MY_ENV/>），则环境变量将被设置为空字符串作为其值。Maven 会自动去除在 pom 中指定的值的首尾空白字符，因此无法指定一个需要以空格开头或结尾的环境变量。

任何 String 类型的 Maven 变量都可以作为系统属性传递。如果尝试传递其他类型的 Maven 变量（例如 List 或 URL 变量），则该变量表达式将被原样传递（不进行求值）。

通过这种方式定义的环境变量会优先于已存在的值。

使用应用程序参数

可以使用 arguments 属性指定应用程序参数。以下示例设置了两个参数：property1 和 property2=42：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<arguments>
						<argument>property1</argument>
						<argument>property2=${my.value}</argument>
					</arguments>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

在命令行中，参数通过空格分隔，与 jvmArguments 的分隔方式相同。如果某个参数包含空格，请确保用引号将其括起来。在下面的示例中，有两个参数可用：property1 和 property2=Hello World：

$ mvn spring-boot:run -Dspring-boot.run.arguments="property1 'property2=Hello World'"

指定 Active Profiles

可以使用 profiles 参数指定特定应用程序要使用的 active profiles。

以下配置启用了 local 和 dev 配置文件：

<project>
	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
				<configuration>
					<profiles>
						<profile>local</profile>
						<profile>dev</profile>
					</profiles>
				</configuration>
			</plugin>
		</plugins>
	</build>
</project>

要启用的 profiles 也可以在命令行中指定，确保使用逗号分隔它们，如下例所示：

$ mvn spring-boot:run -Dspring-boot.run.profiles=local,dev