跳到主要内容

使用 Maven 运行你的应用程序

DeepSeek V3 中英对照 Running your Application with Maven

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

$ mvn spring-boot:run
shell

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

应用程序在分叉进程中执行，因此在命令行上设置属性不会影响应用程序。如果需要指定一些 JVM 参数（例如用于调试目的），可以使用 jvmArguments 参数，更多详情请参阅调试应用程序。此外，还明确支持系统属性和环境变量。

由于启用配置文件的操作相当常见，因此提供了一个专门的 profiles 属性，作为 -Dspring-boot.run.jvmArguments="-Dspring.profiles.active=dev" 的快捷方式，详情请参见指定激活的配置文件。

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

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

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

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

spring.devtools.remote.restart.enabled=false
properties

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

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

当启用 addResources 时，任何 src/main/resources 目录将在运行应用程序时被添加到应用程序的类路径中，并且在类输出中找到的任何重复项将被移除。这使得资源的热刷新成为可能，这在开发 Web 应用程序时非常有用。例如，你可以处理 HTML、CSS 或 JavaScript 文件，并立即看到你的更改，而无需重新编译应用程序。这也是让前端开发人员无需下载和安装 Java IDE 即可工作的有用方式。

备注

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

为了与 repackage 目标保持一致，run 目标在构建类路径时会排除插件配置中指定的任何依赖项。更多详细信息，请参阅专用示例。

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

spring-boot:run​

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

在本地运行应用程序。

必填参数​

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

可选参数​

参数详情​

addResources​

直接将 Maven 资源添加到类路径中，这样可以实现资源的实时就地编辑。重复的资源会从 target/classes 中移除，以防止在调用 ClassLoader.getResources() 时它们出现两次。请考虑将 spring-boot-devtools 添加到您的项目中，因为它不仅提供了此功能，还提供了更多其他功能。

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

additionalClasspathElements​

应该添加到类路径中的额外类路径元素。一个元素可以是包含类和资源的目录或一个 jar 文件。

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

agents​

代理 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​

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

名称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​

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

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

mainClass​

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

NamemainClass
Typejava.lang.String
Default value
User propertyspring-boot.run.main-class
Since1.0.0

noverify​

表示代理需要 -noverify 的标志。

Namenoverify
Typeboolean
Default value
User propertyspring-boot.run.noverify
Since1.0.0

optimizedLaunch​

JVM 的启动是否需要优化。

NameoptimizedLaunch
Typeboolean
Default valuetrue
User propertyspring-boot.run.optimizedLaunch
Since2.2.0

profiles​

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

Nameprofiles
Typejava.lang.String[]
Default value
User propertyspring-boot.run.profiles
Since1.3.0

skip​

跳过执行。

Nameskip
Typeboolean
Default valuefalse
User propertyspring-boot.run.skip
Since1.3.2

systemPropertyVariables​

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

NamesystemPropertyVariables
Typejava.util.Map
Default value
User property
Since2.1.0

useTestClasspath​

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

NameuseTestClasspath
Typejava.lang.Boolean
Default valuefalse
User propertyspring-boot.run.useTestClasspath
Since1.3.0

workingDirectory​

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

NameworkingDirectory
Typejava.io.File
Default value
User propertyspring-boot.run.workingDirectory
Since1.5.0

spring-boot:test-run​

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

使用测试运行时类路径在本地运行一个应用程序。用于启动应用程序的主类按以下方式确定：首先使用已配置的主类（如果有）。然后使用在测试类目录中找到的主类（如果有）。最后使用在类目录中找到的主类（如果有）。

必填参数​

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

可选参数​

参数详情​

addResources​

直接将 Maven 资源添加到类路径中，这样可以实现对资源的实时就地编辑。重复的资源会从 target/classes 中移除，以防止在调用 ClassLoader.getResources() 时它们出现两次。建议您考虑在项目中添加 spring-boot-devtools，因为它提供了此功能以及更多其他功能。

NameaddResources
Typeboolean
Default valuefalse
User propertyspring-boot.run.addResources
Since1.0.0

additionalClasspathElements​

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

NameadditionalClasspathElements
Typejava.lang.String[]
Default value
User propertyspring-boot.run.additional-classpath-elements
Since3.2.0

agents​

代理 jar 包的路径。

Nameagents
Typejava.io.File[]
Default value
User propertyspring-boot.run.agents
Since2.2.0

arguments​

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

Namearguments
Typejava.lang.String[]
Default value
User property
Since1.0.0

classesDirectory​

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

NameclassesDirectory
Typejava.io.File
Default value${project.build.outputDirectory}
User property
Since1.0.0

commandlineArguments​

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

NamecommandlineArguments
Typejava.lang.String
Default value
User propertyspring-boot.run.arguments
Since2.2.3

environmentVariables​

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

NameenvironmentVariables
Typejava.util.Map
Default value
User property
Since2.1.0

excludeGroupIds​

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

NameexcludeGroupIds
Typejava.lang.String
Default value
User propertyspring-boot.excludeGroupIds
Since1.1.0

excludes​

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

Nameexcludes
Typejava.util.List
Default value
User propertyspring-boot.excludes
Since1.1.0

includes​

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

Nameincludes
Typejava.util.List
Default value
User propertyspring-boot.includes
Since1.2.0

jvmArguments​

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

NamejvmArguments
Typejava.lang.String
Default value
User propertyspring-boot.run.jvmArguments
Since1.1.0

mainClass​

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

NamemainClass
Typejava.lang.String
Default value
User propertyspring-boot.run.main-class
Since1.0.0

noverify​

标志表示代理需要 -noverify。

Namenoverify
Typeboolean
Default value
User propertyspring-boot.run.noverify
Since1.0.0

optimizedLaunch​

JVM 启动是否需要优化。

NameoptimizedLaunch
Typeboolean
Default valuetrue
User propertyspring-boot.test-run.optimizedLaunch
Since

profiles​

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

Nameprofiles
Typejava.lang.String[]
Default value
User propertyspring-boot.run.profiles
Since1.3.0

skip​

跳过执行。

Nameskip
Typeboolean
Default valuefalse
User propertyspring-boot.run.skip
Since1.3.2

systemPropertyVariables​

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

NamesystemPropertyVariables
Typejava.util.Map
Default value
User property
Since2.1.0

testClassesDirectory​

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

NametestClassesDirectory
Typejava.io.File
Default value${project.build.testOutputDirectory}
User property
Since

workingDirectory​

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

NameworkingDirectory
Typejava.io.File
Default value
User propertyspring-boot.run.workingDirectory
Since1.5.0

示例​

调试应用程序​

run 和 test-run 目标会在一个独立的进程中运行你的应用程序。如果你需要调试它，你应该添加必要的 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>
xml

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

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

使用系统属性​

系统属性可以通过 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>
xml

如果值为空或未定义（即 <my-property/>），则该系统属性的值将被设置为空字符串。Maven 会修剪在 pom 文件中指定的值，因此无法通过该机制指定需要以空格开头或结尾的系统属性：请考虑使用 jvmArguments 来代替。

任何字符串类型的 Maven 变量都可以作为系统属性传递。尝试传递任何其他类型的 Maven 变量（例如 List 或 URL 变量）将导致变量表达式按字面传递（未求值）。

jvmArguments 参数优先于通过上述机制定义的系统属性。在以下示例中，property1 的值被 overridden（覆盖）：

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

使用环境变量​

环境变量可以使用 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>
xml

如果值为空或未定义（即 <MY_ENV/>），环境变量将被设置为空字符串。Maven 会修剪在 pom 中指定的值，因此无法指定需要以空格开头或结尾的环境变量。

任何字符串类型的 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>
xml

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

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

指定活动配置文件​

特定应用程序使用的活动配置文件可以通过 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>
xml

可以在命令行上指定要启用的配置文件，确保用逗号分隔它们，如下例所示：

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