当前位置：首页 > web >正文

Maven 项目构建时编译错误问题排查与解决

web 2025/7/3 15:04:46

1. 问题描述

Maven 项目执行命令 mvn clean package 时出现编译错误，如下图所示
mvn 构建错误日志

2. 问题分析

由于是源码编译错误，于是通过查看项目 pom.xml 文件，得到项目源码使用的 Java 版本为 21

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><properties><maven.compiler.source>21</maven.compiler.source><maven.compiler.target>21</maven.compiler.target></properties><build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><configuration><!-- 源码的 Java 版本为 21 --><source>${maven.compiler.source}</source><!-- 最终源码编译为的 Java 版本为 21 --><target>${maven.compiler.target}</target></configuration></plugin></plugins></build>
</project>

再执行命令 mvn -v ，可知当前 mvn 命令依赖的 Java 环境是 Java 17，如下图所示，而项目源码需要编译为 Java 21，这相当于要使用 Java 17 编译生成 Java 21 的字节码，导致构建失败。
mvn 版本信息

Maven 本身也是一个 Java 应用，也就是说它本身的运行也是要基于 JVM 的，mvn -v 命令的输出信息中的 Java 版本就是其运行时依赖的 Java 环境；

Maven 的编译器插件 maven-compiler-plugin 其实并不知道如何编译 Java 源码，它实际是调用了 JDK 中的 javac 工具完成编译的，而这里的 javac 工具就是来源于 Maven 运行时依赖的 Java 环境；

javac 工具考虑了向后兼容性，即允许高版本的 javac 将源码编译为与其版本相同或者比其版本低的字节码，但是无法生成比起自身版本更高的字节码；

3. 问题解决

思路方向：升级 Maven 运行时的 Java 版本（即升级对应 javac 工具的版本）。

我们知道，使用 Maven 前，需要提前设置 Java 环境，设置好对应的 JAVA_HOME 环境变量，所以我们可以直接调整系统的环境变量 JAVA_HOME，让其指向 Java 21，再进行项目构建。但是这样调整会影响系统的其它 Maven 项目，其它 Maven 项目不一定都是使用 Java 21 的，所以采用下面的解决方案：

# 先在当前命令会话临时设置 JAVA_HOME 环境变量（如果是 Windows 系统，语法稍有不同）
JAVA_HOME=/path/to/java/21
# 再执行命令构建
mvn clean package

mvn 构建成功日志

注：可以通过查看 $MAVEN_HOME/bin/mvn 运行脚本的源码知道设置 JAVA_HOME 环境变量起作用的原因。

4. 问题记录

个人在解决问题过程中，发现在当前命令会话临时设置 JAVA_HOME 环境变量一直无法生效，后面经过一番艰辛探索，发现是个人系统存在 mavenrc 的相关文件导致的，该文件是 ~/.mavenrc，其文件内容为：

export JAVA_HOME=/usr/local/java/jdk-17.0.1

而 $MAVEN_HOME/bin/mvn 运行脚本会加载该文件，导致当前命令会话临时设置的 JAVA_HOME 环境变量被覆盖了。
加载 mavenrc 文件脚本源码
最后，考虑到 ~/.mavenrc 这种文件属于特定平台的配置，而不是 Maven 的标准配置，于是直接删除 ~/.mavenrc 文件，以便顺利解决问题。