1. 本地运行SpringBoot的整体思路与前置条件1.1 先搞清楚本地运行到底要经历什么很多人第一次接触SpringBoot项目时第一反应是我代码都拿到了怎么跑不起来 实际上本地运行一个SpringBoot项目核心就三件事把依赖拉下来、把配置改对、把启动类跑起来。你不需要一上来就理解自动装配原理先把流程跑通后面再慢慢补原理效率会高很多。SpringBoot本身是一个约定优于配置的框架本地运行的流程比传统Spring Tomcat那套要简单得多但这不代表没有坑。最常见的坑往往不是代码问题而是环境问题JDK版本不对、Maven源下载慢、数据库没起来、端口被占。所以下面从环境准备讲起。很多教程喜欢一开始就讲自动装配、启动流程的源码分析我觉得对大多数人来说正确路径是反过来——先让项目在本地跑起来看到Started Application in x seconds那行日志再回头研究它为什么能跑起来这样理解更扎实遇到问题也更容易定位。提示不要看到报错就慌SpringBoot的报错信息其实很直白大部分问题看前几行就能定位。1.2 环境准备JDK、Maven、IDE、数据库先列一份清单本地跑SpringBoot项目基本需要这些东西JDKSpringBoot 2.x 要求 JDK8SpringBoot 3.x 要求 JDK17。如果你要同时玩2.x和3.x建议本机装 JDK8 和 JDK17 两个版本IDEA里随时切换。Maven虽然IDEA自带Maven但我还是建议本机装一个独立Maven 3.6后面讲原因。IDEIDEA首选社区版也能用VS Code也能跑但调试体验差一些。数据库与中间件如果项目用了MySQL、PostgreSQL、Redis、RabbitMQ等本地要么装好服务要么用Docker跑容器版。这里特别提醒装JDK时注意版本配对。SpringBoot 2.7.x 用 JDK8 最稳SpringBoot 3.x 必须 JDK17及以上。网上很多老教程是基于2.x写的如果你照着配了JDK8去跑SpringBoot 3.x项目启动直接报错后面细说。1.3 版本选型的坑SpringBoot 2.x vs 3.x很多人其实没有意识SpringBoot 3.0发布后整个依赖库的命名空间都变了。用表格比较一下SpringBoot版本最低JDK常用场景主要区别2.6.xJDK8老项目、学习教程javax.* 包2.7.18JDK82.x最后的长期维护版本很多旧项目在用javax.* 包3.0.xJDK17新项目jakarta.* 包Spring63.2.xJDK17当前主流新项目依赖Spring6.1springboot版本太高这个问题在本地运行旧项目时非常典型。比如一个基于SpringBoot 2.3的老项目你用SpringBoot 3.x的依赖启动会发现一堆老库的包名找不到因为javax换成了jakarta。这不是代码问题是版本空间变了。我见过有人拿一个2019年的毕设项目直接把pom里的SpringBoot版本改成3.2结果启动类都编译不过一脸懵。遇到这种情况最好的做法是老项目就先按老版本跑别为了用新版而升级本地运行追求的是稳定不是新潮。2. 从零创建项目到本地启动的完整流程2.1 用IDEA创建SpringBoot项目的两种方式创建SpringBoot项目最常用的是两种方式。第一种IDEA自带的Spring Initializr。在New Project里选择Spring Initializr填Group一般用公司域名倒序比如com.example、Artifact项目名然后选择SpringBoot版本和需要引入的依赖。IDEA会帮你生成pom.xml、启动类、配置文件等基础结构。这种方式适合你从0开始搭一个项目。第二种直接访问 start.spring.io 网页生成下载解压后导入IDEA。这种方式的好处是选项更清晰还能预览生成的依赖列表比如你想加Web、MySQL驱动、Redis等勾选后生成的pom会自动带上对应starter。不管哪种方式创建完成后我会先看一眼pom.xml确认两件事父依赖版本和Java版本是否匹配依赖有没有缺失。另外注意项目名里不要带中文和空格以前见过有人把项目起名为springboot 项目导入后Maven直接不认路径折腾半天才发现是这个问题。这属于很低级的坑但出现频率还挺高。2.2 项目结构认识pom.xml、启动类、application.yml一个标准的SpringBoot项目结构大概是demo ├── pom.xml ├── src │ ├── main │ │ ├── java/com/example/demo/DemoApplication.java │ │ └── resources/application.yml │ └── test/java/com/example/demo/DemoApplicationTests.java三个文件最重要pom.xmlMaven的构建描述文件声明了SpringBoot父依赖、各种starter依赖、构建插件。启动类DemoApplication.java标了SpringBootApplication注解里面有main方法。application.yml全局配置文件端口、数据库、日志等都在这里改。其中启动类的代码极简单大概长这样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); } }注意启动类必须放在包的最外层。如果放在子package里SpringBoot默认扫不到其余组件启动时容易报Consider defining a bean这类错误。新手容易把Controller、Service、启动类全部放同一个包下这在小项目里没事但包路径一旦不对组件扫描就会漏。2.3 第一次启动mvn spring-boot:run vs 直接运行main方法面对一个SpringBoot项目启动方式有两种。开发阶段我建议直接在主类里右键运行main方法。优点是走IDE调试方便断点能直接打上缺点是你得先让Maven把依赖全部下载完第一次比较慢而且Maven源没配好的话会卡在下载进度条上。另一种是命令行方式mvn spring-boot:run这条命令适合那些不想开IDE、只想快速验证的人。但要注意mvn spring-boot:run 会先在Maven本地仓库里解析依赖如果项目里某些依赖是私有库或未发布到中央仓库的jar命令行方式往往比IDE更容易失败。原因很简单IDE和命令行都会读取Maven的settings.xml但很多人没意识到settings.xml里的profile会决定不同仓库的生效顺序。所以我建议本地开发用IDE跑main方法命令行方式留给CI或服务器去用。2.4 验证启动成功日志、端口、Actuator启动成功后控制台会打出类似这样的日志Tomcat started on port(s): 8080 (http) with context path Started DemoApplication in 1.5 seconds (process running for 1.7)看到Started DemoApplication in x seconds才说明启动成功。然后打开浏览器访问 http://localhost:8080 。如果没有配置任何Controller页面会显示Whitelabel Error Page这其实也正常说明服务已经在跑了。如果你想更直观地确认服务健康状态可以在pom.xml里加一个依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-actuator/artifactId /dependency然后访问 http://localhost:8080/actuator/health 返回 {status:UP} 就说明一切正常。这一步在本地联调时很有用它能区分服务没起来和接口报错两种情况。很多新手一看到Whitelabel Error Page就以为项目没启动成功其实服务是好的只是没写页面误判之后耽误不少时间。3. 配置文件与依赖本地运行的核心细节3.1 application.yml/properties 关键配置项几乎每个SpringBoot项目本地运行都要改一遍配置文件。最常用的是这几个server: port: 8080 servlet: context-path: /demo spring: application: name: demo-service profiles: active: dev datasource: url: jdbc:mysql://localhost:3306/demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver注意几个点context-path 表示访问前缀配了之后接口地址变成 http://localhost:8080/demo/xxx 。profiles.active 用于切换环境dev、prod配置分离时你用得多。数据库url里的时区参数 serverTimezoneAsia/Shanghai 一定要写否则MySQL 8会报时区异常。3.2 端口配置与随机端口的玩法本地运行最烦的就是端口被占。你可以把端口固定成不常用的比如 8080 换成 8081、9090。SpringBoot还支持随机端口server: port: ${random.int[10000,19999]}这个写法在本地同时开多个微服务时特别好用启动时SpringBoot会随机挑一个范围内的端口避免互相冲突。不过如果你是联调场景固定端口更合适不然每次启动端口都不一样前端那边就没法配代理了。另外提一个springboot yml随机端口的细节这里的${random.int[10000,19999]}范围写法实际上SpringBoot内置的随机值生成器会在每次启动时取值并不需要额外引入依赖。但要注意随机端口的范围不能设置得太宽否则不好排查日志。我一般习惯设成10000到19999好记也偏离常用端口区。3.3 数据库连接配置与常见驱动问题本地连接数据库最容易踩的是驱动版本不匹配。比如项目用MySQL 8但pom里引的是 mysql-connector-java 5.x版本会直接报ClassNotFoundException: com.mysql.jdbc.Driver 或者 Unknown database。现在SpringBoot 2.7版本已经自动管理MySQL驱动的版本号你写依赖时通常不写版本会默认用8.0.x。还有一个坑是本地没有MySQL服务。很多人拿到项目后直接改配置文件改成localhost结果启动报Connection refused。解决方法是先确认mysql服务有没有起来mysql -uroot -p能进入命令行再改配置。如果还没装MySQL建议用Docker跑一个测试库docker run -d --name mysql8 -p 3306:3306 -e MYSQL_ROOT_PASSWORD123456 mysql:8这样比本机装MySQL干净很多也方便清理。如果你用的是国产数据库比如金仓、达梦pom里还得额外引入对应驱动jar通用MySQL的配置方式不完全适用驱动类和方言类都需要按厂商文档调整。3.4 引入外部依赖本地jar包的三种方式本地运行项目时经常会遇到一种情况某个依赖不在Maven中央仓库比如接的第三方SDK只给了jar包。这时候有三种处理方式。第一种把jar包安装进本地Maven仓库mvn install:install-file -Dfilexxx.jar -DgroupIdcom.example -DartifactIdxxx -Dversion1.0 -Dpackagingjar然后pom里按正常方式引用坐标即可。这种方式最适合团队协作其他人拉代码后不需要额外操作。第二种把jar放到项目目录下比如lib目录然后在pom里声明system scopedependency groupIdcom.example/groupId artifactIdxxx/artifactId version1.0/version scopesystem/scope systemPath${project.basedir}/lib/xxx.jar/systemPath /dependency这种方式最快但有个副作用打包时默认不会带上system scope的jar除非你配置spring-boot-maven-plugin的includeSystemScope属性。新手经常卡在本地能跑打包部署就NoClassDefFoundError就是这个原因。第三种用SpringBoot打包工具把外部jar一并打进fat jar在spring-boot-maven-plugin里配置plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration includeSystemScopetrue/includeSystemScope /configuration /plugin我个人建议能走第一种就第一种少踩一半的坑。第二种虽然快但给大家埋雷。3.5 引入外部中间件Redis、MQ等本地模拟方案很多SpringBoot项目不只依赖数据库还会依赖Redis、MQ等中间件。本地运行前先把这些服务在本地拉起来。Docker是最省事的docker run -d --name redis -p 6379:6379 redis:7 docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management注意这里的端口要和SpringBoot配置文件里的一致。如果RabbitMQ的管理端口15672被占用会直接影响本地调试因为访问管理台会失败。如果你不想起这些中间件也有两种办法一是把配置切到本地模拟实现比如用MockBean临时替换RedisTemplate二是写一个本地配置类把Bean伪装成真实连接。这些都属于测试技巧开发联调时偶尔用一下可以真要验证功能还是建议起真实中间件。4. 本地运行中常见问题与排查技巧实录4.1 端口被占用本地启动SpringBoot最经典的报错是Web server failed to start. Port 8080 was already in use.排查方法Windows用netstat -ano | findstr 8080macOS/Linux用lsof -i :8080查到占用进程的PID后Windows用 taskkill /PID xxx /F 结束Linux/macOS用 kill -9 xxx。如果这个端口被其他项目占了你也可以直接在配置文件里换成另一个端口。我在本地跑微服务时习惯每个服务用不同端口比如网关8080用户服务8081订单服务8082这样能少很多冲突。4.2 依赖下载慢/失败国内网络环境下载Maven依赖慢这是老话题了。解决方案是修改Maven仓库镜像在~/.m2/settings.xml里配置阿里云镜像mirror idaliyun/id namealiyun maven mirror/name urlhttps://maven.aliyun.com/repository/public/url mirrorOfcentral/mirrorOf /mirror如果你用的是IDEA还要检查一下IDEA设置的Maven路径是不是指向了你本机安装的Maven而不是IDEA自带的。很多人改了settings.xml但IDEA里用的还是它自带的Maven等于没改。另外如果某个依赖一直下载失败可以先删掉本地仓库里对应的最后一级目录再重新reimport避免Maven用了损坏的缓存。4.3 JDK版本不匹配报错JDK版本不匹配常见的报错有UnsupportedClassVersionError: 已从类文件的版本 61.0 中读取该版本高于运行时支持的版本 55.0或者编译时报Error:java: invalid target release: 17第一种情况通常是代码是用JDK17编译的但你用JDK11去运行class文件版本61对应JDK17高于JVM支持的版本。第二种情况常见于IDEA里的Project SDK还是8但pom里配置了maven.compiler.source17。解决方式IDEA里 File - Project Structure - Project SDK 改成JDK17同时 Settings - Build Tools - Maven - Importing 里的JDK也设成17。很多新手只改了Project SDKMaven编译时还会用默认JDK所以两个地方都要改。如果你本机装的是多版本JDK建议在系统环境变量里只保留一个剩下的用IDEA的SDK管理能减少很多混乱。4.4 数据库连接失败数据库相关报错五花八门但基本能归成三类Communications link failure Access denied for user rootlocalhost The server time zone value ... is unrecognized第一类连不上库先ping一下端口通不通telnet localhost 3306。第二类用户名或密码不对检查配置文件里的datasource配置尤其是环境变量覆盖的情况。第三类MySQL 8时区问题url里加 serverTimezoneAsia/Shanghai。还有一种隐藏较深的情况你配置里写的是localhost但MySQL服务用的是IPv6监听导致连接失败。这种情况把localhost改成127.0.0.1往往能解决。4.5 配置文件加载不到配置文件加载不到常见两种一种是有多个profile文件但active没写对导致application-dev.yml没被加载。另一种是yml缩进写错SpringBoot启动时会直接抛Failed to bind properties under server.port to java.lang.Integer这类错误。我的经验是先看target/classes里有没有把配置文件编译进去再看启动日志第一行打印的是哪个profile。注意yml文件对缩进极其敏感我见过有人用Tab缩进导致配置解析失败。写yml统一用两个空格缩进别用Tab编辑器里把这俩显示出来会省很多事。4.6 热部署失效SpringBoot本地开发经常配热部署用spring-boot-devtools。但很多人加了依赖之后发现改了代码不生效常见原因有三个一是IDEA的自动编译没开Settings - Build, Execution, Deployment - Compiler 勾上Build project automatically二是改了pom.xml这类配置文件DevTools默认不触发热重启三是改了application.yml里的devtools配置但没生效。还有一个容易被忽略的点IDEA里必须开启允许并行运行否则多个实例调试时热部署会失效。4.7 问题速查表现象可能原因处理建议启动报Port 8080 already in use端口被占用netstat/lsof查PIDkill或换端口依赖下载卡住网络源慢/失败配Maven镜像aliyun公共仓库UnsupportedClassVersionErrorJDK版本不匹配统一Project SDK与编译JDKConnection refused数据库服务没起或端口不对确认MySQL/Redis等中间件已启动Unknown database xxx数据库没创建CREATE DATABASE xxxWhitelabel Error Page没配任何页面/接口属正常现象补个Controller验证NoClassDefFoundError: javax/xxxSpringBoot 3下依赖老包换为jakarta命名空间的依赖5. 进阶从开发到本地模拟生产运行5.1 打包成jar本地运行本地开发用IDE跑main方法就够了但有时候需要验证生产模式下的行为比如确认接口在正式环境配置下能正常工作。这时建议打成可执行jar来跑。打包命令很简单mvn clean package -DskipTests java -jar target/demo-0.0.1-SNAPSHOT.jar打包成功后target目录下会有两个jar一个带版本号的原版jar另一个是 .jar.original带版本号那个才是SpringBoot的可执行fat jar里面包含了所有依赖和内置Tomcat。运行前把端口环境变量带上更接近生产java -jar target/demo-0.0.1-SNAPSHOT.jar --server.port9090 --spring.profiles.activeprod如果需要在启动时给JVM分配内存可以加上java -Xms256m -Xmx512m -jar target/demo-0.0.1-SNAPSHOT.jar-Xms256m表示初始堆内存256MB-Xmx512m表示最大堆内存512MB。本地机器内存紧张时这个参数能避免内存溢出。如果你的项目比较大比如引入了Elasticsearch、MinIO这些组件堆内存可以给到1GB。5.2 常用启动脚本与目录规划本地模拟生产运行我习惯写一个start.sh脚本#!/bin/bash APP_NAMEdemo-0.0.1-SNAPSHOT.jar LOG_DIRlogs PID_FILEapp.pid mkdir -p $LOG_DIR nohup java -Xms256m -Xmx512m -jar target/$APP_NAME \ --spring.profiles.activeprod \ $LOG_DIR/app.log 21 echo $! $PID_FILE echo $APP_NAME started, pid$(cat $PID_FILE)stop.sh脚本#!/bin/bash if [ -f app.pid ]; then kill $(cat app.pid) rm -f app.pid fi这段脚本就是最朴素的启停方式没有systemd那些复杂逻辑但在本地验证部署流程完全够用。注意nohup和配合使用保证退出终端后进程不挂掉。日志文件放在logs目录下排查问题的时候可以直接 tail -f logs/app.log。5.3 Docker方式运行SpringBootSpringBoot项目本地跑Docker只需要一个DockerfileFROM openjdk:17-jdk-slim VOLUME /tmp COPY target/demo-0.0.1-SNAPSHOT.jar app.jar ENTRYPOINT [java,-jar,/app.jar]构建和运行mvn clean package -DskipTests docker build -t demo-service:1.0 . docker run -d --name demo -p 8080:8080 demo-service:1.0这里要提醒几个点openjdk镜像版本必须和项目JDK匹配SpringBoot 3.x就得用openjdk:17及以上。Docker里跑容器时区默认是UTC如果需要东八区时间Dockerfile里加一句 ENV TZAsia/Shanghai。容器里内存限制用 --memory512m 控制避免在本地一台机器上跑多个容器时把内存吃光。5.4 本地调试补充技巧最后说两个本地调试的小技巧。第一全局过滤器处理上传文件时很多新手在过滤器里读了一遍RequestBody导致Controller里再取文件时是空的。这是因为流只能读一次。正确做法是用OncePerRequestFilter并且把读取到的内容重新包装回Request里。这个坑在本地跑文件上传接口时特别容易遇到现象是接口偶尔成功偶尔失败特别迷惑。第二接口文档。加了springdoc-openapi对应老项目的springfox依赖后本地启动后访问/v3/api-docs能直接看到接口定义如果是springdoc的UI界面则访问/swagger-ui.html。用来排查接口入参特别方便。SpringBoot 3.x必须用springdoc的2.x版本老版本里的javax命名空间会编译不过。关于banner生成器大家喜欢把启动日志里的SpringBoot Banner换成自定义图案用patorjk.com这类工具做成ASCII字符然后放到src/main/resources/banner.txt里。这个纯粹是锦上添花但对团队辨识度有些帮助成员一眼能看出连的是哪个环境。我见过一个团队把dev和prod的banner做成不同颜色和文字确实能减少误操作。踩过几次坑之后我现在的本地运行流程基本固定为先看pom和配置文件再确认JDK版本和数据库是否就绪然后直接main方法启动遇到问题先看端口和依赖。这个思路对新手来说是最省时间的。最后再分享一个小技巧所有配置文件里的敏感信息比如数据库密码、连接地址建议先用环境变量替换SpringBoot原生支持${DB_PASSWORD}这种占位符。这样换一台机器跑的时候你只需要改环境变量不用动代码也能避免把密码提交到仓库里。