UnsupportedClassVersionError本质是JVM版本低于字节码编译版本所致：JDK 21对应主版本号65，若在JDK 17（主版本61）等低版本JVM上运行，则触发该错误；需通过java -version、检查JAVA_HOME与PATH、验证IDE/构建工具配置、比对class文件major version等步骤逐层排查并统一编译与运行环境为JDK 21。
Java程序启动时提示“找不到或无法加载主类”“UnsupportedClassVersionError”“java不是内部或外部命令”，本质是JDK环境异常在不同环节的外显症状，必须按启动链路逐层验证，跳过任一环节都可能陷入反复重装的死循环。
确认JDK是否真实安装并可被系统识别
第一步：打开终端（Windows用CMD/PowerShell，macOS/Linux用Terminal），执行：
java -version
如果返回“'java' 不是内部或外部命令”或“Command not found”，说明系统根本未识别到java可执行文件——此时不要急着重装JDK，先查PATH是否漏加。
第二步：执行 where java（Windows）或 which java（macOS/Linux），看输出路径是否指向你安装的JDK目录下的bin子目录。
第三步：若无输出，手动进入JDK安装目录（如 【C:Program FilesJavajdk-17.0.2in】 或 【/usr/lib/jvm/java-17-openjdk-amd64/bin】），直接运行 java -version。能成功则证明JDK本身完好，问题纯属环境变量配置缺失。
验证JAVA_HOME与PATH是否协同生效
方法一：检查JAVA_HOME是否设置且指向JDK根目录（非jre子目录）
Windows执行：echo %JAVA_HOME%
macOS/Linux执行：echo $JAVA_HOME
输出必须是类似 C:Program FilesJavajdk-17.0.2 或 /usr/lib/jvm/java-17-openjdk-amd64 的完整路径，【结尾不能带in】。
方法二：确认PATH中是否包含 %JAVA_HOME%in（Windows）或 $JAVA_HOME/bin（macOS/Linux）
Windows执行：echo %PATH% | findstr "java"
macOS/Linux执行：echo $PATH | grep java
若未出现JDK bin路径，说明PATH未继承JAVA_HOME，需手动追加——【切勿只把JDK bin路径硬编码进PATH，否则切换JDK版本时将失效】。
方法三：验证javac是否存在
执行 javac -version
失败则说明JAVA_HOME指向的是JRE而非JDK，或PATH未生效；成功则证明开发工具链已就位。
排查IDE与构建工具使用的JDK是否与系统一致
IntelliJ IDEA：
① 打开 File → Project Structure → Project，检查 Project SDK 是否选中你期望的JDK版本（如17），而非“Project default SDK”这种模糊选项；
② 进入 Settings → Build → Compiler → Java Compiler，确认 Target bytecode version 与 Project SDK 版本严格一致；
③ 若使用Maven，打开 Maven → Importing，勾选 “Import Maven projects automatically”，并确认 JDK for importer 设置为同一JDK。
VSCode：
按 Ctrl+Shift+P → 输入 “Java: Configure Java Runtime”，在“Java Toolchain”列表中确认已检测到目标JDK；
若未出现，打开 settings.json 手动添加：
"java.home": "/path/to/your/jdk-17"（macOS/Linux）或 "java.home": "C:\Program Files\Java\jdk-17.0.2"（Windows）；
【注意：此处路径必须精确到JDK根目录，且不能有尾部斜杠】。
Maven项目：
检查 pom.xml 中是否显式声明了编译版本：
<properties>
<java.version>17</java.version>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
</properties>
缺失此项会导致Maven默认用JDK 8编译，即使系统装了JDK 17也会生成不兼容字节码。
诊断运行时版本冲突的核心证据
当程序抛出 java.lang.UnsupportedClassVersionError 时，错误信息末尾会显示类似 “Unsupported major.minor version 61.0” 的数字——这个61.0就是关键线索：
Java 17 对应 major version 61，Java 11 是 55，Java 8 是 52。
执行 javap -verbose YourMainClass.class | grep "major" 可直接读取该class文件的实际版本号；
再比对 java -version 输出的JRE版本，二者不匹配即为根源。
若使用Spring Boot Fat Jar，不要仅依赖 java -jar 启动时的报错——它可能调用的是系统默认JRE而非你配置的JDK。
强制指定JRE运行：
"/path/to/jdk-17/bin/java" -jar your-app.jar
若此方式成功，则100%确认是环境变量或脚本中JRE路径错配。
容器与CI/CD环境中的隐蔽陷阱
Docker镜像中常见错误：基础镜像标称 openjdk:17-jdk，但实际拉取的是 jre 版本。
验证方式：docker run --rm -it openjdk:17-jdk javac -version
若报错“command not found”，说明镜像不含编译器，只能运行不能编译——生产镜像可用 jre，但构建镜像必须用 jdk。
Jenkins流水线中：不要依赖全局JAVA_HOME，应在 pipeline 脚本内显式指定：
environment { JAVA_HOME = "/opt/java/jdk-17" }
sh 'export PATH=$JAVA_HOME/bin:$PATH && mvn clean package'
否则节点上多个JDK共存时，mvn 命令可能调用错版本。
