企业官网建设流程全解析

1. 从“能跑”到“精通”：SpringBoot Maven插件到底在做什么？

先抛一个问题：你有没有经历过这种场景——从网上粘了一段spring-boot-maven-plugin配置，然后mvn clean package一顿操作，盯着终端打出一行BUILD SUCCESS，就觉得自己“会了”？然后第二天换了个项目，加了个依赖，启动报No main manifest attribute，瞬间懵掉。

如果你点头了，这篇就是写给你的。

SpringBoot Maven插件远不止是“打包成JAR”这么简单。它本质上接管了“如何把一个SpringBoot应用变成一个可以独立运行、自带依赖、自带启动逻辑的产物”这件事。没有它，你用mvn package打出来的只是一个普通的、缺胳膊少腿的JAR——没有主类信息、没有依赖、没有任何自启动能力。而有了它，一个java -jar app.jar就能把整个应用拉起来，不用提前装Tomcat、不用手动配置classpath、不用写启动脚本。

这篇不聊那些网上人人都抄的demo，而是从插件的工作原理、关键配置、常见坑到实际部署场景，把spring-boot-maven-plugin扒一层皮，让你从“会粘贴”进化到“会思考”，遇到问题能自己定位、自己解决。

2. repackage的灵魂：可执行JAR是怎么“骗过”Java的

2.1 先看一段标准的插件配置，很多人第一行就理解错了

一个最常见的配置长这样：

<build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <version>2.7.18</version> <executions> <execution> <goals> <goal>repackage</goal> </goals> </execution> </executions> </plugin> </plugins> </build>

很多人看到<goal>repackage</goal>，第一反应是“哦，就是重新打包呗”。这么说没错，但这个“重新打包”不是把原来的JAR覆盖一遍这么简单。它的真实逻辑是：先执行项目的正常编译打包流程，拿到一个普通的JAR包，然后把这个普通JAR里塞进三样东西——项目本身的所有依赖（BOOT-INF/lib）、项目编译产物（BOOT-INF/classes）、一个引导类（org.springframework.boot.loader.Launcher）——最终生成一个新的、真正可执行的JAR。

也就是说，你mvn package之后target目录下产出的其实不止一个包。如果你留心看target下，会发现有一个.original结尾的文件——那是Maven原始打包的结果，repackage之后的可执行JAR是“二次加工”的产物。很多人第一次看到这个文件，还以为是程序出了问题，其实这是设计使然。

2.2 为什么不能直接依赖JVM解析classpath？——JarLauncher的盘算

这里有一个关键问题：普通的JAR，JVM靠Main-Class去找入口，依赖通过Class-Path声明去加载。但SpringBoot插件生成的JAR，依赖全部嵌套在BOOT-INF/lib里，这是一个JVM并不认识的结构——它不会自动去BOOT-INF/lib里找依赖。

所以插件在MANIFEST.MF里写了一个秘密：把Main-Class指向org.springframework.boot.loader.JarLauncher，真正的业务入口类（比如com.example.Application）被记录在Start-Class属性里。JarLauncher作为中间层，自定义了一套ClassLoader，专门用来从BOOT-INF/lib和BOOT-INF/classes里加载类。

所以整个启动链是：

java -jar app.jar -> JVM 加载 JarLauncher（MANIFEST里的 Main-Class） -> JarLauncher 启动自定义 ClassLoader -> ClassLoader 加载 BOOT-INF/classes 和 BOOT-INF/lib 里的类 -> 反射调用 Start-Class 里的 main() 方法

这就是为什么很多人在IDE里直接跑没有问题，但一打成JAR就报ClassNotFoundException或者NoClassDefFoundError——大概率是打包方式不对，导致了启动链路断裂。

2.3 Jar、War、分层：layout参数的隐形决策

插件还允许你通过<layout>参数指定打包结构，常见的有JAR、WAR、ZIP、DIR。默认情况下，项目是JAR工程就打JAR结构，是WAR工程就打WAR结构。

这里有个实际场景很值得注意：如果你的项目是WAR包，并且想部署到外部Tomcat容器里，你必须把repackage的<layout>显式声明为WAR，同时还要保证MANIFEST里有Main-Class对应的还是JarLauncher吗？

其实不是。War包如果要在外部容器中运行，就不需要JarLauncher了，这时候插件的repackage会自动判断，并生成一个兼容外部容器的WAR包结构。但如果你在WAR工程里忘了配置spring-boot-starter-tomcat的provided作用域，打出来的WAR包会把Tomcat也打包进去，部署到外部容器时就会出现一堆莫名其妙的冲突。

关于layout选择，我个人的经验是：绝大多数SpringBoot应用根本不需要手动指定layout，默认的JAR结构就够用。只有当你确定要部署到外部Servlet容器时，才有必要关心WAR layout的细节。别一开始就给自己加戏。

2.4 版本的隐性差异

spring-boot-maven-plugin的版本要和SpringBoot父POM（spring-boot-starter-parent）的版本严格对应。SpringBoot 1.x时代的插件和2.x时代行为差异很大，3.x时代又有变化。

比如SpringBoot 3.x中，JarLauncher被重构了，不再推荐直接使用老式org.springframework.boot.loader下的类路径加载方式；而且SpringBoot 3.x只支持Java 17以上。如果你的项目还在Java 8，别硬上3.x，老老实实用2.7.x。因为这个插件版本和JDK版本、SpringBoot版本是三位一体绑定的，任一个不一致，都会出现诡异报错。

这个点很多人栽过跟头——plugin版本看着没问题，Java版本也对，但就是启动报UnsupportedClassVersionError。多半是某个依赖是Java 8编译的，被塞进了一个Java 17构建的JAR里导致的。

3. 真正用得上的配置项：从被忽略到主动掌控

3.1 mainClass、classifier、excludes——三个高频操作

先明确一件事：多数场景下你不必配置mainClass，插件会从工程的源文件里自动找带main方法的类。但多模块项目中，插件可能找错或找不到，这时手动指定是必须的：

<configuration> <mainClass>com.example.MyApplication</mainClass> </configuration>

classifier的作用很多人不理解。它允许你在生成可执行JAR时，额外再保留一个普通JAR。比如同时生成app.jar（可执行版）和app-exec.jar（普通版），给其他模块做依赖引用时不至于引到不可执行的包。这种场景主要发生在被其他服务依赖时，或者需要单独把普通JAR上传到Maven仓库时。

excludes解决的问题是：有一些依赖在编译期需要，但运行时完全不应该出现在可执行包里，比如某些本地开发专用工具、测试框架或SPI实现。配置方式：

<configuration> <excludes> <exclude> <groupId>com.example</groupId> <artifactId>dev-tools</artifactId> </exclude> </excludes> </configuration>

这里要提醒一句：如果你把spring-boot-devtools这种运行时热加载工具排除掉，会导致本地热更新失效。一般devtools是开发时需要，但不应该在生成的可执行JAR里，因为它会让线上应用产生一些不可预测的行为（比如自动重启、远程调试端口）。所以这个排除操作其实是很推荐的做法。

3.2 分层构建：从“一个大JAR”进化为“分层JAR”

从SpringBoot 2.3开始，插件支持分层构建（Layered JAR）。这个概念对Docker部署场景极其重要。

默认一个SpringBoot应用打包后，就算一个CRUD项目也动不动就几十MB，其中超过一半是第三方依赖的JAR。如果你每次改一行代码，都要把整个几十MB的包推到服务器，再重新构建Docker镜像，那效率真的低到令人抓狂。分层的思路是把JAR内部按“稳定程度”分成多个层：依赖层（几乎不变）、资源层（偶尔变）、应用层（每次变）。Docker构建时利用层的缓存机制，只重新构建变化的那一层。

具体在Docker中使用分层JAR的方式是：

FROM openjdk:17-jdk-slim ARG DEPENDENCY=target/*.jar WORKDIR /app COPY ${DEPENDENCY} app.jar RUN java -Djarmode=layertools -jar app.jar extract COPY extracted/BOOT-INF/lib /app/lib COPY extracted/BOOT-INF/classes /app/classes COPY extracted/application /app/application ENTRYPOINT ["java", "-cp", "app:app/lib/*", "com.example.Application"]

这段Dockerfile利用-Djarmode=layertools -jar app.jar extract把分层JAR解压，然后再分步COPY到镜像里。这样依赖层在镜像里是固定的Layer，多次构建只有应用层变化，Docker的Layer Cache能大幅缩短CI构建时间。

实操下来这个特性真的能救命。之前一个项目用未分层方式构建Docker镜像，每次部署都要推到服务器上重传几十MB；改用分层之后，依赖层只在首次构建时全量COPY，之后每次可能只推几百KB的类文件，部署速度体感快了一个数量级。

3.3 跳过repackage的几种场景——不是所有项目都需要执行JAR

有一种情况，你的模块是一个纯粹的内部依赖模块，根本不打算独立运行（比如一个公共配置模块或者工具包）。这时候就不该配置repackage的execution。如果配置了，打出来的包会变成一个包含了所有依赖的大JAR，其他模块引用它时会发现重复依赖，或者Maven依赖解析时出现奇怪的冲突。

正确的做法有两种：一是直接不给该模块配置spring-boot-maven-plugin；二是配置了插件但把repackage的execution删掉，让插件只在需要时显式调用。

还有一种场景是项目里同时有普通应用模块和springboot应用模块，父POM里统一配了插件，子模块继承时想要“只打包不repackage”，需要这样处理：

<configuration> <skip>true</skip> </configuration>

把skip设为true，插件会直接跳过repackage目标，但其他目标仍然照常。这个开关如果你没见过，建议收藏起来，真的会遇到。

3.4 自定义配置的最终形态：一个多场景兼顾的范例

看一个相对完整的多环境配置示例：

<plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <executions> <execution> <goals> <goal>repackage</goal> </goals> </execution> </executions> <configuration> <mainClass>${start-class}</mainClass> <layout>ZIP</layout> <classifier>exec</classifier> <excludes> <exclude> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-devtools</artifactId> </exclude> </excludes> </configuration> </plugin>

这里的${start-class}可以在父POM的properties里统一设置为一个绝对正确的入口类，然后在子模块里覆盖。这样多模块工程里不会出现“类找不到”的问题。ZIPlayout则是适合解压部署的结构，它会把一切扁平化到一个目录下，对持续集成后的Docker构建更友好。

4. 实操全链路：从构建命令到疑难问题排查

4.1 命令行那些高频操作的正确姿势

先看最常见的几个。注意我下面要讲的是“姿势”，不只是命令本身。

mvn clean package

这个命令的一连串执行其实是：清理target目录 -> 编译 -> 执行测试（如果你没有跳过）-> 打JAR -> repackage生成可执行JAR。问题是测试常常会拖慢构建速度，而且有些测试在CI环境里根本没有意义。所以实际项目里我几乎总是敲：

mvn clean package -DskipTests

-DskipTests是编译但不跑测试的选项。但有的团队要求测试代码必须编译（至少语法要通过），用-Dmaven.test.skip=true才能连编译一起跳过。

再看install和package的区别：package只是生成JAR到target目录，install除了打包还会把产物安装到本地Maven仓库。多模块项目中，子模块之间依赖时，父模块必须用install安装到本地仓库，其他模块才能通过Maven坐标引用到。如果只用package，另一个模块一编译就会报找不到依赖。

命令行里还有一个容易被忽视的场景：多环境打包。比如你有application-dev.yml和application-prod.yml，打包时想指定环境变量，需要配合Maven的resource过滤：

<resources> <resource> <directory>src/main/resources</directory> <filtering>true</filtering> </resource> </resources>

然后构建时用-Dspring.profiles.active=prod或通过--spring.profiles.active参数在启动时覆盖。但是这里有个坑：如果你的配置里有$符号（比如自定义金额、邮箱模板），Maven的过滤会把$变量抢走导致配置损坏。这种情况建议把配置文件的目录分开，或者关闭那个特定目录的过滤。

4.2 实战：mvn spring-boot:run，它和java -jar有什么本质区别？

在本地开发时，另一个高频操作是：

mvn spring-boot:run

这个命令和java -jar的区别不在于“能不能跑起来”，而在于它用的classpath是不同的。spring-boot:run直接使用当前Maven依赖下的精确类路径，相当于在IDE里右键执行main方法。这种模式下不会触发repackaged的BOOT-INF/lib加载逻辑，所以偶尔会遇到一个诡异的现象：用spring-boot:run能跑，打JAR后跑不起来。原因通常是你用了某些只存在于IDE/Maven运行环境中的依赖，或者运行时动态生成的东西没有真正打入JAR的结构里。这个体验如果不亲历一次，不太容易理解。

另一个注意点是，mvn spring-boot:run默认情况下不会读取target里已经构建的产物，而是直接按照源码和classpath动态运行。所以某个奇怪情况下，你改了application.yml但它没生效，可能不是配置写错了，而是Maven没有触发重新编译资源。此时最好先来一发mvn compile resource:resources或干脆mvn clean。

4.3 与外部配置中心/环境变量的协作：Start-Class如何传递参数

生产环境中，一个SpringBoot应用很少用内置默认配置，更多是使用Nacos、Apollo这类配置中心，或者通过环境变量注入配置。

比如你用K8s部署，经常会在Dockerfile的ENTRYPOINT里写：

java -jar -Xmx512m -Xms256m app.jar --spring.profiles.active=prod --server.port=8081

这些参数在JarLauncher启动时会被传给Start-Class的主方法。所以虽然MANIFEST里的Main-Class是JarLauncher，但你所有JVM参数和Spring Boot的--参数依然可以照常工作。做过Java开发的都知道这个--参数就是SpringBoot对标准命令行参数解析的约定——它不是JVM参数，而是SpringBoot自身的配置绑定。

这里有一个经验之谈：不要让Run配置依赖于IDE参数。尽量用环境变量或启动脚本把参数固化下来，不然换台电脑、换个人启动就翻车。

4.4 多模块父工程里，插件生效顺序带来的依赖查找问题

多模块SpringBoot项目是个大话题，其中一种常见的诡异“找不到类”，发生在父模块的pom.xml配置了插件，子模块继承时需要明确依赖顺序。

Maven插件本身没有包顺序的强制绑定，但如果你有多个插件同时使用（比如spring-boot-maven-plugin和maven-shade-plugin），要保证repackage排在最后。maven-shade-plugin这种把依赖打成“fat jar”的逻辑和SpringBoot插件的嵌套JAR机制是冲突的。如果你在构建时发现target里生成了好几个JAR，且大小都差不多，多半是这两个插件打架了。

正确的做法是：万不得已不要使用maven-shade-plugin，SpringBoot的嵌套JAR机制已经完全能替代它。如果你确实有第三个场景需要拆分依赖，请在<executions>的顺序上保证SpringBoot repackage最后执行，而不要让它被shade之后进一步修饰。

5. 实战排查：那些要命报错的根因和修复法

5.1 启动报Unable to open nested entry "BOOT-INF/lib/xxx.jar"怎么办？

这个错，多半是因为你没有通过java -jar方式启动，而是直接改了启动脚本，把内部文件用普通的JVM类加载机制给处理了。另一个常见原因是：target目录里躺着之前构建失败的中间产物，或者脚本把原始JAR覆盖了。

实际操作中，建议先执行mvn clean再mvn package，不要使用增量构建结果。如果还报错，检查JAR里BOOT-INF/lib是否有损坏的文件，使用以下命令快速验证：

jar tf app.jar | grep BOOT-INF/lib | head

一旦能看到依赖文件列表，就说明结构是完整的。

5.2No main manifest attribute, in app.jar

这个报错是最常见的。原因简单粗暴：MANIFEST.MF里没有Main-Class这一行。为什么没有？因为repackage目标没有执行，或者执行了但被跳过了。最常见的原因是你只配置了插件但没有绑定execution里的repackage goal。很多人可能从某个“精简版”教程里抄来了这行：

<plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin>

没有<executions>里的repackage绑定，插件默认不会执行任何额外动作。这是“粘贴失败”的高发区。修复方式就是补上标准的executions配置。如果你确定配置了，再检查一下是不是上级POM里统一加了<skip>设置。

5.3 本地能跑，打包后却报ClassNotFoundException: com.mysql.cj.jdbc.Driver？

这种问题八成发生在数据库驱动、动态加载类等场景。核心原因是：repackaged JAR的类加载器是LaunchedURLClassLoader，它在加载BOOT-INF/lib下的JAR时，不会自动读取JAR内部的META-INF/services。如果你的依赖里用了SPI机制（比如JDBC驱动），且这个驱动本身是“provided”范围，repackage时就会漏掉驱动文件。

同样是SPI的问题，还会出现在日志实现上（SLF4J选择器），比如配置了logback却只在本地生效。实操建议：在项目里全局搜索META-INF/services，确认哪个SPI依赖还在，如果缺失就手动补充依赖范围。

5.4 反复出现Process terminated且没有日志输出

这种情况经常出现在Docker构建后，或者内存不足的环境里。容器环境里如果给了很低的内存，JVM可能在启动阶段就OOM。不要只盯着SpringBoot插件，先看系统日志：

docker logs <container-id> 2>&1 | tail -50

如果确实内存不够，改成：

java -jar -Xmx256m -Xms64m app.jar

如果日志完全没有，考虑是不是/dev/urandom熵源不足的问题。在Linux Dcoker环境里，JVM的SecureRandom经常因为熵不足在启动时卡住。解决办法是给JVM加参数：

-Djava.security.egd=file:/dev/./urandom

这个思路很多做容器化部署的人都踩过，尽早加上。

5.5 Maven依赖冲突怎么查？

SpringBoot插件的依赖管理（dependencyManagement）能统一很多传递性版本，但它只约束本身依赖，无法解决你手动引入的其他冲突。如果你的动态依赖报错，推荐直接使用：

mvn dependency:tree

如果树太大，组合grep关键词。例如查某个mysql驱动有没有多个版本：

mvn dependency:tree -Dincludes=mysql:mysql-connector-java

dependency:tree是我们排查这类问题最锋利的刀。另外一个思路是使用mvn dependency:analyze，它能列出“未使用的显式依赖”和“使用了的隐式依赖”。这些操作虽然不属于插件本身，但在调试插件构建异常时很有用。

5.6 分层构建时的提取失败：file not found: extracted/BOOT-INF/lib

有次同事在Docker构建时发现：明明Java代码没改，增量构建却极其慢，最后定位到是分层提取没有生效。原因在于他用的是2.3之前的SpringBoot版本，或者没有在插件配置里开启：

<configuration> <layers> <enabled>true</enabled> </layers> </configuration>

在SpringBoot 3.x中，分层默认是开启的（在2.3及以上默认生成.layers文件），但如果你用jar tf app.jar验证，发现里面没有layers.idx文件，那就是没生效。除了检查版本，还要注意Docker的Layer Cache机制：如果你把几十MB的依赖层文件改了一点点（比如版本号），Docker依然会重建这一层。

所以，做分层构建时，尽量保持依赖层足够“稳定”——依赖库的升级可以集中在一个专门的MR里，避免每次新加一个小依赖就导致整层缓存失效。

6. 从插件到部署，一次完整的“精通”实战路径

6.1 配置正确后，你应该在target里看到什么

当你执行完一次标准的mvn spring-boot:repackage或mvn clean package后，target目录应该长这样：

target/ classes/ # 编译产物 app.jar # 打包生成的普通JAR（未repackage前） app.jar.original # repackage前的普通JAR备份 app-exec.jar # 如果配置了classifier，app.jar为普通版，app-exec.jar为可执行版

看到.original就说明repackage发生“二次加工”了。如果在target里只看到app.jar，没有.original，绝大多数情况是重复执行了package而没有先clean，或者插件的executions没绑定成功。

6.2 生产环境常见部署组合：systemd + 脚本

很多非容器化环境里，我们还是会用systemd管理Java进程。一个常见的service脚本如下：

[Unit] Description=SpringBoot Application After=network.target [Service] User=deploy ExecStart=/usr/bin/java -Xmx512m -jar /opt/app/app.jar --spring.profiles.active=prod SuccessExitStatus=143 Restart=always RestartSec=10 [Install] WantedBy=multi-user.target

这里的SuccessExitStatus=143别忽略。因为systemd在停止Java进程时发SIGTERM，SpringBoot应用默认行为是执行优雅停机然后退出，退出码通常是143。如果不设置这个状态，systemd会判定进程是异常退出的，导致日志里出现莫名的“failed”。

6.3 容器化部署与镜像瘦身的再补充

对于Docker用户，结合插件和分层机制是整个部署链路最优雅的方式。实际生产里，我一般建议Dockerfile这样构建：

FROM maven:3.9-eclipse-temurin-17 AS build WORKDIR /src COPY pom.xml . RUN mvn dependency:go-offline -B COPY src ./src RUN mvn package -DskipTests FROM eclipse-temurin:17-jre WORKDIR /app COPY --from=build /src/target/*-exec.jar app.jar ENTRYPOINT ["java", "-jar", "app.jar"]

这个是一个“多阶段构建+直接复制JAR”的简化案例。但如果你用分层JAR，就能把构建阶段换成“解压分层然后分步COPY”，从而利用Docker layer缓存，达到快速构建的效果。

6.4 一个让我彻底意识到“版本锁定”重要性的案例

最后分享一个真实的踩坑故事。有一次接手一个老项目，SpringBoot版本被锁在2.1.x，但有人为了用新特性，偷偷把spring-boot-maven-plugin的版本升级到2.7。问题就出现了：mvn package成功，java -jar启动却一直报“jar is not a valid jar file”。折腾了半天，最后定位到是插件版本和SpringBoot版本不一致，导致repackage生成的可执行JAR里包含的是新版本的JarLauncher，而项目里的SpringBoot核心类还是2.1.x的，两者完全不兼容。

那一瞬间我终于理解了为什么用spring-boot-starter-parent管理插件版本是个多么反直觉但非常重要的设计：父POM通过<pluginManagement>锁定了插件版本，你只需要继承，就能保证版本一致。不要手动覆盖插件版本，除非你知道自己在干什么。

7. 最后的最后，送给你几个能救命的小习惯

第一次接触插件时，总想着“用更高的版本、更复杂的配置，显得自己很专业”。但踩过几轮坑之后，我更推荐这种务实做法：

第一，新建SpringBoot项目时优先用Spring Initializr生成，生成的POM天然带正确的插件配置，至少省掉80%的“复制粘贴后忘掉executions”问题。

第二，每次改插件配置后，先在本地用mvn spring-boot:run验证代码没问题，再用mvn clean package && java -jar验证产物没问题。两套机制（开发期和打包期）都要通，缺一不可。

第三，多看target目录里的文件名。.original文件是否存在、jar的大小是否合理（几千KB太小可能是依赖没打进去）、layers.idx是否存在，这些蛛丝马迹比满屏日志更有说服力。

第四，有空跑一下mvn help:effective-pom，看看Maven实际生效的插件配置是什么。很多时候你以为自己配了，其实被某个上级POM的占位符覆盖了，动手查一次能省半天排查时间。

SpringBoot Maven插件不难，但它值得你用“研究者”的姿态去对待。知其然，也知其所以然之后，下次遇到构建问题，你第一反应就不会是“是不是我的代码写错了”，而是“来，让我看看插件的嵌套JAR到底做了什么”。这种自信，是靠一次一次验证、一遍一遍看JAR内部结构堆出来的。希望你读完这篇，能少走我当年走过的那些弯路。