企业官网建设流程全解析

说起在 IDEA 里创建一个 SpringBoot 项目，很多人觉得这是再基础不过的开局操作。但我给团队做新人培训时发现，十个新手里有七个会在这一步卡住——不是卡在代码层面，而是卡在版本匹配、依赖下载、Maven 仓库这些“看起来不是问题的问题”上。IDEA 版本不对、JDK 版本不匹配、Spring Boot 版本选太高、镜像源没配，随便一个都能让你在“写第一行代码之前”折腾半小时。这篇教程就是要把这些前置坑提前拆给你看，从环境准备到项目跑起来、再到第一次在浏览器里看到接口返回，一条线走完。适合刚接触 Spring Boot 的初学者，也适合那些之前用 Eclipse 或其他编辑器、刚切换到 IDEA 的开发者。

1. 开工前的三件套：JDK、IDEA、Maven 的版本怎么选才不闹心

1.1 JDK 版本：Spring Boot 2.x 和 3.x 的分水岭

创建 Spring Boot 项目之前，先确认 JDK。这是最容易出问题的环节，因为你电脑上装的 JDK 版本直接决定了你能用哪个版本的 Spring Boot。

Spring Boot 2.x 系列（比如 2.7.x）最低要求 JDK 8，往上兼容到 JDK 17 甚至 21。而 Spring Boot 3.x 系列最低要求 JDK 17。也就是说，如果你本机装的是 JDK 8，却选了一个 Spring Boot 3.2 的版本，那项目创建完大概率编译报错，报错信息还特别含糊——什么UnsupportedClassVersionError，新人一看就懵，根本想不到是版本不匹配。

我的建议很直接：

• 如果你是跟着老项目走，或者公司技术栈锁定在 JDK 8，那 Spring Boot 选 2.7.x 就好。
• 如果是从零开始学新东西，建议直接 JDK 17 + Spring Boot 3.x，因为 3.x 已经是主流，相关的资料、新特性、社区讨论都在这边。
• 如果你装的是 JDK 21 这种最新版，也没问题，Spring Boot 3.2 以上对 JDK 21 支持得很好。

怎么查自己电脑的 JDK 版本？打开终端或 CMD 输入：

java -version

输出里会直接显示版本号，比如openjdk version "17.0.8"或java version "1.8.0_202"。注意，JDK 8 的版本号显示是1.8开头，别把它当成 1.8 版本还在 JDK 1.x 时代，这就是 JDK 8。

如果你还没有 JDK，去 Oracle 官网下载就行，注意选择对应操作系统的安装包。不想用 Oracle JDK 的话，OpenJDK 也完全够用，两者的区别在这个场景下基本感受不到。还有一个重点：记住你安装的 JDK 路径，后面在 IDEA 里配置项目 SDK 时要手动选。

1.2 IDEA 版本：社区版够用吗？哪个版本才不算“过时”

IDEA 分为 IntelliJ IDEA Ultimate（旗舰版）和 IntelliJ IDEA Community（社区版）。很多人担心社区版功能不全，实际上对于创建一个 Spring Boot 项目来说，社区版完全够用。

社区版和旗舰版在 Spring Boot 开发上的主要区别在于对 Spring 框架的专用支持。旗舰版有一个 Spring Assistant 或者叫 Spring 项目脚手架的内置支持，创建 Spring Boot 项目时图形化操作更顺畅，可以直接在界面里勾选依赖。社区版这边创建项目时没有那个专门的 Spring 向导，但我们可以采用另外两种方式达到同样的效果，后面我会详细说。也就是说，社区版只是多两步操作，不耽误事。

关于 IDEA 版本本身，我建议你用最新稳定版。IDEA 官方每年会发一个大版本，比如 2023.1、2023.2，每个大版本里又有 Update。新版本对高版本 JDK 的支持、对 Maven 的兼容性都更好。如果电脑配置一般，运行最新版可能有卡顿，那退而求其次选择 2022.3 或 2023.1 也完全没问题。

提示：如果你之前已经装了 IDEA，可以在 Help → About 里看版本号。如果版本过旧，比如 2020 或 2021，建议升级，否则后面创建 Spring Boot 3.x 项目时会遇到内置运行环境不支持的情况。

1.3 Maven 配置：IDEA 自带的 Maven 和镜像源设置

创建 Spring Boot 项目后，IDEA 会通过 Maven 下载一大堆依赖 jar 包。这里有一个关键点：IDEA 内置了 Maven，但你最好不要直接用它，原因很简单——内置 Maven 的配置文件默认指向中央仓库，在国内网络环境下下载依赖奇慢无比，一个spring-boot-starter-web就能让你等到怀疑人生。

解决办法：配置一个好用的镜像源。具体操作分两步。

第一步，找到你本机 Maven 的配置文件。如果你没有单独安装 Maven，IDEA 内置的 Maven 在 IDEA 安装目录下的plugins/maven/lib/maven3/conf/settings.xml。如果你自己装过 Maven，就是%MAVEN_HOME%/conf/settings.xml或~/.m2/settings.xml。

第二步，在<mirrors>节点里加一段阿里云镜像配置：

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

然后在 IDEA 里打开设置（File → Settings → Build, Execution, Deployment → Build Tools → Maven），把 User settings file 指向你配置好的那个 settings.xml。这样依赖下载速度会快一个数量级。

IDEA 自带的 Maven 和本地 Maven 具体用哪个，我倾向于用 IDEA 自带的，但配置文件用自己修改过的那份，相当于既享受了内置的便利，又拿到了自定义配置的加速效果。如果你单独安装了 Maven，直接在 IDEA 里指定你的 Maven home 路径就行。

2. 创建项目的两条路：内置向导和 Spring Initializr 网页端，差别在哪

2.1 IDEA 内置向导的完整操作流程

如果你用的是旗舰版 IDEA，或者社区版装了 Spring Assistant 插件，可以直接用内置向导。

打开 IDEA，选择 New Project（或者 File → New → Project），左侧列表找 Spring Initializr。这里有四个关键字段要填：

• Name：项目名，一般全小写，多个单词用中划线分隔，比如demo-project。
• Location：项目存放路径，建议单独建一个文件夹统一管理代码。
• Type：选择 Maven，默认就是这个。
• Group：公司或组织的域名倒写，比如com.example。这个会变成包路径的一部分。
• JDK：下拉框里选择前面确认好的 JDK 版本。

填完之后点 Next，进入依赖选择页面，在左侧搜Spring Web，勾选上，再按需勾选其他依赖（这个后面单独讲）。然后点 Create 或 Finish，IDEA 会自动联网生成项目骨架并开始下载依赖。

这个过程如果顺利，右下角会出现一个依赖下载的进度条。下载完成后，左侧目录结构会变成标准的 Maven 工程结构，pom.xml文件也生成了。

2.2 用 Spring Initializr 网页端创建，适合社区版用户

社区版没有内置 Spring Initializr 引导，但这其实不是问题。打开浏览器访问https://start.spring.io（Spring 官方提供的初始化服务），这个页面就是一个完整的项目生成器。

页面上需要填的信息和 IDEA 内置向导几乎一模一样：Project 选 Maven，Language 选 Java，Spring Boot 版本选一个稳定版（别选带有SNAPSHOT或RC字样的），Group 填com.example，Artifact 填项目名。右侧的 Dependencies 区域点 Add Dependencies，搜索Spring Web并添加。

填完点 Generate，浏览器会下载一个 zip 压缩包。解压后，用 IDEA 的 File → Open 打开这个文件夹，选择信任项目（Trust Project），IDEA 识别到pom.xml后会自动把它作为一个 Maven 项目导入并下载依赖。

这两条路的最终结果完全一样，区别只在于项目骨架是 IDEA 生成的还是网页端生成的。我个人的习惯是直接用网页端，因为里面对 Spring Boot 版本的展示更直观，还能提前看到依赖列表，比较省事。IDEA 内置向导适合不想切浏览器的场景。

2.3 Group、Artifact、包名的讲究

新手在填这些字段时觉得无所谓，但其实它们决定了你后面写代码的包结构。始终理解一个原则：Group 是组织标识，Artifact 是项目标识，两者拼起来就是 Maven 仓库里这个项目的坐标。

一个典型的项目坐标：

<groupId>com.example</groupId> <artifactId>demo-project</artifactId> <version>0.0.1-SNAPSHOT</version>

生成的项目里会有这样一个包路径：com/example/demo_project。这里有一个小细节，如果 Artifact 里带中划线，生成的包名的中划线可能会被去掉或转为下划线，这是正常的。后面你创建 Controller、Service 这些类时，都放在这个包下面，不要乱放。

这里还要注意一个点：不少人会把 Group 写成com.公司名.部门名，这没问题，但最好从一开始就统一规范，因为一旦项目启动，包名改起来非常痛苦，涉及大量移动文件的操作。

3. 依赖勾选背后的逻辑：Spring Web 之外，你到底需要什么

3.1 Spring Web：让项目拥有 Web 服务能力

创建项目时，依赖列表里最核心的就是Spring Web。这个依赖会引入内嵌的 Tomcat 服务器、Spring MVC 框架以及其他 web 支持。勾选之后，你的项目才具备启动 HTTP 服务、处理请求、返回 JSON 数据的能力。

用一个生活化的类比：Spring Web 就是你项目的“快递收发室”。它负责接收外部来的请求（快递），然后路由给你写的 Controller（收件人），再把返回值（回执）封装成 HTTP 响应发给客户端。如果没有这个依赖，项目启动了也只是一个空壳，没有任何对外服务能力。

很多初学者在这里会犯一个选择困难症：依赖列表那么长，到底该勾哪些？我的建议很简单：第一次跑通项目，只勾 Spring Web 就够，其他什么都不用加。等后面确实用到某个功能时，再手动往pom.xml里加依赖就行。Maven 支持随时加依赖，不用一开始就面面俱到。

3.2 几个常用依赖的适用场景

虽然我建议新手先只勾 Spring Web，但了解其他常见依赖的用途还是有必要的，因为你在看别人项目时会频繁遇到它们。

不是让你全部勾上，而是要理解：依赖这个东西是按需引入的，勾得越多，项目启动越慢，攻击面也越大。比如你只是做一个给 App 提供 JSON 数据的后端接口，那 Thymeleaf 这个模板引擎就完全没必要引入。

3.3 pom.xml 里发生了什么

创建完项目后，打开pom.xml看一下，里面核心结构是这样的：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.0</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build>

spring-boot-starter-parent是 Spring Boot 的父工程，它统一管理了所有 starter 的版本号。这就是为什么你在依赖里不需要写 Spring Web 的版本号——父工程已经帮你管好了。这种设计叫“依赖版本集中管理”，能有效避免不同依赖版本冲突。

spring-boot-starter-web是 web 场景的启动器，它本身不带代码，但会把 Spring MVC、内嵌 Tomcat、Jackson JSON 处理库等一系列必要依赖都传递引进来。这也是 Spring Boot 简化配置的精髓：你引入一个 starter，等于配好了完整的一套能力。

spring-boot-maven-plugin是打包插件，没有它你无法将项目打包成可执行的 jar 包。这个插件默认执行目标，把依赖和项目本身打成一个可执行的 fat jar。

4. 把项目跑起来：从启动日志到浏览器看到接口返回

4.1 认识 IDEA 里生成的目录结构

项目创建完成后，IDEA 左侧的目录结构长这样：

demo-project/ ├── src/ │ ├── main/ │ │ ├── java/ │ │ │ └── com/example/demo_project/ │ │ │ └── DemoProjectApplication.java │ │ └── resources/ │ │ ├── static/ │ │ ├── templates/ │ │ └── application.properties │ └── test/ │ └── java/ │ └── com/example/demo_project/ │ └── DemoProjectApplicationTests.java ├── pom.xml └── .idea/

DemoProjectApplication.java是启动类，里面就几行代码，但整个 Spring Boot 项目的启动都靠它。resources目录放配置文件、静态资源和模板文件。static目录放静态页面、JS、CSS，templates目录放模板引擎文件，application.properties是核心配置文件。test目录放测试代码。

启动类长这样：

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

@SpringBootApplication是一个组合注解，包含@SpringBootConfiguration、@EnableAutoConfiguration和@ComponentScan。它标记这个类是应用的入口，Spring Boot 会扫描这个类所在包及其子包的组件。这就是为什么 Controller 不能放在这个包外面，放在外面 Spring 扫不到，接口就会 404。

4.2 写第一个 Controller

项目能启动之后，我们写一个简单的接口来验证整个链路是否打通。在启动类所在的包下新建一个controller子包，再在子包里创建一个HelloController.java：

package com.example.demo_project.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, Spring Boot!"; } }

@RestController注解让这个类成为处理 HTTP 请求的控制器，并且默认将返回值直接写入 HTTP 响应体，也就是返回纯文本或 JSON。@GetMapping("/hello")表示这个方法处理 GET 请求，路径是/hello。

这里要特别注意包路径。HelloController放在com.example.demo_project.controller包里，而启动类在com.example.demo_project包里，这样 Spring Boot 的组件扫描能扫到它。如果你把 Controller 放到com.other这种与启动类不相关的包下，启动类注解里的@ComponentScan默认扫描范围就不覆盖它，接口会直接 404。

4.3 启动项目与日志解读

在 IDEA 里，点开DemoProjectApplication，点击类名左侧的绿色三角形箭头，选择 Run。也可以右键运行。看到控制台开始刷日志时，不要慌，等它刷完。

第一次启动时，因为要加载全部依赖，可能耗时较长。启动成功的标志是类似下面的日志：

Tomcat started on port(s): 8080 (http) with context path '' Started DemoProjectApplication in 2.345 seconds (process running for 2.789)

看到Tomcat started on port(s): 8080就说明 Web 服务器已经起来了。Started DemoProjectApplication in 2.345 seconds表示应用启动完成。稍等片刻，浏览器访问http://localhost:8080/hello，页面会看到：

Hello, Spring Boot!

到这一步，你的第一个 Spring Boot 项目就正式跑通了。从创建项目到浏览器看到自定义内容，这条链路是 Spring Boot 开发里最基础也是最核心的闭环。后面所有的 CRUD、对接数据库、写业务逻辑，都是在这个闭环上加码。

5. 新手最容易踩的坑与排查思路

5.1 端口被占用：那个“8080 already in use”的报错

启动项目时如果控制台报Web server failed to start. Port 8080 was already in use，那说明 8080 端口已经被另一个进程占用了。新手第一次遇到这个报错很慌，其实它是最容易解决的问题。

排查链路：先确认谁占用了端口，然后杀掉它，或者给项目换个端口。

在 Windows 下打开 CMD 运行：

netstat -ano | findstr 8080

输出的一行里会显示 PID，比如最后一列是 12345。再运行：

taskkill /PID 12345 /F

就能把占用进程杀掉。如果是 Linux 上，命令是：

lsof -i:8080

杀掉进程后重新启动项目即可。

另一个思路是给项目换端口。在application.properties里加一行：

server.port=8081

这样项目就会从 8081 端口启动。如果你同时跑多个 Spring Boot 项目，这个操作更常用。

5.2 依赖下载失败：反复报红竖弯的 Maven 错误

创建完项目后，如果pom.xml里出现红色波浪线，或者External Libraries里看不到依赖，多半是依赖没有成功下载。这在国内网络环境下太常见了。

最常见的现象是 IDEA 右下角一直转圈，Maven 仓库里不断出现*.lastUpdated后缀的文件（这些是下载失败后留下的缓存标记）。解决方法分两类：

一类是配置阿里云镜像，也就是前面 1.3 节提到的，这是在源头上解决问题；另一类是手动删除本地 Maven 仓库中所有*.lastUpdated文件，然后 Reimport。

IDEA 里点一下右侧 Maven 面板的刷新按钮（Reload All Maven Projects）就行。如果还不行，删掉本地仓库里那些失败的目录后重新刷新。本地仓库默认位置是C:\Users\你的用户名\.m2\repository，删错的风险不大。

注意：不要去改 Spring Boot 的版本号来迁就依赖下载失败。很多新手看到报错第一反应是把版本降级，结果越降越乱。先排除镜像源和网络问题，再考虑版本问题。

5.3 版本不匹配：JDK 与 Spring Boot 的隐性冲突

这个问题隐蔽性很强，报错信息往往不是直接的“版本不兼容”，而是像：

• Unable to import maven project: See logs for details
• Invalid source release: 8
• 编译时出现大量红色波浪，但代码看起来没问题

排查链路：点击 File → Project Structure → Project Settings → Project，确认 Project SDK 和 Language Level 是否匹配。比如你的 JDK 是 17，但 Language Level 选的 8，编译就会报Invalid source release: 8。

再确认 Maven 的 JDK 设置。File → Settings → Build Tools → Maven → Runner，看 JRE 是不是也指向了正确版本。这一步很多人忽略，因为 IDEA 有多个“当前 JDK”的概念，Project SDK 一个、Maven Runner JRE 一个、模块的 SDK 一个，任何一个不对都会引发莫名其妙的问题。

5.4 包扫描不到的坑：启动类位置放错了

这个坑我在 4.2 节提过，但还是要单独拿出来强调，因为它几乎是新手必踩。Spring Boot 默认会扫描启动类所在包及其子包下的所有组件，如果你把 Controller 放在启动类的包外面，启动时不会报错，但浏览器访问就是 404，排查起来完全没有思路，因为控制台非常干净，什么错都不报。

检查方法：看你的启动类在哪一层包，Controller/Service 这些类必须在它的子包下。比如启动类是com.example.demo_project.DemoProjectApplication，那其他类必须在com.example.demo_project或com.example.demo_project.xxx下。

5.5 首次启动慢：不用怀疑自己的电脑坏了

第一次启动 Spring Boot 项目时，因为需要加载很多类和引用资源，耗时可能在 5 到 10 秒以上，这是正常的。如果启动时控制台输出了一堆 DEBUG 日志，可能是日志级别配置的问题，不影响使用。

真正值得注意的是启动过程中 Maven 还在后台下载依赖的情况。这样项目启动会被阻塞，看起来像卡死了，其实是在等 Maven 下载完依赖。解决办法还是回到 1.3 节的镜像源配置上，依赖下载飞快，启动自然就顺。

6. 让项目更顺手的几个配置：端口、Banner、热部署

6.1 application.properties 与 application.yml 的选择

Spring Boot 支持两种配置文件格式，application.properties和application.yml。两者的功能等价，但语法风格不同。很多老前辈倾向于用 yml，因为它的层级用缩进表示，嵌套结构看起来更清晰；新人则更容易接受 properties 的键值对格式，因为不需要纠结缩进对齐。

两种格式我都用过，长期下来更推荐.properties。理由很简单：完全不需要介意缩进问题，而且 IDEA 对 properties 的自动补全和跳转支持更成熟。不过你接手别人的项目时，两种格式都会遇到，所以至少要能看懂.yml的写法。比如配置端口和上下文路径，.properties写：

server.port=8080 server.servlet.context-path=/api

.yml写：

server: port: 8080 servlet: context-path: /api

注意.yml里冒号后面要有一个空格，否则解析报错。

6.2 Banner：让你的项目启动有点仪式感

Spring Boot 启动时控制台会打印一个巨大的 ASCII Art Logo，默认是 Spring 的图标。很多开发者会把它替换成自己项目的 Banner，算是一种小小的仪式感，也能在团队里区分不同服务。

生成 Banner 可以用在线 Banner 生成器，比如 patorjk.com 的 Text to ASCII Art Generator，输入你想展示的文字，生成出 ASCII 图后复制。然后到src/main/resources目录下新建一个banner.txt文件，把生成内容粘贴进去，重新启动项目就能看到效果。

这里有一个小技巧：在 Banner 文本里可以加上变量，比如$(spring-boot.version)、$(application.title)这种，Spring Boot 会自动替换成实际值。用这个方式把版本信息放到控制台，启动时一眼就能确认版本是否正确，排查环境问题时非常省事。

6.3 DevTools 热部署：改代码不用重启

开发过程中，每次改代码都要手动重启项目，非常打断思路。引入 Spring Boot DevTools 可以解决这个问题。它的原理并不复杂：监控 classpath 下的文件变化，发现变化后自动重启应用，整个过程只需要一两秒。

要使用的话，在pom.xml里加入：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-devtools</artifactId> <optional>true</optional> </dependency>

optional设为true的作用是让这个依赖不传递到依赖本项目的外部模块，避免把开发用的热部署功能打包进生产环境。

加完依赖后，IDEA 里还需要一步设置：File → Settings → Build, Execution, Deployment → Compiler，勾选 Build project automatically。再打开高级设置（Settings → Advanced Settings），勾选 Allow auto-make to start even if developed application is currently running。这步设置做完，修改代码后 IDEA 自动编译，DevTools 监听到变化就会自动重启，开发体验会提升一大截。

这里提醒一句：DevTools 是开发阶段用的工具，不要用它替代生产环境的部署方案。生产环境打包时它不会生效，因为它只存在于optional的开发依赖里。

6.4 多环境配置：开发、测试、生产分开管理

最后说一个很实用但新手接触不到的配置——多环境管理。Spring Boot 支持通过配置文件名后缀实现多环境切换，例如：

• application-dev.properties：开发环境
• application-test.properties：测试环境
• application-prod.properties：生产环境

然后在application.properties里指定当前使用哪个环境：

spring.profiles.active=dev

这样启动时会加载application-dev.properties，而公共配置放在application.properties里。数据库连接地址、端口号、日志级别这些不同环境的差异化配置都可以按环境拆开，避免每次部署都要手动改配置。

切换到不同环境时，只需要改spring.profiles.active的值就行，或者启动时通过参数指定：

java -jar demo-project.jar --spring.profiles.active=prod

在这套机制下，项目配置文件会清爽很多，不会出现一堆注释掉的历史配置。

我个人的体会是，创建 Spring Boot 项目这件事本身没什么高深的技术含量，但它像是盖楼前的地基。地基打得稳，后面写接口、连数据库、对接 Redis、集成消息队列的时候，少出一堆环境问题；地基打得草率，JDK 版本和框架版本不匹配、Maven 仓库不通、热部署没配好，这些小问题后面会反复回来找你麻烦。特别是当你从复制粘贴别人的代码转向自己从零搭建项目时，动手走一遍完整流程，对 Spring Boot 的运行机制理解会上一整个台阶。所以哪怕你已经会创建项目了，也建议按这篇教程的链路重新走一遍，重点把版本选型、镜像源配置和多环境管理的习惯建立起来，这会让你后续的 Spring Boot 开发顺畅很多。