解决 Java 编译报错：源发行版 17 需要目标发行版 17

问题背景

遇到 java: 警告：源发行版 17 需要目标发行版 17 这种报错，核心问题通常是编译环境与运行环境的版本定义不一致。别急，咱们按顺序排查几个关键点。

一、验证 JDK 环境是否一致

首先确认本地安装的 JDK 版本。有时候系统里装了多个版本，但构建工具默认调用了旧版本。

检查命令：

java -version
javac -version

确保输出显示的是 JDK 17（如 17.0.11）。如果低于 17，建议直接安装 JDK 17。

验证构建工具使用的 JDK： Maven 和 Gradle 可能各自携带了不同的 JDK 环境，需单独确认：

mvn -v
gradle -v

看输出中的 Java version 字段，必须与项目要求的 17 保持一致。

二、修复构建工具配置

Maven 项目

在 pom.xml 中，除了父工程依赖，编译器插件的配置才是关键。Spring Boot 3.x 通常要求 JDK 17，但插件版本过低可能导致兼容性问题。

推荐配置：

<properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <!-- 推荐使用 release 标志，语义更明确 -->
    <maven.compiler.release>17</maven.compiler.release>
</properties>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
        </plugin>
    </plugins>
</build>

这里用 release 参数比单独设 source/target 更稳妥，它能同时控制源码级别和字节码目标版本。

Gradle 项目

Gradle 同样需要显式指定兼容性，或者使用工具链自动管理。

显式设置：

tasks.withType(JavaCompile) {
    sourceCompatibility = '17'
    targetCompatibility = '17'
}

工具链配置（推荐）：

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

工具链能避免手动指定带来的路径混乱问题。

三、检查环境变量

很多时候是环境变量没生效。重点检查 JAVA_HOME 是否指向正确的 JDK 17 目录。

Windows:

echo %JAVA_HOME%

Linux/macOS:

echo $JAVA_HOME

确保 PATH 变量中包含 %JAVA_HOME%\bin 或 $JAVA_HOME/bin，否则命令行可能调用到系统自带的旧版 Java。

四、IDE 配置检查

如果是 IntelliJ IDEA，有时 IDE 的缓存或设置会覆盖构建工具的设定。

1. 项目结构： File > Project Structure > Project，将 Project SDK 和 Project language level 都设为 17。
2. 模块设置： Modules > Sources，确保语言级别也是 17。
3. 编译器设置： File > Settings > Build, Execution, Deployment > Compiler > Java Compiler，检查 Target bytecode version 是否为 17。

搞定这些基本就稳了，重新刷新一下项目依赖即可。