自定义Gradle插件引发Multiple dex files define异常的解决求助

这种场景我之前踩过好几次坑，核心问题要么是Transform的输出清理逻辑没做好，要么是代码里不小心持有了文件句柄导致删不掉，给你几个针对性的解决思路：

1. 补全增量构建下的输出清理逻辑 #

Gradle的增量构建会跳过未修改的输入，但如果你的Transform没处理已移除的输入，旧的输出文件就会残留。一定要在transform方法里处理RemovedInput：

@Override
void transform(TransformInvocation invocation) throws TransformException, InterruptedException, IOException {
    // 处理增量构建的移除输入
    if (invocation.isIncremental()) {
        for (RemovedInput removedInput : invocation.getInputs().getRemovedInputs()) {
            // 根据移除的输入路径，删除对应的输出文件
            File outputDir = getOutputDirForInput(removedInput);
            if (outputDir.exists()) {
                FileUtils.deleteDirectory(outputDir);
            }
        }
    } else {
        // 非增量模式下，直接清空整个Transform输出目录
        File outputRootDir = invocation.getOutputProvider().getContentLocation(
            "myplugin",
            getOutputTypes(),
            getScopes(),
            Format.JAR
        );
        if (outputRootDir.exists()) {
            FileUtils.deleteDirectory(outputRootDir);
        }
    }
    // 剩下的正常Transform逻辑...
}

这里的FileUtils可以用Apache Commons IO或者Gradle自带的org.gradle.api.file.Directory.deleteDir()方法。

2. 检查并释放所有文件句柄 #

很多时候文件删不掉，是因为代码里打开了JarFile、InputStream等资源但没关闭。一定要用try-with-resources语法自动释放：

// 错误示例：没关闭JarFile，导致文件被占用
JarFile jarFile = new JarFile(inputJar);
// ...处理逻辑
// jarFile.close(); 忘记关闭

// 正确写法
try (JarFile jarFile = new JarFile(inputJar)) {
    // 处理JAR内容的逻辑
} catch (IOException e) {
    // 异常处理
}

排查时可以用系统工具查看文件句柄占用（比如Windows的Process Explorer，Mac的lsof），确认是不是你的插件进程在持有文件。

3. 给Transform任务绑定前置清理动作 #

如果暂时找不到问题根源，可以先通过Gradle任务强制清理输出目录。在插件代码里给你的Transform任务添加前置依赖：

// 在插件的apply方法里配置
project.tasks.withType(MyPluginTransform) { transformTask ->
    def cleanTransformDir = project.tasks.create("cleanMyPluginTransform", Delete) {
        delete "${project.buildDir}/intermediates/transforms/myplugin"
    }
    transformTask.dependsOn(cleanTransformDir)
}

这样每次执行Transform前，都会先删掉旧的输出目录，从根源避免残留。

4. 排查重复类注入的问题 #

你遇到的DexException: Multiple dex files define异常，除了文件残留，也可能是Transform重复处理了同一个类。比如：

• 你的Transform把某个类多次写入输出JAR
• 输入的依赖里已经包含该类，插件又额外注入了一次

检查你的Transform逻辑：

• 遍历输入时，是否过滤了不需要处理的JAR（比如系统依赖、第三方库）
• 写入输出时，是否判断过类是否已经存在，避免重复添加

5. 临时禁用增量构建排查 #

如果不确定是不是增量构建的问题，可以先在项目的gradle.properties里添加：

android.enableBuildCache=false

或者在Transform里强制关闭增量：

@Override
boolean isIncremental() {
    return false;
}

如果关闭后问题消失，那肯定是增量处理的逻辑有漏洞，回到第一点补全即可。

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