SpringBoot Maven 项目插件配置与构建链路优化实践

前阵子接手一个跑了好几年的 SpringBoot Maven 项目，打开根 pom.xml 一看，plugins 节点下密密麻麻躺着一二十个插件，有的明显是从别的项目复制过来的，连注释都写着别人的团队名。构建一次将近三分钟，CI 上偶尔飘红，团队里没人能说清每个 plugin 到底在干什么。这轮我把整个 build 链路从 clean 到 deploy 完整梳理了一遍，整理出一份可以照着用的 plugin 配置清单。

你如果也在维护 SpringBoot Maven 项目，或者刚接触 pom 里那段 <plugins>，这篇文章就是给你写的。它不会复述 Maven 官方文档，而是告诉你一个真实项目里哪些插件值得留下、每个插件该配什么参数、哪些配置是"照抄了但不知道为什么要抄"。文章会从插件运行机制、核心插件逐项拆解、辅助插件、继承与版本管理，最后用一次实测排查案例讲清楚"插件执行顺序导致的打包事故"。

1. 先搞清底层运行机制：生命周期、阶段与插件目标的三角关系

1.1 生命周期只是时间轴，插件目标才是干活的

很多刚接触 Maven 的人容易把 pom 里配的插件理解成"一个独立的程序"，比如觉得 spring-boot-maven-plugin 就是用来打 jar 的。这个理解不算错，但有一个更准确的说法：Maven 本身只提供了三套生命周期和时间轴——clean、default、site，clean 负责清理，default 负责从编译到部署的全部构建过程，site 负责生成项目站点。而生命周期本身不干任何活，它只是一个编排好的顺序列表。

真正执行动作的是绑定到"生命周期阶段"上的插件目标。一个插件可以包含多个 goal，例如 spring-boot-maven-plugin 有 repackage、run、build-image 等多个目标；maven-compiler-plugin 有 compile、testCompile 等目标。你在 pom 里看到类似下面的配置时：

xml复制<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>

它的含义不是"把插件加到项目里"，而是"在 default 生命周期的 package 阶段执行 repackage 这个目标"。execution 标签里的 goals 决定执行哪个目标，phase 如果不写，则使用该目标默认绑定的阶段，repackage 默认就绑定在 package 阶段。

理解这层关系后，你就能解释很多怪现象。比如为什么明明 pom 里没有显式执行 maven-compiler-plugin，compile 阶段依然能编译？因为 Maven 在 default 生命周期里为 compile、test、package 等阶段预绑定了默认插件，你什么都不配，构建也能跑。显式声明插件通常是为了覆盖默认参数、调整版本，或者绑定额外的目标。

1.2 三类常见声明位置，以及命令行直接调用的场景

插件在 pom 里的声明位置其实有讲究。最常用的是 <build><plugins> 直接声明，它会跟着当前项目在对应的生命周期阶段执行。第二种是放在 <build><pluginManagement> 里，它只声明配置和版本，不实际执行，等子模块在 <plugins> 里真正引入时才生效。第三种是放在父 pom 的 <build><plugins> 里，让所有继承的子模块都执行。

命令行直接调用是另一个入口，例如：

bash复制mvn dependency:tree
mvn spring-boot:run
mvn compiler:compile

这种用法不依赖 pom 里的 plugin 声明，Maven 会临时解析对应版本的插件并执行。它适合排查问题、临时验证目标，但不适合作为项目构建的固定流程，因为你在命令行指定的插件版本可能和 pom 里不一致，导致验证结果失真。我习惯先跑 mvn help:effective-pom 看合并后的完整配置文件，再决定要不要用命令行直接调目标。

2. 构建链路上的核心插件：编译、测试与打包的配置逐个拆

2.1 编译：maven-compiler-plugin 的几个关键参数

SpringBoot 项目的编译配置几乎离不开 maven-compiler-plugin。虽然不配也能编译，但 Java 版本、编码、注解处理器这几个点不控制好，迟早出乱子。一个比较完整的配置长这样：

xml复制<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <version>3.13.0</version>
  <configuration>
    <release>17</release>
    <encoding>UTF-8</encoding>
    <parameters>true</parameters>
  </configuration>
</plugin>

这里重点说三个参数。第一是 release，我推荐直接用 release 而不是 source/target。source 和 target 只告诉编译器接受哪个版本的源码语法、生成哪个版本的字节码，但编译器还是拿着 JDK 17 的类库来编译，容易编出在低版本跑不了的产物；release 连 JDK 公共 API 都限制在指定版本内，SpringBoot 3.x 要求 Java 17 起步，配 release 是更稳妥的做法。

第二是 encoding，不配的情况下 Maven 可能用系统默认字符集，在中文 Windows 环境下编译带中文字符串的代码会出现乱码，CI 服务器和本地环境不一致时，同样的代码在不同机器上编出的结果可能不一样，这类问题排查起来很耗时。第三是 parameters，这个参数会保留方法参数名，Spring MVC 在接 POST 表单参数、Spring Boot 在读取配置绑定时都依赖它，Java 8 之后加了 -parameters 编译参数，Maven 里打开这个开关能避免一部分"参数名丢失导致的绑定失败"。

另外，如果你的项目用了 Lombok 或 MapStruct，建议把 annotationProcessorPaths 配上：

xml复制<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <annotationProcessorPaths>
      <path>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>${lombok.version}</version>
      </path>
      <path>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct-processor</artifactId>
        <version>${mapstruct.version}</version>
      </path>
    </annotationProcessorPaths>
  </configuration>
</plugin>

很多项目直接依赖 Lombok 就完事，不配置 annotationProcessorPaths，依赖里确实带上了 Lombok，但注解处理器是 Java 9 模块化之后被强制隔离的，不在 classpath 上扫描了，于是 local 能跑 CI 报错或者编译过了但 getter/setter 生成不出来。把这些处理器显式列出来，构建环境就和本地 IDE 环境一致了。

2.2 测试：surefire 与 failsafe 的分工

单元测试默认由 maven-surefire-plugin 执行，集成测试推荐用 maven-failsafe-plugin。这个名字看起来像"故障安全"，它的设计思路是：单测失败应该直接中断构建，而集成测试失败发生在打包之后，失败时允许保留产物用于排查。

surefire 的常用配置主要是控制测试类的匹配规则、是否跳过测试、内存参数：

xml复制<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>3.2.5</version>
  <configuration>
    <skipTests>false</skipTests>
    <includes>
      <include>**/*Test.java</include>
      <include>**/*Tests.java</include>
    </includes>
    <argLine>-Xmx1g</argLine>
  </configuration>
</plugin>

这里最容易踩的坑是跳过测试的方式。-DskipTests 只跳过执行，测试类还是会编译，编译错误照样暴露出来；而 -Dmaven.test.skip=true 连测试编译都跳过，适合临时快速打包验证，但不建议长期用，因为等于把测试代码和测试依赖全屏蔽了，下次直接开测时会有一堆编译问题需要重新处理。

我自己的习惯是：本地开发用 mvn install -DskipTests 快速跳过执行，CI 流程里跑全量测试，发布前再用 mvn verify 跑一次完整的，failsafe 的集成测试绑在 integration-test 阶段，跟 surefire 错开，分工明确。

2.3 打包：spring-boot-maven-plugin 的 repackage 是绝对主角

这是 SpringBoot 项目里最不缺的一个插件，但它值得多说两句，因为它的机制影响了整个产物的结构。spring-boot-maven-plugin 的 repackage 目标会把项目打成一个可执行 fat jar，里面按照 BOOT-INF/classes、BOOT-INF/lib、org/springframework/boot/loader 三层结构组织，启动类不再是你项目里的 main 类，而是 Spring Boot 的 JarLauncher。

配置如下：

xml复制<plugin>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-maven-plugin</artifactId>
  <configuration>
    <mainClass>${start-class}</mainClass>
    <layers>
      <enabled>true</enabled>
    </layers>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>repackage</goal>
      </goals>
    </execution>
  </executions>
</plugin>

mainClass 也可以不写，Spring Boot 会从编译产物里自动找，但项目里有多个 main 类时它会报错或选错，显式写出来最省心。layers 是 Spring Boot 2.3 之后引入的分层特性，配合 Dockerfile 可以实现"只把业务代码层发到镜像，依赖层利用构建缓存"，对镜像体积和构建速度都有帮助，2.3 之后的版本建议直接打开。

还有一个容易踩的细节：repackage 默认会替换原来的普通 jar，原产物会保留为 .original 后缀。如果你还配了 maven-jar-plugin 或者 assembly 插件，它们生成的也是同一个 target 路径下的同名 jar，先后顺序会互相覆盖，这个坑我在第 5 部分会展开讲。

2.4 用 maven-assembly-plugin 和 dependency-plugin 的注意点

不是所有项目都适合用 boot 的 fat jar。有些交付场景要求把依赖打成单独的 lib 目录，方便替换某个第三方 jar 或者做外置依赖管理。这时候常见的是 maven-dependency-plugin 的 copy-dependencies 目标：

xml复制<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <executions>
    <execution>
      <id>copy-dependencies</id>
      <phase>package</phase>
      <goals>
        <goal>copy-dependencies</goal>
      </goals>
      <configuration>
        <outputDirectory>${project.build.directory}/lib</outputDirectory>
        <includeScope>runtime</includeScope>
      </configuration>
    </execution>
  </executions>
</plugin>

这个插件把依赖 jar 复制到指定目录，includeScope 控制复制范围，一般 runtime 就够了，test 和 provided 依赖在运行时不出现，复制进来反而会带来版本冲突。outputDirectory 我习惯放在 target 下，不要在项目目录里新建 lib 目录，否则容易被当作源码提交进仓库。

如果你确实需要把依赖的 class 全部展开并和项目 class 打进同一个 jar，那就用 maven-assembly-plugin 的 jar-with-dependencies：

xml复制<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-assembly-plugin</artifactId>
  <configuration>
    <descriptorRefs>
      <descriptorRef>jar-with-dependencies</descriptorRef>
    </descriptorRefs>
    <archive>
      <manifest>
        <mainClass>com.example.Application</mainClass>
      </manifest>
    </archive>
  </configuration>
  <executions>
    <execution>
      <id>make-assembly</id>
      <phase>package</phase>
      <goals>
        <goal>single</goal>
      </goals>
    </execution>
  </executions>
</plugin>

但是我要提前给个醒：SpringBoot 项目里，assembly 的 jar-with-dependencies 和 spring-boot-maven-plugin 的 repackage 本质上是冲突的。两个插件都会在 package 阶段重写同一个最终产物，后者会把前者打好的 fat jar 再套一层 Boot 结构，结果经常是启动时找不到主类或者类重复加载。如果你已经用了 spring-boot-maven-plugin，就不要再加 jar-with-dependencies；反过来，如果你要用 assembly 做全量依赖 jar，那就别用 boot 的 repackage，用普通 jar 启动器或者自己写启动脚本。

3. 容易被忽略的辅助插件：版本信息、覆盖率与环境校验

3.1 给运维看版本：git-commit-id-maven-plugin

生产环境上排查问题时，最怕的就是"这个 jar 对应哪个 commit"。特别是多环境多版本并行发布时，代码版本对不上，问题定位就无从谈起。git-commit-id-maven-plugin 会在构建时把当前 Git 仓库的 commit id、分支、构建时间等写入 git.properties 文件，Spring Boot 的 Actuator 会自动读取并暴露在 /actuator/info 接口里。

xml复制<plugin>
  <groupId>io.github.git-commit-id</groupId>
  <artifactId>git-commit-id-maven-plugin</artifactId>
  <version>9.0.1</version>
  <executions>
    <execution>
      <id>get-the-git-infos</id>
      <goals>
        <goal>revision</goal>
      </goals>
      <phase>initialize</phase>
    </execution>
  </executions>
  <configuration>
    <generateGitPropertiesFile>true</generateGitPropertiesFile>
    <generateGitPropertiesFilename>${project.build.outputDirectory}/git.properties</generateGitPropertiesFilename>
    <failOnNoGitDirectory>false</failOnNoGitDirectory>
  </configuration>
</plugin>

我把 failOnNoGitDirectory 设为 false，是因为有些构建场景（比如从压缩包发布）没有 Git 元数据，直接失败会让发布流程卡住。生成的结果可以在运维平台或监控系统里拉取，排查问题时一个接口就能看到线上跑的到底是哪个 commit，这个信息在故障复盘里价值很大。

3.2 测试覆盖率的字节码插桩

如果想在 CI 上收集单测覆盖率，jacoco-maven-plugin 是事实标准。它的准备阶段给测试 JVM 加一个 javaagent，在类加载时动态插桩，记录每个分支的执行情况，然后生成 HTML/XML 报告。

xml复制<plugin>
  <groupId>org.jacoco</groupId>
  <artifactId>jacoco-maven-plugin</artifactId>
  <version>0.8.12</version>
  <executions>
    <execution>
      <goals>
        <goal>prepare-agent</goal>
      </goals>
    </execution>
    <execution>
      <id>report</id>
      <phase>verify</phase>
      <goals>
        <goal>report</goal>
      </goals>
    </execution>
  </executions>
</plugin>

需要注意两点。一是 jacoco 版本要跟项目用的 Java 版本匹配，Java 17 及以上要用 0.8.8 之后的版本，否则插桩会报 Java class version 不支持。二是如果项目里已经配置了 surefire 的 argLine 或者 fork 参数，jacoco 的 agent 参数容易被覆盖掉，导致覆盖率始终显示 0，这时需要把 jacoco 的 agent 参数合并进 argLine，或者放到一个. 配置文件里统一管理。

3.3 环境校验与发布配套

maven-enforcer-plugin 可以在构建早期强制校验环境，比如 Maven 版本、JDK 版本、操作系统禁止项。它很适合放在公司统一 parent pom 的 pluginManagement 里：

xml复制<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-enforcer-plugin</artifactId>
  <version>3.5.0</version>
  <executions>
    <execution>
      <id>enforce-maven</id>
      <goals>
        <goal>enforce</goal>
      </goals>
      <configuration>
        <rules>
          <requireMavenVersion>
            <version>3.8</version>
          </requireMavenVersion>
          <requireJavaVersion>
            <version>17</version>
          </requireJavaVersion>
        </rules>
      </configuration>
    </execution>
  </executions>
</plugin>

这样配置之后，即使有人本地用的是旧版 Maven 或者 JDK 11，构建会在编译之前直接报错退出，而不是等编译时抛出一堆看不懂的 warning 和语法错误。错误信息提前到环境阶段消化，能省下大量排查时间。

发布配套方面，maven-source-plugin 用来生成 sources jar：

xml复制<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-source-plugin</artifactId>
  <executions>
    <execution>
      <id>attach-sources</id>
      <phase>verify</phase>
      <goals>
        <goal>jar-no-fork</goal>
      </goals>
    </execution>
  </executions>
</plugin>

jar-no-fork 不会触发新的生命周期，单纯把源码打成 jar 附到产物上。如果你要把 jar 传到公司内部仓库供其他团队用，源码包对使用方调试非常有帮助。同理，maven-javadoc-plugin 可以生成 doc jar，但 javadoc 编译严格时，代码里一点不规范都会被卡住，反而影响发布，建议在内部仓库场景下要么规范好注释，要么只在发布公共组件时启用。

4. 继承体系下的 plugin 管理：parent、pluginManagement 与作用域

4.1 plugins 与 pluginManagement 的本质区别

这个区别很多人一开始会绕晕。简单说：

• <build><plugins> 声明的是"立即生效"的插件，子模块会继承并执行。
• <build><pluginManagement> 声明的是"备选配置库"，它自己不会执行任何目标，等某个模块在 <plugins> 里引用了同一个 groupId/artifactId 时，才把配置合并进去。

pluginManagement 最适合统一管理插件版本和公共参数。比如公司内部要求所有子模块都用同一版 compiler 插件、同一套测试配置，就放在父 pom 的 pluginManagement 里；某个模块不需要这套配置，只要不引用对应的 plugin 就行。

这里我经常看到的问题，是把不需要执行的插件直接放在父 pom 的 <build><plugins> 里，导致每个子模块都执行一遍。比如在父 pom 里直接放 jacoco 的 prepare-agent 和 report，结果所有子模块跑一遍报告，构建时间从一分钟拖到五分钟，还产生一堆多余的 target/site 目录。正确做法是：插件要不要默认执行，取决于它是不是全模块通用的；不确定的，一律先放 pluginManagement。

4.2 继承 starter-parent 之后，哪些插件版本不用写

大部分 SpringBoot 项目会继承 spring-boot-starter-parent，这个 parent 内部有两层配置：一是 dependencyManagement 管理了大量依赖的版本，二是 pluginManagement 管理了一批插件的版本和默认参数。下面这些插件的版本号在继承之后通常不需要你再写：

• spring-boot-maven-plugin
• maven-compiler-plugin
• maven-surefire-plugin
• maven-jar-plugin
• maven-resources-plugin
• maven-clean-plugin

特别是 spring-boot-maven-plugin，它的版本和 Spring Boot 版本是绑定的，如果自己写了一个不匹配的版本，repackage 时可能生成错误格式的 jar。继承 starter-parent 的情况下，直接不写版本最安全。

但要注意，starter-parent 只在它管理的插件列表里提供版本。如果你用了 maven-assembly-plugin、maven-dependency-plugin、jacoco、git-commit-id 等它没管的插件，这些版本就得自己写。不写版本意味着由 Maven 发行版决定默认插件版本，而 Maven 3.8 和 3.9 对同一插件的默认版本并不相同，换一台机器或者换 CI 镜像，构建行为就可能变。所以规则很简单：自定义引入的插件一律写版本，parent 已经管的插件不重复写。

4.3 多模块项目的插件声明边界

多模块项目里，插件声明的位置需要额外谨慎。父 pom 的 <build><plugins> 中配置的插件会被所有子模块继承执行。比如你希望只有 web 模块做 repackage，如果把它放在父 pom 里，那么 common、dal 模块也会尝试 repackage，打出来一堆不可执行的 jar，白白拖慢构建。

更合理的做法是：

• 父 pom 的 pluginManagement 放全项目统一的插件版本和参数；
• 需要每个模块都执行的插件（如 enforcer、source）才放父 pom 的 plugins；
• 只有特定模块要执行的插件（如 spring-boot-maven-plugin 的 repackage），放到对应子模块的 <build><plugins>。

另外，SpringBoot 项目还有一个常见配置：父 pom 里用 <properties> 定义 start-class，然后在子模块的 spring-boot-maven-plugin 里引用 ${start-class}。如果子模块没有显式指定 mainClass，repackage 又在父 pom 里执行，Maven 会因为找不到主类而采用编译产物的第一个 main 类，结果经常选错。我的建议是每个 SpringBoot 启动模块都在自己的 pom 里显式写上 mainClass，不依赖父级推断。

5. 一次插件执行顺序引发的打包事故：完整排查链路

5.1 事故现场：三重打包插件叠加的目标冲突

有一次同事报障，说项目打包之后，java -jar 启动时报 ClassNotFoundException: org.springframework.boot.loader.JarLauncher。他打开的 jar 是能正常用 java -cp 跑的老式结构，解压后看到 classes 直接在根目录，没有 BOOT-INF 目录。

我第一反应是 repackage 没跑，或者跑了又被覆盖了。去 target/ 目录看了一眼，发现同名 jar 在构建过程中被写入了多次，还有一个 .original 文件。再往上翻 pom，问题就清楚了：pom 里同时配了三个打包相关插件——maven-jar-plugin 生成普通 jar、maven-assembly-plugin 配置了 jar-with-dependencies、spring-boot-maven-plugin 配置了 repackage。这三个插件全都默认绑定在 package 阶段。

Maven 在同一个生命周期阶段内有多个插件的执行顺序，按照 pom 里声明的先后顺序（父 pom 合并之后）执行。这个项目的顺序是：jar → assembly → repackage。也就是普通 jar 先生成，assembly 覆盖成含依赖的 fat jar，repackage 再把这个 fat jar 进行字节码层面的二次包装。结果 Boot 启动器期望的内部结构已经被 assembly 改变了，repackage 无法正确生成 BOOT-INF，最终产物就成了一个"半 Boot 结构"的坏 jar。

5.2 用 effective-pom 和 describe 一步步定位

当时我的定位链路可以完整记下来，你也可以照着操作。

第一步，查看最终生效的合并配置，确认插件顺序和参数到底是谁覆盖了谁：

bash复制mvn help:effective-pom -Doutput=effective-pom.xml

打开 effective-pom.xml，能直接看到所有父 pom 合并后的 plugins 列表和 executions。比肉眼翻 parent 和子 pom 快得多。当时发现 assembly 和 repackage 的 execution 都绑定在 package 阶段，且顺序是 assembly 在前、repackage 在后。

第二步，用 describe 命令看插件的默认绑定阶段，确认问题是否出在"默认绑定"上：

bash复制mvn help:describe -Dplugin=org.apache.maven.plugins:maven-assembly-plugin -Ddetail

输出里可以看到 single 目标的默认阶段、参数要求，这一步能确认 assembly 确实默认在 package 执行，也就是不需要额外配置 phase 它也会跑。

第三步，打开 target 目录对比构建中间产物，确认哪些文件被覆盖：

bash复制ls -lah target/

最终发现除了 .original 之外，还有一个 original-xxx.jar 或者类似命名的备份文件，加上测试 jar，一堆同名文件混在一起，无法直接判断最终可执行的是哪个。再用 jar tf 看最后产物的内部结构，确认没有 BOOT-INF，问题坐实。

5.3 修复与预防

修复方案要根据交付场景来选。如果确定要的是 SpringBoot 可执行 jar，那么把 maven-assembly-plugin 整个去掉，保留 spring-boot-maven-plugin 的 repackage 就够了，SpringBoot 的 fat jar 已经把依赖全部带上了。如果交付场景明确要求"依赖外置、分离部署"，那就去掉 repackage，保留 assembly 的 jar-with-dependencies 或者用 dependency-plugin 复制依赖到 lib 目录，配合自定义启动脚本。

我的选择是去掉 assembly，保留 repackage，同时在 pom 里给 spring-boot-maven-plugin 显式加上 mainClass，避免以后再被选择困难症困扰。这个改动之后，构建时间也明显降下来了，因为 assembly 的 jar-with-dependencies 在合并依赖时开销很大，每次打包都要把几十个依赖的 class 全部解压合并，耗时占比很高。

之后我在项目里加了一个预防动作：在 CI 脚本里对最终产物做一次结构校验，用 jar tf 检查是否存在 BOOT-INF/classes 和 BOOT-INF/lib，没有就直接失败。这个步骤成本低，但能避免"打包成功但产物没法跑"这种最尴尬的线上事故。

另一个值得养成的习惯是：每次改动 pom 里的插件配置后，本地先跑一遍 mvn clean package 并实际启动一次，再推代码。插件配置的修改，尤其是打包链路上的调整，光看编译通过远远不够，产物能不能跑才是验收标准。整个排查过程给我最大的体会是：Maven 插件出问题时，先不要急着猜，先看 effective-pom，再确认插件的默认阶段和真正执行的目标，最后用产物结构来验证。这套链路不依赖高级工具，但能解决 90% 的插件配置类问题。