在使用 Android Studio 构建一个多年未改动的老项目时，突然遇到了一个构建失败的问题，报错信息为：

java.lang.ArrayIndexOutOfBoundsException

起初，这个错误非常令人困惑。因为这个项目包括：

  • Gradle wrapper (gradlew)

  • Android Gradle Plugin (AGP)

  • SDK 和 build tools

  • 所有依赖配置

都多年没有变动过，也未曾升级或调整过任何版本。那么，这个错误是从何而来呢？

一、排查过程

通过日志分析和 Google 搜索，最终锁定了可能的根源——Android Gradle Plugin（AGP）版本 3.3.3 的一个已知 Bug。

虽然我们没有改动任何配置，但随着 Android Studio 或 JDK 本身的升级，可能在新的构建环境下触发了旧版 AGP 的兼容性问题。

1. 临时解决方案验证

为验证是否真的是 AGP 的问题，我尝试了以下步骤：

  1. 修改 build.gradle 中的 AGP 版本号：

    classpath 'com.android.tools.build:gradle:3.4.3'

  2. 同步项目（Sync Project with Gradle Files）并成功构建。

  3. 然后再将 AGP 版本还原为原来的 3.3.3：

    classpath 'com.android.tools.build:gradle:3.3.3'

  4. 再次 Sync，构建也恢复正常。

这个操作等同于“热启动”或“刺激”Gradle 缓存机制，让旧版本 AGP 在新环境中重新生成依赖或缓存，从而规避了异常。

2. 问题确认方式：关闭代码混淆

为了进一步验证是否是 AGP 的问题，可以尝试将 minifyEnabled 设为 false，即关闭代码混淆功能：

buildTypes {
    release {
        minifyEnabled false
        // proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
    }
}

如果此时构建成功，那么就可以基本确定是 AGP 在处理 ProGuard 或 R8 混淆时出现了数组越界的问题。

二、问题总结

这个问题的产生其实并非你的代码或配置有误，而是老旧版本的 AGP 在新环境中兼容性不佳，可能与以下因素有关：

  • Android Studio 升级

  • JDK 版本升级（尤其是从 Java 8 到 Java 11 及以上）

  • Gradle daemon 缓存损坏或不兼容

  • 构建工具链的某些组件在后台被更新（如 SDK Build Tools）

三、推荐解决方案

  1. 临时规避：如上述方法所示，通过切换 AGP 版本激活缓存修复机制，再切回原版本可暂时解决。

  2. 更长期方案：如果条件允许，建议升级 AGP 和 Gradle 到较新的稳定版本（建议 AGP 4.x 及以上，Gradle 至少使用 5.x~6.x 之间），以避免遗留兼容性问题。

  3. 构建环境隔离：考虑使用 Docker 或专门的 CI/CD 构建环境来保持项目依赖的固定性，避免受到本地开发工具链变更的影响。

四、结语

构建系统是一个项目中最容易被忽视但又极其脆弱的环节。即便你多年未改动，系统升级也可能无声地“破坏”旧环境下的一些默认行为。

遇到类似莫名其妙的构建异常时，不妨也考虑下这些“幽灵般”的兼容性问题——尤其是 AGP 和 Gradle，它们的组合版本对稳定性影响很大。

如果你也遇到类似问题，欢迎留言交流解决经验。