Spring Boot Maven 项目 pom.xml 插件用法全整理（2026企业级实战版）

Java程序员威哥

81人浏览 · 2026-03-20 08:03:01

Java程序员威哥 · 2026-03-20 08:03:01 发布

覆盖99%高频使用插件：Spring Boot官方核心插件、编译/资源/测试/打包基础插件、MyBatis逆向/Docker构建/代码覆盖率进阶插件
每个插件配实战配置+参数详解+避坑指南，新手看完就能用，老手看完能避坑

开篇：Maven插件的“痛”与“通”

做Spring Boot开发的同学一定遇到过：

打包后运行报错：no main manifest attribute；
编译版本不对：项目用JDK17，插件默认JDK8；
资源文件变量没替换：application.yml中的${project.version}没生效；
不知道用什么插件：MyBatis逆向生成、Docker镜像构建、代码覆盖率怎么配？

本文把Spring Boot项目中高频使用的Maven插件按场景分类，从核心插件→基础插件→进阶插件，一次性讲透所有配置，配实战代码+避坑指南，让你彻底“通”透Maven插件！

一、核心插件（Spring Boot项目必备）

1.1 spring-boot-maven-plugin（最核心，官方插件）

作用

Spring Boot官方核心打包/运行插件，一键实现：

打可执行jar/war包（内置Tomcat，直接java -jar运行）；
本地运行Spring Boot项目（mvn spring-boot:run）；
构建Docker镜像（可选）；
排除内置依赖（如打war包时排除Tomcat）。

实战配置（直接复制到pom.xml）

<build>
    <plugins>
        <!-- Spring Boot官方核心插件 -->
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <version>3.3.0</version> <!-- 必须和Spring Boot版本一致！ -->
            <executions>
                <execution>
                    <goals>
                        <goal>repackage</goal> <!-- 打包成可执行jar -->
                    </goals>
                </execution>
            </executions>
            <configuration>
                <!-- 1. 指定启动类（可选，默认自动找带@SpringBootApplication的类） -->
                <mainClass>com.example.demo.DemoApplication</mainClass>
                <!-- 2. 打包时排除内置Tomcat（打war包时用，可选） -->
                <!--
                <excludes>
                    <exclude>
                        <groupId>org.springframework.boot</groupId>
                        <artifactId>spring-boot-starter-tomcat</artifactId>
                    </exclude>
                </excludes>
                -->
                <!-- 3. 打包时包含系统依赖（可选） -->
                <includeSystemScope>true</includeSystemScope>
            </configuration>
        </plugin>
    </plugins>
</build>

参数详解

version：必须和Spring Boot版本完全一致，否则报错；
repackage：核心goal，将普通jar重新打包成可执行jar；
mainClass：指定启动类，默认自动扫描，多启动类时必须指定；
excludes：排除内置依赖，打war包时排除Tomcat。

常用命令

# 1. 打包成可执行jar
mvn clean package
# 2. 本地运行Spring Boot项目
mvn spring-boot:run
# 3. 跳过测试打包
mvn clean package -DskipTests

避坑

版本必须匹配：Spring Boot 3.3.0对应插件版本3.3.0，不能乱改；
找不到主类：检查启动类是否在scanBasePackages范围内，或手动指定mainClass；
打war包：必须排除内置Tomcat，同时修改<packaging>war</packaging>。

二、基础插件（所有Maven项目通用）

2.1 maven-compiler-plugin（编译插件，必配）

作用

指定JDK编译版本，解决项目JDK版本和插件默认版本不一致的问题。

实战配置

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.13.0</version>
    <configuration>
        <!-- 1. 源代码JDK版本 -->
        <source>17</source>
        <!-- 2. 目标字节码JDK版本 -->
        <target>17</target>
        <!-- 3. 编码格式（必配，防止中文乱码） -->
        <encoding>UTF-8</encoding>
        <!-- 4. 启用预览特性（可选，JDK17+用） -->
        <compilerArgs>
            <arg>--enable-preview</arg>
        </compilerArgs>
    </configuration>
</plugin>

避坑

source和target必须和项目JDK版本一致，否则报错；
必须加<encoding>UTF-8</encoding>，否则中文注释/字符串会乱码。

2.2 maven-resources-plugin（资源文件处理插件）

作用

处理src/main/resources下的资源文件，支持变量替换（如${project.version}替换为项目版本）。

实战配置

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <version>3.3.1</version>
    <configuration>
        <encoding>UTF-8</encoding>
        <!-- 开启资源文件变量替换 -->
        <useDefaultDelimiters>true</useDefaultDelimiters>
    </configuration>
    <!-- 配置需要处理的资源文件 -->
    <executions>
        <execution>
            <id>copy-resources</id>
            <phase>process-resources</phase>
            <goals>
                <goal>copy-resources</goal>
            </goals>
            <configuration>
                <outputDirectory>${project.build.outputDirectory}</outputDirectory>
                <resources>
                    <resource>
                        <directory>src/main/resources</directory>
                        <filtering>true</filtering> <!-- 开启过滤，替换变量 -->
                        <includes>
                            <include>application*.yml</include>
                            <include>application*.properties</include>
                        </includes>
                    </resource>
                </resources>
            </configuration>
        </execution>
    </executions>
</plugin>

变量替换示例

# application.yml
app:
  name: ${project.name}
  version: ${project.version}

打包后会自动替换为：

app:
  name: demo
  version: 1.0.0

2.3 maven-surefire-plugin（单元测试插件）

作用

执行src/test/java下的单元测试，生成测试报告。

实战配置

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.2.5</version>
    <configuration>
        <!-- 1. 跳过测试（可选，生产环境不建议） -->
        <!-- <skipTests>true</skipTests> -->
        <!-- 2. 指定测试类（可选） -->
        <includes>
            <include>**/*Test.java</include>
        </includes>
        <!-- 3. 排除测试类（可选） -->
        <excludes>
            <exclude>**/*IntegrationTest.java</exclude>
        </excludes>
    </configuration>
</plugin>

常用命令

# 执行所有单元测试
mvn test
# 跳过测试打包
mvn clean package -DskipTests

2.4 maven-jar-plugin（打普通jar包）

作用

打普通jar包（非Spring Boot可执行jar），一般用于第三方依赖。

实战配置

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <version>3.4.2</version>
    <configuration>
        <!-- 指定普通jar的主类（可选） -->
        <archive>
            <manifest>
                <mainClass>com.example.demo.MyMainClass</mainClass>
            </manifest>
        </archive>
    </configuration>
</plugin>

2.5 maven-war-plugin（打war包）

作用

打war包，部署到外部Tomcat。

实战配置

<packaging>war</packaging> <!-- 首先修改packaging为war -->

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-war-plugin</artifactId>
    <version>3.4.0</version>
    <configuration>
        <!-- 1. war包名称（可选） -->
        <warName>demo</warName>
        <!-- 2. 排除web.xml（Spring Boot项目可选，因为用嵌入式Tomcat） -->
        <failOnMissingWebXml>false</failOnMissingWebXml>
    </configuration>
</plugin>

三、进阶插件（企业级开发常用）

3.1 mybatis-generator-maven-plugin（MyBatis逆向生成插件）

作用

根据数据库表自动生成Entity、Mapper接口、Mapper XML文件，告别手写CRUD！

实战配置

<plugin>
    <groupId>org.mybatis.generator</groupId>
    <artifactId>mybatis-generator-maven-plugin</artifactId>
    <version>1.4.2</version>
    <configuration>
        <!-- 1. 指定generatorConfig.xml配置文件路径 -->
        <configurationFile>src/main/resources/generatorConfig.xml</configurationFile>
        <!-- 2. 允许覆盖生成的文件 -->
        <overwrite>true</overwrite>
        <!-- 3. 输出详细日志 -->
        <verbose>true</verbose>
    </configuration>
    <dependencies>
        <!-- 数据库驱动（必须加，否则找不到驱动） -->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <version>8.3.0</version>
        </dependency>
        <!-- MyBatis Generator核心依赖 -->
        <dependency>
            <groupId>org.mybatis.generator</groupId>
            <artifactId>mybatis-generator-core</artifactId>
            <version>1.4.2</version>
        </dependency>
    </dependencies>
</plugin>

配套generatorConfig.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE generatorConfiguration
        PUBLIC "-//mybatis.org//DTD MyBatis Generator Configuration 1.0//EN"
        "http://mybatis.org/dtd/mybatis-generator-config_1_0.dtd">
<generatorConfiguration>
    <!-- 数据库连接配置 -->
    <context id="MySqlContext" targetRuntime="MyBatis3">
        <jdbcConnection driverClass="com.mysql.cj.jdbc.Driver"
                        connectionURL="jdbc:mysql://localhost:3306/demo?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai"
                        userId="root"
                        password="123456">
        </jdbcConnection>

        <!-- Entity生成位置 -->
        <javaModelGenerator targetPackage="com.example.demo.entity" targetProject="src/main/java">
            <property name="enableSubPackages" value="true"/>
            <property name="trimStrings" value="true"/>
        </javaModelGenerator>

        <!-- Mapper XML生成位置 -->
        <sqlMapGenerator targetPackage="mapper" targetProject="src/main/resources">
            <property name="enableSubPackages" value="true"/>
        </sqlMapGenerator>

        <!-- Mapper接口生成位置 -->
        <javaClientGenerator type="XMLMAPPER" targetPackage="com.example.demo.mapper" targetProject="src/main/java">
            <property name="enableSubPackages" value="true"/>
        </javaClientGenerator>

        <!-- 指定要生成的表 -->
        <table tableName="user" domainObjectName="User" enableCountByExample="false" enableUpdateByExample="false" enableDeleteByExample="false" enableSelectByExample="false" selectByExampleQueryId="false"/>
    </context>
</generatorConfiguration>

常用命令

# 执行逆向生成
mvn mybatis-generator:generate

避坑

必须加数据库驱动依赖，否则报错找不到驱动；
overwrite设为true会覆盖原有文件，注意备份。

3.2 docker-maven-plugin（Docker镜像构建插件）

作用

一键构建Docker镜像，推送到镜像仓库，告别手动写Dockerfile！

实战配置

<plugin>
    <groupId>com.spotify</groupId>
    <artifactId>docker-maven-plugin</artifactId>
    <version>1.2.2</version>
    <configuration>
        <!-- 1. 镜像名称 -->
        <imageName>demo/${project.artifactId}:${project.version}</imageName>
        <!-- 2. Dockerfile路径（可选，也可以用inline配置） -->
        <dockerDirectory>src/main/docker</dockerDirectory>
        <!-- 3. 构建参数 -->
        <resources>
            <resource>
                <targetPath>/</targetPath>
                <directory>${project.build.directory}</directory>
                <include>${project.build.finalName}.jar</include>
            </resource>
        </resources>
        <!-- 4. 推送到镜像仓库（可选） -->
        <!--
        <serverId>docker-hub</serverId>
        <registryUrl>https://registry.hub.docker.com</registryUrl>
        <pushImage>true</pushImage>
        -->
    </configuration>
</plugin>

常用命令

# 构建Docker镜像
mvn clean package docker:build
# 构建并推送镜像
mvn clean package docker:build docker:push

3.3 jacoco-maven-plugin（代码覆盖率插件）

作用

统计单元测试的代码覆盖率，生成覆盖率报告。

实战配置

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.12</version>
    <executions>
        <execution>
            <id>jacoco-initialize</id>
            <goals>
                <goal>prepare-agent</goal>
            </goals>
        </execution>
        <execution>
            <id>jacoco-report</id>
            <phase>test</phase>
            <goals>
                <goal>report</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <!-- 覆盖率阈值（可选，低于阈值报错） -->
        <rules>
            <rule>
                <element>PACKAGE</element>
                <limits>
                    <limit>
                        <counter>LINE</counter>
                        <value>COVEREDRATIO</value>
                        <minimum>0.8</minimum> <!-- 要求行覆盖率≥80% -->
                    </limit>
                </limits>
            </rule>
        </rules>
    </configuration>
</plugin>

常用命令

# 执行测试并生成覆盖率报告
mvn clean test jacoco:report
# 报告位置：target/site/jacoco/index.html

3.4 versions-maven-plugin（依赖版本检查插件）

作用

检查项目依赖和插件的最新版本，自动升级版本。

实战配置

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>versions-maven-plugin</artifactId>
    <version>2.17.1</version>
    <configuration>
        <!-- 允许升级到稳定版本 -->
        <allowSnapshots>false</allowSnapshots>
    </configuration>
</plugin>

常用命令

# 检查所有依赖和插件的最新版本
mvn versions:display-dependency-updates
mvn versions:display-plugin-updates
# 自动升级到最新稳定版本
mvn versions:use-latest-versions

3.5 git-commit-id-plugin（Git提交信息插件）

作用

将Git提交信息（提交ID、时间、分支）生成到git.properties文件，方便排查问题。

实战配置

<plugin>
    <groupId>pl.project13.maven</groupId>
    <artifactId>git-commit-id-plugin</artifactId>
    <version>4.9.10</version>
    <executions>
        <execution>
            <goals>
                <goal>revision</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <!-- 生成git.properties到target/classes -->
        <generateGitPropertiesFile>true</generateGitPropertiesFile>
        <generateGitPropertiesFilename>${project.build.outputDirectory}/git.properties</generateGitPropertiesFilename>
    </configuration>
</plugin>

四、高频避坑总结（必看）

spring-boot-maven-plugin版本不匹配：必须和Spring Boot版本完全一致；
编译版本不对：maven-compiler-plugin的source/target必须和项目JDK一致；
中文乱码：必须加<encoding>UTF-8</encoding>到编译和资源插件；
找不到主类：检查启动类位置，或手动指定mainClass；
MyBatis逆向生成找不到驱动：必须在插件依赖中加数据库驱动；
资源文件变量没替换：maven-resources-plugin必须开启<filtering>true</filtering>。

五、高频插件速查表

插件	作用	核心goal
spring-boot-maven-plugin	Spring Boot打包/运行	repackage, run
maven-compiler-plugin	指定JDK编译版本	compile
maven-resources-plugin	处理资源文件/变量替换	resources
maven-surefire-plugin	单元测试	test
mybatis-generator-maven-plugin	MyBatis逆向生成	generate
docker-maven-plugin	构建Docker镜像	build, push
jacoco-maven-plugin	代码覆盖率	prepare-agent, report