项目本地启动失败该怎么办

1、JDK 版本是否设置正确#

检查 IDEA 中 Project SDK 是否与项目要求的 JDK 版本一致。

如果不一致，可以在 File → Project Structure → Project SDK 中修改。

2、是否使用正确的方式启动#

SpringBoot 项目不一定就是直接运行启动类来启动。

如何判断：

如果启动类继承了 SpringBootServletInitializer 类，说明这个项目采用的是外置容器（如 Tomcat）的部署方式，不是通过内嵌容器直接启动的：

1
@SpringBootApplication
2
public class YourApplication extends SpringBootServletInitializer {
3
    @Override
4
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
5
        return application.sources(YourApplication.class);
6
    }
7

8
    // 可选：保留 main 方法，便于本地用内嵌容器直接运行测试
9
    public static void main(String[] args) {
10
        SpringApplication.run(YourApplication.class, args);
11
    }
12
}

这种情况，需要先配置外置容器（如配置 Tomcat），然后通过容器来启动项目。

如果不确定项目应该怎么启动，直接问同事。

3、多配置文件，确保使用正确的配置文件启动#

很多项目有多个环境配置文件，比如：

• application-dev.yml：开发环境
• application-prod.yml：生产环境

确保你激活的是本地开发环境的配置。如果用错了配置文件，可能会连接到错误的数据库或中间件。

4、项目启动需要使用的中间件，确保本地网络可以访问#

项目启动可能依赖以下中间件，确保它们已经启动并且网络可达：

• MySQL
• Redis
• RabbitMQ / Kafka
• Elasticsearch
• Nacos / 注册中心

1、拒绝连接#

1
Connection refused
2
java.net.ConnectException: Connection refused

原因： 本地无法连接到目标服务（比如数据库、Redis、中间件等）。

排查方式：

使用 telnet 命令检测具体的 IP 和端口是否通畅：

1
telnet <IP> <端口>

如果 telnet 不通，说明目标服务没有启动，或者网络不通。

2、类找不到#

1
ClassNotFoundException
2
NoClassDefFoundError
3
java.lang.NoSuchMethodError

原因： 明明存在这个类，但运行时却说找不到，基本就是缓存问题。

解决方式：

1. 清除 IDEA 缓存并重启（File → Invalidate Caches → Invalidate and Restart）
2. 在 Maven 面板中 clean 整个工程
3. 再 install 整个工程

3、端口被占用#

1
Web server failed to start. Port XXXX was already in use.

原因： 项目要使用的端口已经被其他程序占用了。

解决方式：

使用如下命令查看端口是否被占用：

1
netstat -ano | findstr :8080

找到占用端口的进程 PID 后，可以使用以下命令结束进程：

1
taskkill /PID <进程ID> /F

或者直接在 IDEA 的启动配置中把端口号改成其他未被占用的端口。

4、配置属性错误#

1
ConfigurationPropertiesBindException
2
IllegalArgumentException: Could not resolve placeholder 'xxx' in value "${xxx}"

原因： 配置文件中的属性值格式错误、类型不匹配或引用了一个不存在的属性。

排查方式：

检查 application.yml 或 application.properties 中对应的配置项，确认属性名是否正确、值是否符合要求。