Android项目添加Ktor库后出现重复文件编译错误的原因与最优解咨询

Hey there, let's unpack what's going on here and find the best fix for your issue.

What's Causing the Error? #

The root problem is duplicate metadata files from indirect dependencies. When you added those Ktor client libraries (websocket, cio, android), each of them pulls in the kotlinx-io library as a transitive dependency. Since these Ktor modules might reference the same kotlinx-io library but from different build paths, the kotlinx-io.kotlin_module metadata file ends up being included multiple times in your APK. Android's build tools flag this as an error because they don't allow duplicate files at the same path.

The Optimal Solution (No More Guesswork) #

Instead of relying on pickFirst (which has version mismatch risks) or broad exclude rules (which can break dependencies), let's fix this properly with two key steps:

1. Use Ktor's BOM to Align All Dependency Versions #

Ktor provides a Bill of Materials (BOM) that ensures all Ktor-related dependencies (including transitive ones like kotlinx-io) use the exact same version. This eliminates version conflicts that could cause duplicate or mismatched files.

Add this to your root project's build.gradle (or build.gradle.kts if you're using Kotlin DSL):

dependencyManagement {
    imports {
        mavenBom "io.ktor:ktor-bom:$ktor_version"
    }
}

Then, in your app module's build.gradle, you can simplify your dependencies by removing the version numbers (the BOM handles this):

implementation "io.ktor:ktor-client-websocket"
implementation "io.ktor:ktor-client-cio"
implementation "io.ktor:ktor-client-android"

(Note: Make sure your ktor_version variable is defined in the root build.gradle, e.g., ext.ktor_version = "2.3.3" — pick a version compatible with Android Studio 3.3; older versions like 1.6.8 might be more stable for older Gradle setups.)

2. Safely Exclude the Duplicate Metadata File #

Once versions are aligned, the duplicate kotlinx-io.kotlin_module files are identical, so we can safely exclude them without risking runtime errors. Add this to your app module's build.gradle inside the android block:

android {
    // ... other configs

    packagingOptions {
        exclude 'META-INF/kotlinx-io.kotlin_module'
    }
}

This only removes the redundant metadata file, not the actual kotlinx-io library code — so you won't hit NoClassDefFoundError issues here.

Why Your Temporary pickFirst Solution Is Risky #

pickFirst tells the build tool to randomly select one of the duplicate files. If the transitive dependencies ever pull in different versions of kotlinx-io, you might end up with a mix of old and new class files, leading to runtime crashes like NoSuchMethodError or IllegalAccessError. Using the BOM first ensures all versions match, making either exclude or pickFirst safe — but exclude is more explicit and avoids any chance of random selection.

Final Check #

Sync your Gradle project, clean and rebuild, and the error should disappear completely. This approach addresses the root cause (version misalignment and duplicate metadata) instead of just masking the symptom.

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