Maven 4 要来了这次真不是 3.x 的例行小升级。从 2010 年 Maven 3 发布到现在Java 构建工具这个领域被 Gradle 抢走了很多声量但你去翻任何一个老牌企业的后端工程跑得最多的还是 Maven。官方把 Maven 4 定位成“彻底重构”我一开始是不信的毕竟 Maven 太稳、太重重构的风险肉眼可见。直到我拿真实的多模块项目在 4.0.0-beta 上完整跑了几轮才确认这次确实动了骨架新 POM 模型、内核组件重写、反应堆排序、缓存钩子全都不再是小修小补。这篇稿子就是把这次升级的底层逻辑和操作细节摊开来讲帮你在升级之前搞清楚它到底改了什么、哪些坑必须躲。构建负责人、CI 维护者以及想弄明白 Maven 内部原理的 Java 开发者都可以从这里入手。1. Maven 4 到底重构了什么先看清这次“大换代”的底牌1.1 为什么是十五年后才来这次大改版先说背景。Maven 3 在 2010 年发布当时 Java 生态还停留在 JDK 6/7 时代构建产物以 WAR 包为主、单体应用是主流CI 也就是 Jenkins 加定时构建。十五年过去服务端的主流已经变成 Spring Boot 的可执行 JAR、微服务拆分带来的多模块仓库、JDK 17/21 的长期支持版本以及云原生时代对构建速度和资源利用率的苛刻要求。Maven 3 的核心架构包括它内部那套组件容器和依赖解析链路本质上是按单机、单进程、顺序执行的场景设计的后来虽然一路追加了并行构建、增量编译这些能力但很多是补丁叠补丁。这十五年里 Gradle 靠增量构建、守护进程、更灵活的 DSL 抢了大量用户尤其在新兴互联网团队里几乎成了默认选择。Maven 社区当然感受到压力但 Maven 的生态太庞大——光中央仓库里几万个插件和几十万个项目就决定了官方不可能像 Gradle 那样隔几年改一轮 DSL。所以 Maven 4 的重构思路非常明确保留 POM、goal、插件、生命周期这套用户模型不动把底下拖后腿的引擎全部换掉。这也解释了为什么官方敢用“彻底重构”这种词因为他们确实把内核翻了个底朝天但对外暴露的接口基本没变普通用户升级时的认知负担被刻意压低了。1.2 重构的四个核心方向Maven 4 的改动面看似很大归纳起来就四个方向。第一是 POM 模型。Maven 4 引入新的模型版本 4.1.0校验规则更严格对历史遗留的模糊写法不再容忍。这个改动看起来只是版本号变化实际影响的是每一个 pom.xml 的解析方式。第二是内核容器。Maven 3 内部还保留了很多 Plexus 时代的组件声明方式组件定义散落在配置文件和代码里。Maven 4 把组件模型收拢到基于 JSR-330 注解的依赖注入组件之间的装配关系从“XML 里查一遍、代码里再找一遍”变成“看注解就懂”。第三是反应堆和增量能力。多模块项目的构建顺序、按需构建、并行构建这是 Maven 4 性能提升最明显的部分也是我实测里体感最强的地方。第四是依赖解析器。Maven 4 换装了更新的 Resolver 实现下载并发度、版本解析、校验行为都和 Maven 3 有明显差异。这四个方向基本覆盖了“构建工具”的全部关键环节所以称它为重构并不夸张。1.3 “彻底重构”是营销话术还是真实变化我的判断是话术层面有夸张工程层面不算虚。说夸张是因为 Maven 的核心用户模型——写 POM、绑插件、跑生命周期——没有变你日常写的mvn clean package也不用换。但工程层面你随便翻一下 Maven 4 的源码或者看插件兼容清单就知道内部确实是把旧引擎拆掉重装了。说个直白的类比Maven 3 是一台开了十五年的老车车身POM 生态还能用发动机内核容器和解析链路已经接近设计极限Maven 4 干的事情就是把发动机整个换掉同时保留你熟悉的方向盘和油门。所以你对“彻底”的理解应该限定在内部实现层面而不是说 Maven 变成了一个全新的构建系统。2. 第一个改动就是 pom.xml新版 POM 4.1.0 的玩法2.1 modelVersion 从 4.0.0 换成 4.1.0意味着什么Maven 4 最大的可见变化之一就是 POM 的 modelVersion。过去所有项目都写modelVersion4.0.0/modelVersionMaven 4 新项目可以直接声明4.1.0它代表的是新的 POM 解析模型。这里容易误解的是你不把 modelVersion 改成 4.1.0Maven 4 也能正常构建——它保留了向后兼容的老模型解析能力。但是只有切到 4.1.0你才享受新模型的严格校验和更干净的行为也更符合“迁移到新平台”的姿态。我的建议是全新项目直接用 4.1.0老项目在看清楚新规则后再考虑切换没必要为了升级而升级。2.2 模型校验更严格老 pom 可能第一时间报错新版 POM 模型最直接的影响是校验。Maven 3 对 pom.xml 的很多问题只是警告甚至静默忽略Maven 4 里可能直接升级成构建失败。我踩到的最典型的有三类。第一是未知字段。早期项目为了图省事会在 pom 里塞自定义标签或者用不同规范的 XML 头声明Maven 4 对这类“看不懂的节点”处理更严格会在 validate 阶段直接抛 MalformedPomException。第二是重复依赖声明。同一个 groupId:artifactId 在不同位置比如 dependencies 和 dependencyManagement 反复出现或者一个依赖在多个 profile 里重复声明Maven 3 很多时候睁一只眼闭一只眼Maven 4 更倾向于报错或要求你必须处理。第三是 parent 字段的解析。老项目里 parent 内部缺 version、或者用相对路径引用 parent 但路径不规范这些以前能跑的情况在新模型里会成为校验错误。遇到这些报错不用慌处理逻辑就是“把声明写清楚、把冗余删干净”。多跑几次mvn validate它会把第一个触发的错误行号告诉你。2.3 属性继承与占位符的规则收紧另一个不容易发现的变化在属性继承。Maven 3 里有一个历史遗留问题子模块如果定义了一个同名属性但是值是空的或者被误写成空字符串会覆盖父 POM 里精心配置的全局值而且很难排查。Maven 4 的新模型对空值属性做了更严格的限制默认不再允许空值覆盖父级定义。这个改动对大型聚合工程特别友好因为大型项目里往往有几十个模块之前经常出现某个子模块悄悄把公共版本号覆盖成空导致构建行为诡异的情况。占位符方面Maven 4 对${project.version}、${project.groupId}这类内置属性的解析时机和处理方式也更收敛以前那种“临时在命令行里用 -D 覆盖 project 属性”的做法在新模型下可能失效。这点很多老手会中招我建议迁移时专门搜索一下脚本和 CI 配置里有没有这类参数覆盖。2.4 一个可直接参考的迁移示例下面是一个真实项目里我把 POM 切到 4.1.0 后的核心片段可以作为参考。注意我只列了变动较大的部分没有把完整 pom 贴出来。project xmlnshttp://maven.apache.org/POM/4.1.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.1.0 https://maven.apache.org/xsd/maven-4.1.0.xsd modelVersion4.1.0/modelVersion parent groupIdcom.company/groupId artifactIdcompany-parent/artifactId version2.5.0/version /parent artifactIdorder-service/artifactId packagingjar/packaging properties maven.compiler.release17/maven.compiler.release /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies /project这里重点看几个地方。http://maven.apache.org/POM/4.1.0这个命名空间和对应的 XSD 路径是 Maven 4 新模型的标准声明IDE 里有没有它决定了代码提示和校验是否生效。maven.compiler.release我直接写 17少绕一层 source/target 的坑。依赖省略了版本号是因为版本统一放在公司 parent 的 dependencyManagement这也是新模型下最推荐的写法能让校验和继承行为更可预期。3. 内核动手Plexus 老容器退场反应堆排序更聪明3.1 组件模型从 XML 驱动转向注解驱动很多人不知道Maven 3 的内核里还保留了一整套 Plexus 时代的组件机制组件实现要在一个 XML 描述文件里登记再通过命名规则和类型查找装配。这套机制在 Java 刚兴起的年代是先进的但到了注解和类型安全的时代就成了维护负担。Maven 4 把内部组件进一步收拢到基于 JSR-330 的依赖注入模型组件之间是直接的构造器注入或注解注入不再依赖字符串键值查找。这个改动对普通用户的影响不明显但对插件开发者是实打实的利好。今后写自定义 Mojo 时依赖注入的方式更接近 Spring 的思维向前兼容的选项也更多。团队里如果有人维护内部插件升级前要重点确认插件工程里依赖的 Maven API 版本至少编译打包用的maven-plugin-api和maven-plugin-annotations需要跟着升到对应版本。3.2 反应堆排序与增量构建反应堆Reactor是 Maven 聚合多模块项目时用来确定“谁先构建、谁后构建”的核心组件。Maven 3 的反应堆基本靠依赖关系做拓扑排序能跑但很保守在一个几十个模块的仓库里运行mvn clean install经常会把跟本次改动无关的模块也完整跑一遍时间全浪费在无关模块上。Maven 4 对反应堆的重写核心目标是“更精确的构建计划”。它基于依赖图做按需计算配合新的构建计划和缓存钩子理论上可以让多模块项目只重新构建真正受影响的模块。我实测一个 30 个模块的微服务仓库在 Maven 4 的 beta 版本上配合缓存特性单纯改一个底层公共模块后跑mvn install构建时间从 Maven 3.9 的 2 分 40 秒左右降到 1 分出头。这里要说明这个数字和机器配置、模块耦合度关系很大但方向是明确的。-pl、-am、-amd这些多模块参数在 Maven 4 里的语义也有调整。比如-pl指定项目时Maven 4 对上下文的推导更智能构建列表外的项目不再被误纳入。如果你的流水线里大量使用这类参数迁移后要专门验证一遍构建顺序不要默认“参数没变结果就一定没变”。3.3 并行构建从“能跑”到“敢开”Maven 3 就支持-T并行构建但社区里长期不敢多用容易出现插件状态竞争、模块输出目录互相污染、日志错乱等诡异问题。Maven 4 的内核重构把线程模型和组件状态管理重新梳理了一遍并行构建的稳定性明显提升。我现在的建议是如果项目模块数超过 15 个可以在 Maven 4 环境里直接尝试mvn -T 1C clean verify1C表示 CPU 核数比固定写-T 4要灵活尤其线上构建机核数不固定时。实测下来模块之间没有共享 target 目录的项目基本都能平稳跑完。如果你的项目里有些老插件写死了全局静态状态并行时还是会出问题这类插件需要单列出来通过配置文件要求串行执行。4. 依赖解析、仓库策略晋级路上最容易被坑的地方4.1 Maven Resolver 的新表现Maven 4 把依赖解析链路换到了更新的 Resolver 实现。最直观的感受是下载变快了多个依赖可以并行拉取不再是一根队列慢慢走。版本解析也更快特别是一个仓库里存在大量版本的场景Maven 4 对版本区间的处理更高效很多老项目里因为解析太慢设置的“固定版本号”习惯在 Maven 4 里可以得到缓解但我依然建议保持显式版本声明让人读代码时一眼能看懂。Resolver 对 checksum 的校验也更严格。以前文件下载下来校验失败往往只是警告Maven 4 里这种错误更容易导致构建中断。这是好事能避免本地仓库里躺着一堆损坏的快照依赖导致莫名其妙的构建失败。代价是如果你的内网私服或者 HTTP 仓库响应不规范迁移后的失败频率会明显上升。4.2 HTTP 仓库与中央仓库的安全策略Maven 从 3.8 开始默认阻止从 HTTP 地址拉取外部依赖这是为了防中间人篡改。Maven 4 把这类安全策略继承下来而且检查更细致。很多企业内部私服还停留在 HTTP升级后第一反应往往是“依赖怎么拉不下来了”。对策有两个方向。一个是把私服升级到 HTTPS这是干净的长久方案。另一个是如果短期做不到需要在settings.xml里对指定仓库显式放行mirror idinternal-http/id mirrorOf*/mirrorOf urlhttp://repo.internal.company.com/maven-public//url blockedfalse/blocked /mirror注意这里不是所有 Maven 版本都支持blocked标签的写法具体要以你使用的 Maven 4 版本的官方 schema 为准。我的真实建议是趁着升级 Maven 4 的契机把私服证书链整理一遍HTTP 的问题今天不解决以后也会以更难看的方式爆发。4.3 版本区间、快照依赖与新锁定习惯Maven 4 对依赖版本区间比如[1.0,2.0)的解析行为更严格不再允许那种“区间拉大、依赖靠运气”的写法。如果你项目里有这类写法升级后很可能会出现版本选择结果变化某个间接依赖被解析到预期之外的版本进而引发编译或运行问题。排查手段是比对 Maven 3 和 Maven 4 生成的dependency:tree这个对比在灰度阶段必须做一遍。快照依赖的处理倒是更顺手了时间戳解析更快本地快照和远程快照的冲突判定也清楚了一点。但我还是要给一个老掉牙但有效的建议发布到中央仓库或者生产环境的构建不要依赖快照版本尤其不要依赖别人私服上的快照。Maven 4 再强也解决不了治理问题。4.4 依赖冲突报错变严格Maven 4 在 POM 合并和依赖树构建时对冲突的容忍度比 Maven 3 低。以前出现“两个依赖传递了同一个 jar 的不同版本”只是警告最终以最近优先规则选一个。现在遇到一些会真正导致运行时歧义的冲突构建直接中止。这不是坏事但它意味着迁移后你要处理的“历史遗留问题”会集中暴露。建议在迁移阶段专门安排一次依赖清理把统一版本号放到 dependencyManagement 里让每个模块的依赖版本都可追踪。5. 从 Maven 3 平滑迁移到 Maven 4一次完整实操记录5.1 迁移前检查清单我拿到任何项目做 Maven 4 迁移都会先过一遍下面这张表每一项都有可能是坑。检查项重点关注内容对应操作JDK 版本Maven 4 自身通常要求较新的 JDK我这次用的是 JDK 21确认 CI 和本地环境的 JAVA_HOMEMaven Wrapper项目里 mvnw 指向的还是老 Maven重新生成 wrapper 指向 Maven 4插件清单列出所有 plugins 的 groupId/artifactId/version对照兼容列表逐个确认自定义插件/扩展内部开发的 Mojo、扩展、build-extension检查 maven-plugin-api 版本父 POM公司级 parent 是否还在用老模型先切到 4.1.0或者先用 4.0.0依赖版本区间是否存在[a,b)这类宽泛声明替换成固定版本HTTP 仓库私服是否还是 HTTP准备 HTTPS 或 settings 放行CI 脚本是否有 -D 属性覆盖、-pl/-am 参数逐个验证行为差异这张表做完继续往下走才有意义。5.2 先别急着换全局 Maven用 Wrapper 隔离版本我不建议一上来就把开发机或 CI 的全局 Maven 换成 4。正确姿势是在一个分支上用 Maven Wrapper 把项目锁定到指定版本这样 Maven 3 和 Maven 4 可以同时存在于不同项目互不干扰。生成 wrapper 很简单mvn wrapper:wrapper -Dmaven4.0.0-beta-2执行后项目根目录会出现mvnw和.mvn/wrapper/maven-wrapper.properties里面写着对应版本号。之后团队统一用./mvnw构建老项目保持原来的mvn命令平滑过渡。这个改动建议直接合进主分支让所有开发者都在相同版本下协作避免“我这边能过你那边过不了”的环境差异。5.3 按阶段验证从 validate 到 package迁移最忌讳“一把梭直接跑打包”。我按生命周期阶段顺序来验证哪个阶段挂了就停在哪个阶段修不浪费后面的时间。./mvnw -V validate ./mvnw help:effective-pom ./mvnw -DskipTests compile ./mvnw verify-V会打印 Maven 和 JDK 版本第一件事确认你真的跑在 Maven 4 上。validate会把新模型校验的潜在错误先暴露出来。help:effective-pom输出合并后的有效 POM花十分钟扫一遍能提前看到继承关系、profile 激活、依赖版本管理是否正常。compile阶段主要暴露插件兼容问题。最后再跑完整verify此时要带上 CI 里可能用到的参数比如-T 1C、--no-transfer-progress。5.4 插件兼容性处理绕不开的工作量插件兼容是我这次迁移里工作量最大的一块。常见插件比如maven-compiler-plugin、maven-surefire-plugin、maven-jar-plugin、maven-install-plugin官方基本都发布了适配 Maven 4 的版本升级到较新的稳定版即可。我建议至少把这些版本线提上来plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-compiler-plugin/artifactId version3.13.0/version /plugin plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-surefire-plugin/artifactId version3.2.5/version /plugin真正麻烦的是自定义插件和扩展。如果你的项目里有用 Apache Maven 的 API 直接写的 Mojo先检查它依赖的maven-plugin-api、maven-core、maven-model版本最好升级到与 Maven 4 对应的版本线重新编译。有些老插件在 Maven 4 下运行时会直接报“requires Maven version 3.x”之类的话这种只能升插件或者剥离开。不要在一个自定义插件上耗太久评估一下它承担的能力是否能被现成插件替代不能的话再投入时间去适配。5.5 在 CI 里灰度一条流水线跑两个版本项目回到正常进度后CI 的灰度也很重要。不需要大动干戈就在现有流水线里加一个“预检任务”用同一个仓库同时跑 Maven 3 和 Maven 4 两条构建对比产物与成功状态跑一到两周。伪代码思路如下# 预检任务构建后用 diff 对比 manifest 与关键产物 ./mvnw -q clean package -DskipTests mv target/order.jar target/order-m4.jar # 与 Maven 3 构建的 order-m3.jar 对比产物内容 # 如果 jar 内容差异明显或检查项失败则该次提交标记为不通过这个做法的收益是可以在不打断主线构建的前提下暴露 Maven 4 对具体提交的隐性影响。我实际跑下来最常见的问题是某些依赖版本在 Maven 4 下解析结果不同jar 包内容出现差异但这种差异未必是错误。你需要根据业务情况定一个“哪些差异可接受、哪些不可接受”的标准不要让灰度机制变成摆设。6. 常见问题速查我在升级路上踩过的 6 个坑6.1 典型问题与排查方式表格下表是我这次迁移中最常遇到、也最值得提前预防的问题你可以直接拿去当排查手册。现象可能原因解决方案启动直接提示 JDK 版本不支持Maven 4 自身要求的 JDK 版本高于当前 JAVA_HOME升级 JDK或继续用 Maven 3 等待团队统一升级MalformedPomException/ 模型校验失败pom 里存在未知节点、空属性覆盖、重复声明运行./mvnw validate定位行号按新模型规则修正插件报错 “requires Maven version”插件依赖的 Maven API 太旧升级插件版本自定义插件重新编译适配依赖解析结果和 Maven 3 不同宽泛版本区间在新解析器下选择不同固定版本号到 dependencyManagement灰度对比 dependency:tree私服依赖拉不下来私服是 HTTP安全策略默认拦截仓库升级 HTTPS 或 settings.xml 显式放行指定仓库并行构建偶发失败老插件存在全局状态线程不安全对该插件所在的模块限流串行或升级插件6.2 三条最值得记住的升级建议第一条别在生产环境“跳级”。如果你们还在 Maven 3.6 甚至更早先升到 Maven 3.9.x让项目和插件先在接近 Maven 4 的规范下跑顺再考虑切 4。跳两级会让问题叠加排查成本成倍上涨。第二条迁移期间把“依赖树对比”做成常规动作。Maven 3 和 Maven 4 的解析差异是最隐蔽的坑运行时才暴露的问题往往都能靠早期的dependency:tree对比揪出来。第三条关注官方发布说明里的兼容性清单。跟 Maven 4 适配的插件列表一直有更新你的项目里如果有一堆老插件一定对照清单过一遍而不是只升级几个核心插件就想当然。7. 写在最后的个人观察7.1 把升级当成一次依赖治理的契机我这次迁移做完之后最大的收获其实不是构建变快而是项目里多年来攒下的依赖债务被强制清理了一遍。Maven 4 更严格的模型校验和解析规则逼着我把那些“能跑但说不清为什么”的依赖声明、自定义标签、空属性覆盖全部处理掉了。换个角度看这比任何一次手工发起的“重构周”效果都好——因为目标很明确不修就过不了构建。如果你打算升级建议不要只盯着技术验证顺手做三件事把父 POM 里所有属性过一遍删掉无用项把依赖版本区间全部改成明确版本把 CI 脚本里的每一条 Maven 命令重新背一遍含义。这三件事做完你的项目会比升级前健康一个档次。7.2 什么情况下我建议再等等尽管 Maven 4 的方向我很认可但如果你属于下面几类情况我建议再等一两个小版本再切项目里有大量老旧的第三方插件且维护方已经不活跃或者你们刚经历过大版本 JDK 升级团队没有余力同时消化两个变化又或者你们的构建链路大量依赖 Maven 3 的冷门行为比如通过命令行覆盖内置属性这种骚操作。这些情况下先把 Maven 3.9 的规范吃透比急着追新版本更划算。7.3 最后说点真心话升级 Maven 4 的成本比我预想的低但收益也没有发布会文案吹的那么大。它没有把 Maven 变成秒天秒地的构建神器而是把一个老平台的运行机制重新拉回到了现代 Java 的水平线上。真正的红利是那些被新旧版本撕裂地带的改善更干净的 POM 模型、更可靠的并行构建、更可控的依赖解析、更有想象空间的缓存链。如果你团队还在 Maven 3.8等正式版发布后跟第一个修正版本再全面切换如果已经用 3.9 且模块较多现在就可以找一个小型项目用 wrapper 灰度跑起来。最后再补一句真心话升级前把所有插件列出来逐项核对兼容性这件事你做得越细后面踩的坑就越少。
