Android Studio导入Akka HTTP依赖报错：mergeDebugJavaResource执行失败

问题场景 #

在Android项目中尝试用Akka-HTTP-client替代Retrofit，导入相关依赖后出现构建错误，错误信息如下：

Execution failed for task ':app:mergeDebugJavaResource'.
> A failure occurred while executing com.android.build.gradle.internal.tasks.MergeJavaResWorkAction
   > 5 files found with path 'reference.conf' from inputs:
      - /home/vasanth/.gradle/caches/modules-2/files-2.1/com.typesafe.akka/akka-http_2.13/10.2.6/e67c00fd41067c8c268748ffebe1ece40dab5984/akka-http_2.13-10.2.6.jar
      - /home/vasanth/.gradle/caches/modules-2/files-2.1/com.typesafe.akka/akka-http-core_2.13/10.2.6/a95560123b64a592e5b5340cc52e41371ee6f6b1/akka-http-core_2.13-10.2.6.jar
      - /home/vasanth/.gradle/caches/modules-2/files-2.1/com.typesafe.akka/akka-stream_2.13/2.6.16/3ec252797aa7d552d0c710e088e5cf6e081f4905/akka-stream_2.13-2.6.16.jar
      - /home/vasanth/.gradle/caches/modules-2/files-2.1/com.typesafe.akka/akka-actor_2.13/2.6.16/37db3d5089e75b685c839e72a216775eae07331a/akka-actor_2.13-2.6.16.jar
      - /home/vasanth/.gradle/caches/modules-2/files-2.1/com.typesafe.ssl-config-core_2.13/0.4.2/93eaf36919de5cfa68f39874c1829faba2a66e4b/ssl-config-core_2.13-0.4.2.jar
     Adding a packagingOptions block may help, please refer to
     https://developer.android.com/reference/tools/gradle-api/7.3/com/android/build/api/dsl/ResourcesPackagingOptions
     for more information

* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.

当前app级build.gradle依赖配置：

dependencies {
    implementation 'com.android.support:appcompat-v7:28.0.0'
    implementation 'com.android.support.constraint:constraint-layout:2.0.4'
    testImplementation 'junit:junit:4.13.2'
    androidTestImplementation 'com.android.support.test:runner:1.0.2'
    androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.2'
    implementation 'com.typesafe.akka:akka-http-core_2.13:10.2.6'
    implementation 'com.typesafe.akka:akka-http_2.13:10.2.6'
    implementation 'com.typesafe.akka:akka-actor_2.13:2.6.16'
    implementation 'com.typesafe.akka:akka-stream_2.13:2.6.16'
}

错误原因 #

Akka系列依赖包（akka-http、akka-stream、akka-actor等）均包含reference.conf文件，这是Typesafe Config库用于提供组件默认配置的文件。Android构建工具在合并Java资源时，默认不允许存在路径相同的重复文件，因此触发冲突报错。

解决方案 #

在app级build.gradle的android代码块中添加packagingOptions配置，指定对重复的reference.conf文件执行合并操作，完整配置示例如下：

android {
    // 保留原有compileSdkVersion、defaultConfig等配置
    
    packagingOptions {
        merge 'reference.conf'
    }
}

dependencies {
    implementation 'com.android.support:appcompat-v7:28.0.0'
    implementation 'com.android.support.constraint:constraint-layout:2.0.4'
    testImplementation 'junit:junit:4.13.2'
    androidTestImplementation 'com.android.support.test:runner:1.0.2'
    androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.2'
    implementation 'com.typesafe.akka:akka-http-core_2.13:10.2.6'
    implementation 'com.typesafe.akka:akka-http_2.13:10.2.6'
    implementation 'com.typesafe.akka:akka-actor_2.13:2.6.16'
    implementation 'com.typesafe.akka:akka-stream_2.13:2.6.16'
}

相关知识 #

• reference.conf：Typesafe Config库的标准配置文件，Akka生态组件通过它定义默认配置参数，多个组件的配置需要合并才能保证Akka正常运行。
• Android打包配置（packagingOptions）：用于控制构建过程中对重复资源/文件的处理逻辑，常用规则包括：
  • pickFirst 'xxx'：保留第一个找到的同名文件
  • merge 'xxx'：合并所有同名文件的内容
  • exclude 'xxx'：排除所有同名文件
• 针对Akka依赖的场景，必须使用merge规则处理reference.conf，否则会丢失部分组件的默认配置，导致Akka运行异常。

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