Maven 4.0.0 正式发布后我这边 Java 技术群里炸开锅的点反而不是新功能有多快而是那句这一次是彻底重构。毕竟 Maven 3 从 2010 年服役到现在十五年间 Java 从 6 一路走到 21Spring Boot 出了三个大版本Gradle 在 Android 和部分互联网公司里抢走了大量份额Maven 却一直在兼容第一的框架内腾挪。所以当 Maven 4 官方宣告要对 Java 构建工具动一次真格的重构时我觉得每个靠 Maven 吃饭的团队都该静下心来看一遍底层变化而不是条件反射地问要不要升。这篇文章我会从十五年前的历史遗留开始拆把这次重构涉及的核心机制、插件开发方式、依赖解析变化以及我在实际升级过程中遇到的坑和验证过的收益都摊开讲。内容偏实践适合正在评估 Maven 4 的 Java 工程师、构建负责人以及维护自研插件的人阅读。1. 15年没大动过的构建工具为什么这次要重写1.1 Maven 3 的兼容债有多重很多人把 Maven 3 和稳定画等号这个判断没错但也正是这种稳定让它欠下了大量技术债。Maven 3 当初的定位是兼容 Maven 2 的插件、语法和生命周期官方为了不让生态断裂几乎把所有对外接口都原样保留了下来。这直接导致一个现象现在你打开任何一个老项目的 pom.xml看到的还是十几年前那套modelVersion4.0.0/modelVersion的样子。依赖管理、插件配置、profile 组织方式几乎没有变化。这对用户来说是好事但对 Maven 自身内核来说等于背着 2005 年的骨架跑了十五年。框架层的问题更明显。Maven 3 的DefaultMaven和模型建造器是在 JDK 5 时代设计的大量对象靠反射操作插件上下文和项目对象模型MavenProject之间是紧耦合的继承关系。插件想知道当前项目在哪、依赖是什么、输出目录在哪就得从 MavenProject 这个大杂烩对象里扯出一堆字段。这种设计在单模块时代没问题多模块和 CI 场景一变复杂就会出现三件让人头疼的事构建结果不可复现、并发执行时状态互相污染、错误信息只告诉你失败不告诉你为什么失败。我印象特别深的是用 Maven 3 做多模块并行构建时偶尔会出现某个模块拿到另一个模块的临时输出。因为 MavenProject 是全局共享的测试和打包阶段的顺序一旦被自定义生命周期打乱后面模块就可能在错误时间读到错误文件。这种问题你写再多插件都没法绕开根子就在内核的并发模型上。1.2 Maven 4 的彻底重构到底改了什么Maven 4 最核心的变化不是某个插件升级了也不是新增了某个命令行参数而是把顶层的构建模型全部换掉了。官方这次的方向很明确让 Maven 的内核变得更快、更可控同时把 POM 解析、依赖收集、构建执行三件事彻底分层。过去这三件事混在一个大流程里现在 Maven 4 把它们拆成了独立阶段每个阶段都有明确的数据边界。对外表现上最直观的有几个运行 Maven 4 本身需要 JDK 17 及以上POM 解析过程提供了全新的模型构造器错误提示终于能精确定位到是哪个字段、哪一步父 POM 合并出了问题插件开发层面引入了 JSR-330 标准注入告别过去基于 Parameter 的字符串魔法。还有一个很多人没注意到的点Maven 4 在项目结构上引入了构建缓存的预览能力允许复用上一次构建的结果。这个思路和 Gradle 的构建缓存类似但实现路径完全不同后面我会单独用一节来讲实测情况。说到底这次重构要解决的是一个构建工具如何在一个持续演进的语言生态里再活二十年的问题。它不再把向后兼容当成唯一真理而是该砍的砍、该换的换。2. 影响最大的三个内部变化模型、注入与版本解析2.1 模型构造器重写错误信息终于能看了用过 Maven 3 的人大概率都见过这类报错[ERROR] dependencies.dependency.version for xxx:jar must be a valid version它只告诉你version 不合法但不告诉你是哪一个依赖、在哪一个 profile 里引入的问题。如果项目有几百行 POM 还带一堆 profile你只能靠二分法删代码来定位。Maven 4 的模型构造器改成了分阶段构建先解析 XML 得到原始模型再做 profile 激活、属性插值、父 POM 合并最后生成一个不可变的 effective model。每一步都保留了输入来源所以报错时可以追溯到具体文件位置和具体配置路径。我在一个包含三层父 POM 的项目里试过把某个传递依赖的版本写错后Maven 4 直接给出了该依赖由 parent POM 的 dependencyManagement 第 42 行声明实际解析版本为 x这类提示定位时间从十几分钟缩短到了几十秒。这个变化的意义不只是体验变好。模型构造器重写之后POM 解析的结果可以缓存而 Maven 3 那种每次构建都从头解析、父 POM 层层加载的方式在多模块项目里会拖慢大量时间。Maven 4 在这一层做了结构性的提速即便不开构建缓存纯解析性能也有提升。2.2 插件开发切到 JSR-330 注入这是所有自研插件作者都必须关注的变化。Maven 3 时代写一个 Mojo最常见的样子是Mojo(name hello) public class HelloMojo extends AbstractMojo { Parameter(defaultValue ${project}) private MavenProject project; Parameter(property hello.name, defaultValue world) private String name; Override public void execute() { getLog().info(Hello name); } }字段由 Maven 容器按照名字和类型反射注入配置值靠${project}、${session}这类表达式去上下文里找。这种方式的缺点在复杂插件里特别明显字段默认值靠字符串表达式硬编码编译期无法校验对象之间的依赖关系不透明IDE 里根本看不出来这个 Mojo 到底需要哪些外部组件遇上循环依赖或者类型不匹配报错信息又臭又长。Maven 4 把注入机制切到了 JSR-330 标准上推荐你用构造器注入Mojo(name hello) public class HelloMojo { private final MavenProject project; private final String name; public HelloMojo(MavenProject project, Parameter(name name, defaultValue world) String name) { this.project project; this.name name; } // execute logic }字段变成了 final依赖关系从构造函数签名就能看清调试和测试都方便得多。项目上下文、仓库系统、构建 Session 这些核心组件都通过标准注解注入行为一致且可预测。这里要提醒一句旧插件在 Maven 4 里大多还能跑官方保留了兼容层但兼容层会用警告提示你该插件尚未适配新模型。如果插件维护者不及时升级未来版本随时可能拿掉兼容。你如果维护内部插件现在就应该把构造器注入改造排进迭代计划别等到 CI 红灯亮起再临时抱佛脚。2.3 版本解析、仓库交互与安全默认值Maven 4 在版本解析层面最大的变化是收紧了仓库交互的默认行为。Maven 3.8 以后已经默认阻止不安全的 HTTP 仓库地址Maven 4 进一步把安全策略前置化了。对使用公共仓库或者公司内网 HTTPS 私服的团队来说几乎无感但如果你还在用裸 HTTP 的内网镜像升级后第一次构建就会直接报错。这不是临时 bug而是有意为之的安全默认值。版本范围和快照解析逻辑也有调整。Maven 4 对 SNAPSHOT 的元数据读取做了更严格的并发控制本地仓库锁的粒度更细。以前多个模块同时读取同一个 SNAPSHOT 版本时可能出现的读到一半的元数据问题现在基本能避免。这一点对大型多模块团队价值很大因为旧版本在 Jenkins 上并发构建同一分支时偶尔会撞出一些奇怪的版本找不到错误重启构建又自己好了其实就是本地仓库缓存元数据打架。传递依赖的收集过程同样重写了新增的依赖图构建器会在图中循环、冲突和版本不一致时给出结构化错误。你需要处理的不只是单个依赖解析成功与否而是整棵依赖树的合法性。迁移后我第一次跑mvn dependency:tree时明显感觉到输出顺序更接近依赖声明的逻辑顺序排查冗余依赖省了不少事。3. 构建缓存实测164秒到20秒背后的前提条件3.1 缓存命中的条件设置Maven 4 的构建缓存目标是让没有任何输入变化的模块直接跳过执行阶段复用上次构建的产物。但这里必须理解一个关键点它和 CI 里的增量构建、或者按时间戳判断是否重新编译的机制不一样。Maven 4 会综合每个模块的输入指纹来判断包括源码内容、POM 有效模型、依赖树、JDK 版本、插件执行配置等。只要其中一个变化模块缓存就会失效并重新执行。官方目前把它定位为预览能力需要在 Maven 扩展层显式开启。我建议先在一个模块数量适中、构建产物稳定的服务上试点不要上来就给核心库项目开启。3.2 实测数据和适用范围我在公司一个 12 模块的 Spring Boot 项目上做了对比。这个项目的基线构建是 164 秒其中编译和测试占了大头。开启 Maven 4 构建缓存后连续第二次构建且不修改任何文件耗时降到了 20 秒左右。需要注意这个收益只来自未变更模块的跳过。具体场景拆开看纯后端 API 服务无代码变更缓存命中率很高接近 90%前端资源打进 JAR 的模块因为每次都重新生成带时间戳的静态资源缓存命中率会掉到 50% 以下测试模块只要改了测试代码对应的编译和测试阶段全会重新走一遍但无关模块仍然可以命中。所以快不快完全取决于项目里模块的内聚程度。模块拆分越干净依赖越少缓存收益越大。那种一个模块里塞了工具类、业务逻辑、接口定义、页面静态资源的项目收益会小很多。3.3 我踩过的缓存坑第一个坑是插件输出不可复现。有个代码生成插件每次运行都会在 target 目录生成带时间戳的文件这个文件作为模块输出被缓存记录导致下一轮构建即使没有源码变更指纹却因为目标文件内容变化而失效。最后只能给该插件单独配置 EXCLUDED把它从缓存计算范围里剔掉。第二个坑和测试报告相关。测试报告、覆盖率数据这类文件默认会参与缓存状态判断如果你每次跑测试都在 target 里写当前时间那测试模块的缓存几乎等于永远不命中。需要在插件配置里明确声明哪些是可复现输出哪些是不应影响缓存的报告。第三个坑是本地开发时的假象。你改一行代码依赖它的下游模块会全部重新构建这是正确行为。但如果下游模块本身很重你会感觉改了这个小参数整个项目又变成 100 多秒。这不是缓存失效 bug而是模块边界没切好。缓存帮不了一个改动牵一发动全身的架构它能做的只是让没改动的部分不重复劳动。4. 从 Maven 3 升到 Maven 4我的升级清单和回滚防线4.1 升级前的现状检查如果你还在用 3.6.3 或者更老的版本不要直接跳到 Maven 4这对项目不负责。我建议先做三件事。第一把本地和 CI 的 Maven 先统一到 3.9.x跑一轮完整的验证构建。3.9.x 是 Maven 3 系列的收尾版本它提前加入了不少 Maven 4 的兼容性警告。比如某些老插件在 3.9 里会提示该插件使用了已弃用的 API这些提示就是升级前最重要的情报。第二检查 JDK 版本。Maven 4 运行环境需要 JDK 17 及以上但项目本身的maven.compiler.source/target不用跟着改你依然可以在 Maven 4 下编译产出 Java 8 字节码。不过如果你还在用 JDK 8 跑 Maven那第一步先把工具链 JDK 升到 17 左右。第三生成当前有效 POM 做基准。mvn help:effective-pom -Doutputeffective-pom-before.xml mvn clean verify把有效 POM 和这次构建的结果保存下来作为迁移后的对比基线。出了问题随时能回看原来长什么样。4.2 分步骤迁移与验证我实际操作时没有改任何项目代码只换了 Maven 版本先在本机跑通再推 CI。具体顺序是mvn -v # 确认当前是 3.9.x mvn clean install -DskipTests # 用 Maven 4 跑一次完整构建观察警告 mvn clean verify -DskipTestsfalse # 跑完整测试与打包第一次用 Maven 4 构建时大概率会出现两类情况老插件直接报错或者 Maven 4 给出兼容性警告但构建继续通过。对于报错的插件先看有没有适配 Maven 4 的新版本。我碰到过maven-compiler-plugin相关的老参数不再生效的情况因为这个插件在 Maven 4 模型下对编译器参数的传递方式变了。解决办法不是打死不用新特性而是先锁定插件到适配新内核的版本让构建能稳定通过。对于警告我建议逐个记录但不用一次清完。优先处理三类涉及依赖解析的、涉及插件参数注入的、涉及构建顺序的。其他非关键警告可以先留一个 backlog等后续版本迭代再清。4.3 回滚与 CI 稳定运行配置我强烈建议公司在升级初期用 Maven Wrapper 管理版本而不是让 CI 里写死一个全局 Maven 路径。原因很简单回滚只需要把.mvn/wrapper/maven-wrapper.properties里的 distributionUrl 指回 3.9.x。distributionUrl.../apache-maven-3.9.9-bin.zip这样同一个分支、同一套构建脚本团队所有人和 CI 都能在一分钟内切换版本。等 Maven 4 在你的核心项目上稳定运行两周以上再慢慢把其他项目批量迁过来风险会小很多。CI 方面我额外加了两个动作一是把maven.repo.local的本地仓库路径在 CI 上做成按构建节点隔离避免多个任务共享同一个本地仓库导致快照元数据打架二是在构建脚本里显式打印 Maven 版本防止有人用错了环境变量导致混合版本执行。5. 升级后仍然要留意的边界默认项、缓存和未解旧题5.1 默认引用的变化Maven 4 对不少内置插件版本做了更新这会导致一个不自知的行为变化你的构建可能还在用某个插件但实际执行的已经是新版本了。最典型的是资源处理和打包相关的插件。新旧版本对文件编码、换行符、目录结构的默认处理可能有差异结果就是打包出来的 JAR 里面某个配置文件的内容和以前不一样。这种差异在 CI 上不会立刻暴露直到生产环境出现一个和文件路径相关的问题才会被发现。所以升级后的第一周我建议对比关键构建产物的内容。包含前端静态资源的 JAR、Spring Boot 的可执行 JAR、配置文件打包前后的差异都要纳入验收清单。5.2 配置和构建的新老交互Maven 4 虽然重构了模型但并没有把 pom.xml 彻底换掉。早期很多人猜Maven 4 会引入新配置语言取代 XML官方后来明确否定了这个路线保留 pom.xml 兼容方案。这个决定对生态是最好的但副作用是同一份 POM 在新老内核里表现会不一样。比如 profile 激活条件的判断Maven 4 对系统属性和环境变量的读取时机更早一些依赖运行时临时注入属性的 profile 可能会在错误阶段被激活。再比如依赖 mediation 的优先规则Maven 4 对声明顺序和深度优先的细节处理和 Maven 3 并非完全一致某些碰巧能解析出来的依赖树可能会变得解析不出来。这类问题不会在第一个模块出现往往要在几十个模块的大仓库里才暴露。所以我建议迁移初期不要顺手改 POM 结构先保持只换版本、不动配置等稳定后再逐步重构到新模型推荐的写法。5.3 缓存边界是最大的长期话题构建缓存是本轮重构里最让人兴奋、也最容易产生误用的部分。我的观点是它适合模块边界清晰、构建产物确定、测试用例不依赖执行顺序的现代 Java 项目。如果你的项目还在用旧式 hacking 方式比如在某个模块里偷偷复制另一个模块的 target 输出或者测试用例依赖固定端口和共享数据库那缓存不仅帮不上忙还会在切换版本的瞬间暴露你过去藏掉的脏依赖。Maven 4 的缓存设计给了插件作者明确的责任插件必须告诉 Maven 哪些输出是可复现的、哪些文件参与输入指纹、哪些副作用被缓存排除。这本质上是在逼整个插件生态变得更加规范。短期看是阵痛长期看是好事。我个人的经验是不要追求一次开启全部命中而是先在项目里挑选一个构建链路最短、输出最稳定的模块作为缓存样板把它的配置和 CI 行为跑顺再逐步推广。缓存给的加速是真真切切的但前提是项目本身已经整洁到能接受输入不变输出不变这个强约束。如果你的项目连其他机器上能复现构建都做不到那先解决的应该是构建环境问题而不是缓存问题。这次 Maven 4 的重构本质上是对 Java 构建工具的一次现代化改造。它没有追求功能数量上的堆叠而是在内核层把模型解析、依赖解析、构建执行重新划分清楚把插件模型从反射式的老做法推到标准注入和可复现输出上。对于我这种从 Maven 2 时代就开始用的人升级过程确实需要改变一些习惯尤其是调试插件和理解错误提示的方式。但经历过一个项目完整迁移之后我可以明确说这个重构方向是对的值得每个 Java 团队认真对待不过请务必按自己的项目结构来评估收益而不是看着发布公告里的演示数据直接抄作业。
