Android Gradle Plugin 7.x 升级 8.1：一场“升级大冒险”的实战总结
2025-07-17 | 预计阅读时间：3分钟
最近，Android Play 官网给咱来了个“硬核要求”：target 得升级到 35。这一升级可不得了，原本的 7.x 版本直接“罢工”，只能硬着头皮往 8.1 冲。这一路上那可是状况百出，不过别担心，我把这些“升级路上的坑”都记录下来了，希望能给各位小伙伴们排排雷。
一、升级背景与目标：一场“技术大跃迁”
咱的目标很明确，就是要把项目的 Gradle 和 AGP 升级到官方推荐的最新兼容版本，也就是 Gradle 8.1.0 + AGP 8.1.0。为啥要这么干呢？还不是为了能支持更高的 compileSdk、Kotlin 和 Jetpack Compose 这些新特性，让咱的项目也能跟上时代的步伐。
咱这项目结构可不简单，是个多模块的“大家庭”，里面有 bird、plane、tetris、tank 等游戏模块，还大量使用了 Jetpack Compose、Kotlin、Navigation 这些现代技术栈，就像一个装备精良的“技术战队”。
二、升级步骤与“大坑”集合
1. Gradle Wrapper 升级：初遇“兼容性难题”
操作起来倒是简单，把 gradle/wrapper/gradle-wrapper.properties 中的 distributionUrl 改成 8.1.0 就行。可谁能想到，升级完就出问题了。AGP 7.x 和 Gradle 8.x 就像两个“不对付”的小伙伴，根本不兼容，编译的时候直接报错：
Cannot use @TaskAction annotation on method IncrementalTask.taskAction$gradle_core() because interface org.gradle.api.tasks.incremental.IncrementalTaskInputs is not a valid parameter to an action method.
这错误信息看着就头大，不过解决办法也不难，必须得同步把 AGP 升级到 8.1.0 及以上版本。
2. 升级 AGP 和 Kotlin 版本：“版本匹配大作战”
在 build.gradle 里把 com.android.application 和 com.android.library 插件版本都升级到 8.1.0，Kotlin 插件也升级到 1.9.0（和 Compose 1.5.4 是推荐组合）。本以为万事大吉了，结果又报错了：
This version (1.3.0) of the Compose Compiler requires Kotlin version 1.7.20 but you appear to be using Kotlin version 1.9.0 which is not known to be compatible.
原来是低版本的 Compose Compiler 和新 Kotlin 不兼容啊。那就简单，把 compose_version 升级到 1.5.4，再在所有用到 Compose 的模块 build.gradle 里加上：
composeOptions {
kotlinCompilerExtensionVersion '1.5.4'
}
3. Manifest package 属性问题：“包名大迁移”
AGP 8 就像个“严格的管家”，要求所有模块的 AndroidManifest.xml 都不能再用 package="..." 属性了，必须在 build.gradle 的 android 块里用 namespace 声明包名。
这可苦了咱，得把所有 AndroidManifest.xml 里的 package 属性都删掉，然后在每个模块的 build.gradle 的 android 块里加上正确的 namespace。
4. BuildConfig 和 R 类引用问题：“R 类失踪案”
这里又出了两个小插曲。一个是用了 buildConfigField 但没开启 buildFeatures.buildConfig，另一个是升级 namespace 后，代码里 R 类的包名和实际生成的不一致，导致“Unresolved reference: R”的错误。
解决办法也不难，在 build.gradle 的 android 块里加上：
buildFeatures {
buildConfig true
}
再全局搜索，把所有 R 类的 import 都替换成新 namespace，比如把 import com.a.find.bird.R 改成 import com.a.gbox.bird.R。
5. Jetpack Compose API 变更：“API 搬家记”
Compose 1.2 的时候，LazyVerticalGrid 等 API 搬到了 foundation.lazy.grid 包，参数也从 cells 变成了 columns。
这就得把 import 改成 import androidx.compose.foundation.lazy.grid.*，再把 cells = GridCells.Fixed(3) 改成 columns = GridCells.Fixed(3)。
6. 资源跨模块访问与 R 类别名：“资源引用大改造”
主模块 Demo 代码里直接引用了其他模块（如 plane、bird）的 R 类资源，升级 namespace 后就找不到了。
这时候 Kotlin 的 import 别名功能就派上用场了，像这样：
import com.a.gbox.plane.R as PlaneR
import com.a.gbox.bird.R as BirdR
再把代码里相关资源引用改成 PlaneR.drawable.xxx、BirdR.drawable.xxx。
7. 其他常见问题：“升级小贴士”
- Kotlin/Compose 版本兼容：一定要查阅 Compose 官方兼容表，别自己瞎搭配。
- Gradle 警告：AGP 8.1.0 官方支持到 compileSdk 33，用 34 会有警告，但不影响编译。
- API 变更：像
consumeAllChanges()已经废弃了，得用consume()替换。
三、升级建议与总结：“升级秘籍大公开”
- 升级顺序：先升级 Gradle Wrapper，再升级 AGP 和 Kotlin，最后处理 Compose 和各模块兼容性。就像搭积木一样，一步一步来，别着急。
- 全局搜索替换：升级 namespace 和 R 类后，一定要全局替换 import 和资源引用，不然就会像我一样，被各种“找不到引用”的错误折磨。
- 多模块同步：所有用到 Compose 的模块都要同步升级 composeOptions，不然就会“一个模块掉链子，整个项目都瘫痪”。
- 查阅官方文档：遇到 API 变更、兼容性问题，第一时间查阅官方升级指南，官方文档就是咱的“升级宝典”。
- 分步编译调试：每次修正一类问题后及时编译，就像给病人看病一样，一步一步排查，逐步定位和解决新报错。
四、版本兼容性参考：“版本搭配指南”
| Gradle | AGP | Kotlin | Compose Compiler | 状态 |
|---|---|---|---|---|
| 8.1.0 | 8.1.0 | 1.9.0 | 1.5.4 | ✅ 推荐 |
| 8.5 | 8.1.0 | 1.9.0 | 1.5.4 | ✅ 兼容 |
| 8.0 | 8.0.2 | 1.8.20 | 1.4.7 | ⚠️ 旧版本 |
常见错误与解决方案速查：“错误急救手册”
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
| Cannot use @TaskAction annotation | AGP 版本过低 | 升级 AGP 到 8.1.0 |
| Namespace not specified | 缺少 namespace 声明 | 在 build.gradle 中添加 namespace |
| Unresolved reference: R | R 类包名错误 | 更新 import 语句 |
| GridCells not found | Compose API 变更 | 使用 foundation.lazy.grid 包 |
| Compose Compiler version incompatible | 版本不匹配 | 升级 Compose Compiler 版本 |
经过这场“升级大冒险”，咱的项目终于成功适配了最新的 Gradle 和 AGP，支持了更高版本的 Kotlin 和 Jetpack Compose，就像给项目换了一身“新装备”，为后续的功能开发和维护打下了坚实的基础。希望我的这篇实战总结能帮到有类似需求的小伙伴们，让你们的升级之路少一些坎坷，多一些顺利！
