Maven build failed这种红字报错见过不少但Failed to execute goal org.codehaus.mojo:exec-maven-plugin:1.6.0这句话绝对能排进我最常被问到的榜单前三。第一次遇到它时我的第一反应是冲进代码里翻main方法查启动类折腾了快两小时。后来才发现这个报错十有八九和你的业务代码没关系真正的坑藏在插件本身、JDK版本、类路径这几层里。这篇文章就专门拆解这个报错。我会先说清楚exec-maven-plugin这个插件到底在构建过程中扮演什么角色再按照我实际踩坑的频率把最容易出问题的几个层面讲透最后给出一套完整的排查流程。无论你是刚接触Maven的新手还是被这个报错折磨了一下午的老油条顺着这篇的思路走一遍基本能定位到问题。1. 先搞清楚这个报错是什么它只是一个包装壳很多人看到Failed to execute goal org.codehaus.mojo:exec-maven-plugin:1.6.0:java ...就直接懵了因为报错信息里没有任何业务线索只有插件坐标和一个failed。这里的关键认知是Maven本身不直接跑你的Java程序它只是负责调度插件。exec-maven-plugin这个插件的作用是在Maven的构建流程里帮你去执行一个外部程序——最常见的就是执行某个类的main方法或者运行一条可执行命令。当你看到这句Failed to execute goal其实它只是Maven在说某个插件任务没跑成功真正的病因藏在后面跟着的Caused by堆栈里。可以把这个过程理解成快递运输Maven是快递公司exec插件是某个中转站你的代码是包裹。中转站告诉你包裹未送达只是结果通知真正的原因可能是包裹太大、地址写错、车辆坏了得查具体的派送记录。同理直接看这句红色加粗的Failed to execute goal没有意义有意义的是它下面那一串以Caused by开头的异常堆栈。触发这个插件的常见入口有三类命令行直接执行mvn exec:java -Dexec.mainClasscom.example.Main在 pom.xml 里通过execution绑定到某个生命周期阶段比如compile或test阶段自动执行在IDE里点右键RunIDE底层经常也是帮你调用exec插件我见过一个典型的案例某个项目本地跑得好好的换了一台新电脑拉代码后直接报这个错。很多人第一反应是重新编译、清理缓存结果还是一样。这种代码没变但环境变了的情况大多数和插件版本、JDK版本、类路径隔离有关而不是代码本身的逻辑问题。提示排查这类报错的第一步永远是找到Caused by那几行它才是真正告诉你哪里出问题的入口。先不急着改pom先看堆栈。2. exec插件的运行机制拆解java vs exec要真正理解这个报错得知道exec插件有两种执行模式它们的失败表现完全不同。很多人搞混这两个goal导致排查方向从一开始就跑偏。2.1 exec:java 和 exec:exec 的本质区别这两个goal经常让人混淆但它们做的事情有本质不同。exec:java是在Maven进程内部直接加载并运行Java类的main方法。所谓内部是指它不启动一个新的JVM而是复用Maven运行时的类加载器ClassRealm把你的项目依赖和插件自身依赖全部装进同一个内存空间。这种模式的优点是省事、启动快非常适合本地调试。缺点是它无法真正做到类路径隔离如果依赖之间有冲突很容易出现奇怪的类明明存在却加载不到的情况。exec:exec则是真正fork出一个全新的独立Java进程去执行你的程序。它可以指定独立的jvmArgs、独立的classpath、设置工作目录、配置环境变量基本上等同于在命令行手动敲一条java -cp xxx YourMainClass。这种模式更接近生产环境的启动方式但配置复杂度高而且一旦fork失败报错信息会绕开Maven的日志框架直接输出进程退出码或底层错误。我把两者的核心差异整理成了一张表对比项exec:javaexec:exec是否fork新JVM否复用Maven进程是启动独立JVMclasspath来源Maven的运行时类路径可能混入插件依赖需显式指定或依赖classpathScope配置可配置JVM参数通过jvmArgs有限支持完整支持最接近生产环境失败后的报错抛MojoExecutionException堆栈在Maven日志中可能看到process exited with不同退出码典型使用场景本地快速调试main方法需要隔离环境、自定义启动参数的场景常见失败点类冲突、mainClass写错、模块访问限制进程启动失败、路径配置错误、环境变量缺失我个人的习惯是本地调试用exec:java验证脱离Maven环境后还能不能跑时用exec:exec。很多在exec:java下能正常跑的程序一换到exec:exec就报类找不到这种前后对比本身就是照妖镜。2.2 为什么Maven只展示Failed to execute goal这么干巴巴的一句话这是Maven插件体系的一个特性也恰恰是它不友好的地方。Maven调用任何插件执行时最终都是通过反射调用该插件的execute()方法。只要插件内部抛出异常Maven就会把它包装成MojoExecutionException然后向外输出统一的错误头——也就是你看到的Failed to execute goal 插件坐标:goal。这意味着无论底层是ClassNotFoundException、InaccessibleObjectException、端口被占用还是依赖下载失败最上层的报错永远长一个样子。所以排错时必须有剥洋葱的心态。一个完整的报错通常长这样[ERROR] Failed to execute goal org.codehaus.mojo:exec-maven-plugin:1.6.0:java (default-cli) on project demo: Execution default-cli of goal org.codehaus.mojo:exec-maven-plugin:1.6.0:java failed: ... [ERROR] ... - [Help 1] [ERROR] [ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch. [ERROR] Re-run Maven using the -X switch to enable full debug logging.注意看最后两行提示用-e看完整堆栈用-X开启调试模式。这是Maven在明示你报错被我包装过了。排查的第一步就是执行mvn exec:java -e -X把完整的堆栈打出来然后从Caused by开始往上看。3. 最隐蔽的根因之一JDK版本与exec-plugin 1.6.0的版本错配这是我在实际项目中遇到最多的原因尤其是从JDK 8升级到JDK 11或17之后报错比例飙升。3.1 版本发布时间线插件比JDK老很多exec-maven-plugin 1.6.0 这块版本第一次发布大约是在2017年前后设计目标基本是围绕JDK 8的。它默认的行为、反射方式、类加载逻辑都建立在JDK内部API随便访问这个前提上。JDK 9开始引入了模块系统JPMS最显著的变化是JDK内部API不再默认开放给外部程序随意反射访问。编译期可能一切正常到了运行期代码一旦尝试用反射去改JDK类库的内部字段或者访问非导出模块里的类JVM就会不客气地抛InaccessibleObjectException。而这个过程恰好发生在exec插件为你启动的那个JVM里于是异常被一层层包装最终从表面看就是那个万能报错头。3.2 典型异常长什么样如果你在高版本JDK下用了exec-maven-plugin 1.6.0报错堆栈里通常会出现类似下面的内容Caused by: java.lang.reflect.InaccessibleObjectException: Unable to make field private final java.util.ArrayList java.util.Collections.emptyList accessible: module java.base does not opens java.util to unnamed module 6b3eafae at java.base/java.lang.reflect.Field.canSetAccessible(Field.java:...) at java.base/java.lang.reflect.Field.setAccessible(Field.java:...)看到InaccessibleObjectException、does not opens ... to unnamed module这两个关键字基本可以断定是JDK版本与插件版本不兼容。这里说的unnamed module指的就是Maven进程以及exec插件fork出的程序所在的那个不成模块的普通类路径环境。3.3 两种修复路线路线一升级插件版本推荐最省力的方案是直接升级exec-maven-plugin到 3.x 系列。新版本对JDK 9做了大量适配默认处理了模块访问相关的问题。在pom.xml里显式声明版本即可plugin groupIdorg.codehaus.mojo/groupId artifactIdexec-maven-plugin/artifactId version3.1.0/version executions execution goals goaljava/goal /goals /execution /executions /plugin路线二保留旧版本但手动开放模块访问如果因为某些原因无法升级插件版本可以通过jvmArgs传递--add-opens参数来手动开放访问权限。比如plugin groupIdorg.codehaus.mojo/groupId artifactIdexec-maven-plugin/artifactId version1.6.0/version configuration jvmArgs jvmArg--add-opensjava.base/java.utilALL-UNNAMED/jvmArg jvmArg--add-opensjava.base/java.langALL-UNNAMED/jvmArg /jvmArgs /configuration /plugin这条路只能说能用实际使用中往往会遇到没开放干净的包接二连三也要补参数。我的经验是排查顺序先从插件版本入手升级到3.x往往能直接解决几十个奇怪的小问题。3.4 判断是不是这个原因的最快方法不用猜直接看三个数mvn -version显示的Java版本pom或父pom中exec-maven-plugin的版本报错堆栈里是否包含InaccessibleObjectException、module相关字样顺手排一个对照表配合项目使用的JDK版本选择推荐插件版本JDK版本exec-plugin 1.6.0exec-plugin 3.1.0JDK 8正常正常JDK 11可能报InaccessibleObjectException正常JDK 17大概率报模块访问错误正常JDK 21严重不兼容正常提示还容易忽略的一点是IDE里默认的JDK和你terminal里JAVA_HOME指向的可能不是同一个版本。我遇到过几次命令行没问题、IDE一直报错的情况最后发现是IDE的Runner JRE配得太老。这个属于环境错配和插件本身无关但排查时一定要想到。4. 不是模块问题的那些根因类路径与mainClass如果说JDK版本是时代造成的坑那类路径和mainClass的问题就是自己挖的坑。这类问题在团队协作项目里特别常见因为每个人IDE状态、Maven本地仓库缓存都不一样。4.1 mainClass写错报错却不像报错使用exec:java时Maven需要通过-Dexec.mainClass或pom配置里mainClass找到入口。这里的常见错误有几个第一类名没有写全限定名。比如落在了com.example.demo.Main结果配置写了Main。Maven解析不到时抛出的往往是ClassNotFoundException但它在堆栈里很容易扫过就忽略。第二main方法签名不对。Java要求入口方法必须是public static void main(String[] args)一个字都不能错。如果写成了public void main或者参数名写错Java运行时会报Main method not found in class ...。第三类放在test目录但配置在compile阶段执行。exec:java默认使用runtime阶段的classpath如果你的启动类在src/test/java里没经过test-compile就执行自然找不到类。这个坑在跑测试辅助工具时特别容易踩。4.2 依赖冲突编译期不报运行期才崩exec:java复用的是Maven的运行时类路径scope这意味着项目里compile和runtime范围内的依赖会被全部塞进去。如果一个类在多个依赖里都存在比如不同版本带了同一个包Maven会按照依赖声明顺序或最近定义优先策略选择其中一个但这个过程不一定和你的预期一致。于是就会出现这种情况编译阶段一切正常因为编译只需要接口但运行到具体实现时类加载器在一个意想不到的位置找到了同名类抛NoSuchMethodError、LinkageError或者NoClassDefFoundError。这些错误被包装成exec执行失败后非常迷惑人因为它们都不是常规的ClassNotFoundException。我还遇到过META-INF/services服务发现机制导致的诡异问题。某个模块用了SPI方式加载实现编译期只需要依赖接口模块运行期的具体实现来自另一个runtime依赖。某个依赖声明为了provided或没有正确传递整个程序编译全通过一exec:java就崩报NoClassDefFoundError查半天才发现是SPI实现类的JAR根本没进入运行classpath。4.3 一个典型的编译期正常运行期崩案例某次做数据处理模块本地main方法里加载了一个配置中心的客户端编译、打包都正常。但用mvn exec:java启动时程序刚跑几行就报NoClassDefFoundError指向配置中心的一个内部类。排查过程让我印象最深这个内部类所在的JAR确实在本地仓库里pom里也写了依赖按道理不应该缺。最后用了mvn dependency:tree一查才发现那个依赖在父pom中被声明成了optional导致它不会传递到本模块的运行时路径而IDE里能跑是因为IDE的依赖分析逻辑更宽容自动把optional依赖也加进去了。这个案例说明一个道理exec插件报错时不要只盯着代码看先跑一遍dependency:tree把依赖图从上到下捋一遍。很多时候所谓缺类不是真的缺是没进入运行时。5. 排错实操从复现到定位的标准化流程前面讲了原理这部分给一套可以照做的排查流程。我每次遇到这个报错基本都按这个顺序走从拿到报错到定位半小时内能收敛。5.1 第一步抓住原始堆栈别让Maven帮你藏第一步很重要但也是最容易被跳过的。直接在终端里跑mvn exec:java -e -X-e会输出完整堆栈-X会输出调试级别日志。这两个参数一上来就把Maven包装报错的那层壳揭掉了。跑完不要急着关终端从输出里找到第一个Caused by它通常离真正的异常最近。同时检查当前终端JAVA_HOME指向mvn -version echo $JAVA_HOME java -version这三条命令显示的内容必须保持一致。这里经常出现一个情况Maven本身用的是JDK 17但你pom里java.version写的是1.8编译确实是按兼容模式走可运行时反射行为可能依然受JDK 17底层限制。版本信息不一致就是隐患。5.2 第二步最小化复现隔离变量如果你手里是一个大型项目依赖多、模块多不建议在一个庞大的项目里来回试。我的做法是直接新建一个最小的临时目录放三个文件一个pom.xml、一个带main方法的类、一个最简单的exec插件配置。能复现问题说明问题大概率出在插件、JDK、环境这三者的组合上不能复现说明问题出在项目本身的依赖或配置组合上。这个对照能快速把排查范围缩小一半。在这个最小工程里分别测试升级exec插件版本切换JDK版本修改jvmArgs调整classpathScope每调整一个变量记录一次mvn exec:java的结果基本几轮就能锁定具体是哪个变化解决了问题。5.3 第三步按检查表逐项排除当你掌握了一个最小复现工程下面这张表可以直接当成清单用检查项验证命令/操作通过标准JDK版本一致性mvn -version与项目要求的JDK版本一致exec插件版本查看pom中artifact版本优先使用3.xmainClass全限定名mvn exec:java -Dexec.mainClass...能加载到对应类依赖树mvn dependency:tree -Dverbose无版本冲突或缺失pom中的classpathScope检查exec插件配置视启动需求设为compile/runtimeIDE Runner JRE检查IDE设置与命令行一致Maven本地仓库缓存mvn -U强制更新排除下载不完整可能系统字符集Windows下检查GBK乱码排除编码导致的解析问题这表里的每一项我都踩过。比如第6项IDE的Runner JRE之前说过是IDE和命令行行为不一致的元凶第7项Maven本地仓库缓存一旦之前依赖下载中断留下半截文件Maven不会自动重新下载跑步起来的情况也会以exec报错出现第8项GBK乱码某些Windows环境下日志输出乱码会让你误解异常位置影响判断。5.4 第四步验证修复效果问题定位并修复后不要只在命令行跑一次就收工。我通常在同一台机器上用两种方式验证mvn clean verify mvn exec:java -Dexec.mainClassYourMainClass如果项目打包本身有问题clean verify会先暴露出来避免把插件问题混在一起。跑完后再用exec:exec测试一次进程独立启动模式确认fork出的JVM退出码是0。只有这三种方式全部通过我才会认为这个报错真正解决。6. 修复后的预防让pom配置变得能打报错解决不是终点关键是不让它反复出现。最后这部分谈谈配置规范化和多环境构建的策略。6.1 一份值得抄作业的exec插件配置经过多次打磨我现在倾向用下面这套配置兼顾隔离性、可控性和可调试性plugin groupIdorg.codehaus.mojo/groupId artifactIdexec-maven-plugin/artifactId version3.1.0/version configuration mainClasscom.example.Main/mainClass classpathScoperuntime/classpathScope cleanupDaemonThreadsfalse/cleanupDaemonThreads /configuration executions execution idrun-main/id phasecompile/phase goals goaljava/goal /goals configuration !-- 只在这里留mainClass方便命令行覆盖不容易混乱 -- mainClasscom.example.Main/mainClass /configuration /execution /executions /plugin几点说明classpathScope默认是runtime如果启动时需要用到测试/编译期的类需要显式调整。cleanupDaemonThreads设为false可以避免某些后台线程在程序结束后仍拖住Maven进程的问题这个参数在启动带线程池的程序时会救你一命。如果在命令行执行mvn exec:java -Dexec.mainClass...注意它和pom里mainClass的优先级关系命令行参数会覆盖pom配置利用这个特性做切换很方便。6.2 多JDK环境下的统一策略每个开发者电脑上的JDK版本、Maven版本完全一致是不可能做到的。项目组里一半人用JDK 8、一半用JDK 17时exec插件报错几乎是必然的。我建议借用构建辅助插件来强制固定构建环境比如maven-enforcer-plugin通过规则约定本项目必须使用哪个Java版本不符合就提前失败。plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-enforcer-plugin/artifactId version3.4.1/version executions execution idenforce-java/id goals goalenforce/goal /goals configuration rules requireJavaVersion version[17,18)/version /requireJavaVersion /rules /configuration /execution /executions /plugin这样配置后谁用了不匹配的JDKMaven会直接给出Java版本不满足要求的明确提示而不是让exec插件在运行到一半时才以Failed to execute goal的方式爆出来。这个把错误提前到构建启动阶段的思路能让团队整体的排错效率高很多。6.3 团队协作中那些容易被忽略的版本漂移还有一个细节值得专门提一下尽量在项目pom里显式声明exec-maven-plugin的版本不要依赖父pom或超级pom里继承来的版本。有些项目把插件版本放在一个公共父pom的pluginManagement里子模块只管引用artifactId不写version。这个做法的风险是一旦父pom升级或父模块引用了另一个父模块插件版本可能在不知不觉中发生变化。版本变化带来的行为差异比业务代码变更隐蔽得多。我自己维护的一些基础脚手架项目里现在都强制要求插件版本必须在模块内部显式声明宁可多写几行也不要在别人电脑上跑不出来时才去找版本漂移的问题。另外如果你在团队里经常被同事问为什么我这台机器报这个错可以在代码仓库的README里直接写清楚JDK要求、命令行运行方式、IDE运行方式、需要显式的环境变量。看着像废话实际上能省掉大量反复沟通的成本。有一次我照着这个思路写了一段运行环境说明之后团队里关于exec插件报错的提问量明显降了一个档次。结尾从我第一次看到Failed to execute goal org.codehaus.mojo:exec-maven-plugin:1.6.0时的手足无措到现在基本能在几分钟里定位问题最大的体会就是Maven报错不可怕可怕的是只盯着最上面那行红色加粗字。现在只要看到这个报错我的肌肉记忆就是先往下翻Caused by再看JDK版本最后才轮得到检查自己项目的代码和依赖。最后分享一个小技巧如果你经常用mvn exec:java启动本地服务可以把这个命令固化成一个小脚本把jvmArgs、mainClass、系统环境变量都写进去。这样既避免了每次敲长串参数容易出错也等于把这个项目应该怎么启动这件事固化成了团队约定。再遇到这个报错就能更快地区分到底是环境问题、配置问题还是插件本身的坑了。
