老实说作为一名Android开发者，Zui让人头秃的时刻之一，莫过于打开Android Studio，kan到那个提示升级Gradle的小弹窗。你心里想着“这次应该没什么大不了吧”，结果点击同步之后满屏的红色报错代码瞬间让你怀疑人生。特别是当你辛辛苦苦写好的构建脚本，突然因为官方废弃了某个核心API而彻底罢工时那种心情简直无法用语言形容。

Zui近，不少朋友在把项目升级到Android Gradle Plugin 8.0甚至Zui新的9.0版本时dou遇到了同一个棘手的问题：以前用来修改APK文件名的那个老伙计——applicationVariants.all，居然找不到了！去翻官方文档，谷歌轻描淡写地说一句“Yi废弃”，然后推荐你用新的androidComponents。结果当你兴冲冲地换过去，发现连outputsdou变得神龙见首不见尾。这简直就像是你刚学会怎么开车，厂家就把方向盘给拆了只给你留了个操纵杆，还没给说明书。

别急，经过我几天的摸索、踩坑，甚至去GitHub Issues里翻遍了各路大神的讨论，终于出了一套在AGP 8.0及9.0版本下既Neng优雅地重命名APK，又Neng随意移动文件位置的完整方案。今天就把这些压箱底的经验分享出来希望Neng帮你省下不少抓头发的时间。

在深入代码之前，咱们先聊聊为什么非得改这个名。对于个人开发者来说默认的app-release.apk或许还Neng凑合用，但在稍微正式一点的团队协作或CI/CD流程中，这简直就是灾难。你想想，测试群发了一堆包，大家手机里dou躺着一个叫“app-release”的图标，谁分得清哪个是V1.0，哪个是刚修复了Bug的V1.1？

通常，我们需要把版本号、版本号、构建类型甚至渠道名dou塞进文件名里。比如MyApp_V1.0.5_Build102_Release.apk，这样一目了然出了问题也Neng立刻溯源。所以掌握构建产物的命名权，其实是工程规范化的第一步。

在AGP 7.0甚至geng早的“远古时代”，我们的操作非常简单粗暴。直接在android闭包里通过applicationVariants.all就Neng遍历所有变体，然后直接修改outputFileName。代码大概长这样：

android {
    ...
    applicationVariants.all { variant ->
        variant.outputs.all { output ->
            outputFileName = "你的应用名_V${variant.versionName}_Build${variant.versionCode}_${variant.buildType.name}.apk"
        }
    }
}

这段代码陪伴了我们hen多年，简单、直观、有效。但是随着Gradle构建性Neng优化的推进，这种在配置阶段直接操作所有变体的方式，因为会拖慢构建速度，被谷歌官方判定为“不合规”。于是从AGP 8.0开始，这套API被彻底移除。Ru果你强行在8.0上用，迎接你的只有报错。

既然老路走不通，那就只Neng适应新规则了。官方引入了新的变体API——androidComponents。这个API的设计理念是“延迟注册”，也就是说它不会在配置阶段立刻执行，而是等到任务图准备好之后才介入，从而提升构建效率。

不过这个新API的文档确实有点晦涩，特别是关于如何修改输出文件名这一点，官方示例简直像是藏着掖着。下面我分两种场景，手把手教你该怎么写。

Ru果你的需求hen简单，只是想把生成的app-debug.apk改成App_V1.0_Debug.apk，而不需要移动它的位置，那么恭喜你，代码量非常少。我们不需要去管那些复杂的任务依赖，直接利用onVariants回调即可。

这里有个坑要注意，androidComponents块必须放在android块的Zui外层，和它是平级的关系，千万别嵌进去，否则Gradle可不认这笔账。

在你的app/build.gradle.kts中，加入以下逻辑：

// 放在Zui外层，不要放android块里
androidComponents {
    onVariants { variant ->
        variant.outputs.forEach { output ->
            // 这里我们Ke以自由拼接字符串，把版本信息dou塞进去
            val apkName = "你的应用名_V${output.versionName.get}_Build${output.versionCode.get}_${variant.buildType}.apk"
            // 这一步是关键，需要强转一下类型才Neng设置文件名
            .outputFileName = apkName
        }
    }
}

这段代码的逻辑非常清晰：每当Gradle准备好一个变体，我们就遍历它的所有输出，然后重新定义文件名。这里用到了output.versionName和output.versionCode，这些dou是现成的属性，直接拿来用就行。那个强转成VariantOutputImpl的操作虽然kan起来有点“黑魔法”，但在目前的AGP版本中是必须的，因为公开接口里暂时没直接暴露setter。

有时候，我们的需求可Nenggeng变态一点。比如我希望构建完之后APK不仅仅改个名，还Neng自动复制到项目的根目录下的ApkOutputs文件夹里方便打包发给测试或者上传到分发平台。

这种情况下光靠onVariants里的简单回调就不够了因为文件还没生成出来呢，我们没法移动它。我们需要在构建任务真正执行完毕之后插入一个“小尾巴”动作。

这就涉及到了Gradle的任务管理。我们需要找到对应的assemble任务，然后给它挂载一个doLast钩子。具体代码如下稍微有点长，但逻辑hen严密：

import java.nio.file.Files
import java.nio.file.Paths
import java.nio.file.StandardCopyOption
// 放在Zui外层，不要放android块里
androidComponents {
    onVariants { variant ->
        variant.outputs.forEach { output ->
            val out = output as com.android.build.api.internal.VariantOutputImpl
            // 这里用afterEvaluate是为了确保所有任务dou配置完毕，我们再去查找任务
            afterEvaluate {
                // 拼接任务名称，比如 assembleDebug 或 assembleRelease
                val capitalizedVariantName = variant.name.replaceFirstChar { it.uppercase }
                tasks.named {
                    doLast {
                        // 1. 找到APK默认生成的目录
                        // 注意：这里用到了SingleArtifact.APK来获取路径，这是官方推荐的方式
                        val apkFolder = Paths.get(
                            variant.artifacts.get(
                                com.android.build.api.artifact.SingleArtifact.APK
                            ).get.toString
                        )
                        // 2. 构建原始文件路径和新文件路径
                        val apkPath = apkFolder.resolve)
                        // 定义你想要的新名字
                        val newApkName = "你的应用名_V${out.versionName.get}_Build${out.versionCode.get}_${variant.name}.apk"
                        // 这里我演示的是在同级目录下改名，Ru果你想移动到别处，修改resolve的参数即可
                        // 比如想移动到项目根目录的build文件夹，Ke以写成 Paths.get
                        val newApkPath = apkFolder.resolve
                        // 3. 执行移动操作
                        // StandardCopyOption.REPLACE_EXISTING 表示Ru果文件存在就直接覆盖，不报错
                        Files.move
                        // 打印个日志，告诉自己搞定了
                        println}")
                    }
                }
            }
        }
    }
}

这段代码虽然kan起来有点绕，但核心思想就是“守株待兔”。我们先算好任务名，等构建跑完，直接去默认输出目录把文件抓出来扔到我们想去的地方。使用了Java NIO的Files.move方法，比传统的File操作geng高效一些。

在折腾这个问题的过程中，我也遇到了不少奇葩的错误，这里顺便列出来给大家提个醒：

找不到VariantOutputImpl这个类属于内部API，有时候IDE会提示找不到符号或者标红。Ru果遇到这种情况，尝试把import补全，或者无视IDE的标红，直接运行试试，通常编译是没问题的，只是IDE的索引还没跟上。

路径问题在使用Files.move时一定要确保目标目录是存在的。Ru果目标文件夹还没创建，Files.move可Neng会抛出NoSuchFileException。Ru果需要，Ke以在移动前加一句Files.createDirectories来确保目录存在。

AGP版本差异上述代码在AGP 8.0及以上版本dou是验证通过的。但Ru果你还在用7.x，建议还是老老实实用回applicationVariants，别强行升级API，容易得不偿失。

虽然谷歌这次升级AGP确实给我们带来了不少阵痛，把原本好用的API给废了文档也写得云里雾里但不得不承认，新的androidComponents API在 性和性Neng上确实geng有潜力。一旦你习惯了这种基于Variant和Task的编程思维，以后遇到geng复杂的构建需求时就会觉得游刃有余了。

希望这篇保姆级的教程Neng帮你解决APK重命名的烦恼。下次再遇到谷歌“坏事Zuo尽”乱改API的时候，别慌，多翻翻源码，多kankanIssues，总Neng找到解决办法的。毕竟我们程序员Zui擅长的就是解决别人制造的问题，对吧？