AGP 版本号规则与命名约定
刚开始接触 Android Gradle 插件时，我对着版本号发过好几次呆。4.2.0、7.3.1、8.0.0-alpha12…… 这些到底怎么解读？升级会不会炸？说白了，版本号就是插件的“身份证”，读懂了它，你就能预判兼容性风险。这一节，我带你彻底搞懂 AGP 的版本号体系。
版本号结构：三段式
AGP 遵循语义化版本（SemVer）规范，格式为 主版本号.次版本号.补丁版本号，后面有时还会挂预发布标签。举个例子：8.0.0-beta01
主版本号：API 不向下兼容时递增。比如从 7.x 升到 8.x，你的 build.gradle 大概率要改写法。
次版本号：新增功能但向下兼容。比如 7.2 → 7.3，通常可以平滑升级。
补丁版本号：修复 bug，不引入新功能。比如 7.3.0 → 7.3.1，放心升。
预发布标签：alpha / beta / rc，代表测试阶段。数字越大越接近稳定版。
为什么我要强调“三段式”？因为我在项目中见过有人把 4.2.0 和 7.0.0 混为一谈，结果升级时 Gradle 版本不兼容，编译直接挂掉。
命名约定一览
| 版本号示例 | 含义 | 推荐使用场景 |
|---|---|---|
| 8.0.0 | 主版本稳定版 | 生产项目（需确认 Gradle 版本匹配） |
| 7.4.2 | 次版本补丁版 | 多数成熟项目的首选 |
| 8.0.0-alpha12 | 内测版（功能不稳定） | 尝鲜验证新特性，别上生产 |
| 7.3.0-beta04 | 公测版（API 基本冻结） | 深度适配测试 |
| 8.1.0-rc01 | 候选发布版 | 最后验证，一个月内大概率转正 |
我曾经踩过的坑：误把 8.0.0-alpha12 的 API 当作稳定版，写了一大堆 namespace 相关自定义代码。结果稳定版出来直接废弃了那个 API，重构了两天。
所以，带 alpha / beta 的版本，我个人的习惯是：只在分支里玩，绝不合并到 main。
版本号与 Gradle 版本的映射
每个 AGP 版本都绑定了最低 Gradle 版本。这在 官方兼容性表 里写得很清楚。这里我列几个常用的对应关系，你心里有数就行。
| AGP 版本 | 最低 Gradle 版本 | 推荐 Gradle 版本 |
|---|---|---|
| 8.0 – 8.1 | 8.0 | 8.0 – 8.2 |
| 7.4 – 7.6 | 7.5 | 7.5 – 7.6 |
| 7.0 – 7.3 | 7.0 | 7.1 – 7.4 |
| 4.2 – 6.0 | 6.7.1 | 6.7 – 7.4 |
| 3.6 – 4.1 | 6.1.1 | 6.1 – 6.7 |
升级 AGP 前，先看一眼 Gradle wrapper 的版本。我曾经直接升 AGP 没升级 Gradle，报了一大堆 Unsupported class file major version 错误。别学我，记住：先升 Gradle，再升 AGP。
解析版本号的代码片段
有时候在 CI 脚本里需要动态判断 AGP 版本，我们可以写个 Gradle task 来解析：
// 在 app/build.gradle 中
tasks.register('printAgpVersion') {
doLast {
def agpVersion = com.android.build.gradle.internal.Version.ANDROID_GRADLE_PLUGIN_VERSION
println "当前 AGP 版本: $agpVersion"
def parts = agpVersion.split('\\.')
def major = parts[0].toInteger()
def minor = parts[1].toInteger()
def patch = parts[2].replaceAll('[^0-9].*$', '').toInteger()
println "主版本: $major 次版本: $minor 补丁: $patch"
if (agpVersion.contains('alpha')) {
println "警告：这是内测版，不要用于生产！"
}
}
}这段代码能帮你快速判断当前环境。我在公司内部 CI 的 pre-check 里就用类似逻辑，防止有人不小心把 alpha 版本合进 release 分支。
升级时记住这几条铁律
- 主版本号不同，别搞混：7.x 和 8.x 的 API 差异巨大，升级前务必阅读迁移文档。
- 次版本号升级，先看 release note：虽然理论上向下兼容，但我遇到过 7.4 中某个 DSL 属性被标记为 deprecated，不影响编译但会报 warning。
- 补丁版本号只管升：修复 bug 的，闭着眼升就行。
- 预发布版本只用于测试：我习惯在 CI 的
nightly分支上跑 alpha 版本，确保项目能及时适配。 - Gradle 版本必须匹配：这是最常见的问题，没有之一。
嗯，版本号规则其实就这些。说白了，它就是一套「谁改了什么」的标签系统。你理解了这个规则，后面再看瀑布图的兼容性关系时，一眼就能判断那是主版本断层还是小版本更新。