企业官网建设流程全解析

第一次在 IDEA 里用 Gradle 创建 Spring Boot 项目，卡在下载上半小时，最后弹一句could not install gradle distribution from reason: java.net.sockettimeoutexc然后直接劝退的人真的太多了。这个报错跟代码一毛钱关系都没有，纯粹是 Gradle 发行包压根没下载下来。这篇不是从官网截一堆图的那种新手教程，而是把从 Gradle 安装、镜像加速、IDEA 配置、到项目能跑通的全链路走一遍，重点解释每一步为什么这么做，以及过程中最常见的几个坑怎么排查。看完你就能很顺畅地搭出第一个能用 IDEA 跑起来的 Spring Boot 项目，后面再遇到类似报错也不会慌。

1. 先用30秒说清Gradle和Spring Boot到底是什么关系

1.1 构建工具和开发框架不是二选一

很多人在搜索“gradle项目和springboot项目区别”，其实这两个东西根本不在同一个维度上，不存在二选一的关系。

Gradle 是构建工具，负责的事是编译源码、下载第三方依赖、执行测试、打 jar/war 包，类似 Maven 的角色。Spring Boot 是一个开发框架，帮你快速搭建 Web 应用，内置了 Tomcat、自动配置、健康检查这些能力。你的 Spring Boot 项目可以用 Maven 构建，也可以用 Gradle 构建，只要把构建脚本重写一遍，src下面的代码结构完全不用变。反过来，一个 Gradle 项目也可以完全不用 Spring Boot，只写普通 Java 库。

所以当你看到“Gradle 项目”和“Spring Boot 项目”这两个词被放在一起比较时，正确的理解是：这是两个正交的选择——一个是决定怎么构建，一个是决定用什么框架。

1.2 什么场景下建议用Gradle

我用 Gradle 的时间不算短，但说实话，它并不是在任何场景下都比 Maven 好。Gradle 的优势在三方面比较明显：

• 构建脚本写起来简单。Maven 的 XML 配置太长，Gradle 用 Groovy 或 Kotlin DSL，几行就能搞定依赖和插件配置。
• 增量构建能力强。第二次、第三次构建通常比 Maven 快不少，因为它会缓存每个 task 的输入输出，只有文件变动了才重新执行。
• 构建缓存和并行任务调度做得更好，多模块项目里优势尤其突出。

但它的缺点也很直接：如果你所在团队没人用过 Gradle，学习成本得算进去；Gradle 第一次构建往往比 Maven 还慢，因为要下载发行包、初始化 daemon 进程、编译脚本，这些时间开销在前面等着。

我的建议是：Android 开发者转 Java 后端、平时做多模块项目、或者对构建速度有硬要求的人，直接上 Gradle 是划算的。如果只是写个快速验证的小项目，Maven 更省心。但既然你已经决定学 Gradle，那现在踩坑建立正确环境，比以后项目复杂了再返工要好得多。

2. 环境准备：Gradle 不是让 IDEA 自动下载的

2.1 先确定 Java 版本，再看 Gradle 版本

这一步很多人上来就跳过，最后项目起不来才回头查。Gradle 和 Java、Spring Boot 三者之间存在版本兼容关系，选错组合最常见的报错就是Unsupported class file major version，意思是当前 Gradle 版本不认你这个 JDK 编译出来的 class 文件。

我常用的搭配是下面这个表，正常来说够用：

注意这个表不是官方兼容矩阵的完整版，只是我实际项目里用过且稳定的组合。如果你想换其他版本组合，务必去 Gradle 官网看当前版本的 compatibility matrix，这个文档写得很清楚。尤其是 JDK 21 刚出来那阵子，一堆人用 Gradle 8.4 以下版本跑 Java 21 项目，直接报错，然后怀疑人生。

另外，Spring Boot 版本和 Gradle 插件版本也有关。Spring Boot 官方维护了一个spring-boot-gradle-plugin，不同 Spring Boot 版本对 Gradle 版本有最低要求，Spring Boot 3.x 基本要求 Gradle 7.5 以上。版本太老的话，插件会直接告诉你当前 Gradle 版本不支持。

2.2 手动下载并安装 Gradle

为什么我强调“不要让 IDEA 自动下载”？因为 IDEA 在新建项目时如果检测不到合适的 Gradle，会自动去官方服务器下载发行包，这个下载在国内经常会超时，然后就出现开头那个SocketTimeoutException。

建议你自己手动下载一次，一劳永逸：

1. 打开 Gradle 官网的 release 页面，找当前稳定版本，下载binary-only包就够了，不用下载complete包，那个带着源码和文档，大而且没用。
2. 解压到一个路径里没有中文、没有空格的目录，比如D:\tools\gradle-8.7。
3. 配置环境变量：
   • 新建GRADLE_HOME，值为D:\tools\gradle-8.7
   • 在PATH末尾追加%GRADLE_HOME%\bin
4. 新开一个命令行窗口，输入gradle -v，能输出版本信息就说明安装成功。

另外我强烈建议顺手配置一个GRADLE_USER_HOME。这个目录默认在用户主目录下的.gradle，里面存放的是依赖缓存、Wrapper 发行包、构建日志，时间长了能有几个 G。放在 C 盘会很痛苦，我一般把它指到D:\tools\gradle-repo。方法是在系统环境变量里新增GRADLE_USER_HOME，路径自定义即可。

配置好GRADLE_USER_HOME还有一个直接好处：如果你想离线复用依赖，把整个gradle-repo目录打包拷到另一台机器，再配上同一个环境变量路径，新机器上 Gradle 构建时就基本不会再重复下载依赖了，这在某些网络不太稳定的环境里特别管用。

2.3 Wrapper 是什么，为什么 IDEA 更喜欢它

Gradle Wrapper 是 Gradle 官方推荐的项目级 Gradle 分发机制。每个通过正式方式创建的 Gradle 项目都带一个gradle/wrapper/gradle-wrapper.properties文件，里面声明了项目固定使用哪个版本的 Gradle。开发者不需要在本机预先安装相同版本的 Gradle，只要执行项目下的gradlew或gradlew.bat，Wrapper 会自动去下载对应版本的 Gradle 发行包，然后运行构建。

这套机制解决的最大问题是团队协作一致性。你本机是 Gradle 8.7，同事本机是 Gradle 7.6，如果是直接用系统命令构建，会出现两边行为不一致的诡异问题。用 Wrapper 之后，大家都按项目配置文件里的版本执行，保持统一。

IDEA 在打开 Gradle 项目时默认就是走 Wrapper 的，它会读取gradle-wrapper.properties然后决定用哪个 Gradle。这也意味着如果你在 IDEA 里新建项目时选了使用 Wrapper，IDE 会先去找本地缓存里有没有对应版本的 Gradle，没有就会开始下载——这又回到下载超时的问题了。所以正确姿势是，先手动安装好本地 Gradle，再在 IDEA 里配置好，让 IDEA 优先能识别到它。

关于本地 Gradle 和 Wrapper 版本不一致引发的坑，我在第 6 章专门讲，这里先记住一个原则：命令行统一用./gradlew，IDEA 里的 Gradle 设置选择gradle-wrapper.properties对应的分发版本，不要让 DevTools 和本地安装的 Gradle 版本互相打架。

3. 卡在下载？先把国内镜像配好再动手

3.1 两个层面的下载问题

Gradle 项目跑不起来，绝大多数情况不是代码问题，而是网络问题。这里的下载分成两个层面：

第一个层面是 Gradle 发行包本身，几百 MB，如果走官方services.gradle.org的下载地址，在国内经常超时。这就是could not install gradle distribution报错的根源。第二个层面是项目依赖，也就是 Spring Boot、Tomcat、Jackson 这些 jar 包，默认从 Maven Central 下载，Central 在国内时快时慢，慢起来也是各种超时。

解决思路也是两层：发行包层面用国内镜像或本地安装，依赖层面用阿里云等 Maven 镜像仓库。

3.2 给 Gradle 发行包加速的三种方式

第一种方式：IDEA 里指定本地 Gradle。打开Settings -> Build, Execution, Deployment -> Build Tools -> Gradle，在Distribution那一栏选择Local installation，然后填你自己解压的路径D:\tools\gradle-8.7。这种方式下 IDEA 不会再去下载发行包，加载项目速度会快很多。

第二种方式：修改gradle-wrapper.properties，把distributionUrl换成国内镜像地址。腾讯云镜像有 Gradle 发行包，格式是：

distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip

把gradle-8.7-bin.zip换成对应版本就行。这样即使走 Wrapper，下载速度也完全能接受。改完记得在 IDEA 里点一下刷新，让 Wrapper 配置重新加载。

第三种方式：手动下载发行包放到本地目录，然后手动执行一次gradle wrapper重新生成 Wrapper，或者干脆用第一种方式配置。本质思路都是一样：不走官方下载地址。

我自己一般直接配腾讯云镜像，同时把 IDEA 的 Distribution 也指到本地，双保险。这样即使镜像站偶尔抽风，构建也不受影响。

3.3 给依赖仓库加速的全局配置

依赖下载加速的核心是改仓库地址。最直接的做法是在项目的build.gradle里加镜像源：

repositories { maven { url 'https://maven.aliyun.com/repository/public' } maven { url 'https://maven.aliyun.com/repository/central' } maven { url 'https://maven.aliyun.com/repository/gradle-plugin' } mavenCentral() }

注意顺序很关键。Gradle 会从上往下依次尝试仓库，第一个仓库有的话就用了。把阿里云镜像放在前面，大部分依赖都能从国内直接命中，只有少数冷门依赖才会走到 Maven Central。

但项目级配置只对这个项目生效，你要是新开一个项目又得重新写一遍。更省事的方式是全局配置：在GRADLE_USER_HOME目录下建一个init.d文件夹，里面放一个init.gradle文件（扩展名.gradle也行），内容如下：

allprojects { repositories { maven { url 'https://maven.aliyun.com/repository/public' } maven { url 'https://maven.aliyun.com/repository/central' } maven { url 'https://maven.aliyun.com/repository/gradle-plugin' } mavenCentral() } }

这样所有通过该GRADLE_USER_HOME运行的 Gradle 项目，都会自动带上这三个镜像源，不用每个项目单独配置。唯一的坑是，init.d里的配置是全局的，在某些情况下会覆盖项目里的仓库配置，如果你遇到“我明明改了 build.gradle 的仓库地址却不起作用”的情况，优先怀疑一下这里。

配置完镜像之后，建议先把GRADLE_USER_HOME里的caches目录旧缓存清掉再重新构建，免得之前下载失败的半截文件继续报错。

4. IDEA 里创建 Gradle 项目：这些选项我建议你这么选

4.1 社区版没有 Spring Initializr，怎么建 Spring Boot 项目

IDEA 分社区版和旗舰版。旗舰版（Ultimate）新建项目向导里直接有 Spring Initializr 选项，勾一下就生成一个标准的 Spring Boot 项目，非常省事。社区版（Community）免费，但默认没有这个 Spring Initializr 入口。

如果只有社区版，也不要觉得被卡住。办法有两个：

第一个办法是打开 Spring 官方站点 start.spring.io，在网页上选好 Spring Boot 版本、构建工具（这里选 Gradle）、Java 版本、依赖（比如 Spring Web），然后点生成，会下载一个 zip 包。解压之后，用 IDEA 直接打开这个文件夹，IDEA 会识别出里面的build.gradle和settings.gradle，作为 Gradle 项目导入。

第二个办法是直接在 IDEA 里新建空 Gradle 项目，然后手动往build.gradle里添 Spring Boot 插件和依赖。这个方法稍微麻烦一点，但对于想搞明白项目结构的新手来说反而更有帮助。下面章节里的例子就是用这个方式手动写出来的。

4.2 新建项目向导里的关键选项

如果你的 IDEA 是旗舰版，直接 New Project 然后选 Spring Initializr，能少走很多弯路。创建过程中有两个选项需要特别留意：

一个是Build script DSL。这里会让你选Groovy DSL还是Kotlin DSL。Groovy DSL 对应的构建文件名是build.gradle，Kotlin DSL 对应的是build.gradle.kts。我建议新手先选 Groovy DSL，因为它出现时间更长，网上能找到的资料、代码片段基本都是 Groovy 语法，遇到问题好搜好解决。你是 Kotlin 重度用户再考虑 Kotlin DSL 不迟。

另一个是JDK下拉框。IDEA 会列出本机已安装的所有 JDK 版本，你选哪一个都行，但要注意版本范围是否在 Spring Boot 和 Gradle 的支持范围内。比如选 JDK 21，那 Gradle 必须 8.5 以上，Spring Boot 最好 3.2 以上，这个链条我在 2.1 节说过。

创建完成之后，IDEA 下方会有一个 Gradle 同步的进度条，第一次会很慢，因为要解析插件和下载依赖。如果一直卡着不动，八成是仓库网络问题，回到第 3 章把镜像配好，然后点右侧 Gradle 面板里的刷新按钮重新同步。

4.3 Project SDK 与 Gradle JVM 不一致的隐患

很多人项目起不来，最后发现是 IDEA 里有两个 Java 设置，一个叫 Project SDK，一个叫 Gradle JVM，两者不一样。

Project SDK 是当前项目的语言级别和编译目标，Gradle JVM 是 Gradle 进程本身运行时所使用的 JDK。如果 Gradle JVM 是 JDK 17，但你 Project SDK 选了 JDK 21，某些情况下 Gradle 会以 Gradle JVM 为准进行编译，这时如果你 Project SDK 的 language level 和实际编译目标不一致，就会产生奇怪报错，比如invalid source release。

设置位置在Settings -> Build, Execution, Deployment -> Build Tools -> Gradle，下面的Gradle JVM下拉框。建议直接让它跟随 Project SDK，或者两个都选同一个 JDK。这个一致性设定花不了你十秒，但能省掉后面大量的排错时间。

5. 把 build.gradle 补全，跑通第一个接口

5.1 最小可用的 build.gradle

如果你是通过 start.spring.io 生成的项目，build.gradle内容已经完整，可以直接跳到 5.2 看目录结构。如果是自己新建的空白 Gradle 项目，就要手动把下面这份配置写进去：

plugins { id 'java' id 'org.springframework.boot' version '3.2.5' id 'io.spring.dependency-management' version '1.1.4' } group = 'com.example' version = '0.0.1-SNAPSHOT' java { toolchain { languageVersion = JavaLanguageVersion.of(17) } } repositories { maven { url 'https://maven.aliyun.com/repository/public' } mavenCentral() } dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' testImplementation 'org.springframework.boot:spring-boot-starter-test' } tasks.named('test') { useJUnitPlatform() }

逐个解释一下：

plugins块里的java是最基础的 Java 插件，让 Gradle 认识src/main/java目录。org.springframework.boot插件负责处理 Spring Boot 的打包任务和依赖版本管理。io.spring.dependency-management插件会引入 Spring Boot 的 BOM（Bill of Materials），也就是一堆常用第三方库的推荐版本清单，这样你在dependencies里写依赖时不用手动写 version，它会自动选择合适版本。

java.toolchain块指定构建需要的 JDK 版本为 17。这里只要本机装了 JDK 17，Gradle 会自动去找，即使 Project SDK 设成了 JDK 21 也能正常编出来，算是多了一层保护。

dependencies里只加了一个spring-boot-starter-web，它会把 Spring MVC、内嵌 Tomcat、Jackson 序列化等一堆东西全带进来，这就是 Spring Boot 的“起步依赖”设计——你加一个，全家桶到位。

5.2 目录结构、启动类和 Controller

Spring Boot 项目的标准目录结构长这样：

my-demo/ ├── build.gradle ├── settings.gradle ├── gradle/ │ ├── wrapper/ │ │ ├── gradle-wrapper.jar │ │ └── gradle-wrapper.properties ├── gradlew ├── gradlew.bat └── src/ ├── main/ │ ├── java/ │ │ └── com/example/demo/ │ │ ├── DemoApplication.java │ │ └── controller/HelloController.java │ └── resources/ │ └── application.properties └── test/ └── java/

settings.gradle这个文件也很重要，里面至少要有项目名，类似：

rootProject.name = 'my-demo'

DemoApplication.java是整个应用的入口，必须有@SpringBootApplication注解：

package com.example.demo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }

这个注解最关键的地方在于它默认会扫描所在包及其子包，找到所有@RestController、@Service、@Repository之类的组件。如果你的启动类放的位置太深或者太浅，扫描范围不对，Controller 就不会被注册。新手最容易犯的错就是把启动类丢到和 Controller 同一个包外面，结果访问接口 404。

然后写一个最简单的 Controller 验证链路：

package com.example.demo.controller; 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 from Gradle Spring Boot"; } }

运行方式有两种：IDEA 里直接打开DemoApplication，点击旁边的绿色三角形运行；或者在项目根目录命令行执行gradlew bootRun。后者用的就是 Wrapper，第一次可能下载东西，之后都是直接用。我用 IDEA 跑更多，因为方便打断点调试，但命令行方式可以让你确认“不依赖 IDE 也能启动”，排查问题时很有用。

5.3 启动后“不显示端口号”的真实原因

很多人在 IDEA 里点启动后，控制台只看到 Spring Boot 的大 Banner，却看不到熟悉的Tomcat started on port 8080这一行，以为是项目出问题了。实际上应用很可能已经正常跑起来了，你直接访问http://localhost:8080/hello能通，那就不用慌。

看不到日志最常见的三个原因：

第一个原因是 IDEA 控制台的日志过滤。IDEA 控制台右上角或工具栏有个 filter 下拉，如果当前过滤级别把 INFO 日志隐藏了，Tomcat 启动那一行就会被吞掉。你改成 Show All 或者 All Log 就行。

第二个原因是日志里其实输出了，只是被大量调试日志盖住了。Spring Boot 默认应该显示 INFO 级别，但如果你在application.properties里写了logging.level.root=WARN之类的配置，启动日志就会被压缩，端口号也不打印。把配置删掉或改成 INFO 就好。

第三个原因比较坑：IDEA 的运行窗口显示的是上一次运行进程，不是新启动的进程。尤其是你改了配置后没重新 Run，控制台还是旧的输出。点一下运行窗口左侧的重新运行按钮，或者手动停掉旧的再跑一次就行。

如果控制了以上三点还是没有端口号，那就要去看有没有报错堆栈，尤其是端口被占用的情况，Spring Boot 会在启动阶段直接失败，同时告诉你Port 8080 was already in use。处理方式很直接，换个端口或者杀掉占用进程，在application.properties里写server.port=8081就能改端口。

6. 搭建过程中最常见的五个坑：从报错到根因的排查链路

6.1 SocketTimeoutException：Gradle 发行包下载超时

现象：新建项目时 IDEA 日志窗口提示could not install gradle distribution from reason: java.net.sockettimeoutexc，进度条一直不走，最后构建失败。

根因：IDEA 根据 Wrapper 配置去官方服务器下载 Gradle 发行包，网络连接超时。这不是代码问题，也不是环境配置问题，纯粹是下载源不可达或太慢。

排查顺序：

1. 打开项目里的gradle/wrapper/gradle-wrapper.properties，看distributionUrl是官方地址还是镜像地址。
2. 如果是官方地址，换成https\://mirrors.cloud.tencent.com/gradle/对应的版本。
3. 也可以在 IDEA 的Settings -> Build Tools -> Gradle里把 Distribution 改成Local installation，选择本机已安装的 Gradle 路径，根本不用远程下载。
4. 如果以上都做了还是超时，检查GRADLE_USER_HOME里是否有之前下载失败留下的残留文件，删掉caches目录再重试。

这个坑的原理很简单，解决方式也简单，但因为报错信息里全是英文长路径，第一眼看很容易以为是自己代码或配置写错了。记住一个判断口诀：只要是gradle distribution或者download相关的报错，先怀疑网络，别怀疑代码。

6.2 Java 版本与 Gradle 版本不匹配

现象：构建时报Unsupported class file major version，或者Your build is currently configured to use Java 21.0.4 and Gradle 8.8之类的版本提示，有时候还会直接在插件加载阶段失败。

根因：Gradle 的每个版本都有支持的 Java 版本范围，JDK 版本太新，Gradle 不支持；或者 Gradle 版本太老，跑不了新 JDK。特别常见的是 JDK 21 配 Gradle 8.4 以下版本，必挂。

排查顺序：

1. 命令行执行gradle -v，看当前 Gradle 版本和 JVM 版本。
2. 去 Gradle 官网查当前版本的 Java compatibility matrix，确认支持范围。
3. IDEA 里同时检查Project SDK和Gradle JVM，保证两者一致。
4. 如果用的是 Wrapper，改gradle-wrapper.properties的版本号，升级到支持范围内。
5. 如果不想升 Gradle，就换低版本的 JDK，比如 JDK 17 配 Gradle 7.6 就很稳。

我个人的习惯是，本地装一个 JDK 17 和一个 JDK 21，需要切换时在 IDEA 里改Project SDK就行，Gradle JVM 跟着 Project SDK 走。这样大部分组合都能覆盖。

6.3 依赖解析失败：Could not resolve 开头的一堆报错

现象：报错形如Could not resolve org.springframework.boot:spring-boot-starter-parent:3.2.5，或者Could not resolve gradle:gradle:8.7。

根因：分成两小类。第一类是仓库里找不到这个依赖，可能是坐标写错了，也可能是版本不存在。第二类是网络问题，仓库连不上。至于Could not resolve gradle:gradle:8.7这种，多半是构建脚本或某个插件声明了奇怪的依赖坐标，把 Gradle 自身当成了外部依赖解析，正常项目里不应该出现，重点检查buildscript块是不是有五花八门的 classpath 配置。

排查顺序：

1. 先看报错里要解析的是哪个坐标，复制到浏览器去阿里云 Maven 仓库查存不存在。
2. 如果坐标存在，检查repositories里是否配置了可用的镜像源，顺序是否把阿里云放在了 Maven Central 前面。
3. 如果坐标不存在，回build.gradle检查版本号是否写错。Spring Boot 3.x 的 starter 版本号要和 Spring Boot 插件的版本号一致，不一致就很怪。
4. 针对Could not resolve gradle:gradle，全项目搜索gradle:字样，看有没有多余的插件声明，删掉后重新同步。

这类报错还有一个隐藏原因：Gradle 把之前解析失败的半成品缓存当成了一次结果，所以改完仓库地址之后，最好去GRADLE_USER_HOME\caches\modules-2\files-2.1里找到对应路径删掉，然后重新刷新。

6.4 Gradle 缓存残留导致的反复失败

现象：改了镜像地址、改了依赖版本，刷新无数次，报错还是一模一样，像是改了又没改。

根因：Gradle 的缓存机制太强了。它会把每次构建的中间产物、依赖元数据、动态版本对应的实际版本号都缓存下来。如果你之前解析依赖失败过一次，失败的状态可能也被缓存，导致后续构建不肯重新请求远程仓库。

排查顺序：

1. 项目根目录找.gradle文件夹，这是当前项目的本地状态缓存，可以整个删掉，不影响依赖下载，只是重新构建时要再同步一次。
2. GRADLE_USER_HOME\caches目录是全局依赖缓存，如果确认是仓库地址切换后仍拉旧版本，就按依赖名到modules-2下删对应目录。
3. 在 IDEA 的 Gradle 面板里点刷新或者Reload All Gradle Projects。如果还不行，关掉 IDEA 重新打开，让 Gradle daemon 进程重启。

有些时候，甚至要执行一次./gradlew clean build --refresh-dependencies，其中--refresh-dependencies会强制 Gradle 忽略缓存的动态版本结果，重新请求远程仓库。这是我最常用的兜底命令。

6.5 启动类扫描不到组件：404 和 “没有数据源”的连锁反应

现象：项目构建成功，启动也成功，但访问/hello返回 404；或者在启动时提示找不到DataSourceAutoConfiguration之类的内容。

根因：第一种情况是组件扫描路径问题，@SpringBootApplication默认扫描DemoApplication所在包及子包，如果你的 Controller 放在这个包外面，Spring 容器根本不知道它的存在。第二种情况是spring-boot-starter-web被不小心排除掉了，或者你在@SpringBootApplication(exclude = ...)里排除了某些自动配置类，比如不需要数据源时排除了DataSourceAutoConfiguration，结果日志里全是自动化配置跳过的信息。

排查顺序：

1. 检查包结构。DemoApplication.java在最外层，比如com.example.demo，所有 Controller、Service 都要放在com.example.demo的子包下面。
2. 检查dependencies里有没有spring-boot-starter-web。如果只加了spring-boot-starter而没有web，项目也能启动，但不是一个 Web 应用，当然不会处理 HTTP 请求。
3. 检查启动日志里有没有自动配置相关的省略信息，碰到不明确的exclude配置先注释掉再试。
4. 如果确实不需要数据库，就别引入数据库相关依赖；如果已经引入了，启动时又因为没配置连接而失败，可以在配置里排除数据源的自动配置类，但更推荐直接去掉相关依赖，避免后续混淆。

这个问题不算难，但它会把你的视线从“代码逻辑”拉到“框架机制”上，新手容易一头雾水。其实记住一个核心就好：Spring Boot 的自动配置不是魔法，它也是按包路径扫描和按类路径判断依赖来决定的。依赖加了什么、类放在哪，都是有迹可循的。

根据我个人经验，搭环境这件事，顺序和版本决定了大半的成败。先把 Java 版本定了，再选 Gradle，再配镜像，最后才去碰 IDEA 的选项，这个顺序一旦乱了，各种报错会轮着来。而镜像配置是投入产出比最高的一步，不管是 Gradle 发行包还是 Maven 依赖，提前配好之后，后续新建任何 Gradle 项目都不会再被网络卡住。最后再说一个小技巧：如果你经常要开新项目，把写好的那份init.gradle存在GRADLE_USER_HOME\init.d目录里，以后每次新建项目，依赖仓库地址自动就是阿里云，你只需要关注业务代码本身就行。