Spring Boot 4.0 企业级开发环境搭建：Maven、Gradle 与 IDE 配置

作者：苏三2026-11-06Spring Boot 4.0Spring Boot 4MavenIDEAJava 21

前言

同样一份 Spring Boot 代码，在 A 的电脑能启动，在 B 的电脑却报 Java 版本、依赖下载或端口占用，问题通常不在业务代码，而在开发环境没有对齐。

这篇教程不假设你已经装好所有工具。完成后，你应当能够从终端启动配套项目、打开健康检查，并知道每个工具版本在哪里确认。

本篇不修改业务代码，重点是建立后续 48 篇教程都复用的运行基线。

配套源码地址：

https://github.com/dvsusan/spring-boot4-demo

第 1 步：下载配套源码

先不要急着安装各种插件，第一步是把完整工程下载到本地。

方式一：使用 Git 克隆

先检查电脑有没有安装 Git：

git --version

如果能看到 git version 2.x.x，执行：

git clone https://github.com/dvsusan/spring-boot4-demo.git
cd spring-boot4-demo

方式二：直接下载 ZIP

没有安装 Git 也可以运行项目：

打开 https://github.com/dvsusan/spring-boot4-demo
点击页面右侧绿色的 Code 按钮。
点击 Download ZIP。
解压下载的文件。
进入解压后的 spring-boot4-demo-master 或 spring-boot4-demo-main 目录。

无论使用哪种方式，进入项目目录后都应该看到：

spring-boot4-demo
├── demo-common
├── demo-greeting-starter
├── demo-order
├── demo-web
└── pom.xml

如果目录中没有根目录 pom.xml，说明下载或解压的层级不对。不要在 demo-web 子目录里直接执行整套构建命令。

最终检查结果

全部准备完成后，在项目根目录执行：

mvn clean package -DskipTests
java -jar demo-web/target/demo-web-1.0.0-SNAPSHOT.jar

再请求：

curl "http://localhost:8080/actuator/health"

应该得到类似：

{"groups":["liveness","readiness"],"status":"UP"}

环境检测图

图 1：环境检查不是只看安装命令，最后必须走到健康检查 UP。

看到 UP，说明 JDK、Maven、依赖和端口这条链路已经打通。

第 2 步：安装 JDK 21

本项目固定以 Java 21 编译。先检查终端：

java -version
javac -version

macOS、Linux 或 Git Bash 预期看到：

java version "21.x.x"
javac 21.x.x

Windows PowerShell：

java -version
javac -version

官方下载入口：

https://adoptium.net/temurin/releases/?version=21

下载时选择 JDK 21、LTS、Temurin。不要只下载 JRE，也不要选择 JDK 8、11 或 17。

macOS 安装

Apple Silicon 和 Intel 芯片都从上面的 Temurin 页面下载 macOS 对应的 .pkg 安装包，双击完成安装。

也可以使用 Homebrew：

brew install --cask temurin@21

安装后配置当前终端：

export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export PATH="$JAVA_HOME/bin:$PATH"

希望每次打开终端都生效，可以把这两行加入 ~/.zshrc，然后执行：

source ~/.zshrc

Windows 安装

从 Temurin 页面下载 Windows x64 的 .msi，双击安装。安装向导中勾选：

Set JAVA_HOME environment variable
Add Java to PATH

安装完成后关闭旧终端，重新打开 PowerShell，再执行验证命令。

Ubuntu / Debian 安装

Ubuntu 24.04 或软件源中已经提供 OpenJDK 21 时，可以执行：

sudo apt update
sudo apt install -y openjdk-21-jdk

如果系统软件源没有 JDK 21，请从 Temurin 页面下载 Linux x64 压缩包，解压后把 bin 目录加入 PATH。

安装后如果 java 正常、javac 找不到，通常说明只安装了 JRE 或 IDE 自带了 JDK，但终端 PATH 没有指向它。

检查 Java 安装路径：

echo "$JAVA_HOME"

JAVA_HOME 应该指向 JDK 根目录，而不是 bin 目录。例如 macOS 上可能类似：

/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home

Windows 可以在 PowerShell 中检查：

$env:JAVA_HOME

修改系统环境变量后要重新打开终端或 IDE，旧进程不会自动读取新的 JAVA_HOME。

第 3 步：安装并检查 Maven

配套项目使用 Maven 多模块结构。本文验证版本是 Maven 3.9.9，建议使用 3.9.x：

mvn -version

预期输出的关键信息：

Apache Maven 3.9.x
Java version: 21.x.x

如果 Maven 显示的是 Java 17，而 java -version 显示 Java 21，说明 Maven 脚本读取了另一处 JAVA_HOME。先统一终端环境，再打开 IDE。

官方下载入口：

https://maven.apache.org/download.cgi

macOS 安装

使用 Homebrew：

brew install maven

Windows 安装

从 Maven 官网下载 apache-maven-3.9.x-bin.zip。
解压到固定目录，例如 C:\tools\apache-maven-3.9.9。
把 C:\tools\apache-maven-3.9.9\bin 加入系统环境变量 Path。
关闭旧 PowerShell，重新打开后执行 mvn -version。

Linux 安装

从 Maven 官网下载 apache-maven-3.9.x-bin.tar.gz，例如：

tar -xzf apache-maven-3.9.9-bin.tar.gz
export MAVEN_HOME="$HOME/tools/apache-maven-3.9.9"
export PATH="$MAVEN_HOME/bin:$PATH"

需要永久生效时，把两条 export 写入 ~/.bashrc 或 ~/.zshrc。

国内网络下载 Maven 依赖较慢时，可以在 ~/.m2/settings.xml 配置可信镜像。不要把公司私有仓库账号和密码直接提交到项目。

Maven 和 Gradle 怎么选？

维度	Maven	Gradle
上手成本	结构固定，适合新手	脚本灵活，需要理解构建脚本
可读性	XML 清晰稳定	Kotlin DSL 更强但更自由
多模块项目	配置直观	增量构建能力强
本教程	统一使用 Maven	仅说明差异

这不是技术优劣排名。团队已有构建规范时就跟随团队，不要为了练习新工具重写整套构建。

第 4 步：安装并配置 IDE

IntelliJ IDEA 官方下载：

https://www.jetbrains.com/idea/download/

VS Code 官方下载：

https://code.visualstudio.com/Download

如果使用 VS Code，安装扩展：

Extension Pack for Java
Maven for Java
Spring Boot Extension Pack（可选）

IntelliJ IDEA 打开项目时，选择根目录的 pom.xml，不要分别打开三个子模块。

打开后检查：

Project SDK 是 JDK 21。
Maven Runner 使用的 JDK 也是 21。
Maven 面板能找到 demo-common、demo-greeting-starter、demo-order、demo-web 四个模块。
demo-web 的依赖中能看到另外三个项目模块。

如果需要重新导入：

IDEA：右键根 pom.xml，选择 “Add as Maven Project”，或刷新 Maven 面板。
VS Code：安装 Java Extension Pack，打开根目录，等待 Java 项目导入完成。

IDE 右下角显示的 Java 版本必须和终端一致。只有项目写成 Java 21，IDE 却用 Java 17 解释，源码提示和实际 Maven 构建会互相矛盾。

第 5 步：认识依赖目录

Maven 下载的依赖默认保存在：

~/.m2/repository

清理依赖和清理项目构建产物不是一回事：

# 删除当前项目的 target，重新编译
mvn clean

# 只在依赖损坏时谨慎处理本地仓库中的特定目录

不要随意执行 rm -rf ~/.m2/repository。这会删除所有项目的本地依赖，下一次构建需要重新下载。

配套项目使用 Spring Boot 4.0.3。第一次构建需要下载依赖，之后才会使用本地缓存。看到下载进度时不要立刻判断卡死，可以先检查网络和 Maven 镜像。

第 6 步：首次构建

进入项目根目录。如果前一步已经克隆过，不需要重复执行：

git clone https://github.com/dvsusan/spring-boot4-demo.git
cd spring-boot4-demo
mvn clean package -DskipTests

成功时，demo-web/target/ 下会生成：

demo-web-1.0.0-SNAPSHOT.jar

注意 -DskipTests 只适合第一次确认环境。正常提交前应执行完整测试：

mvn clean verify

如果测试失败，不要用 -DskipTests 把它永久掩盖。先看失败的是测试编译、单元测试还是集成测试，再看具体堆栈。

第 7 步：启动并验证

java -jar demo-web/target/demo-web-1.0.0-SNAPSHOT.jar

启动日志中要确认三个信息：

The following 1 profile is active: "dev"
Tomcat started on port 8080
Started DemoApplication

再请求：

curl "http://localhost:8080/actuator/health"
curl "http://localhost:8080/api/v1/system/info"

第二个接口会显示当前 Java、应用名称和 Profile，可以用来确认 IDE、终端和运行 JAR 使用的是不是同一套环境。

停止服务时在终端按 Ctrl+C。如果端口仍被占用，检查其他终端或 IDE 中是否已有同一应用在运行。

第 8 步：排查端口占用

macOS 或 Linux 查看 8080：

lsof -i :8080

Windows PowerShell：

Get-NetTCPConnection -LocalPort 8080

最省事的验证方式是换端口：

java -jar demo-web/target/demo-web-1.0.0-SNAPSHOT.jar --server.port=18080

换端口后可以启动，说明代码正常，原端口被其他进程占用。不要为了让 8080 空闲而随意结束不认识的系统进程。

常见问题排查

现象	原因	处理方式
`UnsupportedClassVersionError`	运行 JDK 低于编译版本	统一为 JDK 21 或更高
Maven 显示 Java 17	`JAVA_HOME` 指向旧 JDK	修正环境变量并重开终端/IDE
依赖下载很慢	Maven 中央仓库网络较慢	配置团队认可的镜像，检查代理
IDEA 看不到子模块	只打开了子模块目录	从根 `pom.xml` 重新导入
启动提示端口占用	已有服务在运行	停止原进程或使用 `--server.port`
健康检查 404	运行了旧 JAR 或少了 Actuator	重新打包并检查 `demo-web` 依赖

练习题

用命令行把服务启动到 18081 端口，并完成以下验收：

/actuator/health 返回 UP。
/api/v1/system/info 的 activeProfiles 包含 dev。
关闭服务后，端口不再被该 Java 进程占用。

总结

环境搭建的目标不是装满工具，而是让终端、Maven、IDE 和运行进程使用同一套版本。只要 /actuator/health 返回 UP，后续教程就有稳定的起点。

下一篇从空目录搭建多模块工程，并解释为什么业务模块不应该反向依赖 Web 模块。

上一节：Spring Boot 4.0 新特性
 下一节：从零搭建多模块项目

13 个企业级实战项目 · 源码 + 教程 + 答疑

简历包装指导AI Agent 实战高并发·微服务Offer 导向持续更新3000+ 同行交流1V1 答疑3 天包退

覆盖高并发、微服务、分布式与 AI Agent：100万QPS短链、企业智能知识库、商城微服务、SaaS点餐、秒杀、刷题小程序、代码生成器、AI Agent 等。券后 ¥129（原价 ¥159），不满意 3 天包退。

立即获取 13 个项目源码 →