SpringBoot 应用启动失败常见原因与排查思路

SpringBoot 一键启动的爽感谁用谁知道，但一旦启动失败------屏幕上一堆红字报错，有些同学就瞬间懵圈了，到底是哪里错了？该从哪查起？

今天就把 SpringBoot 启动失败的高频原因+排查步骤全讲透：从最基础的端口占用、配置文件错误，到复杂的依赖冲突、Bean 初始化失败，每个问题都给"现象+原因+解决方法"，以后再遇到启动失败，按这个流程查，5分钟内定位问题。

先掌握通用排查思路

不管遇到哪种启动失败，先按这4步走，别上来就瞎改代码：

看日志

：重点看日志里的 ERROR/Exception 关键词，找到"根异常"（最下面的 Caused by）；
定位范围

：根据异常类型判断是配置问题、依赖问题、代码问题还是环境问题；
缩小排查面

：注释掉非核心代码/配置，逐步恢复，找到触发失败的关键点；
验证解决

：改完后重启，看是否解决，没解决就回到第一步，重点排查未覆盖的点。

实战1：高频启动失败场景（现象+原因+解决）

场景1：端口被占用（最常见）

现象：

启动日志报错：

go 复制代码

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 错误为例）：

go 复制代码

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（依赖冲突）：

启动日志报错：

go 复制代码

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 查看依赖树，找到冲突的依赖：

go 复制代码

# Maven
   mvn dependency:tree > dependency.txt  # 导出依赖树到文件
   # 搜索冲突的包（比如 spring-webmvc）
   grep "spring-webmvc" dependency.txt

排除低版本/不兼容的依赖：

go 复制代码

1<dependency>
2<groupId>xxxgroupId>
3<artifactId>xxxartifactId>
4<exclusions>
5<exclusion>
6<groupId>org.springframeworkgroupId>
7<artifactId>spring-webmvcartifactId>
8exclusion>
9exclusions>
10dependency>

现象2（依赖缺失）：

启动日志报错：

go 复制代码

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 里添加缺失的依赖：

go 复制代码

1<dependency>
2<groupId>com.mysqlgroupId>
3<artifactId>mysql-connector-jartifactId>
4<scope>runtimescope>
5dependency>

场景4：Bean 初始化失败

现象：

启动日志报错：

go 复制代码

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：数据库连接失败

现象：

启动日志报错：

go 复制代码

ERROR 12345 --- [           main] com.zaxxer.hikari.pool.HikariPool        : HikariPool-1 - Exception during pool initialization.
com.mysql.cj.jdbc.exceptions.CommunicationsException: Communications link failure

原因：

数据库地址/端口/用户名/密码错误；
数据库服务没启动；
防火墙禁止应用访问数据库；
数据库连接 URL 格式错误。

解决方法：

核对配置文件里的数据库参数：

go 复制代码

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

测试数据库连通性：

go 复制代码

1# 用 mysql 客户端测试
2mysql -h192.168.1.100 -P3306-u root -p123456

检查数据库服务状态（Linux）：

go 复制代码

1systemctl status mysqld  # 查看 MySQL 是否启动

场景6：启动类错误

现象：

启动后无响应，或报错"找不到主类"：

go 复制代码

Error: Could not find or load main class com.xxx.SpringbootDemoApplication
Caused by: java.lang.ClassNotFoundException: com.xxx.SpringbootDemoApplication

原因：

主启动类没加 @SpringBootApplication 注解；
打包插件配置错误，没指定主类；
主类包名/类名写错。

解决方法：

主启动类必须加 @SpringBootApplication：

go 复制代码

1@SpringBootApplication
2publicclassSpringbootDemoApplication{
3publicstaticvoidmain(String[] args){
4SpringApplication.run(SpringbootDemoApplication.class, args);
5}
6}

核对 pom.xml 里的打包插件配置：

go 复制代码

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 排障实战技巧，从入门到精通～