SpringBoot 应用启动失败常见原因与排查思路
SpringBoot 一键启动的爽感谁用谁知道，但一旦启动失败——屏幕上一堆红字报错，有些同学就瞬间懵圈了，到底是哪里错了？该从哪查起？
今天就把 SpringBoot 启动失败的高频原因+排查步骤全讲透：从最基础的端口占用、配置文件错误，到复杂的依赖冲突、Bean 初始化失败，每个问题都给“现象+原因+解决方法”，以后再遇到启动失败，按这个流程查，5分钟内定位问题。
先掌握通用排查思路
不管遇到哪种启动失败，先按这4步走，别上来就瞎改代码：
- 看日志
：重点看日志里的
ERROR/Exception关键词，找到“根异常”（最下面的 Caused by）； - 定位范围
：根据异常类型判断是配置问题、依赖问题、代码问题还是环境问题；
- 缩小排查面
：注释掉非核心代码/配置，逐步恢复，找到触发失败的关键点；
- 验证解决
：改完后重启，看是否解决，没解决就回到第一步，重点排查未覆盖的点。
实战1：高频启动失败场景（现象+原因+解决）
场景1：端口被占用（最常见）
现象：
启动日志报错：
ERROR 12345 --- [ main] o.s.b.web.embedded.tomcat.TomcatWebServer : Tomcat started on port 8080 (http) failed: port 8080 already in use原因：
8080 端口被其他程序（比如另一个 SpringBoot 应用、Tomcat、Nginx）占用。
解决方法：
临时解决：改配置文件的
server.port（比如改成 8081），或启动时指定端口：```bash java -jar app.jar --server.port=8081 ```彻底解决：找到占用端口的进程并杀掉：```bash # Windows netstat -ano | findstr "8080" # 找到进程ID（PID） taskkill /F /PID 进程ID # 杀掉进程 # Linux/Mac lsof -i:8080 # 找到进程ID kill -9 进程ID ```
场景2：配置文件语法错误
现象：
启动日志报错（YAML 错误为例）：
ERROR 12345 --- [ main] org.yaml.snakeyaml.scanner.ScannerException : while scanning a simple key in 'reader', line 10, column 5: port:8080 ^ expected ':' at line 10, column 6: port:8080 ^原因：
YAML 文件：冒号后没加空格、用 Tab 缩进、大小写错误；
Properties 文件：键值对格式错误、特殊字符没转义。
解决方法：
YAML 排查要点：
冒号
:后必须加 1 个空格（port: 8080正确，port:8080错误）；缩进只用 2 个空格，别用 Tab；
字符串含特殊字符（
:/空格）要加单/双引号；
Properties 排查要点：
键值对用
=分隔（server.port=8080）；URL 里的
&转义为&（比如jdbc:mysql://...&useSSL=false要写成&useSSL=false）。
场景3：依赖冲突/缺失
现象1（依赖冲突）：
启动日志报错：
ERROR 12345 --- [ main] org.springframework.context.ApplicationContextException : Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NoSuchMethodError: org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.(Ljava/util/Set;)V原因：
不同依赖引入了同一个类的不同版本（比如 SpringFox 和 SpringBoot 版本不兼容）。
解决方法：
用 Maven/Gradle 查看依赖树，找到冲突的依赖：
# Maven mvn dependency:tree > dependency.txt # 导出依赖树到文件 # 搜索冲突的包（比如 spring-webmvc） grep "spring-webmvc" dependency.txt排除低版本/不兼容的依赖：
1<dependency> 2<groupId>xxxgroupId> 3<artifactId>xxxartifactId> 4<exclusions> 5<exclusion> 6<groupId>org.springframeworkgroupId> 7<artifactId>spring-webmvcartifactId> 8exclusion> 9exclusions> 10dependency>现象2（依赖缺失）：
启动日志报错：
ERROR 12345 --- [ main] org.springframework.boot.diagnostics.LoggingFailureAnalysisReporter : *************************** APPLICATION FAILED TO START *************************** Description: Cannot determine embedded database driver class for database type NONE Action: If you want an embedded database (H2, HSQL or Derby), please put it on the classpath.原因：
配置了数据库连接，但没引入数据库驱动依赖（比如
mysql-connector-java）。解决方法：
在
pom.xml里添加缺失的依赖：1<dependency> 2<groupId>com.mysqlgroupId> 3<artifactId>mysql-connector-jartifactId> 4<scope>runtimescope> 5dependency>场景4：Bean 初始化失败
现象：
启动日志报错：
ERROR 12345 --- [ main] org.springframework.beans.factory.BeanCreationException : Error creating bean with name 'userService': Injection of autowired dependencies failed; nested exception is org.springframework.beans.factory.NoSuchBeanDefinitionException: No qualifying bean of type 'com.xxx.mapper.UserMapper' available: expected at least 1 bean which qualifies as autowire candidate.常见原因：
@Autowired注入的 Bean 不存在（比如 Mapper 没加
@Mapper注解）；主启动类包扫描范围不对（比如 Controller/Mapper 在主启动类的子包外）；
Bean 初始化方法抛异常（比如
@PostConstruct方法报错）。
解决方法：
检查注解：Mapper 加
@Mapper，Service 加@Service，Controller 加@RestController；扩大包扫描范围：主启动类加
@ComponentScan("com.xxx")（指定根包）；检查初始化方法：去掉
@PostConstruct里的危险代码，或捕获异常。
场景5：数据库连接失败
现象：
启动日志报错：
ERROR 12345 --- [ main] com.zaxxer.hikari.pool.HikariPool : HikariPool-1 - Exception during pool initialization. com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure原因：
数据库地址/端口/用户名/密码错误；
数据库服务没启动；
防火墙禁止应用访问数据库；
数据库连接 URL 格式错误。
解决方法：
核对配置文件里的数据库参数：
1spring: 2 datasource: 3url: jdbc:mysql://192.168.1.100:3306/test_db?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai 4username: root 5password:123456测试数据库连通性：
1# 用 mysql 客户端测试 2mysql -h192.168.1.100 -P3306-u root -p123456检查数据库服务状态（Linux）：
1systemctl status mysqld # 查看 MySQL 是否启动场景6：启动类错误
现象：
启动后无响应，或报错“找不到主类”：
Error: Could not find or load main class com.xxx.SpringbootDemoApplication Caused by: java.lang.ClassNotFoundException: com.xxx.SpringbootDemoApplication原因：
主启动类没加
@SpringBootApplication注解；打包插件配置错误，没指定主类；
主类包名/类名写错。
解决方法：
主启动类必须加
@SpringBootApplication：
1@SpringBootApplication 2publicclassSpringbootDemoApplication{ 3publicstaticvoidmain(String[] args){ 4SpringApplication.run(SpringbootDemoApplication.class, args); 5} 6}核对
pom.xml里的打包插件配置：
1<plugin> 2<groupId>org.springframework.bootgroupId> 3<artifactId>spring-boot-maven-pluginartifactId> 4<configuration> 5<mainClass>com.xxx.SpringbootDemoApplicationmainClass> 6configuration> 7plugin>通用排查工具（提升效率）
- IDEA 自带工具
：
启动时打开「Run/Debug Configurations」→ 勾选「Enable debug output」，打印更详细的启动日志；
用「Maven Projects」→「Dependencies」查看依赖树，直观看到冲突依赖。
- 日志级别调整
：
启动时加参数，打印 DEBUG 级日志，看更详细的启动过程：```bash java -jar app.jar --logging.level.root=DEBUG ``` - SpringBoot 启动诊断
：
SpringBoot 自带失败分析器，日志里会提示「Action」（解决建议），重点看这部分。 启动失败的 5 个坏习惯
- 不看日志直接改代码
：上来就瞎改配置、删依赖，越改越乱；
- 忽略“Caused by”
：只看最上面的异常，不看根原因（根异常才是关键）；
- 依赖随便加
：看到别人的代码里有啥依赖就加啥，导致依赖冲突；
- 配置文件手写
：不用 IDE 提示，手动敲 YAML/Properties，容易犯语法错误；
- 生产环境直接复制开发配置
：比如开发用的自签名证书、测试库地址，直接丢到生产。
下一期，咱们会讲：SpringBoot 应用监控（Actuator + Prometheus + Grafana），实时看应用状态，提前发现问题，避免线上故障。
如果这篇文章帮你搞定了启动失败的排查，麻烦点个赞、在看，关注我，后续还有更多 SpringBoot 排障实战技巧，从入门到精通～
- 不看日志直接改代码