Android Gradle构建报错：DuplicateRelativeFileException问题求助

我之前也碰到过这个棘手的问题，咱们先把问题拆明白，再一步步解决。

错误成因拆解 #

这个报错的核心是Android打包时发现多个依赖（模块或JAR包）包含了完全相同路径的文件——这里就是META-INF/INDEX.LIST。这个文件是Java的jar工具自动生成的，用来记录JAR包内的文件索引，很多第三方库或者你自己的子模块在打包成JAR时都会带上它。当多个带这个文件的依赖被引入项目，打包合并阶段就会因为重复文件触发冲突。

分步排查步骤 #

1. 精准定位重复文件的来源 #

首先得搞清楚到底是哪几个依赖在输出这个重复文件，别瞎猜。在Android Studio的Terminal里执行对应命令：

• 如果你用Mac/Linux：

  ./gradlew app:dependencies --configuration releaseRuntimeClasspath
  

• 如果你用Windows：

  gradlew.bat app:dependencies --configuration releaseRuntimeClasspath
  

  这个命令会输出release环境下的完整依赖树，你可以搜索结果里的JAR包。或者用更直接的命令检测重复：

  ./gradlew app:checkReleaseDuplicateClasses
  

  这个任务会直接指出哪个依赖带了重复的META-INF/INDEX.LIST，精准定位源头。

2. 检查packagingOptions的写法是否正确 #

很多人说exclude无效，大概率是写法错了。要注意路径的大小写（INDEX.LIST是全大写），还有语法是否符合你的构建脚本类型：

• 如果你用Groovy的build.gradle：

  android {
      packagingOptions {
          exclude 'META-INF/INDEX.LIST'
      }
  }
  

• 如果你用Kotlin的build.gradle.kts：

  android {
      packagingOptions {
          exclude("META-INF/INDEX.LIST")
      }
  }
  

3. 排查隐藏的依赖/模块 #

有时候重复文件来自你自己的子模块，或者是某个依赖的间接依赖。比如子模块打包时自动生成了这个文件，或者某个第三方依赖的依赖链里藏着带INDEX.LIST的库。这时候结合依赖树的输出，逐个排查就能找到问题。

针对性解决方法 #

如果单纯exclude无效（比如出现其他奇怪错误），试试这些替代方案：

方案1：用pickFirst替代exclude #

有些情况下exclude可能误删了某个库需要的文件（虽然INDEX.LIST一般是可选的），这时候可以让Gradle选择第一个找到的文件，而非全部排除：

• Groovy：

  android {
      packagingOptions {
          pickFirst 'META-INF/INDEX.LIST'
      }
  }
  

• KTS：

  android {
      packagingOptions {
          pickFirst("META-INF/INDEX.LIST")
      }
  }
  

方案2：移除重复的依赖 #

如果排查后发现是两个依赖重复引入了同一个带INDEX.LIST的库，可以通过exclude依赖的方式删掉重复项。比如：

• Groovy：

  implementation('com.example:some-library:1.0.0') {
      exclude group: 'com.common', module: 'duplicate-module'
  }
  

• KTS：

  implementation("com.example:some-library:1.0.0") {
      exclude(group = "com.common", module = "duplicate-module")
  }
  

方案3：手动处理JAR包（万不得已时用） #

如果某个第三方库的JAR里确实带了INDEX.LIST，且没有其他办法，你可以手动解压这个JAR，删除META-INF/INDEX.LIST，再重新打包成JAR，替换项目里的依赖。这个方法比较繁琐，优先用前面的方案。

额外注意点 #

• 如果你用的是Android Gradle Plugin 7.0+，语法没问题，但建议升级到最新稳定版，旧版本可能存在exclude失效的bug。
• 每次修改完构建脚本后，一定要执行./gradlew clean再重新构建，避免缓存干扰导致修改不生效。

内容的提问来源于stack exchange，提问作者Ali