SpringBoot常见问题排查手册：启动失败、依赖冲突与404错误

fanxbl957

于 2025-03-29 11:24:33 发布

阅读量909

点赞数 14

CC 4.0 BY-SA版权

分类专栏： Web 文章标签： spring boot 后端 java

本文链接：https://blog.youkuaiyun.com/ashyyyy/article/details/146643090

Web 专栏收录该内容

401 篇文章

订阅专栏

🎓博主介绍：Java、Python、js全栈开发 “多面手”，精通多种编程语言和技术，痴迷于人工智能领域。秉持着对技术的热爱与执着，持续探索创新，愿在此分享交流和学习，与大家共进步。
📖DeepSeek-行业融合之万象视界(附实战案例详解100+)
📖全栈开发环境搭建运行攻略：多语言一站式指南(环境搭建+运行+调试+发布+保姆级详解)
👉感兴趣的可以先收藏起来，希望帮助更多的人

SpringBoot常见问题排查手册：启动失败、依赖冲突与404错误

一、引言

Spring Boot 作为一款广泛应用的 Java 开发框架，极大地简化了 Spring 应用的搭建和开发过程。然而，在实际开发中，开发者难免会遇到各种问题，其中启动失败、依赖冲突和 404 错误是比较常见的。本文将详细介绍这些问题的排查方法，帮助技术人员快速定位并解决问题。

二、Spring Boot 启动失败问题排查

2.1 配置文件错误

Spring Boot 的配置文件（如 application.properties 或 application.yml）是应用启动的重要依据，如果配置文件存在错误，可能会导致启动失败。

2.1.1 语法错误

在 application.yml 中，语法要求比较严格，缩进、冒号等都需要正确使用。例如，以下代码存在缩进错误：

server:
port: 8080  # 错误：port 应该有缩进

正确的写法应该是：

server:
  port: 8080

2.1.2 配置项缺失或错误

某些必要的配置项缺失或配置错误也会导致启动失败。比如，连接数据库时，数据库连接信息配置错误：

spring.datasource.url=jdbc:mysql://localhost:3306/mydb
spring.datasource.username=root
spring.datasource.password=wrongpassword  # 错误的密码

2.2 依赖问题

依赖冲突或缺失可能会导致启动失败。

2.2.1 依赖缺失

如果项目中缺少必要的依赖，Spring Boot 可能无法正常启动。例如，使用 Spring Data JPA 时，缺少 spring-boot-starter-data-jpa 依赖：

<!-- 缺少此依赖 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

2.2.2 依赖冲突

不同版本的依赖可能会存在冲突，导致启动失败。可以使用 Maven 的 dependency:tree 命令查看依赖树，找出冲突的依赖：

mvn dependency:tree

然后通过排除冲突的依赖来解决问题，例如：

<dependency>
    <groupId>com.example</groupId>
    <artifactId>example-library</artifactId>
    <version>1.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>conflicting-group</groupId>
            <artifactId>conflicting-artifact</artifactId>
        </exclusion>
    </exclusions>
</dependency>

2.3 端口被占用

如果 Spring Boot 应用指定的端口已经被其他应用占用，启动时会抛出端口被占用的异常。可以通过以下步骤解决：

2.3.1 查看端口占用情况

在 Windows 系统中，可以使用以下命令查看端口占用情况：

netstat -ano | findstr :8080

在 Linux 或 macOS 系统中，可以使用以下命令：

lsof -i :8080

2.3.2 释放占用的端口

如果发现端口被占用，可以通过任务管理器（Windows）或 kill 命令（Linux 或 macOS）来释放占用的端口。例如，在 Linux 系统中，使用以下命令杀死占用 8080 端口的进程：

kill -9 <进程 ID>

2.3.3 修改应用端口

如果无法释放占用的端口，可以修改 Spring Boot 应用的端口。在 application.properties 中添加以下配置：

server.port=8081

三、依赖冲突问题排查

3.1 版本冲突

不同版本的依赖可能会存在兼容性问题，导致应用出现各种异常。

3.1.1 手动指定版本

可以手动指定依赖的版本，避免使用默认的版本。例如：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>2.5.4</version>
</dependency>

3.1.2 使用 Spring Boot 依赖管理

Spring Boot 提供了依赖管理功能，可以统一管理依赖的版本。在 pom.xml 中添加以下配置：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.5.4</version>
</parent>

3.2 传递依赖冲突

有些依赖会引入其他依赖，这些传递依赖可能会与项目中的其他依赖冲突。

3.2.1 排除传递依赖

可以通过排除传递依赖来解决冲突。例如：

<dependency>
    <groupId>com.example</groupId>
    <artifactId>example-library</artifactId>
    <version>1.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>conflicting-group</groupId>
            <artifactId>conflicting-artifact</artifactId>
        </exclusion>
    </exclusions>
</dependency>

3.2.2 使用依赖分析工具

可以使用 Maven 的 dependency:analyze 命令来分析依赖情况，找出未使用的依赖和冲突的依赖：

mvn dependency:analyze

四、404 错误问题排查

4.1 控制器映射问题

404 错误通常是由于请求的 URL 没有对应的控制器方法处理导致的。

4.1.1 检查控制器注解

确保控制器类使用了 @RestController 或 @Controller 注解，并且方法使用了 @RequestMapping、@GetMapping 等注解。例如：

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, World!";
    }
}

4.1.2 检查请求路径

确保请求的路径与控制器方法的映射路径一致。例如，请求 http://localhost:8080/hello 才能访问上述控制器方法。

4.2 静态资源问题

如果请求的是静态资源（如 HTML、CSS、JavaScript 文件），可能会因为静态资源配置问题导致 404 错误。

4.2.1 检查静态资源目录

Spring Boot 默认的静态资源目录是 src/main/resources/static。确保静态资源文件放在该目录下。

4.2.2 配置静态资源映射

如果需要自定义静态资源映射，可以在 application.properties 中添加以下配置：

spring.mvc.static-path-pattern=/static/**
spring.resources.static-locations=classpath:/custom-static/

4.3 过滤器或拦截器问题

过滤器或拦截器可能会拦截请求，导致请求无法到达控制器。

4.3.1 检查过滤器或拦截器配置

确保过滤器或拦截器的配置正确，不会误拦截请求。例如，以下是一个简单的过滤器配置：

import javax.servlet.*;
import javax.servlet.annotation.WebFilter;
import java.io.IOException;

@WebFilter(urlPatterns = "/*")
public class MyFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        // 过滤逻辑
        chain.doFilter(request, response);
    }
}

五、总结

本文详细介绍了 Spring Boot 常见的启动失败、依赖冲突和 404 错误的排查方法。通过对配置文件、依赖、端口、控制器映射、静态资源和过滤器等方面的检查，可以快速定位并解决这些问题。在实际开发中，遇到问题时要冷静分析，逐步排查，相信通过本文的方法，技术人员可以更高效地解决 Spring Boot 开发中的问题。