如果你的工程还在用applicationVariants、libraryVariants这两个变体入口那么最近升级 AGP 时大概率已经撞墙了。这两个老入口在 AGP 7.0 里被明确划入废弃区AGP 8.0 开始直接查无此项官方给出的替代路径就是androidComponents。我自己在维护的几个工程里这个迁移点花了一个下午踩完坑之后发现核心思路其实不难旧 API 切的是“变体结果”新 API 切的是“变体生命周期”。这篇内容就围绕这个迁移点把为什么改、新接口怎么用、几个高频替换场景、还有实际排查中遇到的问题一次写透适合正在升级 AGP、维护构建脚本或者准备写 Gradle 插件的工程师参考。1. 为什么非改不可旧 Variant API 的问题不在“旧”而在“耦合”1.1 旧 API 直接暴露了内部实现applicationVariants和libraryVariants刚出现的时候确实帮很多人省了事。那时候想遍历所有变体只需要写一段如下的脚本android { applicationVariants.all { variant - println(variant name ${variant.name}) } }但问题也出在这里variant这个对象不是一套稳定接口它更像是 AGP 内部实现类的投影。AGP 版本一升级内部类一调整构建脚本里拿到的variant.outputs、variant.applyFeature、variant.buildType这些成员就有可能静默变化甚至直接编译报错。具体到实际项目里表现最多的就是依赖了variant.outputs[0].outputFile、variant.mergeResourcesProvider、variant.processManifest这类内部对象一旦 AGP 把某个任务挪走或改名脚本就要跟着改一遍。这也是为什么官方从 AGP 4.1 开始尝试新的 Variant API并在 AGP 7.0 正式稳定。到 AGP 8.0老 API 基本退场继续写applicationVariants.all就会出现“找不到属性”这类错误。所以这不是“想不想换”的问题而是“必须在某个版本之前换掉”的问题。1.2 新旧 API 的核心差异我用一张表把新旧 API 的关键区别列出来方便你做迁移时对号入座对比维度旧 APIapplicationVariants/libraryVariants新 APIandroidComponents触发时机afterEvaluate后变体完全生成拆成beforeVariants和onVariants两个阶段对象类型直接暴露 AGP 内部类稳定的Variant/VariantBuilder接口能否修改变体开关通过variantFilter { ignore true }beforeVariants { enable false }能否修改输出名通过variant.outputs.all { outputFileName ... }onVariants { outputs.forEach { ... } }对 app / library 的处理分成两套 DSL 入口逻辑经常复制两遍统一一套 API按模块类型自动适配AGP 版本兼容7.0 前为主7.0 后废弃7.0 后可用8.0 起是主路这段表格里最重要的是两行一是“触发时机”二是“对象类型”。老 API 总有一种“等所有事情都定完了我再冲进去改”的即视感所以脚本里经常要写afterEvaluate来保证能拿到完整变体列表。新 API 则把变体生命周期拆成了“变体信息确认前”和“变体信息确认后”两个阶段让插件和脚本作者可以更早介入也可以更安全地只读取结果。1.3 app 和 library 为什么不再需要两套入口旧工程里常见的一个情况是主工程用applicationVariants.all库模块里再用libraryVariants.all两边各写一份几乎一样的逻辑。很多人以为这是 Android 模块类型天然需要区隔其实更多是历史遗留。AGP 内部对 application 和 library 的构建链确实有过较大差异于是直接暴露了两个入口。到了androidComponents这一代AGP 内部已经在 Variant 模型上做了统一。无论你处理的是 App 模块还是 Library 模块回调里的对象都实现了同一个Variant接口只是最终能消费的产物类型不同。于是“遍历所有变体做同一件事”的逻辑不用再为模块类型写两份。这个变化对多模块工程特别有用后面写迁移场景时会再展开。2. androidComponents 到底怎么用入口、生命周期和关键对象2.1 先认准三个核心方法androidComponents不是单个函数而是一个带着多种回调和选择器能力的扩展块。最常用的是这三个beforeVariants(selector) { variantBuilder - ... }onVariants(selector) { variant - ... }selector()配合withBuildType、withName、withProductFlavor之类的方法做变体筛选beforeVariants发生在 DSL 配置最终确定之前适合做“禁用变体”这类提前干预。onVariants则是在一个变体的信息已经生成完毕后触发适合读取applicationId、namespace、versionName也适合修改buildConfigFields、manifestPlaceholders这类可变 Map。如果你不需要关心具体阶段只想对所有变体回调那直接写onVariants { variant - ... }就够了。举个最简单的筛选例子只看 debug 变体android { androidComponents { onVariants(selector().withBuildType(debug)) { variant - println(debug variant ${variant.name}) } } }有些 AGP 版本里selector还支持withName、withProductFlavor等条件但不同小版本提供的能力略有差异。最稳的办法是先只过滤buildType必要时再查当前 AGP 版本的VariantSelectorAPI 文档。2.2 androidComponents 块在脚本里的位置和写法androidComponents要写在android块内部和defaultConfig、buildTypes同级。和旧 API 写android.applicationVariants.all的调用方式不同现在是声明式块。android { namespace com.example.app compileSdk 34 defaultConfig { applicationId com.example.app versionCode 1 versionName 1.0 } buildTypes { release { minifyEnabled true } } androidComponents { onVariants { variant - println(Variant: ${variant.name}, appId: ${variant.applicationId}) } } }用 Kotlin DSL 其实也差不多区别多半在引号和 lambda 写法的细节。如果你在androidComponents块里想去访问项目的tasks可以直接用tasks因为这个块在执行时已经能拿到 project 上下文。但注意不要在这里面随便调用project.afterEvaluate否则又绕回老路失去新 API 的优势。2.3 关键对象Variant、VariantBuilder、VariantOutput刚开始从旧 API 迁移时最容易搞混的就是Variant和VariantBuilder的分工。VariantBuilder是beforeVariants回调里的参数它代表“正在构建中的变体定义”可以修改enable属性来控制这个变体是否进入构建。Variant是onVariants回调里的参数代表“已经配置完成的变体”适合读取信息或修改一些附带产物配置。这里列一下我平时用得比较多的属性对象常用属性说明VariantBuildername、buildType、productFlavors、enable变体在 DSL 最终确定前的信息可改enableVariantname、buildType、applicationId、namespace、versionName、versionCode、outputs变体配置完成后可读信息VariantbuildConfigFields、manifestPlaceholders可修改的 Map最终写入构建产物VariantOutputoutputFileName输出文件名在多输出场景下逐个配置写迁移脚本时一个很实用的排查技巧是先在onVariants里把variant.properties相关的信息打出来看当前 AGP 版本到底暴露了哪些字段。每个 AGP 小版本可能都有少量字段增删以你本地实际使用版本的接口为准比死记 API 更可靠。3. 实操迁移四个高频场景从旧写法改成新写法3.1 场景一遍历变体并自定义 APK 输出文件名旧写法里最常见的需求是改 APK 输出名通常长这样android { applicationVariants.all { variant - variant.outputs.all { output - def fileName MyApp-${variant.name}.apk output.outputFileName fileName } } }迁移到新 API 后逻辑基本能平移android { androidComponents { onVariants { variant - variant.outputs.forEach { output - output.outputFileName MyApp-${variant.name}-${variant.versionName}.apk } } } }注意我用了outputs.forEach而不是outputs.all。旧 API 里outputs比较像一个集合新 API 里VariantOutput仍然可以存在多个输出比如启用 APK split 后会有多个 output。所以这种写法能覆盖到每一个输出比直接取第一个更稳。另外这个写法对 library 模块同样适用。如果你在一个 library 里也曾经用libraryVariants改 AAR 输出名迁移后你可以直接复用同一个androidComponents块不用再区分 application 还是 library。3.2 场景二动态注入 BuildConfig 字段和 Manifest 占位符很多工程会根据变体动态注入不同的接口地址。旧写法一般是android { applicationVariants.all { variant - variant.buildConfigField String, API_URL, \https://old.example.com\ variant.mergedFlavor.manifestPlaceholders [host: old.example.com] } }新 API 的写法要换成操作buildConfigFields和manifestPlaceholders这两个 Map。以 Groovy 为例import com.android.build.api.variant.BuildConfigField android { androidComponents { onVariants { variant - variant.buildConfigFields.put( API_URL, new BuildConfigField(String, \https://api.example.com\, API 接口地址) ) variant.manifestPlaceholders.put(host, api.example.com) } } }如果你用的是 Kotlin DSL构造BuildConfigField可能更简洁部分版本还提供了buildConfigField(...)扩展函数。核心点是onVariants阶段里这些 Map 仍然允许追加内容所以当你需要针对不同 buildType 注入不同值时可以在回调里用variant.buildType做分支判断。这里有个容易踩的坑老 API 里直接调variant.buildConfigField新 API 里是往MapProperty里put。如果你习惯性地写成variant.buildConfigFields.put...没问题但如果你还想用“给整个 variant 设置字段”的旧思路就会发现新 API 并没有这个全局方法。看清当前操作的是“字段集合”还是“单个字段”迁移会顺畅很多。3.3 场景三用 beforeVariants 替代 variantFilter 禁用变体很多团队会通过variantFilter把不需要的渠道或 build type 组合排除掉旧代码长这样android { variantFilter { variant - if (variant.buildType.name release) { variant.ignore true } } }到新 API要做的不再是“过滤”而是“禁用”android { androidComponents { beforeVariants { variantBuilder - if (variantBuilder.buildType release) { variantBuilder.enable false } } } }这里面的语义变化值得注意旧 API 的ignore更像是在构建过程中告诉你“这个变体我已经生成了只是你别编了”新 API 的enable false则会更早介入直接让这个变体不进入后续任务链。我实测下来后者对整个配置阶段的开销小一些因为变体被禁用后后续很多任务就不会再为它占坑。如果你的需求是“某个 flavor 某个 buildType 的组合不要了”同样在beforeVariants里判断variantBuilder.productFlavors即可。注意variantBuilder.productFlavors的数据结构在 AGP 7.x 和 8.x 中有过细节调整建议先打印看一下。3.4 场景四自定义任务挂接到变体构建流程旧脚本里经常要在变体构建前执行自定义任务例如根据变体信息生成配置文件。旧写法大概是android { applicationVariants.all { variant - def task tasks.register(generate${variant.name.capitalize()}Config) { println(generate for ${variant.name}) } variant.mergeAssetsProvider.configure { dependsOn task } } }新 API 下我习惯在onVariants回调里先用tasks.register创建任务再通过任务名依赖接入已有构建链android { androidComponents { onVariants { variant - def taskName generate${variant.name.capitalize()}Config tasks.register(taskName) { doLast { println(generate for ${variant.name}) } } tasks.named(merge${variant.name.capitalize()}Assets).configure { dependsOn taskName } } } }这里要特别提醒一下任务名基于variant.name生成时注意大小写和驼峰命名。比如 variant 名是freeRelease那么任务名是generateFreeReleaseConfig对应的 merge 任务是mergeFreeReleaseAssets。如果你启动了包名大小写不敏感的文件系统还要小心任务名冲突。如果你不想直接用任务名字符串去碰 AGP 内部任务新 API 也提供了更高级的variant.sources相关方法可以把自定义生成的目录挂到变体 source 上。但那一套理解成本更高对于大多数只想在某个任务前插入步骤的场景先依赖任务名是最容易上手的迁移方式。4. 常见问题与排查技巧实录4.1 onVariants 里改 versionName、buildType 为什么不生效这个问题我见到的频率非常高。很多人把onVariants当成一个“万能修改窗口”试图在里面给variant.versionName或variant.buildType直接赋值。但新 API 中Variant对象的信息在onVariants阶段已经基本锁定你拿到的versionName、applicationId都是只读快照。如果你需要改版本号应该回到defaultConfig或buildTypes里用常规 DSL 方式修改。那什么时候能改可变属性答案是buildConfigFields、manifestPlaceholders这类专门设计为可写的 Map。新 API 的设计哲学是把“应该在配置阶段定下来的数据”和“允许在变体生成后才补充的数据”分开。你只有在正确的阶段做正确的事脚本才不会越写越乱。4.2 app 和 library 模块并存逻辑要写两份吗不需要。这个问题的答案在新 API 里非常明确androidComponents是统一的入口不管你在 app 模块还是 library 模块回调都会触发。如果你担心同一个回调同时影响 app 和 library而你需要区分处理最简单的做法是在模块级脚本里定义一个标识boolean isLibrary plugins.hasPlugin(com.android.library) android { androidComponents { onVariants { variant - if (isLibrary) { // 只处理 library 变体 } else { // 只处理 app 变体 } } } }如果你是把逻辑写在一个 common 脚本里给多个模块 apply也可以通过project.plugins判断模块类型。这样的好处是公共逻辑只维护一份每个模块通过条件分支兼容各自的需求。实际项目里大多数逻辑是 app 和 library 都能共用的比如统一改输出文件名、注入同一个 BuildConfig 字段这种就不用区分。4.3 用 tasks.named 挂依赖时提示找不到任务在onVariants里调用tasks.named(merge${variant.name.capitalize()}Assets)有时候会报 “Task named not found”。原因通常是这个任务的name并不是你以为的那个大小写组合或者 AGP 在那一刻还没有创建对应的任务注册。一个比较稳的处理办法是不要直接named而是用tasks.configureEach做过滤tasks.configureEach { task - if (task.name merge${variant.name.capitalize()}Assets) { task.dependsOn(taskName) } }不过这个写法在高并发配置下也有潜在问题因为configureEach会匹配所有任务每次回调都会做字符串比较。如果项目任务很多建议还是直接确认任务名的准确大小写并尽可能把tasks.named放在回调内最靠后的位置。另一个方向是使用新 API 的variant.sources能力让 AGP 以“生成 source 目录”的方式把自定义任务直接接入但那个 API 相对底层后面如果你做自定义 Gradle 插件再深入研究会更合适。4.4 常见问题速查表现象原因处理方式applicationVariants或libraryVariants编译报错AGP 8.0 已移除旧 API全部改为androidComponents块variant.ignore true不再生效旧 variantFilter 语义被移除用beforeVariants中variantBuilder.enable false在onVariants中给versionName赋值没反应Variant对象已进入只读阶段回到defaultConfig或buildTypes修改改了buildConfigFields但 BuildConfig 没更新可能写错了字段名或值类型先打印variant.buildConfigFields确认 key自定义任务依赖挂不上任务名大小写或时机不对用tasks.configureEach过滤或查任务注册名多个模块逻辑重复旧 API 下被迫写两套合并到统一的androidComponents块5. 给从旧 API 迁过来的同行的几个建议说实话迁移这件事最怕的不是 API 不会用而是你心里还留着旧 API 的思维惯性。我第一次改的时候总想着在新 API 里找一个“等所有变体出来后再统一处理”的入口结果onVariants明明每个变体都会回调一次我却还挂在afterEvaluate里绕圈子。后来想通了新 API 是“一个变体一个回调”不是“一个集合一次回调”。我个人在实际项目里的做法是迁移时先保留旧逻辑新写一个临时的onVariants回调把所有变体的name、buildType、applicationId、outputs先打印出来确认数据结构和预期一致后再逐段替换旧逻辑。这样每一步都有可验证的中间结果出问题也容易定位。最后再分享一个小技巧如果你同时维护多个 Android 模块不要在每个build.gradle里复制同一段androidComponents逻辑建议把公共逻辑抽到buildSrc或者单独的 Gradle 脚本里用插件方式统一 apply。这样可以减少后续 AGP 升级时的修改面也让变体逻辑真正变成“一套配置所有模块生效”。这一步做踏实了后面再升级 AGP 版本会轻松很多。
