背景

在多模块 Maven 项目中，你是否遇到过这样的场景：只是修改了某个内部公共模块中的一行代码，为了在另一个业务模块里通过 exec:java 运行一下主类做验证，却不得不先执行一遍耗时的 mvn install，把公共模块重新安装到本地仓库？又或者，你想用脚本获取一个模块的完整类路径，结果 Maven 报错说在中央仓库找不到你自己的内部模块？

这两个开发痛点表面上看似无关，实则源自同一个底层机制：Maven Reactor（反应堆）对内部模块依赖的“短路解析”。理解了这一机制，你就能解释为什么 exec:java 可以无需 install 直接运行，也能手动复刻这一行为，用一行命令获取包含内部模块 target/classes 的完整类路径。

本文将从真实的报错案例出发，逐步拆解 Maven Reactor 的工作原理，最后提供一份可直接套用的命令模板。文中所有模块名、包名均已抽象化，与任何具体项目无关。

问题复现：为什么内部模块“找不到”？

一个典型的多模块结构

假设我们有一个标准的多模块工程，根项目名为 demo-platform，下面包含几个子模块：

• platform-bom：BOM 模块，packaging=pom，统一管理依赖版本。
• platform-common：公共模块，提供工具类和核心抽象。
• platform-service：业务模块，依赖 platform-common。

这是一个非常常见的微服务或中台项目骨架。

错误示范：在子模块目录里直接运行

某天，你想为 platform-service 编写一个启动脚本，需要先获取它的完整类路径。你顺手 cd 进入 platform-service 目录，输入：

cd platform-service
mvn dependency:build-classpath

然后控制台返回一长串报错：

[ERROR] Failed to execute goal on project platform-service:
  Could not resolve dependencies for project com.example:platform-service:jar:1.0.0:
  Failed to collect dependencies at com.example:platform-common:jar:1.0.0:
  Failed to read artifact descriptor for com.example:platform-common:jar:1.0.0:
  com.example:platform-bom:pom:1.0.0 was not found in https://repo.maven.apache.org/maven2
  during a previous attempt.
  This failure was cached in the local repository and resolution is not reattempted
  until the update interval of central has elapsed or updates are forced.

报错的关键信息包含两层：第一层是“找不到 platform-bom”，第二层是“这次失败已被缓存，不会重试”。

报错根因：脱离了 Reactor

当你 cd 进入子模块目录单独执行 Maven 命令时，Maven 只能看到当前这一个 pom.xml，它完全不知道 platform-common、platform-bom 是“内部模块”。于是它按照普通第三方依赖的流程去解析：先查本地仓库 ~/.m2/repository，没有就去远程中央仓库查找。

显然，你的内部 BOM 不可能发布到中央仓库，因此解析失败。失败之后，Maven 还会在本地仓库留下一个 *.lastUpdated 标记文件，将这次失败缓存起来，导致后续即便你修正了命令，也可能因为缓存而继续失败。

换句话说，问题不是“必须 install”，而是你压根没有让 Reactor 启动。

核心原理：Reactor 与“短路解析”

要理解“不 install 也能运行”的魔法，必须先搞懂 Maven Reactor 的工作机制。

Reactor 是什么

Reactor（反应堆）是 Maven 在多模块构建时的“调度大脑”。当你在项目根目录执行 Maven 命令时，Reactor 会执行三件事：

1. 扫描所有子模块的 pom.xml，建立模块清单。
2. 根据模块间的 关系，计算依赖图。
3. 拓扑排序，决定构建顺序（被依赖的模块先构建）。

完成这三步后，Reactor 在内存里就已经清楚地知道“模块 B 依赖模块 A，且 A 正在本次构建中”。这个“知道”非常关键，它直接决定了下一步的解析策略。

两种依赖解析模式

Maven 对依赖的解析有两种截然不同的模式，区别在于“依赖路径指向哪里”：

第一种模式下，Maven 把内部模块当成普通第三方库，去本地仓库查找 JAR 包。第二种模式下，Maven 会直接把内部模块的编译输出目录 target/classes 当作依赖路径。

短路解析的本质

为什么 Maven 要这么做？因为在一个聚合构建里，内部模块的代码可能刚刚被修改过，本地仓库里的 JAR 是旧的。如果还按常规模式去取 JAR，修改的代码根本不会生效。所以 Maven 干脆绕过 JAR，直接用实时编译出来的 target/classes 目录——这样既保证了代码是最新的，又省去了 install 这一步。

这就是“不 install 也能运行”的理论基础：Maven 并不依赖 JAR 包来连接内部模块，而是直接利用编译后的 class 文件目录。

Exec 插件为何“不 install 也能跑”？

理解了短路解析，再来看 exec:java 的行为就豁然开朗了。

Exec 插件的 ClassLoader 构建

exec:java 或 exec:exec 在运行你的 Main 类时，会通过 MavenSession 获取 Reactor 中所有已构建模块的 MavenProject 对象，直接读取它们的 getOutputDirectory()（也就是 target/classes），把这些目录和外部 JAR 包路径拼接起来，构建一个 URLClassLoader，然后用这个 ClassLoader 启动你的应用。

注意这里的关键：Exec 插件获取到的内部模块路径，是 target/classes 这样的文件目录路径，而不是本地仓库里的 JAR 路径。这一切都建立在“Reactor 已经把内部模块识别为反应堆项目”的前提之上。

生命周期阶段的隐式保障

但 Exec 插件本身并不神奇，它有一个隐含前提：target/classes 必须已经存在。这个前提通常由 Maven 生命周期阶段来保证。

我们日常使用的 mvn exec:java 命令，往往不是孤立执行的，而是配合阶段一起运行，比如：

mvn compile exec:java -pl platform-service -am

这条命令做了两件事：

1. compile：触发 Maven 生命周期，Reactor 确保上游模块（platform-common）被编译，生成了 target/classes。
2. exec:java：插件启动时，Reactor 直接把 target/classes 路径交给插件。

所以 Exec 插件“不 install 也能运行”的真相是：它搭乘了 Reactor 生命周期的顺风车，而 compile 阶段保证了 target/classes 已经就绪。如果你去掉 compile，直接运行 mvn exec:java -pl platform-service -am，同样会因为 target/classes 不存在而失败。

手动获取类路径的正确姿势

理解了原理，我们就能手动复刻 Exec 插件的行为，用 dependency:build-classpath 获取一份完整的类路径。这个插件是 Maven 官方 maven-dependency-plugin 提供的一个 goal，专门用于输出当前模块的完整依赖类路径。

三个关键要素

要让 build-classpath 正确工作，必须同时满足三个条件：

1. 在根目录运行：激活 Reactor，让 Maven 拥有全局视野。
2. 用 -pl + -am 锁定范围：-pl 指定目标模块，-am（also-make）把它在 Reactor 中依赖的上游模块一起纳入构建。
3. 绑定一个生命周期阶段：这是最容易被忽略的一点，下面单独说明。

最容易踩的坑：必须绑定生命周期阶段

dependency:build-classpath 只是一个 Goal，它默认不属于任何生命周期阶段。如果你只运行：

mvn dependency:build-classpath -pl platform-service -am

会发生什么？Reactor 虽然被激活了，上游模块也被纳入了，但没有任何阶段被触发。也就是说，process-classes / compile 都没执行，target/classes 没有生成。下游模块解析上游依赖时，发现 artifact 文件不可用，就会回退到本地仓库解析——结果撞上 *.lastUpdated 失败缓存，报出和第一节一模一样的错误。

这就是为什么很多人“明明加了 -pl 和 -am 还是失败”的原因：缺少了生命周期阶段这一步。

完整命令模板

正确的命令必须在前缀加一个会触发 process-classes 的阶段，比如 compile 或 test-compile：

mvn compile dependency:build-classpath 
  -pl platform-service -am 
  -Dmdep.outputFile=classpath.txt

参数解释：

• compile：触发编译，确保上游模块产出 target/classes。
• -pl platform-service：只在 platform-service 模块上执行 goal。
• -am：自动构建它依赖的上游模块。
• -Dmdep.outputFile=classpath.txt：把类路径输出到文件，避免控制台日志太长不易查找。

执行流程会变成：每个上游模块先运行 compile（生成 target/classes），再运行 build-classpath。下游模块解析上游依赖时，artifact 文件就是 target/classes 目录，不再回退到仓库，也就不会触发 *.lastUpdated 缓存。

几个常用变体

只看控制台输出（适合快速验证）：

mvn compile dependency:build-classpath -pl platform-service -am

控制台会输出一大段日志，其中包含 Dependencies classpath: 字样，后面跟着的就是完整类路径。

只取 runtime 范围（适合打包运行场景）：

mvn compile dependency:build-classpath -pl platform-service -am 
  -Dmdep.includeScope=runtime -Dmdep.outputFile=cp.txt

includeScope 可以过滤依赖范围，runtime 通常对应运行时需要的依赖。

包含测试类（适合运行测试场景）：

mvn test-compile dependency:build-classpath -pl platform-service -am 
  -Dmdep.outputFile=cp.txt

test-compile 会同时编译主代码和测试代码，target/test-classes 也会被生成。

验证与结果分析

命令运行完之后，如何判断 Reactor 短路解析真的生效了？打开生成的 classpath.txt，查看内部模块对应的路径形态。

成功的标志：路径是目录

如果类路径里出现形如下面的内容，说明 Reactor 解析成功，使用的是编译输出目录：

D:workspaceplatform-commontargetclasses;
D:workspaceplatform-servicetargetclasses;
C:UsersAdmin.m2repositoryorgspringframeworkbootspring-boot3.0.0spring-boot-3.0.0.jar;
...

可以清楚看到两类截然不同的路径：

• 内部模块：表现为本地工程目录（.../target/classes），证明 Reactor 跳过了本地仓库。
• 第三方库：表现为本地仓库中的 JAR 包（.../.m2/repository/...），走的是常规解析。

失败的标志：路径是 JAR

如果类路径里内部模块对应的路径变成了这样：

C:UsersAdmin.m2repositorycomexampleplatform-common1.0.0platform-common-1.0.0.jar

说明 Reactor 没有进行短路解析，走的是本地仓库 JAR。这通常意味着两种情况：要么你没在根目录运行，要么你没加 compile 阶段，要么你之前 install 过这个模块，本地仓库里恰好有 JAR。

拿到类路径之后怎么用

有了 classpath.txt，你就可以直接用 java -cp 启动应用，完全绕过 mvn install：

java -cp "target/classes;$(cat classpath.txt)" com.example.MainClass

注意把当前模块自己的 target/classes 也加进去（因为 build-classpath 输出的是依赖路径，不包含当前模块自身）。Windows 使用分号 ; 分隔，Linux/macOS 使用冒号 : 分隔。

避坑指南：失败缓存的“幽灵”

如果你修正了命令之后依然报错，提示 This failure was cached in the local repository and resolution is not reattempted，那是 Maven 的失败缓存在作祟。

缓存是怎么产生的

Maven 在尝试从远程仓库下载依赖失败后，会在本地仓库对应目录下生成一个以 .lastUpdated 结尾的标记文件，里面记录了失败时间。后续再次解析这个依赖时，Maven 会先检查这个标记文件，如果距离上次失败还没超过更新间隔（默认 24 小时），就直接拒绝重试，连远程仓库都不去询问。

这个机制本意是避免频繁请求不存在的依赖，但在我们的场景里却成了“幽灵”——你明明已经修正了命令，让 Reactor 来解析内部模块了，但缓存还在那里挡路。

两种清除方式

方式一：加 -U 强制更新

最简单的办法是在命令里加 -U 参数，强制 Maven 忽略失败缓存重新解析：

mvn compile dependency:build-classpath -pl platform-service -am -U

-U 会强制 Maven 忽略之前缓存的失败记录，重新去仓库（包括 Reactor）解析。

方式二：手动删除 .lastUpdated 文件

如果 -U 还不行，可以手动删除本地仓库里对应的 .lastUpdated 文件。找到 ~/.m2/repository/com/example/platform-bom/ 目录，删掉里面的 *.lastUpdated 文件即可。也可以用一行命令批量清理：

# Linux/macOS
find ~/.m2/repository -name "*.lastUpdated" -delete
# Windows PowerShell
Get-ChildItem -Path "$env:USERPROFILE.m2repository" -Recurse -Filter "*.lastUpdated" | Remove-Item

清理完之后再运行正确的命令，就不会再被缓存干扰了。

场景对照表

把前面讲过的几种命令放在一起对比，会更直观：

这张表能解释一个常见困惑：为什么“先 install 再单跑”也能成功，但拿到的类路径形态不一样？因为 install 之后本地仓库里有了 JAR，单跑时 Maven 走常规解析，直接取 JAR 路径。这和 Reactor 短路解析拿到 target/classes 目录是两种完全不同的行为。

何时才真正需要 install？

讲到这里，可能有人会问：那是不是以后都不用 install 了？并不是。install 在以下场景里依然不可替代：

1. 脱离 Reactor 的脚本/CI 步骤里单独运行某个模块：比如 CI 流水线里有一个独立的步骤只构建并运行 platform-service，不带上 platform-common，那就必须先把 platform-common install 到本地仓库。
2. 让非 m2e 的 IDE 或第三方工具从本地仓库取依赖：有些老旧的 IDE 插件或第三方工具不识别 Reactor，只能从本地仓库取 JAR。
3. 发布到团队共享的 Nexus/私服：这是 install 之外还需要 deploy 的场景，但 install 是前置步骤。

如果你只是想在本地调试、运行一下主类、生成一份类路径给脚本使用，那么用本文的“三部曲”命令就够了，完全不需要 install。

总结：三部曲口诀

回到最初的问题：Maven Exec 插件如何实现不 install 内部模块直接运行？怎么通过 mvn 命令获取内部模块类路径？

答案可以浓缩成一句话：Exec 插件搭乘了 Reactor 的顺风车，而 Reactor 通过短路解析把 target/classes 当作内部模块的依赖路径。要手动复刻这一行为，记住三部曲口诀：

1. 找根目录：始终在项目根目录运行 Maven 命令，确保 Reactor 激活，拥有全局视野。
2. 定目标：用 -pl -am 锁定构建范围，-pl 指定目标模块，-am 自动带上上游依赖。
3. 加编译：务必在命令前加上 compile 或 test-compile 阶段，确保内部模块有产物输出。

最终命令模板：

mvn compile dependency:build-classpath 
  -pl  -am 
  -Dmdep.outputFile=classpath.txt

如果之前有失败缓存，加 -U 强制更新：

mvn compile dependency:build-classpath 
  -pl  -am -U 
  -Dmdep.outputFile=classpath.txt

掌握了这一点，你就能在多模块项目中游刃有余地进行调试和脚本编写，彻底告别繁琐的重复 install。更重要的是，你理解了 Maven Reactor 的设计哲学——构建时优先使用实时产物，而非仓库里的旧 JAR——这会让你在面对 Maven 的各种“奇怪行为”时，多一份从容。