《Spring Boot 入门》2.1 JDK 与 Maven 环境准备

本节目标：在你的机器上装好 JDK 21 与 Maven 3.9.12，正确配置 JAVA_HOME 与国内镜像，并学会用 java -version、mvn -v 自证环境可用；读完后能独立排查「版本不匹配」「JAVA_HOME 未生效」「拉包慢」三类故障。
适用版本：Spring Boot 4.1.x（Java 21）

2.1 JDK 与 Maven 环境准备

上一节 1.3 版本线的选择 已经确定本书以 Spring Boot 4.1.x 为主线。要让它跑起来，第一件事是把工具链装好。本节把「装环境」拆成六步：定版本、装 JDK、配 JAVA_HOME、装 Maven、配国内镜像、选 IDE，最后给一张常见问题排查表。

版本基线：为什么锁定 Java 21

Spring Boot 4.1 的系统要求是 Java 17 起步，但那是下限，不是推荐值。下面这张表是本书全程使用的基线，后面每一节的实测输出都建立在这套版本上。

Java 的发布节奏是「每 6 个月一个特性版本，每 2 年一个长期支持版（LTS）」。17、21、25 都是 LTS，其余是只维护半年的过渡版本。选 LTS 的理由很实际：企业项目不会为了尝鲜每半年升级一次运行时，而框架、构建工具、CI 镜像对 LTS 的兼容验证也最充分。

为什么不选更新的 25？因为本书要保证示例在你手上能一次跑通。21 是当前被 Spring Boot 4.1、主流 IDE 和容器基础镜像验证得最透的 LTS；25 也能跑，但你若遇到工具链的边角问题，排查成本会转移到版本差异上，反而偏离了学习主线。先跑通，再谈升级，这是入门阶段最省心的策略。

顺带记一个容易混淆的点：Spring Boot 的「4.1」和 Java 的「21」是两条完全独立的版本线，前者是框架版本，后者是运行时版本。看到 spring-boot-starter-parent 的版本号时不要以为它和 JDK 版本有对应关系。

安装 JDK

三平台各有惯用方式，先给一张速查表，再展开说明。

macOS。 用 Homebrew 装 Temurin 21 最省心，它会落到标准 JDK 目录，供 /usr/libexec/java_home 识别：

brew install --cask temurin@21

安装完成后 JDK 位于 /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home。macOS 自带的 java 只是个转发器，真正挑哪个 JDK 由 /usr/libexec/java_home 决定，后面配 JAVA_HOME 时会用到它。

Linux。 推荐用 SDKMAN，它能同时管理多个 JDK 版本并切换：

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install java 21.0.12.1-tem

SDKMAN 会把 JDK 装到 ~/.sdkman/candidates/java/21.0.12.1-tem，并在激活时自动帮你设置 JAVA_HOME。

Windows。 从 adoptium.net 下载 OpenJDK21U-jdk_x64_windows_hotspot_21.0.12.1_1.msi 双击安装即可。安装器默认目录是 C:\Program Files\Eclipse Adoptium\jdk-21.0.12.1+1-hotspot，请记住这个路径，下一步配环境变量要用。注意别去装 Oracle 的 JDK 再纠结授权问题，Temurin 是免费且与 Oracle JDK 二进制兼容的选择。

配置 JAVA_HOME（三种 shell 写法）

JAVA_HOME 是给工具看的环境变量：Maven、Gradle、IDEA 都靠它找到 JDK。它和 PATH 里能直接敲 java 是两回事——java 能用，不代表 JAVA_HOME 已设置，这是后面「Maven 用的是 Java 8」这类故障的根源。

macOS 默认 shell 是 zsh，写入 ~/.zshrc：

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

Linux 常见的是 bash，写入 ~/.bashrc（登录 shell 也可写 ~/.bash_profile）：

export JAVA_HOME="$HOME/.sdkman/candidates/java/current"
export PATH="$JAVA_HOME/bin:$PATH"

Windows 有两种写法。用 cmd 的 setx 写进注册表（执行后必须新开一个终端才生效）：

setx JAVA_HOME "C:\Program Files\Eclipse Adoptium\jdk-21.0.12.1+1-hotspot"
setx PATH "%JAVA_HOME%\bin;%PATH%"

用 PowerShell 则修改用户级环境变量：

[Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Eclipse Adoptium\jdk-21.0.12.1+1-hotspot", "User")
$env:Path = "$env:JAVA_HOME\bin;$env:Path"

改完配置后，重开终端再验证。在已打开的终端里 source ~/.zshrc 只对当前窗口有效，新窗口不会自动继承。

验证 JDK 安装

最直接的证据是版本号：

java -version

openjdk version "21.0.12.1" 2026-08-18 LTS
OpenJDK Runtime Environment Temurin-21.0.12.1+1 (build 21.0.12.1+1-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.12.1+1 (build 21.0.12.1+1-LTS, mixed mode, sharing)

逐行读：第一行是版本与 LTS 标记；第二行是运行时实现（Temurin-21.0.12.1+1 即 Eclipse Adoptium 的构建）；第三行是虚拟机类型，64-Bit Server VM 表示是服务端 JIT。注意 java -version 的输出实际走的是标准错误流，用脚本抓取时要写 java -version 2>&1。

再确认 JAVA_HOME 确实生效：

echo "$JAVA_HOME"

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

两个命令一起看才有意义：如果 java -version 是 21 但 echo $JAVA_HOME 为空，说明只是 PATH 里恰好有 21，工具链仍可能找不到它。

安装 Maven 3.9.12

Maven 是个纯 Java 程序，安装就是「下载压缩包 + 加进 PATH」。macOS 也可以用 brew install maven，但 Homebrew 版可能绑定它自己的 JDK，多版本共存时容易踩坑，因此更推荐手动解压：

curl -O https://dlcdn.apache.org/maven/maven-3/3.9.12/binaries/apache-maven-3.9.12-bin.tar.gz
tar -xzf apache-maven-3.9.12-bin.tar.gz -C ~/

然后把 bin 目录加进 PATH（macOS/Linux 的 zsh/bash 通用）：

export PATH="$HOME/apache-maven-3.9.12/bin:$PATH"

Windows 用户下载 apache-maven-3.9.12-bin.zip 解压后，把 apache-maven-3.9.12\bin 加进系统 PATH 即可。

验证 Maven

mvn -v

Apache Maven 3.9.12 (848fbb4bf2d427b72bdb2471c22fced7ebd9a7a1)
Maven home: /Users/you/apache-maven-3.9.12
Java version: 21.0.12.1, vendor: Eclipse Adoptium, runtime: /Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home
Default locale: zh_CN, platform encoding: UTF-8
OS name: "mac os x", version: "26.3", arch: "aarch64", family: "mac"

这里最该盯的是第三行 Java version。它必须显示 21.x。如果它显示 1.8.0_xxx，说明 Maven 没读到 JAVA_HOME，回退用了系统里某个老 JDK——这不是 Maven 装错了，而是环境变量没配好。后面构建时你会看到 invalid target release: 21 之类的报错，根因就在这里。

第二行 Maven home 指向解压目录，可用来自查 PATH 是否指到了正确的那份 Maven。

用国内镜像加速依赖下载

Maven 默认从 repo.maven.apache.org 拉依赖，国内访问常慢到超时。解决办法是在用户级配置文件 ~/.m2/settings.xml 里加一个镜像。若该文件不存在，直接新建：

<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0
                              https://maven.apache.org/xsd/settings-1.2.0.xsd">
  <mirrors>
    <mirror>
      <id>aliyun-central</id>
      <name>Aliyun Central Mirror</name>
      <mirrorOf>central</mirrorOf>
      <url>https://maven.aliyun.com/repository/central</url>
    </mirror>
  </mirrors>
</settings>

几个要点：

• mirrorOf 写 central 表示只镜像 central 仓库，不会影响 Spring 的里程碑或快照仓库，最安全。
• 不要把 mirrorOf 写成 *，否则可能把公司私有仓库也一起劫持，导致内部依赖拉不到。
• ~/.m2/repository 是本地仓库，下载过的依赖缓存在这里。首次构建要把 Spring Boot 全家桶拉下来，本书实测首次构建耗时约 73 秒，之后的增量构建降到 38 秒左右，这个差异是正常的。

配好后想确认镜像真的生效，可以在任意 Maven 项目里加 -X 观察实际使用的仓库地址：

mvn -X compile 2>&1 | grep "Using mirror"

[DEBUG] Using mirror aliyun-central (https://maven.aliyun.com/repository/central) for central (https://repo.maven.apache.org/maven2).

看到 Using mirror 指向 aliyun，说明镜像配置被正确读取了；若这行不出现，多半是 settings.xml 的路径或 XML 格式有问题。

IDE 与必要插件

命令行能跑通就够了，但日常开发还是需要一个顺手的编辑器。两款主流选择对比：

IDEA 的 Spring 支持是它相对其它 IDE 的核心差异：@Autowired 注入哪个 Bean、自动配置为何生效或未生效，它能直接在编辑器里画出来。社区版没有这些能力，但本书的所有示例都能靠命令行跑通，社区版一样能学。

VS Code 需要装两个扩展包：vscjava.vscode-java-pack（Java 语言支持）和 vmware.vscode-boot-dev-pack（Spring Boot 工具）。装完后在命令面板里选 Spring Initializr 也能生成项目，和下一节的网页方式等价。

常见环境问题排查

把上面几步遇到的故障汇总成一张表，遇到问题按症状查：

排查这类问题有个通用思路：先让工具自报身份。java -version 告诉你运行时是谁，mvn -v 告诉你构建工具是谁、它用的是哪个 Java，echo $JAVA_HOME 告诉你环境变量是谁。三者对不上，问题就出在它们之间的连接处，而不是某个工具本身。

小结

• Spring Boot 4.1 要求 Java 17+，本书统一用 Java 21 LTS 与 Maven 3.9.12，主线版本为 Spring Boot 4.1.1。
• 装 JDK 后必须配置 JAVA_HOME；macOS 用 java_home 命令，Linux 用 SDKMAN 路径，Windows 用 setx 或 PowerShell 写用户变量。
• 验证口诀：java -version 看运行时，echo $JAVA_HOME 看变量，mvn -v 的 Java version 行看两者是否接通。
• ~/.m2/settings.xml 里加 mirrorOf=central 的阿里云镜像能显著加速拉包；首次构建慢是正常的。
• IDE 首选 IntelliJ IDEA Ultimate，社区版与 VS Code 也能完成本书全部示例。
• 环境类故障的通用排查法：让每个工具自报身份，比对三者是否指向同一个 JDK。

环境就绪后，下一步是用官方初始化器生成项目骨架——表单怎么填、依赖怎么选、生成的 pom.xml 每一段是什么意思，见下一节 2.2 用 start.spring.io 生成项目 。

阅读导航：上一节：1.3 版本线的选择 · 下一节：2.2 用 start.spring.io 生成项目 。