你有没有过这种经历在 start.spring.ioSpring Initializr上选好 Spring Boot 版本、点几下鼠标下载项目压缩包IDEA 里一打开还没写任何业务代码编译就直接抛红java: 无效的源发行版: 16。这个报错我前后帮人排查过不下十次。说句实话它本身不是个难问题但它特别能折磨人——因为报错指向的是 Java 16很多人第一反应是我机器上装的是 JDK 8/11那我把 16 卸了/换了不就行了结果换完还是报错或者不知道去哪一步换。这篇文章把这个问题从现象到根因完整拆一遍覆盖 IDEA Maven / Gradle、命令行、以及打包机上同样的坑。如果你正被invalid source release: 16这类红色报错卡住照这条链路走一遍基本能根治。1. 先把报错翻译成人话编译器要的是 Java 16你机器里根本没有先别着急改配置要把这行报错读懂。无效的源发行版16对应的英文是invalid source release: 16它不是一个警告或提示而是javac编译器在启动时给的硬错误。意思非常直白你要求编译器用 Java 16 的语法规则来编译源码但当前正在执行的 JDK 根本不认识 Java 16 这个版本号。也就是说这个问题不是代码写错了而是编译工具链的版本不对齐。常见情况是你本机装的是 JDK 8 或 JDK 11但项目里通过 Maven 插件或者 IDEA 配置把编译参数指定成了-source 16 -target 16。javac 检查到当前自己是 1.8 或 11看到目标版本 16 超出自己的能力范围直接拒绝干活。用一个生活化的类比javac 就像一个只装了英文翻译包的翻译机你递给它一份法语文件要求它翻成法语。它不会瞎猜不会硬着头皮勉强翻而是直接罢工告诉你这个语言我不认识。你可以直接在命令行里复现这个机制。装 JDK 8 的机器上$ java -version openjdk version 1.8.0_382 Java(TM) SE Runtime Environment (build 1.8.0_382-b05) $ javac -source 16 -target 16 Test.java javac: 错误: 无效的源发行版: 16JDK 11 上结果类似只是报错文字可能是 invalid flag: 16或者 release version 16 not supported本质都一样。编译器不会因为你代码里没用到什么新特性就放你一马-source参数的版本号必须小于等于当前 javac 自己支持的版本否则一律拒绝。这里还有一个反直觉的点很多人以为Java 16 也是个稳定版本编译器版本低点无所谓。实际上 javac 的-source/-target只能向下兼容一两个版本JDK 8 连 Java 9 都不认识更别说 16。每代 JDK 编译器的知识范围是固定的它支持的源发行版列表里没有的就是没有不会自动降级也不会猜测你要什么。2. 项目是 Initializr 生成的为什么它会默认生成 Java 16搞清楚报错原理后下一个自然的问题是我这项目明明是 Spring Initializr 生成的它为什么给我搞出一个本机没有的 Java 16原因在于 start.spring.io 生成项目时pom.xml 里有一个关键属性properties java.version16/java.version /properties而你从官网下载项目时页面上有一个Java 版本下拉框它默认值取决于你选的 Spring Boot 版本。很多人创建项目时注意力全在 Spring Boot 版本、依赖选择上Java 下拉框压根没注意直接用默认值于是项目就在本地被声明成了 Java 16。把时间线拉长一点看更清楚Spring Boot 2.4.x 时代Initializr 默认 Java 是 11。Spring Boot 2.5.x 时代也就是 2021 年那会儿Spring 官方把默认 Java 版本提到了 16当时 Java 16 正好是 LTS 之后的短期版本社区讨论度很高。后来 Spring Boot 3.x 把基线直接抬到 Java 17所以现在的 start.spring.io 默认基本是 17 或 21。如果你用的教程、笔记、视频是两三年前的或者你当时创建项目的时候网页刚好停留在某个旧选项组合上download 下来的项目很可能就是java.version16。还有一部分情况是你用了内网私有化的 Initializr 服务那个服务版本很老默认值自然也是旧版本的 16。Spring Boot 父 POMspring-boot-starter-parent会读取这个java.version属性自动帮你配置maven-compiler-plugin的 source/targetplugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId configuration source16/source target16/target /configuration /plugin也就是说你在网站上点的那个看似不起眼的 Java 16 下拉框最后会原封不动变成编译器参数。你本机没有 JDK 16就触发了第一节那个硬错误。3. 从报错来源往下追四个配置点怎么互相打架现在正式进入排查环节。见过太多人一上来就改 pom.xml改完没用又改 IDEA 设置改完还是没用因为根本不知道这个报错是由哪一层设置触发的。把下面几个检查点按顺序过一遍基本能锁定问题。3.1 先确认报错是 IDEA 编译器报的还是 Maven 构建报的看控制台的报错位置和信息格式如果报错出现在 IDEA 底部的Build / Compiler 输出格式是java: 无效的源发行版: 16这是 IDEA 自带的编译器在调 javac。如果报错出现在 Maven 面板的构建日志里格式一般是[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:...:compile ... invalid target release: 16这是 Maven 调的编译器。虽然两个来源最终都指向同一个 javac 参数问题但它们的配置入口不同。先区分来源才不会在错误的地方瞎折腾。3.2 命令行确认你现在到底用的是哪个 JDK这一步是地基建议先做。打开终端java -version javac -version echo $JAVA_HOME三条命令的结果要保持一致。很多机器上java -version显示的是 1.8但JAVA_HOME指向的可能是已经装好的 JDK 17 路径或者反过来。IDEA 和 Maven 有时候各自有独立的 JDK 来源不一定跟终端的 PATH 一致但我们要先把这个基准摸清楚。这里有个非常常见的隐藏坑你已经装了 JDK 17只是终端用的还是旧 JDK。Windows 上安装 JDK 17 之后PATH 里如果旧 JDK 的路径排在前面终端永远调的是旧的。Linux/macOS 上则可能是alternatives或.bashrc里的 export 顺序不对。后面第 5 节单独说。3.3 IDEA 里的三个设置点经常互相覆盖IDEA 对编译级别有多个页签级别的设置它们是有优先级关系的很多人只改其中一个所以改完没效果。首先是最显眼的Project Structure。快捷键CtrlShiftAltS打开看两个地方Project - SDK当前项目用的是哪个 JDK。Project - Project language level这个下拉框定义了语言级别8、11、16、17它影响的是 IDEA 内置编译器的-source参数。这两个地方必须互相匹配并且和项目的java.version匹配。如果 Project SDK 是 1.8而 language level 是 16IDEA 的编译器直接就会报无效的源发行版: 16。其次是Settings - Build, Execution, Deployment - Compiler - Java Compiler。这里有一个 per-module 的字节码版本设置它覆盖 Project 级别的 language level。如果之前手贱在这个表里给某个 module 单独设了 target bytecode version那 Project Structure 里怎么改都压不住它。第三处是 Maven 项目特有的Settings - Build, Execution, Deployment - Build Tools - Maven - Runner - JRE。这一个是我见过最隐蔽的坑。它的作用是指定 Maven 构建进程那个跑mvn的 JVM用哪个 JDK。当你点 Maven 面板里的 compile 时走的是这里。如果这个下拉框选的是Project SDK (1.8)或者某个旧 JDK那即使你 Project SDK 已经换成了 17Maven 构建用的还是 1.8pom.xml 里写的 java.version16 照样让它报错。我把四个配置点汇总成一张表方便对照配置点位置影响范围常见坑Project SDKProject Structure - Project整个项目的运行和编译基准下拉框里有 17但实际没装对应 JDK只是历史残留Project language levelProject Structure - ProjectIDEA 内置编译器的 source 级别和 Project SDK 版本不匹配per-module bytecode versionSettings - Build - Java Compiler覆盖 language level改过之后忘了全局怎么改都不生效Maven Runner JRESettings - Maven - RunnerMaven 构建进程的 JDK锁死旧 JRE无视 Project SDK 的变化3.4 Gradle 项目还有一个专属配置如果你的项目不是 Maven 而是 Gradle那除了上面 IDEA 层面的设置外还要注意 Gradle 构建进程本身使用哪个 JDK。Gradle 从 7.3 开始支持完整的 Java 17 编译但你如果项目里gradle/wrapper/gradle-wrapper.properties指向的是一个老版本 Gradle比如 6.x它对 JDK 16 的支持也是不完整的报错形态更多样。Gradle 的 JDK 可以通过gradle.properties指定org.gradle.java.home/usr/lib/jvm/java-17-openjdk或者通过环境变量JAVA_HOME决定。Gradle 的坑在于即使 IDEA 的 Gradle JVM 设置里选对了 JDK命令行直接跑./gradlew build时用的又是另一套环境。所以 Gradle 项目一定要确认命令行和 IDE 两边用的是同一个 JDK。4. 落地修复换 JDK 还是降编译级别看你用哪个 Spring Boot 版本排查完四个配置点接下来才是真正的修复动作。修复方案其实只有两条路让项目匹配本机已有的 JDK或者让本机的 JDK 匹配项目。选哪条路不取决于你的心情而取决于 Spring Boot 的版本。在动手之前先记住一张兼容性对照表Spring Boot 版本最低 Java 要求是否可用 Java 16是否能降级到 Java 82.3.x / 2.4.xJava 8可以可以2.5.x / 2.6.xJava 8可以可以2.7.xJava 8可以可以3.xJava 17不能Spring Framework 6 要求 17不能如果是 Spring Boot 2.5 或 2.6 这种项目POM 里声明 Java 16 是正常的你既可以把 JDK 升级到 16 或 17也可以把编译级别降回本机的 JDK 8/11。但如果你的项目是 Spring Boot 3.x那么最低门槛就是 Java 17Java 16 本身就不满足要求正确的做法是把 JDK 升到 17 或更高而不是把编译级别降下去——降到 8 或 11 会让项目直接跑不起来。4.1 推荐路线装一个和项目匹配的 JDK我的建议是不要折腾降级直接装 JDK 17。理由有三点Spring Boot 3.x 本身就是 17 起步以后你升级 Boot 版本也不用再换 JDK。JDK 17 是 LTS社区支持、各种插件兼容性都比 16 好。Java 16 只是个过渡版本很多老版本 Lombok 在 16 上都有兼容问题在 17 上反而早就修好了。你只需要在 IDEA 里点几下不用改任何项目文件。操作步骤到 Adoptium 官网或你常用的镜像站下载 OpenJDK 17Windows 直接 exe 安装macOS 装 dmgLinux 解压 tarball。IDEA 里File - Project Structure - SDKs - 加号 - Add JDK选择你刚安装的 JDK 路径。在Project - SDK下拉框里选中刚添加的 JDK 17Project language level同步选 17。检查第 3 节那四个配置点确保 Maven Runner 和 Java Compiler 里没有残留旧 JDK 的设置。回到 IDEA点 Maven 面板的刷新按钮Reload All Maven Projects或者右键 pom.xml - Maven - Reload project。重新编译。4.2 妥协路线把编译级别降到本机 JDK如果因为各种原因实在不想装新 JDK比如公司网速太慢、机器权限受限也可以把项目编译级别降到本机已有的 JDK。操作如下在 pom.xml 里修改properties java.version11/java.version /properties把java.version改成你本机 JDK 对应的版本8 就写 811 就写 11。如果项目的 POM 里还显式配置了maven-compiler-plugin而且写死了 source/target也要同步改plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId configuration source11/source target11/target /configuration /plugin同时把 IDEA 的 Project language level 同步改成 11。然后重复步骤 5 和 6。这里必须提醒一句不要直接去下载一个 JDK 16 装上就以为万事大吉。如果你的项目是 Spring Boot 2.5 时代生成的装 JDK 16 确实能编译但 Java 16 已经停止公开更新而且很多 IDE 插件的兼容列表里早就没有 Java 16 了。装 16 是给未来埋雷装 17 才是正道。4.3 改完 POM 还要改 IDEA 的两处“记忆”这是最容易功亏一篑的地方。POM 改好了但是 IDEA 不会立即跟着变。它有自己的项目模型缓存。实际经验是改完 POM 必须做以下两件事的全部组合缺一个都可能继续报错右键 pom.xml - Maven - Reload project。如果还不行File - Invalidate Caches...勾选 Clear file system cache and Local History然后 Restart。再不行关掉项目删掉项目根目录下的.idea文件夹如果不怕麻烦.iml文件也删重新用Open打开项目。别觉得第四步夸张。.idea里的 modules.xml 和 compiler.xml 可能存着旧的 module language levelIDEA 在处理这种情况时常常比我们想象中更恋旧。删掉重开等它从 POM 重新导入是终极干净的方案。5. 改完配置还是一样报错这几种“配置残留”必须清掉走到第 4 节大部分人的问题已经解决了。但还是有相当一部分人改完配置、刷新完 Maven一编译还是同样的红字。这通常不是原理没搞懂而是有几处配置残留没有被清掉。单独列一节因为这些坑真的值得记录。5.1 终端里 java -version 没变装的 JDK 白装了如果你在第 4.1 节装了新 JDK但打开终端执行java -version还是旧版本那说明 PATH 里旧 JDK 的优先级更高。这是 Windows 上极其常见的现象安装新 JDK 只是往C:\Program Files\Java放了一堆文件但系统 PATH 里仍然指向旧的 JDK 8 路径。解决方法Windows系统属性 - 环境变量 - Path找到旧 JDK 的路径通常是C:\Program Files\Java\jdk1.8.0_xxx\bin把它删掉或移到新 JDK 路径后面。Linux/macOS检查~/.bashrc、~/.zshrc或/etc/profile里的export PATH语句确认没有把旧 JDK 的 bin 目录排在前面。5.2 Maven 的全局 settings.xml 里没有玄机但 Maven 本身用的是系统的 JAVA_HOME还有一个很容易误解的点Maven 是个 Java 程序它自己跑在某个 JVM 上。如果你在 IDEA 里通过 Maven Runner 指定了 JDK 17那 IDEA 里的 Maven 构建是好的但你切换到命令行执行mvn clean compile它用的是系统 PATH 里的 JDK完全是另一套。反之亦然。所以无论你在 IDEA 里怎么设置命令行构建必须单独检查环境变量export JAVA_HOME/usr/lib/jvm/java-17-openjdk export PATH$JAVA_HOME/bin:$PATH如果你是 mac 用户也可以写在.zshrc里然后source ~/.zshrc。5.3 IDEA 版本太老不认识 Java 16/17很少人意识到IDEA 自身也有版本上限。如果你的 IDEA 是 2020.3 或更早它内置的编译器组件对 Java 16 的支持是不完整的你在 Project Structure 里可能压根找不到 language level 16 的选项或者选了之后拉不起 JDK 16。这种情况下的表现很迷惑明明 Project SDK 已经指向 JDK 17但编译还会报奇怪的错误。本质上不是项目的问题是 IDE 版本太老。解决思路很直接——升级 IDEA。如果你公司环境不允许升级 IDE那只能走第 4.2 节把项目编译级别降到你 IDE 能支持的范围内。5.4 Lombok 等注解处理器的版本拖后腿如果你在项目里用了 Lombok修完 JDK 版本之后可能遇到第二个报错比如java: 程序包lombok不存在或者更隐蔽的注解处理异常。原因是 Lombok 内部大量使用了 javac 的非公开 APIJDK 版本一换老版本 Lombok 就不认了。Spring Initializr 生成的默认 Lombok 版本往往偏保守当你把 JDK 从 8 升到 17 时最好同时把 Lombok 升级到1.18.30或更高版本。这个细节网上很少写但实际项目里踩到的概率不低。5.5 “最干净也最暴力的”清理流程当所有配置看起来都对、依旧报错的时候我推荐的终极清理流程是记下你当前已经修改好的 POM 配置java.version 的值。关闭 IDEA 项目。删除项目根目录下的.idea文件夹。如果你用的是 Maven删除你的本地仓库里该项目相关的旧 SNAPSHOT 依赖缓存~/.m2/repository不确定的话先保留。重新用 IDEA 打开项目根目录让它重新识别 POM。等右下角索引跑完手动点一次 Maven 面板的刷新再执行 compile。这一步做完所有存储在 IDE 项目文件里的历史配置都会被清空一切从 POM 重新开始。我处理过的最顽固的一例就是这里面的workspace.xml缓存的模块编译选项在作怪改什么都不生效删除.idea后一次就过了。6. 脱离 IDE 的视角命令行和打包机上的同款报错很多人在本地 IDEA 里修好了结果在服务器上打包或者上 CI 流水线又遇到一模一样的报错。这其实一点都不奇怪——本地的修复是基于 IDE 的设置而命令行/CI 环境只认 JDK 相关环境变量和配置文件。6.1 最常见的服务器场景CentOS/Ubuntu 上 mvn compile 报错如果你在服务器上执行mvn clean package报了invalid source release: 16第一件事是看mvn -version的输出$ mvn -version Apache Maven 3.8.7 Maven home: /opt/maven Java version: 1.8.0_292看到Java version: 1.8就明白了Maven 跑在 JDK 8 上。这里不管项目要求的是 16 还是 17反正 8 不认识。处理办法sudo yum install -y java-17-openjdk-devel # 或者 apt install openjdk-17-jdk export JAVA_HOME/usr/lib/jvm/java-17-openjdk export PATH$JAVA_HOME/bin:$PATH但要注意export只对当前终端会话有效关闭终端就没了。要永久生效建议写进~/.bashrc或者/etc/profile然后source。如果服务器上还有别的 Java 程序依赖 JDK 8你就不能全局改默认 JDK而应该只为 Maven 指定JAVA_HOME/usr/lib/jvm/java-17-openjdk mvn clean package这样只改变这一次命令的 JDK不影响系统全局设置。这是一种非常干净的做法。6.2 CI 流水线里的 JDK 矩阵在 GitHub Actions、GitLab CI 这类环境里JDK 版本由流水线配置决定常见错误是在流水线里只配了setup-java的版本但 Maven 用的还是默认 JDK或者流水脚本里的JAVA_HOME被其他步骤覆盖了。GitHub Actions 一般这样用- name: Set up JDK 17 uses: actions/setup-javav3 with: distribution: temurin java-version: 17如果项目是 Spring Boot 3.x流水线里 Java 版本设成 8 或 11那它构建出来的结果必然和本地一样红。CI 环境没有 IDEA 那层可视化配置所有问题都会直接暴露在JAVA_HOME这个环境变量上。排查思路和服务器一致。6.3 用 Maven Toolchains 做多 JDK 管理后期值得了解的进阶方案如果你的日常工作就是同时维护多个用不同 Java 版本编译的项目那么每次切项目都改JAVA_HOME会很烦。Maven 提供了toolchains.xml可以在项目层面指定用哪个 JDK而不用改环境变量。在~/.m2/toolchains.xml里声明toolchains toolchain typejdk/type provides version17/version /provides configuration jdkHome/usr/lib/jvm/java-17-openjdk/jdkHome /configuration /toolchain /toolchains然后在项目的pom.xml里声明使用这个 toolchain再配合maven-compiler-plugin的release参数就可以做到一个 Maven任意切换 JDK。这是一个后期优化方向刚被invalid source release折磨的读者不必立刻上手但知道有这条路能让你以后少走很多弯路。第七节就不设了最后分享两个我从实际项目里沉淀下来的小经验。第一个经验是不要只修不验证。改完配置后别只在 IDEA 里点一次绿色三角就以为完事了。一定要分别验证mvn compile和mvn package两个命令因为 IDEA 内置编译器和 Maven 构建用的是两套机制前者过了不能代表后者过。很多项目本地能跑、打包就挂根子就在这里。第二个经验是报错里出现的版本号是项目想要的环境不是你拥有的环境。看到16不要只想着怎么把 16 弄没要顺着它去确认项目的java.version、IDEA 的 Project SDK、Maven Runner JRE 这三个是否一致。这套排查思路比记住任何一个单一命令都值钱——因为今天你可能遇到 16明天升级 Spring Boot 3 后还会遇到 17、21逻辑完全一样只是数字不同而已。