Spring Boot 项目创建 + 启动排错指南

Spring Boot 项目创建 + 启动排错指南

新手必看！Spring Boot 项目创建不难，难的是「创建后启动报错」——这是绝大多数零基础学习者都会遇到的入门难题。

明明跟着教程一步步点击操作，控制台却突然弹出一堆红色报错日志，看不懂也找不到问题根源；要么看似启动成功，打开浏览器输入地址却始终访问失败，反复尝试却越排错越懵😵💫，最后直接放弃入门。

这篇推文，专门针对新手痛点优化，不冗余、不绕弯、不堆砌专业术语，先手把手教你「3分钟快速创建Spring Boot项目」，全程鼠标操作无需敲命令，再详细拆解「80%新手会遇到的启动报错」，每个报错都附上清晰的原因分析和一步到位的解决方案，新手看完直接就能搞定，轻松跨过入门第一道坎！

适配人群：Spring Boot 零基础新手、项目启动报错不会排查的同学、曾多次尝试搭建却屡屡失败的学习者（全程实操导向，小白也能轻松看懂、跟着落地）

前置准备（极简版，不啰嗦）

项目创建和启动前，一定要提前配置好基础环境，环境无误才能避免后续大部分报错，启动更顺畅，大家直接照搬下面的版本即可，无需盲目追求最新版👇

• JDK：1.8（优先选择Java 1.8版本，兼容性拉满，能适配所有Spring Boot稳定版，新手切记避开JDK 17及以上版本，很多老依赖和教程不兼容，容易踩坑）
• Maven：3.6.3（作为Spring Boot项目的依赖管理核心工具，这个版本稳定性最佳，且需提前配置好阿里云镜像，能大幅提升依赖下载速度，避免下载超时、卡顿问题）
• IDE：IDEA 社区版（免费且功能完全够用，新手无需追求专业版，安装简单、操作友好，内置Spring Boot项目创建模板，能省去很多手动配置步骤）
• Spring Boot：2.7.x（新手首选稳定版，避开3.x版本，该版本部分语法、依赖和配置有较大变化，会大幅增加新手入门难度，先掌握2.7.x版本再升级更稳妥）

重点提醒：JDK、Maven 的环境变量必须提前配置完成并验证成功（没配好或配错的，可以查看我之前的这篇文章: Spring Boot 新手环境搭建超详细指南（避坑版）

第一部分：3分钟创建 Spring Boot 项目（IDEA 实操，全程鼠标操作）

针对零基础新手，全程无需敲一行命令，所有操作都用鼠标点击完成，步骤清晰、节奏舒缓，大家直接跟着点，就能快速创建成功👇

步骤1：新建项目，选择合适的模板

首先打开已经安装好的IDEA社区版，进入首页后，点击左上角的「New Project」（新建项目）；在弹出的页面中，左侧导航栏找到并选中「Spring Initializr」（这是Spring官方提供的项目初始化模板，新手首选）；右侧默认选择「Default」（对应的地址是https://start.spring.io/，无需手动修改），确认无误后，点击右下角的「Next」进入下一步。

步骤2：填写项目基础信息（默认即可，无需修改）

这一步主要填写项目的基本标识信息，新手无需手动修改，保持系统默认配置即可，重点确认「Java Version」（Java版本）选择「8」，这是适配Spring Boot 2.7.x版本的关键，确认无误后，点击「Next」进入依赖选择环节。

（可选优化：Artifact 选项可修改为自己喜欢的项目名，比如 spring-boot-first、spring-boot-demo，注意项目名不要包含中文、空格和特殊符号，避免后续出现路径相关报错）

步骤3：选择依赖（只勾1个，新手完全够用）

依赖是项目运行的核心支撑，但新手无需勾选过多依赖，避免出现依赖冲突、启动报错的问题。在左侧导航栏点击「Web」选项，右侧会弹出对应的Web相关依赖，找到并勾选「Spring Web」（重点提醒：别选错！ Spring Boot 2.7.x版本对应的就是这个依赖，选错会导致后续项目无法正常启动），勾选完成后，点击「Next」进入下一步。

避坑提醒：不要贪心勾选过多依赖，比如同时勾选Web、数据库、缓存等依赖，新手对依赖之间的兼容性不了解，很容易出现依赖冲突，导致项目启动失败，先勾选1个Spring Web依赖，能正常启动项目即可。

步骤4：确认路径，完成项目创建

这一步是关键避坑点，主要选择项目的保存路径：点击「Location」右侧的文件夹图标，选择电脑中的合适路径（核心要求：路径中不能有中文、不能有空格，比如可选择D:\spring-boot-project\spring-boot-first，避免中文路径导致项目无法识别）；路径确认无误后，点击右下角的「Finish」，即可开始创建项目。

点击Finish后，IDEA会自动加载项目，并根据我们提前配置的阿里云镜像，下载Spring Web相关依赖，等待1-3分钟（下载速度取决于网络状况，阿里云镜像能大幅提速，避免国外镜像下载超时），当右下角的下载进度条走完，且项目结构中没有红色报错标识，就说明项目创建成功了。

步骤5：快速核对项目结构（避免创建失败，提前排查问题）

项目创建成功后，新手无需纠结所有文件夹的作用，重点核对2个核心文件，只要这2个文件存在且无报错，就说明项目创建无误，后续可以正常启动👇

1. 启动类：xxxApplication.java（类名由我们之前填写的Artifact决定，比如spring-boot-firstApplication，该类上会带有@SpringBootApplication注解，这是Spring Boot项目的核心启动入口，缺一不可）
2. 配置文件：resources文件夹下的application.properties（默认是空白文件，后续我们可以在这个文件中配置端口、数据库等信息，当前阶段无需修改，只要文件存在即可）

第二部分：项目启动 + 高频报错排错（核心重点，新手必看）

项目创建好后，启动步骤非常简单，但报错率极高，很多新手就是卡在这一步。下面先教大家正确的启动操作，再逐一拆解80%新手会遇到的4个高频启动报错，每个报错都附上清晰的原因分析和一步到位的解决方案，不用百度，对照排查就能快速解决！

第一步：启动项目（正确操作，避免误操作导致报错）

1. 找到项目启动类：在IDEA左侧的项目结构中，展开src → main → java → 对应的包路径，找到带有@SpringBootApplication注解的启动类（xxxApplication.java）；
2. 启动项目：右键点击这个启动类，在弹出的菜单中，选择「Run 'xxxApplication'」（第一个选项，带有运行图标），点击后即可开始启动项目；
3. 判断启动成功：启动过程中，重点观察下方的控制台窗口，如果控制台没有出现任何红色报错日志，且最后一行显示「Started xxx in xxx seconds (JVM running for xxx)」（xxx为具体时间），就说明项目启动成功了！

第二步：4个高频启动报错（附原因+解决方案，一步解决）

下面这4个报错，是80%新手启动Spring Boot项目时都会遇到的，每个报错都清晰说明「报错原因」和「具体解决方案」，新手遇到后，直接对照自己的报错信息，一步步操作，就能快速排查解决，不用浪费时间百度！

报错1：Could not find or load main class（找不到主类）

✅ 报错原因：最常见的报错之一，主要是两个原因导致——要么JDK环境变量配置错误、未生效，要么IDEA未正确识别到本地配置的JDK，导致无法找到项目的启动主类。

✅ 解决方案（按顺序操作，优先排查环境变量）：

1. 重启IDEA和cmd命令行，先重新验证JDK是否配置成功：打开cmd（Win+R输入cmd回车），输入「java -version」和「javac -version」两个命令，若都能正常显示JDK 1.8版本，说明环境变量配置无误；若报错，需重新配置JDK环境变量；
2. 若JDK验证成功，再在IDEA中重新配置JDK：点击顶部菜单栏的File → Project Structure → 左侧选中SDKs → 点击右上角的「+」，选择本地JDK 1.8的安装路径，配置完成后点击Apply → OK，再重启项目即可。

报错2：Maven 依赖下载失败（redownload failed）

✅ 报错原因：核心原因是Maven的阿里云镜像未配置、配置错误，或者镜像地址失效，导致依赖无法从仓库下载，出现下载超时、下载失败的问题；也可能是网络不稳定，导致依赖下载中断。

✅ 解决方案（步骤清晰，复制即用，新手也能操作）：

1. 打开本地Maven的安装路径，找到conf文件夹，用记事本或IDEA打开里面的settings.xml文件，核对「mirrors」标签内的阿里云镜像配置是否正确；
2. 若配置错误或未配置，直接复制下面的代码，粘贴到「mirrors」标签内（替换原有错误配置，确保标签闭合）：

<mirror> 
<id>aliyunmaven</id>  
<mirrorOf>central</mirrorOf>  
<name>阿里云公共仓库</name>  
<url>https://maven.aliyun.com/repository/public</url>  
</mirror>

3. 配置完成后，保存settings.xml文件，回到IDEA，右键点击项目 → 选择Maven → Reload Project（重新加载项目依赖），等待依赖重新下载完成，再启动项目即可。

报错3：端口被占用（Port 8080 was already in use）

✅ 报错原因：Spring Boot项目默认使用8080端口启动，若当前电脑中，有其他程序（比如Tomcat服务器、其他正在运行的Spring Boot项目、聊天软件等）占用了8080端口，就会出现这个报错，导致项目无法启动。

✅ 解决方案（2种方法，选一种即可，新手优先选简单版）：

1. 简单版（快速解决，适合临时使用）：关闭占用8080端口的程序，比如关闭其他正在运行的项目、退出占用端口的软件，关闭完成后，重启当前Spring Boot项目，即可正常启动；
2. 永久版（一劳永逸，避免后续重复报错）：修改当前项目的启动端口，打开resources文件夹下的application.properties空白文件，添加一行代码：server.port=8081（可修改为8081、8082等未被占用的端口），保存后重启项目，即可使用新端口启动。

报错4：启动成功，但浏览器访问失败（Connection refused）

✅ 报错原因：这种情况比较特殊，项目看似启动成功（控制台无红色报错），但浏览器访问时提示“Connection refused”（连接被拒绝），主要原因有3个——端口修改后未重启项目、浏览器访问路径错误，或项目未正确添加Spring Web依赖。

✅ 解决方案（逐一排查，快速定位问题）：

1. 优先排查项目是否重启：若之前修改过项目端口，必须重启项目，端口修改才能生效，未重启的话，浏览器访问旧端口会提示连接失败；
2. 核对浏览器访问路径：正确路径是http://localhost:端口号（端口号是项目启动的端口，默认8080，修改后为8081或其他），不要多输多余字符（比如多输“/”“web”等），也不要少输端口号；
3. 检查Spring Web依赖是否添加成功：点击IDEA顶部菜单栏的File → Project Structure → 左侧选中Libraries，在右侧列表中，确认有spring-web、spring-boot-starter-web相关依赖，若没有，说明依赖下载失败或未勾选，重新勾选依赖并下载即可。

补充说明：很多新手会误以为“启动成功后，浏览器访问显示白页”是报错，其实这是正常现象！因为我们只创建了项目、添加了Web依赖，还没有编写任何接口，浏览器访问后没有对应的资源可以展示，就会显示「白页（Whitelabel Error Page）」，后续编写第一个接口后，就能正常访问了。

第三部分：新手必看总结（提炼核心，避免重复踩坑）

1. 项目创建核心：重点记住两个关键点——「项目保存路径无中文、无空格」「只勾选Spring Web一个依赖」，依赖下载完成后再启动项目，能避免80%的创建类问题；

2. 启动排错逻辑：遇到启动报错，不要慌乱，优先排查3个核心点——「JDK/Maven环境变量是否配置正确」「8080端口是否被占用」「Spring Web依赖是否下载成功」，对照本文的4个高频报错，逐一排查就能快速解决；

3. 新手避坑提醒：环境配好、步骤没错，项目启动基本不会报错；不要盲目追求最新版本，稳定版才是新手的最优选择；遇到报错不要急于百度，先观察控制台的报错信息，对照本文排查，效率更高。

环境搭建和项目启动，是Spring Boot入门的第一步，跨过这一步，后续的学习会越来越顺畅。后续我会持续更新「Spring Boot 第一个接口编写」「数据库连接配置」等新手教程，关注不迷路，新手也能快速上手Spring Boot开发，一步步成长为Java开发者👇