企业官网建设流程全解析

1. 动手之前：先把 JDK、Maven、IDEA 2023 这套底子打好

先亮个结论：在 IDEA 2023 里创建 Spring Boot 项目，本质就是三步——准备好本地构建环境，选择一个创建项目的方式，然后把依赖和配置理顺。很多人第一步就卡在环境上，所以别急着打开 IDEA，先花十分钟把下面这堆事情确认完，后面会顺畅得多。

1.1 JDK 到底该装 8、11、还是 17？

这是新手最容易懵的问题。我直接给结论：如果你用的是 Spring Boot 3.x，JDK 必须装 17 或更高；如果你还在用 Spring Boot 2.7.x，JDK 8 和 11 都没问题。原因是 Spring Boot 3.x 官方的基线就是 Java 17，类库层面大量使用了新版本语法，硬用 JDK 8 去编译会直接报错，别指望能糊弄过去。

我自己实测下来，现阶段最稳妥的搭配是：JDK 17 + Spring Boot 2.7.x/3.x + Maven 3.8+。JDK 8 虽然老项目还在大量用，但新项目除非公司要求，真没必要再开倒车。安装 JDK 之后，记得在 IDEA 的 File → Project Structure → Project 里把 SDK 指到对应版本，同时在 Settings → Build, Execution, Deployment → Compiler → Java Compiler 里把字节码版本（Bytecode version）对齐，否则编译期会冒出各种“java: invalid target release”的怪问题。

1.2 Maven 别用 IDEA 自带的，先自己装一个

IDEA 2023 确实内置了一个 Maven，但默认的配置往往不是你想要的。我更建议单独下载一个 Maven 3.8.x 或 3.9.x，然后把本地仓库地址和阿里云镜像提前配好。

具体做法：下载解压后，打开conf/settings.xml，配置本地仓库路径。我习惯放在D:/maven/repository这类独立目录，避免和系统盘混在一起。关键代码块如下：

<localRepository>D:/maven/repository</localRepository>

再在<mirrors>里加一个镜像：

<mirror> <id>aliyunmaven</id> <name>Aliyun Maven Mirror</name> <url>https://maven.aliyun.com/repository/public</url> <mirrorOf>central</mirrorOf> </mirror>

然后回到 IDEA 2023：打开 Settings → Build, Execution, Deployment → Build Tools → Maven，把 Maven home path 指向你本地解压的目录，User settings file 指向对应的 settings.xml，Local repository 会自动读取。到这里，IDEA 会用你指定的 Maven 去解析依赖，而不是它自带的那个。很多人下载依赖卡半天，十有八九就是少了这个配置。

1.3 IDEA 2023 初始设置，顺手做掉

打开 IDEA 2023 后，先别急着建项目，有两个设置值得动一下：

• 设置 JVM 内存：Help → Change Memory Settings，默认可能只有 512M，如果你后面要跑微服务或者多个模块，建议调到 1024M 到 2048M。我自己调的是 2048M，实测跑 Spring Boot 项目时编译速度快了不少。
• 关掉没用的插件：Settings → Plugins，有些插件会拖慢启动速度。这里不展开，但值得提一句，项目创建阶段不需要装额外的 Spring 插件，IDEA 2023 的 Ultimate 版和 Community 版都内置了 Spring Boot 项目创建入口，Community 版更轻量，也完全够用。

提示：Community 版没有 Spring 的专有代码提示，比如在application.properties里输入server.port不会有自动补全，但这不影响创建和运行 Spring Boot 项目。如果你是学生或个人学习，社区版完全可以用得很舒服，不一定非要去折腾破解相关的东西。

2. 创建 Spring Boot 项目：两种主流做法，推荐第一种

环境就绪之后，开始创建项目。IDEA 2023 里常用的方式就两种：一个是用内置的 Spring Initializr 在线/离线模板创建，另一个是先建空 Maven 项目再手动引入 Spring Boot 依赖。我推荐第一种，因为生成速度快，目录结构标准化，几乎不用改什么。

2.1 用 IDEA 2023 内置的 Spring Initializr 创建

操作非常直接：File → New → Project，左边选择 Spring Initializr。这里有几个选项要说明一下：

• Server URL：默认是https://start.spring.io，国内网络环境下偶尔会连不上。如果连不上，可以换成阿里云的https://start.aliyun.com，不过要注意阿里云的那个版本有时候更新的依赖版本偏旧，生成的项目可能比官方慢一个版本。
• 项目类型：Maven 还是 Gradle。我建议选 Maven，理由很简单：Spring Boot 官方文档的示例几乎全是 Maven，遇到问题搜资料时，Maven 的 pom.xml 写法最通用，你的队友也大概率用 Maven。
• Language：Java。
• 再填 Group、Artifact、Package name。Group 一般填公司域名倒写，比如com.example；Artifact 是项目名，比如demo；Packaging 选 Jar；Java 版本选你本机配好的版本，比如 17。

接下来是依赖选择。第一次创建，别贪多，只要一个 Spring Web 就够了。加上 Spring Boot DevTools（热部署工具），再加上一个 Lombok（简化实体类代码）。这三样搞定，能做 Web 接口，能自动重启，能减少样板代码。后面缺什么再加什么。

点 Finish 之后，IDEA 会开始自动导入依赖。第一次导入通常要等几分钟，因为要下载大量 jar 包，这取决于你前面 Maven 镜像配得好不好。

2.2 手动构建 Maven 项目，再引入 Spring Boot 依赖

如果你用的是社区版，或者你就是想要最大控制权，可以走另一条路：File → New → Project → New Project，选 Maven，不勾选模板，直接建一个空项目。建完后手动在pom.xml里写以下内容：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.5</version> <relativePath/> </parent> <properties> <java.version>17</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build>

然后再手动建src/main/java和src/main/resources目录，写一个带main方法的启动类：

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); } }

相比用 Initializr，这方式多写了大概十行配置，但好处是你能完全掌控每个依赖的版本和插件的细节。我在公司维护老项目时经常这么干，因为有些项目的父 POM 是公司定制的，根本没法用官方模板。

2.3 第一次启动，看看控制器能不能通

无论你用哪种方式创建，第一次运行前最好先写一个测试接口，验证整个链路是否通。在启动类同目录或子包下新建一个 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 Spring Boot on IDEA 2023"; } }

然后点击启动类旁边的绿色三角形，或者右键 Run。启动日志里看到类似Tomcat started on port 8080的字样，就说明项目起来了。浏览器访问http://localhost:8080/hello，如果看到返回的字符串，恭喜，你的第一个 Spring Boot 项目已经成功跑起来了。整个过程非常快，从点击创建到页面返回数据，顺利的话十分钟内就能搞定。

注意：如果启动时报Port 8080 was already in use，说明 8080 端口被占了。解决思路是找到占用进程并停掉，或者直接在application.properties里换一个端口，比如server.port=9090。

3. 工程结构与配置文件，创建完怎么接手

项目创建完，第一眼看到一堆目录和文件，新手容易慌。其实每个目录都有自己的职责，理清楚之后，这个项目你就算接住了。

3.1 pom.xml：锁定版本和依赖

pom.xml是 Maven 项目的灵魂。IDEA 2023 里打开它，你会看到一开始从 Initializr 生成的依赖列表：

• spring-boot-starter-web：Spring MVC + 内嵌 Tomcat + Jackson 等包的全家桶，用来做 Web 项目基本离不开它。
• spring-boot-starter-test：单元测试、集成测试用的，默认包含 JUnit 5。
• spring-boot-devtools：开发热部署工具。改代码后自动重启应用，省去手动重启的麻烦。
• spring-boot-starter：核心自动配置模块，几乎每个项目都要有。
• Lombok：如果你勾了，会在 compile 期自动生成 getter/setter、构造器等方法。

这些依赖的版本都由spring-boot-starter-parent这个父 POM 统一管理，也就是说，你在 pom 里写依赖时通常不需要指定<version>，父工程会帮你也帮我们决定好。这是 Spring Boot 最方便的地方之一，但也是一个坑：如果你需要覆盖某个依赖的版本，得用<properties>里的 key 去覆盖，而不是直接改依赖的 version，不然 Maven 会警告。

我个人的习惯是，创建一个新项目后优先确认三件事：spring-boot 的版本号、Java 版本、以及有没有引入我常用的spring-boot-starter-validation（参数校验）。这些确认完，项目地基才算稳。

3.2 application.properties：常用配置项，别瞎写

在src/main/resources下会有一个application.properties，也有的教程喜欢用application.yml。两种格式都能用，我更喜欢 yml，因为它层级关系更清晰，看着不累。但如果你是新手，properties 反而更直白，因为每行都是key=value。

项目能跑之后，有几个配置是高频出现的：

# 端口配置 server.port=8080 # 项目上下文路径 server.servlet.context-path=/api # 数据源配置（等接入数据库后再启用） spring.datasource.url=jdbc:mysql://localhost:3306/test spring.datasource.username=root spring.datasource.password=123456 # 配置文件激活 spring.profiles.active=dev

特别注意spring.profiles.active这个配置。实际工作中很少有人只用一个配置文件，一般都会分application-dev.properties、application-prod.properties多个环境，通过这个开关来切换。所以说创建完项目后，顺手把多环境配置目录建好，是个好习惯。

关于server.port，有人会遇到“在 IDEA 里改了端口但没生效”的情况。这种情况十有八九是改了但没重新 Run，或者你改的是另一个配置文件。IDEA 里应用配置时，要确保你运行的是当前这个模块，而不是某个历史运行的配置。这也是 IDEA 2023 一个容易踩的细节：Run/Debug Configurations 里选错模块，配置就不生效。

3.3 启动类：为什么要有 @SpringBootApplication

创建完之后你一定会看到@SpringBootApplication这个注解。它其实是个组合注解，相当于@SpringBootConfiguration、@EnableAutoConfiguration、@ComponentScan三个注解绑在一起：

• @SpringBootConfiguration：标注这是一个配置类。
• @EnableAutoConfiguration：让 Spring Boot 依据 classpath 自动配置。这就是为什么你引入spring-boot-starter-web后，应用会自动启动内嵌 Tomcat，你不需要手动配置任何东西。
• @ComponentScan：默认扫描启动类所在包及其子包，把带有@Component、@Service、@Controller、@Repository的类注册成 Bean。

这里有一个经常被忽略的坑：如果你的 Controller 类没有放在启动类所在包的子包里，比如启动类在com.example.demo，但你新建的 Controller 在com.example.controller，那个 Controller 不会被扫描到，接口 404。

遇到这种情况，最简单的办法是把包结构调整到主包下面，或者通过@SpringBootApplication(scanBasePackages = "com.example")扩大扫描范围。我在工作中见过好几个新手在这个问题上卡了一个多小时，最后发现项目结构不对。

3.4 IDEA 2023 左侧面板没显示 target 目录？别慌

代码写完了，编译也成功了，但 IDEA 的 Project 面板里死活看不到target目录，只在文件系统里能找到。这个现象非常常见，原因是 IDEA 默认会把你忽略的目录在工程树里折叠掉。

解决方式：打开 Settings → Editor → File Types，看 Ignore files and folders 列表里是否有target。有的话删掉。要是不想改全局设置，也可以在 Project 面板右上角点一下齿轮，看看 “Show Excluded Files” 是否开启。

其实从我个人经验来说，target目录看不看意义不大，因为它是 Maven 编译输出目录，不是源码，不看反而清爽。但如果你需要确认编译产物是否存在，可以打开 Terminal 执行：

mvn clean compile

然后去target/classes下确认.class文件确实生成了。这个命令比盯着 IDEA 界面靠谱得多。

4. 实操高频问题与排查实录

创建一个 Spring Boot 项目不难，真正让人头疼的往往是创建之后那一堆环境问题。我整理了这几个月来被问过最多的几类，每一条都是我实际踩过或帮人排查过的，直接抄作业就行。

4.1 启动报错：无法访问 jar 包，Maven 依赖下载失败

项目一创建，IDEA 就在后台疯狂下载依赖。如果网络不好或镜像配置不对，“Cannot resolve symbol” 和红色的依赖下划线就全出来了。这个问题十个人有八个人会遇到。

排查步骤按优先级排：

1. 确认 Maven 的 settings.xml 是否真的被 IDEA 读取。打开 Settings → Maven，看 User settings file 那里是不是指向你改过的文件。
2. 确认镜像是否配置成功。可以先跑一个简单的命令验证：

mvn help:system

如果能看到大量Downloading from aliyunmaven的输出，就是镜像生效了。

3. 如果还不行，就把本地仓库里_remote.repositories相关的缓存清掉，重新mvn clean install。IDEA 里对应操作是 Maven 面板右侧的刷新按钮，屡试不爽。

4.2 Spring Boot 版本太高，JDK 版本不匹配

发布时间越新的 Spring Boot，对 JDK 要求越高。比如 Spring Boot 3.2.x 要求 Java 17 起，3.3.x 也一样。很多人直接选了最新的 Spring Boot，结果本机装的是 JDK 8，编译直接报错：

java: error: invalid source release: 17

这种情况有两条路：要么把 JDK 换成 17，要么把 Spring Boot 版本降到 2.7.x。我的建议是直接换 JDK，别在老版本上死磕。你现在学技术，没必要从旧版学起，Spring Boot 3.x 的自动配置、可观测性、虚拟线程支持都是以后的主流方向。

顺带一提，IDEA 2023 里切换项目 SDK 的位置在 File → Project Structure → Project Settings → Project → SDK。改完记得同步改 Project language level，不然还是会有编译问题。

4.3 端口被占用，Tomcat 起不来

启动日志里出现：

Web server failed to start. Port 8080 was already in use.

这是个非常高频的问题。我处理过的最常见场景就是之前某次运行没停干净，或者本地有其他服务占用了默认端口。

处理方式有三种：

1. 找到占用进程并结束。Windows 上用命令行：

netstat -ano | findstr 8080 taskkill /pid [进程号] /f

macOS/Linux 上执行：

lsof -i :8080 kill [进程号]

2. 直接换端口，在application.properties中写上server.port=8081。
3. 如果你用 IDEA 2023 运行多个项目，可以在 Run/Debug Configurations 里给不同项目设置不同的 VM 参数，比如-Dserver.port=8081，这样不用改配置文件就能隔离端口。

方法二最常见，也最简单。但如果你将来要部署到服务器，这个改动记得通过配置文件或环境变量管理，别写死在代码里。

4.4 IDEA 运行配置里找不到 Spring Boot 启动项

明明创建的是 Spring Boot 项目，IDEA 2023 的 Run 按钮却显示不可用，或者只能以 Java Application 方式运行。很多人会纠结要不要专门配置一个 Spring Boot 运行项。

其实不用。IDEA 里 Spring Boot 项目的启动类本质上就是一个带main方法的 Java 类，所以你只需要在启动类里右键选择 Run，IDEA 会自动帮你创建一个 Java Application 类型的配置。除非你需要指定 Profile 或者 VM 参数，才去 Edit Configurations 里填写对应的 Active Profiles 和环境变量。

这里分享一个小细节：IDEA 2023 的 Spring Boot Run 配置里有一个 “Active Profiles” 输入框，很多项目需要指定spring.profiles.active=dev或prod。与其在代码里写死配置文件，我更推荐在运行配置里填这个字段。环境不一样，配置就能跟着切换，大家在同一个仓库里协作时，不会被彼此的本地配置干扰。

4.5 代码改了，服务却不自动重启

使用了 Spring Boot DevTools，按理说改代码后服务会自动重启，但有时候就是不生效。排查顺序是：

1. 确认 DevTools 是否在 pom.xml 里，并且没有把<scope>runtime</scope>去掉。
2. 确认你改的是src/main下的代码，而不是src/test下的代码，测试代码改动不会触发重启。
3. 确认 Build 菜单下 “Build Project” 执行过。如果你只改了代码但没重新编译，DevTools 监测不到变化。
4. IDE 本身的自动编译要打开：Settings → Build, Execution, Deployment → Compiler，勾选 “Build project automatically”，同时开启 “Allow auto-make to start even if developed application is currently running”。

设置好之后，Ctrl+Alt+S 保存修改，等待一两秒，控制台就会看到自动重启的日志。

4.6 从 Gitee 拉取合作项目后，IDEA 里跑不起来

这个场景经常出现在你与他人协作，或者拉了一个教学项目下来。项目从 Gitee 拉下来后，IDEA 并没有马上把它当成 Maven 项目，这时你需要手动导入。

打开 IDEA 2023，点击 File → New → Project from Existing Sources，选中项目所在的目录，然后选择 Maven 导入方式。IDEA 会读取项目的pom.xml，然后把模块结构加载出来。加载过程中如果右下角提示 “Maven projects need to be imported”，直接点 Load Maven Project 即可。

拉下来的项目跑不起来，还有一个可能原因：项目里的application.yml有本地配置依赖，比如数据库地址、Redis 密码等，和你本机环境不一样。这种时候你就要对照着把配置改成你的本地值。千万不要一上来就怀疑代码有问题，配置问题占了九成。

5. 按场景选依赖：项目创建完，后面怎么加功能

创建项目只是开始。不同业务需求要引入不同依赖，很多人问“我该加什么 starter”，我按几个常见场景帮你梳理一遍，跟着选就行。

5.1 Web 接口 + 参数校验

如果你要写 RESTful 接口，除了spring-boot-starter-web，建议把spring-boot-starter-validation也加上。它会提供@Valid、@NotNull、@Min这类注解，让参数校验不再散落在代码里。配合@RestControllerAdvice可以做到统一的异常返回格式，这个在实际项目中几乎是标配。

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-validation</artifactId> </dependency>

加完之后，Controller 里就可以这么写：

@PostMapping("/user") public String addUser(@Valid @RequestBody User user) { // 校验通过后处理业务 }

5.2 连接数据库做持久层

连接 MySQL 和用 MyBatis 的场景，需要加三个依赖：

<dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency>

MySQL 驱动的 groupId 在 8.x 之后改成了com.mysql:mysql-connector-j，老写法mysql:mysql-connector-java在新版本中也能用但会被提示 deprecated。如果你用的是 Spring Boot 3.x，注意 MyBatis 的 starter 要用 3.0.3 以上版本，2.x 系列是为 Spring Boot 2.x 准备的，混用会出现 Bean 初始化异常。

5.3 文件存储和消息队列这类中间件

很多人在项目中引入 MinIO 做文件存储、引入 ActiveMQ 做消息队列、引入 Kettle 做数据抽取。这些能力都会有自己的 starter 或 SDK，但它们大多和“创建 Spring Boot 项目”无关，而是属于“在已创建好的项目中集成中间件”的范畴。

拿 MinIO 举例，你不需要找什么特殊的 starter，官方提供了minioJava SDK，手动在 pom.xml 里加依赖并配置一个客户端 Bean 即可。ActiveMQ 对应的则是spring-boot-starter-activemq。Kettle 这种重量级工具集成比较特殊，需要自己封装调用层。我的经验是：项目骨架和中间件集成分开来做，先把 Spring Boot 项目跑通，再一个一个加中间件，每加一个都要本地验证一次，千万别一次性堆一堆依赖然后祈祷它能一次通过。

5.4 前端如何整合进 Spring Boot

还有个高频需求：“vue 打包后怎么放进 Spring Boot”。做法是把 Vue 的dist目录下的静态文件复制到 Spring Boot 项目的src/main/resources/static目录下，同时保证后端接口有正确的上下文路径。这样打成 Jar 包后就能用同一个端口访问静态页面和接口了。

注意一个问题：如果你的接口路径是/api/user，而 Vue 静态文件直接放在 static 根目录，通常不会冲突。但如果你配置了server.servlet.context-path=/api，那静态资源也会变成/api/index.html，联调时要保持一致。这个细节很容易被忽略，我见到过不少项目前后端联调时页面白屏，最后全是 context-path 的锅。

5.5 关于 HanLP、ASR 这类第三方能力

热词里还有 HanLP 分词、ASR 语音识别相关的内容。这些在 Spring Boot 里通常都是老套路：引入对应的 SDK 依赖，然后统一封装成一个 Service 类，对外提供接口。不要把第三方 SDK 调用写在 Controller 里，因为关联的配置多、异常处理也多，拆开之后可维护性会好很多。定好接口出入参，你之后换厂商 SDK，改动只集中在 Service 层，这是我在多个项目里验证过的做法。

6. 最后分享几个 IDEA 2023 的日常使用习惯

项目从创建到运行，其实只花了几分钟，但你之后会在 IDEA 里待很久。有几个使用习惯我一直沿用了好几年，这里一并分享给你，可能能帮你省不少时间。

第一，每个项目的 Run Configuration 里最好设置好 Active Profiles，而不是靠改application.properties来切换环境。因为多人协作时，各自本地改配置文件很容易造成提交冲突，改运行配置基本不会影响别人。

第二，IDEA 2023 自带 HTTP Client，可以直接在项目里建.http文件测试接口，比 Postman 轻量很多，也方便把测试请求版本化提交。请求写法如下：

GET http://localhost:8080/hello Accept: application/json

第三，日志别全指望 IDEA 控制台。新手阶段就算了，项目跑起来后还是建议配置日志输出到文件，通过可搜索的日志文件排查线上问题，会比翻控制台高效得多。配合 Spring Boot 的logging.file.name和logging.level配置，一套日志策略能解决很多疑难杂症。

第四，我个人的真实体会是，创建一个 Spring Boot 项目本身并不复杂，真正拉开大家差距的，是碰到报错之后有没有体系化的排查思路。环境问题优先看版本匹配和配置文件，依赖问题优先看 Maven 仓库和镜像，运行问题优先看端口和上下文路径。这条思路我用了很多年，从 IDEA 2019 一直用到 2023，几乎没有失手过。

如果你刚装好 IDEA 2023，按照这篇文章把环境搭好，再照着流程创建一个带 Web 接口的 Spring Boot 项目，整个过程不会超过二十分钟。创建完成之后，建议你顺手把多环境配置、参数校验、统一异常处理这三个能力补上，它们会让你后续写业务代码时省心非常多。