一开始接触SpringBoot打包时我犯过一个很低级的错误在IDE里点了几下Build拿到target目录下的jar直接扔到服务器上执行结果报了“no main manifest attribute”当时整个人是懵的。后来才知道SpringBoot打包这回事远不只是“生成一个jar”这么简单它牵涉到内嵌容器的启动逻辑、Maven插件的重新打包机制、可执行jar的目录结构等一系列规则。这篇就把我完整跑通的一个SpringBoot小案例从源码到打包再到执行的全流程拆开讲清楚适合刚接触SpringBoot、准备做毕设、或者正在纠结“为什么我打的jar跑不起来”的朋友。1. 为什么SpringBoot打包值得单独写一篇——先搞清楚jar到底打了什么1.1 普通jar和可执行jar不是一回事很多人以为Java项目打包不就是生成一个jar吗是的但普通jar和SpringBoot可执行jar有本质区别。传统Java项目打成jar后如果需要依赖第三方库通常要把依赖放到单独的lib目录并通过Class-Path指定SpringBoot却要求打出来的jar能够独立运行这意味着Spring Boot Maven Plugin在打包时会做一次专门的“repackage”。简单说这个插件把项目自身编译出来的classes和所有第三方依赖jar全部塞进同一个文件里再写一个特殊的启动器。你在服务器上一句java -jar app.jar操作系统会用java命令启动这个jar而jar里配置的Main-Class也不是你写的那个Application类而是SpringBoot的JarLauncher。JarLauncher先把自己内部的BOOT-INF/lib目录下的依赖加载到类路径再通过反射调用你写的那个主类最终才启动Spring容器。1.2 启动链路上的三个角色JarLauncher、Main-Class和Start-Class如果把打包后的jar解压你会看到META-INF/MANIFEST.MF里有两行关键信息Main-Class: org.springframework.boot.loader.JarLauncher Start-Class: com.example.demo.DemoApplicationMain-Class是JVM规范里“程序入口”的标准字段java命令启动时先执行它Start-Class才是你真正的业务入口类。JarLauncher在中间做了一层“换手”目的是先搞定自定义的类加载环境再调用你的代码。这也是为什么直接在pom里配置maven-jar-plugin并设置Main-Class为DemoApplication的做法在SpringBoot场景下经常失效——因为你绕过了JarLauncher直接用自己的主类去启动一个结构上并不符合Java标准Class-Path规则的胖jar类当然加载不到。1.3 一个反直觉的验证方法看jar包大小判断一个SpringBoot项目打包是否成功最快的方法不是看Build Success而是看target目录下的jar文件大小。一个只写了Controller和配置文件的空项目打包后通常有16MB到20MB如果你看到的是几百KB甚至几KB那大概率没有触发SpringBoot插件的repackage打出来的只是普通jar。这个细节在后面的排查部分还会反复用上。2. 一个最小案例从建项目到能跑先搭建可复现的源码2.1 手工搭建一个最小的SpringBoot工程为了不依赖在线生成工具我习惯手工建一个最简工程结构顺便把pom逻辑讲透。目录如下springboot-demo/ ├── pom.xml └── src/main/ ├── java/com/example/demo/ │ ├── DemoApplication.java │ └── controller/HelloController.java └── resources/ └── application.ymlpom.xml的核心就三块父依赖、Web起步依赖、打包插件。我以热词里出现的SpringBoot 2.7.18为例这个版本已经属于2.7系列的最后一站稳定性和兼容性都经受过大量验证。?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent groupIdcom.example/groupId artifactIdspringboot-demo/artifactId version1.0.0/version packagingjar/packaging properties java.version1.8/java.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project这里有个非常容易被忽略的知识点父依赖spring-boot-starter-parent本身会管理大量的依赖版本同时它的pluginManagement里预设了spring-boot-maven-plugin的执行细节。所以你声明插件的时候只需要写groupId和artifactIdrepackage目标的配置会自动生效。如果你不用parent手动引入依赖时很容易因版本冲突或插件目标缺失导致打包异常。2.2 主类和Controller的写法要点启动类就三行代码但有一个隐性要求它所在的包必须比所有Controller包更“上”。SpringBoot启动时会扫描启动类所在包及其子包如果你的Controller和启动类不在同一个包树下面打包后运行起来接口会404。package com.example.demo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }Controller这样写package com.example.demo.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; RestController public class HelloController { GetMapping(/hello) public String hello() { return hello spring boot jar; } }2.3 写一份不会让运行“翻车”的配置文件application.yml我建议从一开始就写上端口和context-path避免后面拿着jar到处找端口server: port: 8080 servlet: context-path: /demo为什么要写context-path因为很多同学本地跑的时候不写路径接口直接就是http://localhost:8080/hello到了服务器上习惯性加上项目名去访问结果404。明确写一个上下文路径会让前后端联调的预期更清晰。写完这些后先在IDEA里跑一次主类确认控制台出现“Started DemoApplication”并且访问http://localhost:8080/demo/hello能返回字符串再进行打包。3. 两种打包方式对比Maven命令行与IDEA图形化操作3.1 Maven命令行打包从clean到package的完整链路在项目根目录打开终端执行mvn clean package这条命令会先清理target目录然后执行生命周期里的compile、test、package等阶段。如果你的项目里有测试类但暂时不想跑测试可以用mvn clean package -DskipTests注意-DskipTests只是不执行测试代码但会编译测试代码如果要连测试类编译都跳过用mvn clean package -Dmaven.test.skiptrue两者区别非常实用很多老手也容易记混。在打包输出日志末尾你会看到BUILD SUCCESS以及target目录下生成的springboot-demo-1.0.0.jar。这时候你立刻看一眼文件大小如果只有几KB别急着上传服务器先回pom里检查spring-boot-maven-plugin是否真的加入了。3.2 IDEA图形化打包操作细节IDEA右侧的Maven面板展开Lifecycle双击clean再双击package效果和命令行相同。但IDEA面板有一个容易搞混的点Maven面板里除了Lifecycle还有Plugins列表。你在Plugins里展开spring-boot-maven-plugin文件夹里面也能看到repackage目标很多人在这里直接点repackage发现有时候生效有时候不生效。实际上双击spring-boot:repackage的前提是你已经执行了package阶段生成了原始jarrepackage是在这个原始jar基础上“加工”的。正常流程只需要运行Lifecycle里的package就行repackage会自动绑定执行。如果你早期尝试过一些手工配置在pom里给spring-boot-maven-plugin加了executions节再手动执行一次repackage也没问题但新手我还是建议直接跑生命周期避免重复加工触发奇怪问题。3.3 多模块项目的打包提醒如果你的项目是父子多模块结构比如既有common模块又有web模块打包时最好在父目录执行mvn clean package -pl web模块名 -am。-pl指定要构建的模块-am表示同时构建它依赖的其它模块。如果直接只在web模块目录下执行package而common模块还没install到本地仓库会报找不到依赖错误。这个坑在毕设级别的漫画、商城项目里非常常见我见过太多同学卡在“明明本地能跑打包就失败”的环节。4. 执行阶段实测java -jar的全部参数细节与三种常用运行场景4.1 前台运行最简单也最容易踩坑打包成功后进入target目录执行java -jar springboot-demo-1.0.0.jar看到Spring的Banner和“Started DemoApplication”表示启动成功。但这里有一个工作目录坑如果你在服务器上把jar放在/opt/app/目录下却在/root/目录执行java -jar /opt/app/springboot-demo-1.0.0.jar程序的工作目录是/root/。当代码里用了相对路径读写文件比如new File(logs/xxx.log)日志会写到/root/logs而不是jar同目录很多人由此产生“文件不知道跑到哪里去”的疑惑。建议执行前先cd到期望的工作目录。4.2 通过命令行覆盖端口和配置SpringBoot的命令行参数优先级非常高它高于application.yml里的配置。启动时想换端口不用改配置文件重新打包直接java -jar springboot-demo-1.0.0.jar --server.port8081想切多环境配置dev/prod用java -jar springboot-demo-1.0.0.jar --spring.profiles.activeprod这个能力非常重要。实际发布的时候同一个jar可以部署在多套环境无需为每个环境重新打一次包。配置差异全部通过启动参数或外部配置文件注入这也是SpringBoot“一次打包多处运行”的核心理念。如果还有数据库连接、Redis地址等敏感配置我习惯用--spring.config.additional-location/opt/app/config/去加载jar外部的配置文件这个细节后面第6部分再展开。4.3 后台运行与日志管理nohup加输出重定向服务器上必然要关掉SSH窗口之后继续运行所以前台运行没有实际意义。标准做法nohup java -jar springboot-demo-1.0.0.jar --server.port8080 app.log 21 拆开解释一下nohup让进程忽略挂断信号即使终端关闭进程也不退出 app.log把标准输出写入文件21把标准错误也重定向到同一个文件最后的让命令后台执行。如果这条命令执行后立刻返回了一个PID数字说明进程已经挂在后台。查日志用tail -f app.log查进程用jps -ljps会列出当前JVM进程你会看到类似springboot-demo-1.0.0.jar的条目。手动停止进程kill 进程PID如果进程杀不掉再用kill -9强制结束。但注意kill -9不会给Spring容器优雅停机的时间有可能造成正在处理的请求中断常规升级流程里优先使用Spring Boot Actuator提供的shutdown端点做优雅停机。4.4 用Actuator优雅停机在pom里再加一个依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-actuator/artifactId /dependency然后配置management: endpoint: shutdown: enabled: true endpoints: web: exposure: include: health,shutdown这样可以通过POST http://localhost:8080/demo/actuator/shutdown注意端口和context-path来触发容器关闭进程会先完成手头请求再退出。生产环境一般不会把shutdown端点暴露到公网而是配合内网监控使用。5. 打包执行中遇到的高频坑位与完整排查链路5.1 “no main manifest attribute”的根因排查这是我见过最多的报错完整错误是no main manifest attribute, in springboot-demo-1.0.0.jar出现这个错误进入jar目录执行unzip -p springboot-demo-1.0.0.jar META-INF/MANIFEST.MF如果看到的结果里没有Main-Class或者Main-Class不是你预期的JarLauncher说明这个jar根本没走SpringBoot插件。回到pom检查两处是否引入了spring-boot-starter-parent是否在build里声明了spring-boot-maven-plugin。如果没有parent即使加了plugin也可能因为插件版本缺失导致repackage没绑定这时手动补上插件版本即可plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId version2.7.18/version executions execution goals goalrepackage/goal /goals /execution /executions /plugin排查链路就是先看jar大小 — 再看MANIFEST.MF — 最后看pom配置这三步缺一不可。5.2 本地能跑、jar包跑不起来版本与工作目录问题有一种诡异现象是IDEA里点击运行一切正常但java -jar启动时马上报错退出。最常见的是JDK版本不一致IDEA里配置的Project SDK是JDK 11编译期可能用了高版本特性而服务器上运行的是JDK 8启动时报UnsupportedClassVersionError。排查时先确认java -version javap -verbose 你的类名.class | grep major version看到的major version如果是55表示编译目标版本是Java 11如果服务器是1.8必然启动失败。解决办法是在pom里统一java.version和maven.compiler.source值并保证本地与服务器的JDK版本一致。另一个原因是工作目录导致相对路径失效。比如代码里用了相对路径读取某个文件本地IDEA的工作目录就是项目根目录文件放对位置就能读到但jar包运行时的工作目录由启动命令所在位置决定文件不在当前目录就抛FileNotFoundException。这类问题优先将配置文件路径改为classpath:或file:绝对路径或者在启动脚本里用cd固定工作目录。5.3 端口占用问题从错误日志反推启动时如果看到Web server failed to start. Port 8080 was already in use.说明端口被占用。Linux下排查lsof -i:8080 netstat -tunlp | grep 8080找到PID后如果是自己之前启动的残留进程kill PID再重启。Windows下用netstat -ano | findstr 8080。多数情况下错误日志已经明确告诉了端口冲突但很多初学者看到大段异常就慌忽略了最前面这几行关键信息。所以遇到启动失败第一件事不是搜整个日志而是从头看前50行启动失败的真正原因通常都写在前面。5.4 配置文件没打进去的检查方法有同学明明在src/main/resources下写了application.yml也配置了数据库但打包出来的jar运行时好像根本没读取这些配置。检查方法很简单unzip -l springboot-demo-1.0.0.jar | grep application jar tf springboot-demo-1.0.0.jar | grep yml如果发现BOOT-INF/classes下没有application.yml说明resources目录没有被Maven当作资源目录编译进去或者文件放错位置。常见原因是resources目录没有在src/main下而是被手动建成了普通目录。正确结构必须是src/main/resources/application.yml。还有一种坑IDEA的target目录里旧class残留导致新配置没生效。这时候只需要彻底执行一次clean再package。6. 看完打包产物jar解压检查与依赖结构解析6.1 可执行jar的目录结构到底长什么样执行jar tf springboot-demo-1.0.0.jar会看到这样一个结构BOOT-INF/ classes/ com/example/demo/... application.yml lib/ spring-boot-2.7.18.jar spring-webmvc-6.0.14.jar tomcat-embed-core-9.0.83.jar ... META-INF/ MANIFEST.MF org/ springframework/ boot/ loader/ JarLauncher.class ...BOOT-INF/classes存放自己编译的class和配置文件BOOT-INF/lib存放所有第三方依赖。SpringBoot的升级版加载器会利用BOOT-INF这个自定义布局来创建类路径这也是它和传统fat jar最大的不同。理解了这一点你就明白为什么有些反编译工具直接打开jar看不到业务代码——因为业务代码被收纳到了BOOT-INF/classes而不是jar包的根路径。6.2 如何反编译jar里的class文件查看逻辑热词里出现“怎么将springboot jar反编译成项目”这其实是很多接手旧项目的同学的真实需求。先说结论jar里没有源码只有编译后的class文件但借助反编译工具可以还原出可读性相当高的Java代码。推荐两种方式命令行工具CFR是一款优秀的Java反编译工具下载后执行java -jar cfr.jar BOOT-INF/classes/com/example/demo/controller/HelloController.class图形化插件IDEA自带Java Decompiler装好FernFlower插件后直接打开class文件IDEA会实时显示反编译结果。反编译最大的价值不是“抄代码”而是了解jar中实际打包进去的业务逻辑和配置状态确认发布版本和源码版本是否一致。比如有时候代码改了半天结果忘了重新打包发布到测试环境还是旧逻辑反编译一眼就能看出来。6.3 改配置也可以不用重新打包SpringBoot支持通过外部配置覆盖jar内的配置这是生产环境非常常用的技巧。启动时指定java -jar springboot-demo-1.0.0.jar --spring.config.location/opt/app/application.ymllocation指定外部配置文件的路径jar内置的application.yml就不再参与加载完全由外部文件接管。另一种更灵活的是additional-location它会让外部配置和jar内配置共存且外部配置优先级更高java -jar springboot-demo-1.0.0.jar --spring.config.additional-location/opt/app/config/这个特性意味着只要不改代码和依赖就不需要频繁重新打包。数据库连接池大小、日志级别、开关项等都可以通过外部文件在部署时动态调整。配合前面讲的命令行参数覆盖几乎能覆盖所有“不想改包”的场景。6.4 把jar包成Docker镜像的常见姿势现在服务端部署越来越倾向容器化。写一个Dockerfile基于JDK基础镜像把jar复制进去并暴露端口FROM openjdk:8-jre-alpine VOLUME /tmp COPY springboot-demo-1.0.0.jar app.jar ENTRYPOINT [java,-jar,/app.jar]构建镜像和启动容器docker build -t springboot-demo . docker run -d -p 8080:8080 --name demo springboot-demo重心仍然是那个jar文件本身Docker只是把它和运行时环境封装在一起。只要jar能够java -jar正常启动容器化通常不会出错反过来说一个在本地都跑不起来的jar强行塞进容器只会让排查难度加倍。7. 我的上线前检查清单与养成习惯操作多了之后我给自己总结了一套发布前的确认顺序每次跑一遍能省不少事本地完整执行一次mvn clean package -DskipTests确认BUILD SUCCESS检查jar文件大小超过10MB基本说明依赖已打入jar tf查看jar内是否包含application.yml、启动类和可能的静态资源本地java版本与服务器java版本核对确保major version匹配启动命令明确指定端口、profile、外部配置路径启动后用curl http://localhost:端口/上下文/hello验证接口查看日志关键字“Started”和“Tomcat started on port”用jps确认进程存活再退出终端窗口。我个人还有一个坚持了很久的习惯每次打包后会把mvn package产出的jar连同启动命令一起记录到一个部署文档里包括当前jar的md5值。这样一旦线上问题需要回滚我能立刻找到“上次能用的版本”是哪一个而不用凭记忆去猜。打包执行这件事看起来只是三两行命令但它涉及的底层机制和隐藏坑位足够让一个项目从工具链到部署链路完全顺畅地跑起来。希望我踩过的这些坑能帮你少走一段弯路。