企业官网建设流程全解析

1. 为什么这个时间点最适合从 Spring Boot 3 + Vue 3 入手

前后端分离这个词喊了快十年，但真正把这个架构做成标准动作，还是近几年的事。如果你现在打开招聘网站，随便搜一条 Java 后端岗位，十有八九都会写着“熟悉 Spring Boot”、“了解 Vue 等前端框架”。而在 2023 年底 Spring Boot 3 全面普及之后，新项目的起点已经从过去的 Spring Boot 2.x + JDK 8 悄悄变成了 Spring Boot 3.x + JDK 17。这一篇我先把后端环境完整地跑通，Vue 3 那边留到下一篇讲。

选 Spring Boot 3 不是跟风。Spring Boot 3.0 正式发布到现在已经有段时间，社区沉淀足够，网上各种坑也都被踩得差不多了。更关键的是，Spring Boot 3 强制要求 JDK 17 起跳，这意味着我们不需要再纠结要不要升级，直接按新标准来，省得到时候业务做大了再搞一次大版本迁移。Vue 3 这边也一样，Composition API、TypeScript 支持、响应式系统的重构，都是实打实的进步，如果你是从 Vue 2 转过来的，趁现在还没有背着太多旧代码包袱，直接学 Vue 3 是最划算的决策。

这一篇的核心目标是：先把后端环境搭起来，跑通一个最简单的接口，确保 Spring Boot 3 项目能正常开发和调试。环境搭好了，后面所有的功能开发才有地基。基础打得牢，后面才不慌。

2. 搭建 Spring Boot 3 后端环境三大件：JDK、Maven、IDEA

2.1 JDK 17 的安装和坑

Spring Boot 3 要求的最低 Java 版本是 17，所以 JDK 的安装是整个环境的第一步，也是后续所有程序运行的基础。如果你机器上之前装的是 JDK 8 或者 JDK 11，不要偷懒，老老实实装一个 JDK 17 或者是更新的 LTS 版本。

安装 JDK 有几个选择：Oracle JDK、OpenJDK、Eclipse Temurin、Azul Zulu。我个人比较喜欢用 Eclipse Temurin，也就是社区里常说的 Adoptium 项目，因为它完全开源免费，而且官网直接提供各平台的安装包，不需要像 Oracle 那样注册下载。如果你公司的环境有要求，用 Oracle JDK 问题也不大，对于日常开发来说两者的差别几乎感觉不到。

装完 JDK 之后，一定要确认命令行能识别到 Java，否则后面 Maven 编译会报各种莫名奇妙的错。在命令行里执行：

java -version

如果看到类似下面输出，就说明没问题：

openjdk version "17.0.10" 2024-01-16 OpenJDK Runtime Environment Temurin-17.0.10+7 (build 17.0.10+7) OpenJDK 64-Bit Server VM Temurin-17.0.10+7 (build 17.0.10+7, mixed mode, sharing)

这里我必须多说一个坑。很多同学在 Windows 上装完 JDK 之后，命令行里输 java -version 能正常显示版本，但 IDEA 里项目却报“无效的源发行版 17”，或者 Maven 编译直接提示找不到 JDK。这通常是因为系统环境变量里的 JAVA_HOME 指向的还是旧版本的 JDK。解决方法很简单，去系统环境变量里把 JAVA_HOME 改成新装 JDK 的路径，然后重启命令行和 IDEA，问题一般就消失了。

还有个细节需要留意：如果你是 Mac 用户，通过 Homebrew 安装 JDK 很方便，但要注意 Homebrew 默认的 openjdk 并没有被 symlink 到系统默认的 Java 目录里，需要手动执行命令才能让系统识别到。具体方法是查看 brew 安装路径下的提示信息，一般会明确告诉你如何建立符号链接。Windows 用户相对简单，直接改环境变量就行。

2.2 Maven 版本选择和配置文件修改

Maven 是 Java 项目构建的标配工具，Spring Boot 项目也不例外。Spring Boot 3 对于 Maven 的版本要求是 3.5 以上，但我强烈建议装 3.8 或者 3.9 系列。原因很简单：新版 Maven 在依赖解析速度、插件兼容性方面表现更好，尤其是和 Spring Boot 3 自带的 parent POM 配合时，响应式依赖的版本管理会更顺畅。

Maven 装完之后，最重要的就是修改 settings.xml。这个文件默认在 Maven 安装目录的 conf 文件夹下，也可以放在用户目录的 .m2 目录下。我们改它主要做两件事：给仓库配镜像、指定本地仓库位置。之所以要配镜像，是因为 Maven 中央仓库在国内的访问速度实在不稳定，直接拉依赖经常超时，换成国内镜像之后整个下载体验完全不同。

我一般是在 settings.xml 里的 mirrors 标签下加这么一段：

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

mirrorOf 里写 * 表示所有中央仓库的请求都走这个镜像。配置文件改完之后，建议在命令行里先跑一次依赖下载试试，比如建一个临时项目执行 mvn clean compile，确认依赖能顺利拉下来，再进 IDEA 操作，免得 IDEA 里卡半天都不知道是网络问题还是配置问题。

Maven 本质上是 Java 项目的“物流中枢”，它负责把项目需要的所有第三方库下载到本地，并根据依赖声明编译打包。Spring Boot 项目的 pom.xml 里往往依赖几十个甚至上百个库，如果没有 Maven 自动管理版本和依赖关系，手动下载和引入 jar 包会是灾难性的工作。理解了这一点，你就明白为什么要花时间把 Maven 配好。

2.3 IDEA 的安装和关键配置

IDEA 分 Ultimate（旗舰版）和 Community（社区版）。开发 Spring Boot 项目的话，我更推荐 Ultimate，因为 Spring 官方插件、HTTP Client、数据库工具这些实用功能都齐全，社区版虽然也能写代码，但少了 Spring 相关支持，体验差一个档次。如果你没有公司提供的正版授权，可以先试用 30 天，或者用学校邮箱申请免费授权，具体政策每年有微调，自己留意一下官网动态。

装完 IDEA 之后，有几个配置会影响后续开发体验，我逐一说明。

首先是文件编码，必须统一成 UTF-8。在 Settings → Editor → File Encodings 里，把 Global Encoding、Project Encoding、Properties Files 的 Default encoding 全部改成 UTF-8，并且勾选 Transparent native-to-ascii conversion。这个设置主要防止写入中文注释后乱码，前后端开发中编码统一是基本功。

然后是 Maven 配置。在 Settings → Build, Execution, Deployment → Build Tools → Maven 里，把 Maven home path 指向你本地安装的 Maven，User settings file 指向刚才改好的 settings.xml，Local repository 会自动识别你配置的本地仓库路径。这里的逻辑是让 IDEA 直接使用我们命令行的 Maven，而不是 IDEA 自带的 Maven，这样命令行和 IDEA 的构建结果会完全一致，遇到问题时排查路径也清晰。

最后打开 Settings → Build, Execution, Deployment → Compiler → Java Compiler，确认 Project bytecode version 和模块的 Target bytecode version 都选 17，避免编译时出现版本不一致的问题。

3. 创建一个 Spring Boot 3 项目：从初始化到跑通接口

3.1 使用 Spring Initializr 初始化项目

Spring Initializr 是官方提供的项目生成器，IDEA 内置了它的支持。具体操作路径是：File → New → Project → Spring Initializr，然后跟着向导填入各项信息。

关键的选项我直接给出推荐值：

• Project：Maven（不要选 Gradle，除非你本来就熟悉 Gradle）
• Language：Java
• Spring Boot 版本：选择最新的稳定版即可，例如 3.2.x 或 3.3.x
• Group：根据自己的习惯写，一般是 com.你的名字或公司名
• Artifact：项目名，例如 demo、backend、api-server 这些
• Name：跟 Artifact 一致
• Package name：系统会自动生成，确认一下结构没问题就行
• Packaging：Jar
• Java：17

依赖这边，我只勾选一个 Spring Web。因为当前目标是跑通环境，不需要引入太多组件。后面做到数据库操作再选择 MyBatis、Spring Data JPA 等依赖，通过 pom.xml 添加也是一样的效果。

这些问题看起来是信息填写，其实背后决定了项目的基本架构：Group 和 Artifact 会组成 Maven 项目的唯一坐标系坐标，后续引用自己的模块时都要用到；Packaging 选择 Jar 意味着我们会用嵌入式 Tomcat 启动后端，也就是 java -jar 指令直接运行，部署时不需要额外装一个独立的 Tomcat。这些概念放在以前要绕很多弯，Spring Boot 把这些全部简化成了导语上的几个选项。

3.2 项目结构与启动类

生成完成之后，IDEA 会自动打开项目。先花几分钟认识一下目录结构，这对后续开发非常重要。

项目根目录 ├── pom.xml ├── src │ ├── main │ │ ├── java │ │ │ └── com.example.demo │ │ │ ├── DemoApplication.java │ │ │ └── ... │ │ └── resources │ │ ├── application.properties │ │ └── ... │ └── test │ └── java

DemoApplication.java 就是启动类，里面的 main 方法调用 SpringApplication.run，这是整个应用的入口。我见过不少新手把启动类删了或者复制到错误位置，结果项目怎么也起不来，其实只要记住：启动类必须放在根包路径下，也就是所有业务代码包名的上一层，这样 Spring 的组件扫描才能覆盖所有子包。如果你把启动类放到 com.example.controller 这类子包里，Spring 默认扫描不到兄弟包的组件，接口就变为不可访问了。

3.3 修改应用配置文件

Spring Boot 默认生成的是 application.properties 文件，我一般直接改成 application.yml。两种格式功能完全一样，但 YML 的层级结构更清晰，尤其是配置多级嵌套内容时，比如 redis、datasource、自定义参数，缩进结构让人一眼就能看清楚层级关系。注意 YML 对空格敏感，冒号后面必须有一个空格，用 Tab 缩进会直接报错。

首先改端口。默认是 8080，但在日常开发中，8080 这个端口经常被其他程序占用，我习惯直接用 8080 起步，遇到问题再调整。同时我还会加一个 context-path，这样所有接口就统一带上前缀，以后部署到反向代理后面也方便做转发规则区分。配置如下：

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

加上 context-path 之后，一个原本访问 localhost:8080/hello 的接口，现在的访问地址就变成了 localhost:8080/api/hello。这个前缀可以按项目需求随意定义，不加也不影响开发，但是加了会清爽很多。

3.4 写第一个接口验证环境

配置改好了，我们写一个最简单的接口，目的就是验证环境是否真的通。在启动类同级的包下新建一个 controller 包，然后创建一个 TestController：

package com.example.demo.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; import java.time.LocalDateTime; import java.util.HashMap; import java.util.Map; @RestController public class TestController { @GetMapping("/hello") public Map<String, Object> hello() { Map<String, Object> result = new HashMap<>(); result.put("message", "Hello Spring Boot 3"); result.put("time", LocalDateTime.now().toString()); return result; } }

这段代码用了两个最简单的注解。@RestController 表示这个类里的方法直接返回数据并自动序列化为 JSON，不需要走视图渲染；@GetMapping("/hello") 表示把 GET 请求的 /hello 路径映射到下面的方法上。返回值用了 Map，Spring 会自动把它转成 JSON 字符串，方便前端直接读取。

现在点击 IDEA 右上角的运行按钮，或者直接在 DemoApplication 上右键运行。第一条能看到比较长的日志输出，耐心等一会儿，直到出现 Spring Boot 版本号、Tomcat started 的字样，以及 “Started DemoApplication in x.xx seconds” 的提示，就说明启动成功。

打开浏览器访问 http://localhost:8080/api/hello，你会看到类似这样的 JSON：

{"message":"Hello Spring Boot 3","time":"2024-01-15T21:30:45.123"}

后端环境到这里就已经跑通了。从这一个小接口开始，后续的 Controller、Service、Mapper、业务逻辑会逐步在这个框架上铺开。

4. 深入理解依赖管理和启动原理

4.1 pom.xml 的核心内容

很多初学者创建完项目之后对 pom.xml 完全不看，这是不对的。pom.xml 是 Maven 项目的核心配置文件，相当于项目的“安装说明书”。Spring Boot 3 的 pom.xml 里最核心的内容有三块。

第一块是 parent 声明：

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.4</version> <relativePath/> </parent>

这个 parent 继承了 Spring Boot 官方预先配置好的依赖管理方案。简单说，它把 Spring Boot 各组件之间兼容的版本号都定义好了，我们无需再为每个依赖单独写版本号，只要引入 starter 即可，这样能有效避免版本冲突。

第二块是 Java 版本属性，在 properties 标签里：

<properties> <java.version>17</java.version> </properties>

这个属性会影响编译插件的 target 版本。如果你在 IDEA 里把 Java Compiler 改成 17 但这里还是占位符，可能编译会有问题，所以两者要保持一致。

第三块是依赖项 spring-boot-starter-web。这里的 starter 是 Spring Boot 的一个设计理念：官方把所有需要用到的依赖打包成一个开箱即用的组，web 开发需要的内嵌 Tomcat、Spring MVC、Jackson JSON 序列化等全部自动引入。你在引依赖时，不需要去关心底层传递依赖具体有哪些，只需要决定要不要引入这个 starter。

4.2 内嵌 Tomcat 的运行机制

Spring Boot 3 内置了 Tomcat 服务器，并且默认以嵌入式方式启动。这意味着启动类里的那个 main 方法，其实就是调用 SpringApplication.run，从而自动完成以下几个步骤：

• 读取 application.yml 配置
• 初始化 Spring 容器
• 注册所有 Controller、Service、Repository 组件
• 启动内嵌 Tomcat，并监听配置的端口

整个过程不需要部署 war 包，也不需要单独安装 Tomcat。你只需要执行一次构建，生成一个可执行的 jar 包，随后在任何安装了 JDK 17 的机器上直接执行 java -jar 就能运行，部署时非常方便。以前部署一个 Java Web 项目至少要费半个多小时，现在一条命令就解决，这也是 Spring Boot 能迅速流行的原因之一。

初学阶段你不需要理解每个环节的内部细节，但我会建议你观察控制台日志的启动顺序：先加载环境变量和配置，再注册 bean，最后启动 Tomcat。以后遇到启动失败时，看日志定位的直觉就是从这里来的。

4.3 组件扫描和项目包结构

我们在写 Controller 时，把它放在 com.example.demo.controller 包下。这个包和启动类的包名 com.example.demo 有包含关系，能把组件正常扫描进来。如果你新建的包名层级不同，启动时会自动抛出组件扫描不到的错误。

其实组件扫描的机制很简单：@SpringBootApplication 注解里包含了 @ComponentScan，默认扫描当前包及其所有子包。也就是说，启动类所在的包必须是你的业务包层级的最顶层。为了保持这个规则，实际项目中的包结构通常如下：

com.example.demo ├── controller # 控制层，接收请求 ├── service # 业务逻辑层 ├── mapper # 数据访问层 ├── entity # 实体类 ├── config # 配置类 └── common # 公共工具和常量

这个分层结构是业内最常见的做法，遵循关注点分离原则：Controller 只负责接收参数和返回结果，Service 处理业务逻辑，Mapper 访问数据库。初学者一开始可能觉得分层麻烦，但项目复杂起来之后，这个分层能让你快速定位问题所在，非常值得坚持。

5. 后端环境搭建的常见问题与解决记录

5.1 依赖下载慢或者失败

这是出现频率最高的问题。表现在 IDEA 里就是 pom.xml 长时间保持 loading 状态，或者编译时一直卡在下载依赖，最终报出各种无法解析依赖的红色报错。这个问题的根源是网络访问 Maven 中央仓库不稳定，解决方案就是我们前面配置的国内镜像。

如果已经配置了镜像还不行，先检查 settings.xml 路径是否被 IDEA 正确读取。在 IDEA 的 Maven 设置面板里查看 User settings file 指向的文件路径，确认它不是默认的空路径。另一个排查方向是在命令行手动执行以下命令：

mvn clean compile

如果命令行能正常通过而 IDEA 不行，说明是 IDEA 的 Maven 配置问题；如果命令行同样失败，那么问题基本就在 settings.xml 配置。

另一个小技巧：如果某个依赖一直下载不下来，配置好镜像之后，在 IDEA 的 Maven 工具窗口点击刷新按钮，或者执行 mvn clean install -U -DskipTests（-U 强制更新快照版本），通常就能解决。

5.2 Spring Boot 启动失败，提示端口被占用

Tomcat 默认端口 8080，很容易被占用。启动日志里如果出现 “Web server failed to start. Port 8080 was already in use” 这段，就说明端口冲突了。

处理方法有三种：第一种是结束占用端口的进程，Windows 下在命令行执行：

netstat -ano | findstr 8080

然后根据 PID 再执行：

taskkill /PID 1234 /F

Mac 或者 Linux 用户则使用：

lsof -i :8080 kill -9 1234

第二种是直接改 application.yml 里的 server.port，比如改成 8081、9090，一劳永逸不跟别的程序抢。第三种是明确知道自己机器上什么程序占用了端口，跑到那里面把配置改掉。日常开发中第二招最实用，毕竟开发阶段端口随意改，不会带来什么副作用。

5.3 Maven 编译时报 Java 版本不匹配

报错信息里常见 “java: 无效的目标发行版: 17” 或者 “error: release version 17 not supported”，这种问题基本都是编译环境配置混乱导致的。按下面的步骤一一排查即可：

先确认 IDEA 的 Project Structure（快捷键 Ctrl+Alt+Shift+S 或 Cmd+Alt+Shift+S）里的 Project SDK 是否选了 17 或者其他 17 以上的 JDK。再确认 Project language level 是否也已经调成 17。接着看 Settings → Maven → Importing 里的 JDK for importer 选项，也要选对。最后看一眼 pom.xml 里的 java.version 属性。

这四个位置全部一致之后，执行一次 mvn clean compile，正常就不会再报错了。养成这个排查顺序之后，JDK 配置问题基本就是五分钟内的事。

5.4 引入更多依赖时如何避免版本冲突

随着项目深入，你很快就会在 pom.xml 里添加 MyBatis、MySQL 驱动、Redis 客户端等各类第三方依赖。如果此时出现 “jar包冲突” 的问题，比如多个依赖传递依赖了不同版本的同一个库，最简单的排查动作是打开 IDEA 右侧 Maven 工具栏，执行一次 Dependency Analyzer，或者运行：

mvn dependency:tree

通过查看依赖树，你能清楚看到每个依赖到底是从哪条链路引入进来的。在使用官方 starter 的前提下，版本冲突的概率并不高，因为 Spring Boot 的依赖管理已经帮你锁定了主流版本的兼容关系。常见的冲突往往来自自己手动引入的第三方库，这时遵循一个黄金规则：优先找这个库官方推荐的 Spring Boot 集成 starter，然后减少手动管理版本号，可以省掉很多麻烦。

5.5 访问接口 404 的排查思路

404 可以说是新手最常遇到的坑，明明代码从书或视频里原样抄过来，为什么访问就是找不到接口。最常见的两种情况如下。

第一种是接口路径没拼对。我前面配置了 context-path: /api，如果你的 Controller 写的映射是 /hello，那么完整路径是 localhost:8080/api/hello，不是 localhost:8080/hello，缺一个前缀就会 404。排查时先把自己的完整路径和浏览器地址对比，确认路径没拼错。

第二种是启动类位置放错了。如果你把启动类放在 com.example 包下，而 Controller 放在 com.example.demo.controller 包下，Spring 的组件扫描就失效了，Controller 没有注册到容器里，访问自然也是 404。解决办法是将启动类移动到所有包的最外层。

在实际开发中，404 的排查思路其实很简单：启动时看日志里有没有打印 RequestMappingHandlerMapping，它展示了当前所有已经映射到的路径，如果你写的接口没有出现在映射列表里，说明 Controller 没有被扫描到；如果出现了但访问还是 404，那就是路径拼写或者 context-path 的问题。

6. 后端环境搭建的经验心得与下一步规划

环境搭建这件事，看起来没什么技术含量，但恰恰是无数新手的第一个坎。我在实际操作中最大的体会是：环境问题不能靠猜，要用日志定位。Spring Boot 的启动日志和错误信息已经写得非常清楚了，多数情况下照着提示就能找到问题所在。如果是依赖下载问题，先看 Maven 配置；如果是接口访问问题，先看扫描日志和控制台映射路由信息。一旦你有意识地按这个思路排障，前端也好后端也好，解决的问题会越来越快。

另一个非常重要的心得体会是：搭建环境时要养成记录的习惯。我建议你把 JDK 版本、Maven 配置改了哪个文件改了哪一段、application.yml 里配置了什么端口，全部用笔记软件记下来，后面项目变大、配置越来越复杂时，这些记录就是你排查问题的最有力武器。很多老朋友配置了十几个环境，靠的全是那一份及时的笔记。

至于下一步，后端跑通之后，自然要开始搭建 Vue 3 的前端工程。到时候会涉及 Vite 的安装、vue-router 和 Pinia 的引入、前端如何通过 axios 调用后端接口，以及跨域问题如何通过后端 CORS 配置或者开发代理解决。前端工程的目录结构和构建工具链又完全是另一套体系，但有了后端环境的成功经验，前端那边你会更快上手。

搭建环境里我最后再分享一个小技巧：每次换电脑或者重装系统后，我都会先用命令行方式验证 JDK 和 Maven 都能正常工作，然后再打开 IDEA 建项目。这样一旦项目出问题，我能第一时间判断到底是基本环境问题还是项目自身的问题，不会在 IDE 的报错信息里绕圈子。看似多花了五分钟，实际省下的时间远不止五个小时。