AGP版本号规则：语义化版本、主要版本迁移影响

版本号看着简单，碰到的坑其实不少。我刚开始接手AGP升级时，一看版本号是7.4.1，觉得升到8.0没什么大不了。结果CI直接红了一片。说白了，版本号不是随便写的数字，背后是兼容性的红线。

语义化版本（SemVer）在AGP中的应用

AGP 从某个版本开始就遵循语义化版本规范（SemVer）。格式就是 主版本号.次版本号.修订号，规则和普通开源库一样，但含义更重。

• 主版本号（Major）：API 不兼容，强制破坏性变更。比如 AGP 7.x → 8.x，构建脚本语法、内部API都可能改。
• 次版本号（Minor）：新增功能，向后兼容。你可以放心小版本升级，但要认真看Release Note。
• 修订号（Patch）：bug fix，完全兼容。直接升，基本上不会出岔子。

举个例子，我在项目里遇到过 AGP 7.2.0 → 7.4.0 的升级，只改了Gradle和AGP版本号，编译就过了。但有一次从 7.4.0 升到 8.0.0，直接报错说 sourceSets.getByName 没了。嗯，这就是Major级别的威力。

AGP版本号的实际组成

拿 AGP 8.1.3 来说：

主要版本迁移的影响

主版本号每跳一次，AGP 就会引入一批 deprecated API 然后移除老API。常见的影响面：

• 构建脚本语法：比如 DSL 配置方式改变，buildTypes 里的某些闭包被替换。
• 默认行为：例如 AGP 8.0 默认开启了 enableNewResourceShrinking，旧项目可能爆资源删除错误。
• Gradle API 兼容性：AGP 对 Gradle 版本有硬性要求。升级AGP可能同时要升级Gradle。
• 第三方插件：很多插件没有跟上Major升级，会导致编译失败。

如何管理AGP版本迁移

你想想看，CI上几十个模块，手改版本号太容易出错了。我总结了五步流程：

1. 在 gradle-wrapper.properties 里修改 Gradle 版本（如果需要）
2. 在项目根 build.gradle 里修改 AGP 版本号
3. 同步项目，观察 IDE 是否报错
4. 运行 ./gradlew assembleDebug --stacktrace 查看完整错误
5. 根据错误信息逐一修复，反复迭代

代码示例（在项目根 build.gradle）：

// 旧版本
classpath "com.android.tools.build:gradle:7.4.1"

// 新版本
classpath "com.android.tools.build:gradle:8.1.3"

同时 gradle-wrapper.properties 要改：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.4-bin.zip