Maven NoSuchMethodError — 依赖版本冲突

通过检查依赖树并用 dependencyManagement 固定版本，修复传递依赖冲突导致的 NoSuchMethodError 与 NoClassDefFoundError。

症状

遇到“Maven NoSuchMethodError — 依赖版本冲突”时靠猜测只会浪费时间。请按证据排查：先复现症状，再执行针对性诊断，定位根因后修复，并用明确检查验证结果。

可观察到的症状包括：

运行期抛 NoSuchMethodError 或 NoClassDefFoundError，尽管编译通过
错误指向新版库中确有存在的方法
IDE 与打包 jar 的行为不同

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

mvn dependency:tree -Dincludes=com.google.guava:guava

同一 artifact 出现多个不同版本节点即暴露冲突。

步骤 2

mvn dependency:tree -Dverbose | grep -B 3 "guava:jar:20"

verbose 依赖树会显示被省略的版本及引入路径。

步骤 3

mvn dependency:build-classpath -Dmdep.outputFile=cp.txt && grep -o "guava[^:]*" cp.txt

真正决定加载哪个版本的是运行期类路径，而非 IDE。

常见诱因（按出现频率排序）：

同一库的两个版本都在类路径上，且旧版胜出
Maven 的就近优先调解选中了意外的传递版本
shade/relocate 的依赖在最终产物中未被重定位

根因

Maven 对每个 artifact 只用就近优先（同层则先声明者优先）解析出单一版本。传递的旧版本因此可能覆盖你直接声明的新版本，导致按新 API 编译的代码在运行期抛 NoSuchMethodError。

修复

用 dependencyManagement 或直接依赖固定版本，排除有问题的传递路径，并重建依赖树确认只剩一个版本。

注意：固定的版本可能不满足其他库的 API 预期；固定后应验证每个使用方。

<!-- pom.xml: force a single, known-good version -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>33.0.0-jre</version>
    </dependency>
  </dependencies>
</dependencyManagement>

<!-- or exclude the offending transitive path -->
<exclusions>
  <exclusion>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
  </exclusion>
</exclusions>

验证

重建依赖树并确认只解析出一个版本；运行此前失败的代码路径确认无 NoSuchMethodError，再跑全量测试。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。