Android集成Google Play Services Location与commons.io时无法合并dex问题

Hey there! Let's break down why you're hitting that Unable to merge dex error when including commons-io, and walk through practical fixes to get your app running again.

1. 重复类冲突（最常见） #

This is the #1 culprit: another dependency in your project already includes some or all of commons-io's classes. When you explicitly add commons-io as a standalone dependency, you end up with duplicate class definitions. The Dex merger tool can't resolve these duplicates, hence the error.

For example, some third-party SDKs, hidden Android system libraries, or even other open-source dependencies (like certain okhttp/retrofit extensions) might already pull in commons-io indirectly. Adding it again creates a conflict.

2. 依赖版本不兼容 #

If you're using a specific version of commons-io, but another dependency in your project relies on an older (or newer) version, their class structures or method signatures might clash. This mismatch confuses the Dex merger during the merge process.

3. 方法数超限（少见 but possible） #

If your app's method count is already close to the 64K Dex limit, adding commons-io could push it over the edge. This would trigger the merge error, though this scenario usually fixes itself when removing any dependency—not just commons-io.

方法1: 排查并排除重复依赖 #

First, find out which dependency is already including commons-io:

• Run this command in Android Studio's Terminal:

  ./gradlew app:dependencies
  

  (Windows users use gradlew app:dependencies)
• Search the output for commons-io to spot all dependencies that include it.

Then, exclude the duplicate from the conflicting dependency in your module-level build.gradle:

dependencies {
    // Example: If libraryX is pulling in commons-io indirectly
    implementation('com.example:libraryX:1.0.0') {
        exclude group: 'commons-io', module: 'commons-io'
    }
    // Keep your desired commons-io version if needed
    implementation 'commons-io:commons-io:2.15.0' // Replace with your version
}

方法2: 统一commons-io版本 #

If version mismatch is the issue, force all dependencies to use the same commons-io version. Add this to your project-level build.gradle:

allprojects {
    repositories {
        // Your existing repo configs
    }
    configurations.all {
        resolutionStrategy.force 'commons-io:commons-io:2.15.0' // Use a stable version
    }
}

方法3: 开启Multidex（if method count is the problem） #

If you confirm your app is hitting the 64K method limit:

1. Update your module-level build.gradle:

android {
    defaultConfig {
        // ...
        multiDexEnabled true
    }
}

dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
}

2. Update your Application class:
   • Either inherit from MultiDexApplication:

     public class MyApp extends MultiDexApplication { }
     

   • Or initialize Multidex in attachBaseContext:

     public class MyApp extends Application {
         @Override
         protected void attachBaseContext(Context base) {
             super.attachBaseContext(base);
             MultiDex.install(this);
         }
     }
     

3. Don't forget to reference this class in your AndroidManifest.xml.

方法4: 清理缓存并重建项目 #

Sometimes stale cache causes weird merge errors. Try these steps:

• Click Build > Clean Project in Android Studio
• Then Build > Rebuild Project
• Or manually delete the .gradle and build folders, then sync your project again

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