Gradle构建AAB时如何动态重命名输出文件？

Question

在使用 Gradle 构建 Android App Bundle（AAB）时，如何动态重命名输出的 `.aab` 文件（如按 flavor、buildType、版本号、时间戳等组合生成 `app-prod-release-2.1.0-20240520.aab`）？默认情况下，Gradle 将 AAB 输出至 `build/outputs/bundle/` 下，文件名固定为 `app-{flavor}-{buildType}.aab`，不支持直接通过 `android.applicationVariants.all` 或 `outputFileName`（该属性在 AGP 7.0+ 中对 AAB 已被移除）生效。开发者尝试沿用 APK 的重命名方式（如 `variant.outputs.first().outputFileName = ...`）会失败或被忽略；同时，`bundle { }` 块中无原生 `outputFileName` 配置项。如何在不破坏构建流程、兼容 AGP 8.x 和 Gradle 8.x 的前提下，安全、可复用地实现构建后自动重命名，并确保 `assemble` 任务输出路径与 CI/CD 上传逻辑一致？这是多渠道发布和自动化流水线中的高频痛点。

Answer 1

```html

一、问题本质剖析：为什么 AAB 重命名比 APK 更复杂？

自 AGP 7.0 起，Android Gradle Plugin 彻底移除了 outputFileName 对 AAB 的支持，核心原因是 AAB 构建流程已重构为基于 BundleTool 的声明式产物生成（非传统 Gradle OutputFile 模型）。APK 可通过 variant.outputs 直接操作，而 AAB 由 bundle{...} 配置驱动，最终由 packageReleaseBundle（或 flavorized 变体如 packageProdReleaseBundle）任务输出——该任务的输出路径与文件名由内部 BundleTask 硬编码决定，不可通过旧式 DSL 修改。

二、技术演进对照：AGP 7.0+ 与 8.x 的关键差异

维度	AGP ≤6.7（APK 时代）	AGP 7.0+（AAB 时代）
重命名入口	android.applicationVariants.all { variant → variant.outputs.first().outputFileName = ... }	该属性已被弃用且对 AAB 完全无效；variant.bundle 仅提供配置能力，无输出控制权
构建任务类型	PackageApplication（继承自 AbstractOutputAwareTask）	BundleTask（继承自 DefaultTask，无 outputs.files 动态绑定机制）

三、官方推荐路径：使用 applicationIdSuffix + versionNameSuffix 间接影响命名（局限性明显）

此法仅能修改基础名称前缀/后缀，无法注入时间戳、Git SHA 或多维组合逻辑，且不改变 .aab 文件本体名，仅影响 manifest 元数据。实践中已证明无法满足 CI/CD 对可预测、唯一、语义化产物名的需求。

四、工程级解决方案：Hook package*Bundle 任务并执行后置重命名（兼容 AGP 8.2+ & Gradle 8.4+）

这是目前最稳定、无侵入、符合 Gradle 生命周期规范的方式。核心思想是：监听 afterEvaluate，定位所有 PackageBundle 类型任务（如 packageProdReleaseBundle），在其 doLast 阶段执行原子性重命名，并同步更新 project.layout.buildDirectory.dir("outputs/bundle") 下的引用路径。

android {
    // ... flavorDimensions & productFlavors
}
// ✅ 安全 Hook：确保在所有 variant 创建完毕后执行
afterEvaluate {
    android.applicationVariants.all { variant ->
        def bundleTask = tasks.findByName("package${variant.name.capitalize()}Bundle")
        if (bundleTask) {
            bundleTask.doLast {
                def originalFile = bundleTask.outputFile.get().asFile
                def timestamp = new Date().format('yyyyMMdd')
                def versionName = android.defaultConfig.versionName
                def flavorName = variant.flavorName ?: ""
                def buildTypeName = variant.buildType.name
                def newName = "app-${flavorName}-${buildTypeName}-${versionName}-${timestamp}.aab"
                def newFile = file("$buildDir/outputs/bundle/$newName")
                
                // 原子重命名 + 日志审计
                originalFile.renameTo(newFile)
                logger.lifecycle("✅ Renamed AAB: ${originalFile.name} → ${newFile.name}")
                
                // 关键：将新路径注入 project 属性，供 CI 脚本读取
                ext["aabOutputPath_${variant.name}"] = newFile.absolutePath
            }
        }
    }
}

五、CI/CD 协同设计：标准化输出路径契约

为保障流水线健壮性，需定义明确的“产物路径契约”。建议在根 build.gradle 中统一导出：

• ext.aabOutputDir = layout.buildDirectory.dir("outputs/bundle")
• ext.aabGlobPattern = "**/app-*-*.aab"
• 所有 CI 脚本（GitHub Actions / GitLab CI）均通过 find $OUTPUT_DIR -name "*.aab" 或 Gradle 属性读取（如 ./gradlew -q :app:properties | grep aabOutputPath）获取真实路径

六、高阶实践：封装为可复用插件（Gradle Plugin DSL）

将上述逻辑抽象为 com.example.aab-namer 插件，支持参数化配置：

plugins {
    id 'com.example.aab-namer' version '1.2.0' apply false'
}
android {
    bundle {
        // 启用插件增强
        enableAabNaming = true
        namingTemplate = 'app-{flavor}-{buildType}-{version}-{timestamp}-{gitShortHash}'
    }
}

插件内部通过 Project.afterEvaluate + TaskCollection.withType(PackageBundle) 实现零配置接入，大幅降低团队迁移成本。

七、风险规避清单（生产环境必查）

1. ❌ 禁止在 beforeEvaluate 中操作 task —— variant 尚未创建
2. ❌ 禁止使用 copy { from ... into ... } 替代 renameTo() —— 引发双重签名失败（AAB 必须保持原始 ZIP 结构完整性）
3. ✅ 推荐添加校验：重命名后执行 jar -tf $newFile | head -n5 确认 BundleTool 可解析
4. ✅ 在 CI 中启用 --no-daemon --console=plain 避免 Gradle Daemon 缓存导致路径不一致

八、验证流程图（Mermaid）

graph TD
  A[触发 assembleProdRelease] --> B[执行 packageProdReleaseBundle]
  B --> C[生成默认 app-prod-release.aab]
  C --> D[doLast Hook 触发]
  D --> E[读取 variant 元数据]
  E --> F[构造新文件名]
  F --> G[原子 renameTo]
  G --> H[写入 ext.aabOutputPath_prodRelease]
  H --> I[CI 脚本通过 ext 属性读取]
  I --> J[上传至 Play Console / 私有仓库]

九、版本兼容性矩阵

AGP 版本	Gradle 版本	方案是否生效	备注
8.0–8.4	8.0–8.6	✅ 完全支持	BundleTask API 稳定，outputFile.get() 可靠
7.4	7.5	✅ 支持（需降级 useNewBundleTool = false）	部分旧项目需显式关闭新版 BundleTool

十、延伸思考：未来方向——Gradle Configuration Cache 与 AAB 命名的兼容性

当启用 org.gradle.configuration-cache=true 时，doLast Hook 仍有效（因属于 task 执行期），但需避免在 doFirst 中访问 project 状态。建议将所有动态变量（如时间戳）延迟至 doLast 计算，而非在配置阶段预生成——这是保障缓存命中率的关键设计原则。Google 已在 Android Studio Giraffe 中预告 Bundle 命名 DSL 的回归，但短期仍应以任务 Hook 为黄金标准。

```