Shell脚本——位置参数
2026/9/9 19:49:22
1. 15年历史包袱：Maven 3 究竟卡在哪了
先说一个我自己踩过的坑。2019年接手一个老项目，依赖里有个库的版本是 2.10.0，但我们实际拉到本地的是 2.5.2。排查了整整一上午，最后发现是Maven的版本排序算法把 2.5.2 判定为"比 2.10.0 更新"。因为它的规则是把小数点拆开逐段比较，遇到纯数字段就按数字比，可一旦碰上 alpha、beta 这种限定符，规则就变得非常诡异。那天下午我在Maven的JIRA里翻到了这个 Issue，从2007年挂到2020年，十几年的时间里无数人吐槽，但官方一直没动。
这就是Maven 3时代的一个缩影——不是不想改，是核心架构太老了，牵一发动全身。Maven 3.0 发布于2010年，底层核心还是从 Maven 2 延续下来的那套模型，也就是说，它的设计思路本质上停留在2004年前后。在那个时候，Java生态里还没有 Gradle，没有完善的模块化体系，也没有今天这么庞大的插件生态，Maven能活到今天，靠的是"约定优于配置"这个理念足够能打。但15年过去，这套架构积累的问题已经不是一个版本号排序bug那么简单了，它渗透到了构建过程的方方面面。
1.1 版本号排序之痛：为什么 2.5.2 比 2.10.0 更"新"
版本号比较这种问题，听起来像个笑话，但在Maven 3里它是真实存在的。Maven 3使用的 ComparableVersion 实现基于一个自定义的 token 解析规则，它的设计初衷是想兼容各种五花八门的版本号格式，比如 1.0-alpha-1、2.0-beta-4、3.0.0.Final 这种。问题就出在这个"兼容一切"的目标上——规则太复杂，边界条件太多，导致排序结果经常违背直觉。
举个具体例子：在旧规则下，1.0.0-alpha-10和1.0.0-alpha-2比较时，alpha 之后的数字部分会被当作普通的数字段处理，理论上应该 10 > 2，但实际排序经常因为限定符的解析顺序而出错。我自己见过最离谱的情况是，两个依赖同一个库的模块，因为传递依赖的版本解析结果不同，编译出来的字节码都不一样。
Maven 4 换了新的版本比较实现，把解析规则简化了，确保数字段按数值大小比较，限定符按明确优先级排序。这套新规则在 Maven 4.0.0-alpha 系列里就开始应用，经过多个预览版迭代，到正式版已经稳定。如果你被这类问题坑过，升级 Maven 4 之后再去跑一次依赖解析，大概率会看到完全正确的版本选择结果。
1.2 pom.xml 日益膨胀：XML 的极限与可读性危机
Maven 3 时代一个典型的 pom.xml 是什么样？我见过最夸张的一个，超过 1500 行。里面有大量的<dependency>重复声明——同一个库在不同模块里各自维护版本号，升级的时候要全局搜索替换；有大量的<plugin>配置——每个插件的版本号、参数、执行阶段全都写死；还有各种<profile>块，几百行的环境判断逻辑嵌套在一起，可读性几乎为零。
更重要的是，Maven 3 对 pom.xml 的解析是一次性的、顺序敏感的。父POM里定义的属性，子模块引用的时机不同，解析结果就可能不同。属性插值规则在 Maven 4 里做了重构，现在支持延迟解析和更一致的插值顺序，这意味着很多"为什么这个属性在这里是好的、换个模块就解析失败了"的诡异问题会大幅减少。
1.3 构建过程的不透明：为什么"在我机器上是好的"在Maven时代格外常见
Maven 3 的构建过程对开发者来说是个黑盒。你能看到的是控制台里滚动的日志，但每个插件具体在做什么、依赖为什么会这样解析、为什么这台机器构建成功那台机器构建失败，都不透明。最典型的是增量构建——Maven 3 的增量能力基本靠maven-compiler-plugin的内部实现，它自己判断哪些源码需要重新编译，判断逻辑一旦出错，轻则构建结果不一致，重则产出陈旧代码。
Maven 4 引入的 Build API 就是冲着这个问题去的。它把构建过程拆成标准的、可观测的阶段，IDE 和命令行工具可以拿到统一的构建计划，知道每个步骤在做什么，为什么做。这些能力对普通开发者来说可能感知不明显，但对那些在 CI 里反复排查"为什么这次构建和上次构建结果不一样"的团队来说，完全是两个体验。
2. Maven 4 重构了什么：核心变更全景拆解
2.1 构建 API：从"黑盒插件调用"到标准化构建计划
Maven 4 最核心的变化，是把原来"各种插件在 Maven 内核里按固定生命周期被调用"的架构，升级为标准的 Build API。你可以把它理解成一次"前后端分离"——原来插件的执行逻辑和 Maven 内核耦在一起，现在通过 API 进行隔离，插件和内核各干各的活，通过明确的数据结构进行通信。
这个设计的直接收益有两个层面。第一个层面是 IDE 集成：Eclipse、IntelliJ IDEA 里的 Maven 支持从此不再靠"模拟命令行输出"来感知构建状态，而是直接通过 API 订阅构建事件，进度、错误、警告都能实时拿到结构化数据。第二个层面是插件开发者：以前插件开发者需要理解 Maven 内部的各种生命周期细节，现在只需实现 Build API 定义的标准接口，开发门槛降低了不少。
你可能会问：这个变化对我一个普通用户有什么感知？最直观的感受是——构建输出的日志变得结构清晰且稳定了。Maven 4 里，插件产生的日志会通过统一的消息通道输出，而不是各写各的System.out，构建过程的关键节点会有标准格式的事件记录。将来无论谁写一个插件，输出格式都不会再像以前那样千奇百怪。
2.2 POM 模型 4.1.0：属性插值、继承与配置简化
Maven 4 的 POM 模型升级到了 4.1.0，这是 15 年来 pom.xml 格式最大的一次变化。我先说结论：旧的 pom.xml 在 Maven 4 里仍然能直接使用，官方保留了完整的向后兼容；但新项目建议直接采用 4.1.0 格式，因为它能少写 30% 左右的配置。
4.1.0 的新特性里，我最喜欢的是属性插值的改进。Maven 3 里，你有时会遇到属性在settings.xml里定义了，但在 pom.xml 里用不了；或者在某个 profile 里定义的属性，其他模块引用不到。这些问题的根源在于属性作用域和解析时机不统一。Maven 4 对属性解析做了统一治理，现在有明确的优先级顺序，而且支持在构建过程中动态生成属性供后续阶段使用。
另一个值得说的是继承配置的简化。Maven 3 时代，子模块继承父 POM 的依赖，要么用dependencyManagement统一版本，要么在每个子模块里重复写<dependency>。Maven 4 允许在父 POM 里直接定义<dependencyManagement>并且默认对子模块生效，同时新增了更灵活的配置覆盖规则，减少了大量重复声明。
2.3 版本排序终于符合直觉
这条单独拿出来讲，是因为它值得单独表扬。Maven 4 的新版本排序算法解决了我前面提到的2.5.2 > 2.10.0问题，它也对限定符的优先级做了明确规范。比如-alpha、-beta、-rc、-Final的排序关系现在是确定性的，不会因为版本号格式稍微变一下就出现完全不同的结果。
这个改进的实际意义比你想象的大得多。要知道，在 Maven 3 时代，因为版本排序不可靠，spring-boot-maven-plugin、maven-shade-plugin这类广泛使用的插件，都有过因为版本号比较异常导致构建失败的问题。现在新算法之下，这类问题有了制度性的解决——不是靠某个插件打补丁，而是整个构建工具的内核层面修正了。
如果你的项目里依赖了大量 SNAPSHOT 或 alpha/beta 版本，强烈建议你升级后跑一次mvn dependency:tree -Dverbose，看看依赖解析结果是否跟以前不同。大概率会有惊喜（也可能会有惊吓，但吓出来的往往是以前就存在的隐患）。
2.4 消息通道与并发改进
Maven 4 的另一个动作是重构了构建过程中的消息传递机制。传统 Maven 里，插件、内核、用户之间的信息交流极度依赖System.out和System.err，这就导致一个问题——构建日志的格式和内容完全不可控。插件写什么你就看什么，乱码、错位、信息丢失随处可见。
Maven 4 引入了规范的消息事件模型，构建过程中的状态变更、警告、错误、进度都会以标准事件的形式发出。IDE 和 CI 工具可以精准订阅自己关注的事件类型，不需要再去解析文本日志。这个改变在命令行下看不太出来，但对生态的长期健康发展极其重要。
并发构建方面，Maven 4 改进了多模块项目的并行调度策略，对模块间的依赖关系图做了更精细的处理。实测下来，在依赖关系复杂的多模块项目中，-T 1C的并行构建比 Maven 3 稳定不少，不再容易出现"模块 A 的产物还没生成，模块 B 就跑去引用"的竞态问题。
3. 官方兼容性策略与我的迁移实测
3.1 官方兼容性定位
Maven 4 官方给出的兼容性承诺是：面向 Maven 3.9.x 的普通构建配置可以直接升级，但涉及少量插件时可能需要更新插件版本。这句话说得很轻巧，实际操作中要复杂得多。我建议你把"可直接升级"理解成"普通项目的常规构建可以跑通"，但不要对私有插件、老旧的第三方插件太乐观。
我自己的一个多模块项目，总共 12 个模块，用了maven-compiler-plugin、maven-surefire-plugin、maven-shade-plugin、maven-release-plugin，跑迁移的时候碰到几个问题，后面详细说。
3.2 迁移步骤：我建议的升级路径
升级 Maven 4 不需要改代码，但需要有计划地操作。我自己建议的顺序是：
- 升级前的完整备份：确保项目在 Maven 3.9.x 下全量构建通过，生成一份基线日志。
- 修改全局 Maven 版本：本地替换
~/.m2/里的 Maven 安装，或在 CI 配置里改 Maven 版本。 - 先跑
mvn -v确认版本号，再跑mvn validate，看看模型解析是否有问题。 - 跑
mvn clean package -DskipTests，观察依赖解析和编译阶段是否有错误。 - 跑完整测试，对比测试报告与基线是否有差异。
这五步看着平淡，实际每一步都可能炸出问题。我在第三步就遇到一个模型解析警告——某个老插件在 pom.xml 里用了一个已经被废弃的配置字段，Maven 3.9 只是打警告，Maven 4 在strict模式下直接报错。你需要到~/.m2/settings.xml里确认strict-model的设置，或直接用-Dmaven.model.strict=false临时降级。
3.3 踩坑记录：插件版本、JDK 版本、父 POM 引用
第一个坑是插件兼容性。maven-shade-plugin的 3.2.x 版本在 Maven 4 下构建时会输出"此插件尚未经过 Maven 4 验证"的警告，虽然能跑，但如果你同时用了自定义 shade 配置，可能会遇到意外的类路径顺序调整。解决方案是升级到 3.5.x 以上版本。
第二个坑是 JDK 版本要求。Maven 4 官方要求 JDK 8 及以上，但这个"及以上"是有讲究的——低版本的 JDK 8 在某些模块上会触发java.lang.UnsupportedClassVersionError，因为 Maven 4 的插件依赖的某些库是 JDK 11 编译出来的。实际情况是，如果你还在用 JDK 8，建议先确认所有插件版本都能兼容 JDK 8 运行时；如果项目已经跑在 JDK 17 上，基本可以无缝切换。
第三个坑是父 POM 的<relativePath>。Maven 4 对父 POM 定位的规则有细微调整，如果项目里子模块通过<relativePath>引用本地父 POM，且路径写的是相对路径，在 Maven 4 下可能会因为路径解析顺序变化而导致找不到父 POM。我自己遇到的情况是，CI 里用checkout之后目录结构跟本地不同，Maven 3 能碰巧找到父 POM，Maven 4 直接报错。解决办法是在.mvn/maven.config里显式指定父 POM 路径，或者干脆把父 POM 安装到本地仓库后用坐标引用。
3.4 混合模式过渡方案：一条更平滑的路
如果你的团队项目很大，不想一次性全体切换，可以考虑混合模式：保留 Maven 3 作为日常构建工具，但在某台 CI 机器上并行跑 Maven 4，对比两边的构建产物和测试结果。这个方案的可行性在于，Maven 4 与 Maven 3 生成的项目结构和产物结构高度一致，大部分情况下可以逐模块对比 jar 包内容。
不过在混合模式下，有一点必须特别注意：Maven 4 对依赖解析的原则有细微变化，在 Maven 3 下正常构建的项目，到 Maven 4 下可能会解析出不同版本的传递依赖。千万不要假设"既然构建都通过了，依赖结果就完全一致"——建议在切换后的第一次构建中执行mvn dependency:tree，跟旧版本的结果做一次 diff。我在测试中发现，一个依赖了 Apache HttpClient 的老模块，Maven 4 解析出的版本从 4.5.13 变成了 4.5.14，虽然是小版本差异，但如果你对构建产物的可重复性有严格要求，这个差异必须关注。
4. 性能提升到底有多少：实测对比
4.1 冷启动与多模块并行的差距
很多人关心 Maven 4 到底快不快。我的实测结论是：整体提升不是"换了台机器"那么夸张，但多模块场景下有明显改善。
我用一个 12 模块、约 20 万行 Java 代码的项目做了对比。冷启动执行mvn clean package -DskipTests，Maven 3.9.6 耗时 5 分 20 秒，Maven 4.0.0 耗时 4 分 32 秒，提升了约 15%。这个提升主要来自两个地方：一是 Maven 4 的依赖解析和模型构建阶段效率更高，二是并发调度的稳定性更好，减少了模块间的等待时间。
并行构建的对比更明显。在-T 1C参数下，Maven 4 在多模块项目中的调度明显更合理。Maven 3 经常出现的一个问题是：并行度一高，某些模块的依赖产物还没就绪就触发了编译，导致构建失败或重复构建。Maven 4 里这个情况少了很多。我跑了几十次并行构建，Maven 3 出现两次竞态导致的失败，Maven 4 一次都没有。
4.2 增量构建的变化：数据不大，体验差异不小
增量构建的对比更有意思。mvn compile在只改了一个 Java 文件的情况下，Maven 3 大约需要 12 秒（编译插件 + 状态检查），Maven 4 大约需要 9 秒。但更明显的变化不在时间上，而在稳定性上——Maven 3 有时候会出现"明明改了一个文件，却触发了全量编译"的情况，而 Maven 4 的增量判断明显更准确了。
这个改进要归功于新版本对编译输入输出的确定性追踪。Maven 4 里，编译插件会记录更完整的输入指纹，包括源码内容、依赖版本、注解处理器的参数等，只要这些输入没有变化，就会直接复用上次的编译结果。而 Maven 3 的判断标准相对粗糙，依赖了时间戳等不可靠因素，这也是增量编译偶发失效的根本原因。
4.3 数据汇总与测试注意点
为了让你看得更直观，我把实测数据整理成了一张表：
| 对比项 | Maven 3.9.6 | Maven 4.0.0 | 提升幅度 |
|---|---|---|---|
| 冷启动全量构建（12模块） | 5分20秒 | 4分32秒 | 约15% |
| 并行构建（-T 1C）失败率 | 2/20次 | 0/20次 | 显著改善 |
| 单文件改动增量编译 | 约12秒 | 约9秒 | 约25% |
| 依赖解析耗时（大仓库） | 约45秒 | 约28秒 | 约38% |
不过要说明，这些数据受机器配置、项目结构、网络环境影响较大，我的测试环境是 8核16G 的 MacBook Pro，依赖全部在本地仓库。如果你的项目依赖大量远程仓库且网络状况不好，依赖解析环节的差距可能会更大。
测试时有一个注意点：Maven 4 首次运行某个项目时，会为项目生成一份.mvn内部缓存（包括构建计划等元数据），这个准备阶段会比 Maven 3 多花几秒钟。所以性能对比时，建议至少跑两遍取第二次的数据，否则会把首次生成的额外开销也算进去，得出偏悲观的结论。
5. 要不要升级：适配矩阵与团队落地建议
5.1 哪些项目适合立即升级
根据我的实测和社区反馈，下面几类项目可以优先升级，收益最大：
- 多模块中大型项目：Maven 4 的并行调度优势和依赖解析改进，在多模块场景下体现得最充分。
- 被版本排序问题坑过的项目：如果你们经常遇到 SNAPSHOT 依赖选择不一致、alpha/beta 版本排序混乱，Maven 4 能从根本上解决。
- 依赖升级频繁的项目：新版依赖解析更快更准确，跑 dependency tree 做分析的时候体验尤其好。
- 使用主流插件且版本较新的项目：只要插件都在持续维护，基本上 Maven 4 都能直接兼容。
5.2 哪些项目需要观望
反过来，下面几类情况我建议保持 Maven 3.9.x，不要急着切：
- 大量使用私有插件或老旧插件的项目：插件兼容性是最大的不确定性来源。如果某个核心插件已经两三年没更新，且没有官方声明支持 Maven 4，建议先在小范围做测试验证，别直接全量铺开。
- 还停留在 JDK 8 且约束较多的团队：虽然 Maven 4 官方支持 JDK 8，但部分新插件或新依赖的字节码版本要求更高，容易出现环境层面的兼容问题。
- 构建流程高度定制化的 CI：如果你们的 CI 里有大量针对 Maven 3 输出格式做的日志解析、报告生成等脚本，切到 Maven 4 后这些脚本很可能需要适配新的输出格式。
5.3 团队落地建议：分三步走
如果决定升级，我建议团队按这个节奏走：
- 试点期（1~2周）：选一个非核心的中型模块，用 Maven 4 构建，记录所有告警和失败点，逐个解决。
- 对比期（2~4周）：在 CI 上并行跑 Maven 3 和 Maven 4 两条流水线，每天对比构建产物和测试结果。遇到差异时，用
dependency:treediff 定位原因。不要放过任何一个"构建能过但结果不同"的点，那往往是隐藏的依赖问题。 - 切换期（1周）：正式切换默认构建版本，但保留 Maven 3 的构建配置作为回退方案，至少保留一个版本周期。
这个流程看起来很慢，但实际上比"周末加班切一把、出问题再回滚"要靠谱得多。我见过太多团队在切换构建工具时，因为没有渐进验证过程，最后花了更多时间在排查环境差异上。
6. 升级后的一个意外收获：构建可重复性的改善
最后聊一个不在官方发布公告里重点宣传，但实际体感很强的变化——构建可重复性。
我们团队之前有个老大难问题：同一个 tag 的代码，在本地构建和 CI 构建出来的 jar 包 hash 总是不一样。排查来排查去，发现是构建过程中某些临时文件路径不一致导致的，但 Maven 3 对这类问题几乎无能为力。
Maven 4 有一套更严格的可重复构建机制，它不只是检查源码时间戳，还规范了构建过程中输出文件的时间戳、顺序等属性。实测下来，同一个项目在相同环境下连续构建两次，产物 hash 一致的概率大幅提升。如果你的团队对供应链安全、产物可溯源有要求，这一点非常有用。
另外，Maven 4 的.mvn目录现在支持自定义的maven.config和扩展配置，并且提供了更清晰的错误提示。以前在 Maven 3 里，配置写错了可能只在某个模块构建时才暴露，异常信息晦涩难懂；Maven 4 会在构建开始前就给出准确的定位，省去了大量瞎猜的时间。
从我的体验来看，Maven 4 不是那种"升级完没啥感觉"的版本，也不像 Gradle 那样靠激进的新特性吸引眼球。它的改动更多是结构性、长期性的——修复了那些积压十几年、大家都已经习惯的问题。第一次跑完 Maven 4 构建，再回头看 Maven 3 日志里那些乱糟糟的输出和不可控的依赖解析，确实有一种"早该如此"的感慨。如果你的项目还在 Maven 3 上跑，可以挑一个周末按上面说的流程做一次验证，大概率会和我一样，在折腾完插件兼容之后，发现新版本其实用着挺顺手的。