Android Gradle模块中让Java优先使用framework.jar而非android.jar的解决方案咨询

阿华AIGC实验室

2026-4-8

这个问题我之前在做定制化AOSP相关的Android项目时也踩过坑！确实挺闹心的——Kotlin代码能正常访问那些隐藏API，可Java代码一编译就报“找不到符号”，核心原因正如你观察到的：Java编译器（javac）会严格按照Classpath里Jar包的顺序加载类，而Android Gradle插件默认把系统的android.jar排在了前面，导致它的类定义覆盖了自定义framework.jar里的内容；而Kotlin编译器的类解析逻辑刚好和javac不一样，所以没出现这个问题。

给你分享几个亲测有效的解决方法：

手动调整Java编译任务的Classpath顺序（最推荐）
这是针对性最强、兼容性最好的办法。在你那个包含Java/Kotlin混编的模块的build.gradle（或build.gradle.kts）里，添加一段代码，把framework.jar放到Classpath的最前面：

如果你的项目用Groovy DSL编写构建脚本：

tasks.withType(JavaCompile) {
    doFirst {
        // 替换成你的framework.jar实际路径，比如模块libs目录下的文件
        def frameworkJar = files("libs/framework.jar").singleFile
        // 先把framework.jar从原有Classpath中移除
        def adjustedClasspath = classpath.filter { it != frameworkJar }
        // 再将它拼到Classpath的最开头
        classpath = files(frameworkJar) + adjustedClasspath
    }
}

如果用Kotlin DSL：

tasks.withType<JavaCompile>().configureEach {
    doFirst {
        val frameworkJar = file("libs/framework.jar")
        val adjustedClasspath = classpath.filter { it != frameworkJar }
        classpath = files(frameworkJar) + adjustedClasspath
    }
}

这段代码会在Java编译任务执行前，把framework.jar从原来的Classpath里抽出来，再放到最前面，这样javac就会优先加载这个Jar里的类定义，而不是系统的android.jar了。

确认依赖声明的正确性
一定要保持framework.jar的依赖类型为compileOnly，不要改成implementation或api——毕竟我们只是编译时需要用它的隐藏API，运行时还是依赖系统框架的，改类型可能会引入打包冲突或冗余问题。另外，建议把framework.jar放在对应模块的libs目录下，不要放在项目全局的libs里，避免影响其他不需要这个自定义框架的模块。
可选：调整AGP的编译类路径（谨慎使用）
还有一种更激进的方式，直接修改Android Gradle插件的编译类路径配置，但这个方法在不同AGP版本可能有兼容性问题。比如在模块的build.gradle里添加：
```
android {
    compileOptions {
        // 强制将自定义frameworkJar放到类路径最前面
        classpath = files("libs/framework.jar") + classpath
    }
}
```
我只在AGP 4.x到7.x的部分版本测试过能用，新版本的AGP可能调整了配置逻辑，所以更推荐第一种针对JavaCompile任务的调整方式。