1. 项目概述为什么我们需要掌握Gradle插件开发如果你是一名Android开发者那么Gradle对你来说就像空气一样无处不在却又常常被忽略其复杂性。每天我们都在build.gradle文件里添加依赖、配置渠道、开启混淆但你是否想过这些看似简单的配置背后到底是谁在执行当你在Android Studio里点击“Run”按钮从代码到APK这个漫长的构建流水线又是如何被组织和驱动的答案就是Gradle插件。更具体地说是Android Gradle PluginAGP。然而AGP虽然强大但它提供的是一套标准化的构建流程。当你的项目遇到一些特殊需求比如需要自动生成特定代码、在构建过程中处理资源文件、或者集成公司内部特有的质量检测工具时标准的AGP就显得力不从心了。这时开发自定义的Gradle插件就成了解决问题的钥匙。简单来说Gradle插件就是一段可以插入到Gradle构建生命周期中的可执行代码。它允许你扩展Gradle的能力自动化那些重复、繁琐的构建任务将团队的最佳实践固化为工具从而提升整个团队的开发效率和构建质量。我见过很多团队为了一个简单的资源检查或者版本号自动递增写了一大堆脆弱的Shell脚本或Python脚本散落在各个角落维护起来异常痛苦。而一个精心设计的Gradle插件可以将这些逻辑集中、标准化并且无缝集成到开发者最熟悉的IDE和命令行构建流程中。掌握Gradle插件开发意味着你从Gradle的“使用者”变成了“塑造者”。你能深入理解Android构建系统的脉络精准定位构建瓶颈甚至能创造一些提升团队生产力的“黑科技”工具。这不仅是技术深度的体现更是工程化能力的重要标志。接下来我将从一个实战者的角度带你从零开始拆解Android Gradle插件开发的核心要点、实操步骤以及那些官方文档里不会写的“坑”。2. 核心概念与工作原理拆解在动手写代码之前我们必须先搞清楚几个核心概念否则很容易陷入“照猫画虎却不知其所以然”的境地。理解这些原理是写出稳健、高效插件的基础。2.1 Gradle构建的生命周期Gradle构建过程分为三个阶段初始化Initialization、配置Configuration和执行Execution。这是理解插件何时介入的关键。初始化阶段Gradle确定哪些项目Projects将参与构建并为每个项目创建一个Project实例。对于单模块项目就只有一个Project对象。多模块项目则会有多个。我们的插件通常是在这个阶段之后被应用的。配置阶段这是插件“大显身手”的主要舞台。Gradle会解析所有项目的build.gradle脚本执行其中的代码。注意这个阶段是执行配置代码而不是执行任务。例如当你在脚本里写android { compileSdkVersion 33 }这行代码就是在配置阶段被执行它配置了android扩展的属性。插件在这个阶段的主要工作就是向项目添加新的任务Task、配置扩展Extension对象、添加依赖配置Configuration。通过“挂载”到已有的任务上来调整任务的执行顺序或输入输出。执行阶段在配置阶段结束后Gradle已经得到了一个完整的任务依赖关系图Task DAG。当你执行gradle assembleDebug时就进入了执行阶段。Gradle会根据命令行指定的任务名按依赖顺序执行所有相关的任务。我们插件中定义的任务其doLast或doFirst闭包或使用TaskAction注解的方法就是在这个阶段被调用的。关键理解很多新手会混淆配置阶段和执行阶段。记住在build.gradle文件顶层写的任何代码除了任务Action都是在配置阶段运行的。如果你在里面执行一个耗时操作比如网络请求那么每次运行任何Gradle命令即使是gradle tasks这个操作都会执行一次这通常不是你想要的效果。2.2 Project、Task、Extension 三位一体这是Gradle插件开发的三个核心模型。Project你可以把它理解为构建脚本的执行上下文。每个build.gradle文件都对应一个Project对象。插件通过实现PluginProject接口其apply(Project project)方法会接收到这个对象。它是你操作构建的入口你可以通过它来创建任务、管理依赖、获取属性等。Task任务是构建工作的最小单元代表一个原子性的操作比如编译Java类、打包资源、生成DEX文件。插件开发的核心工作之一就是定义新的Task。一个Task由**动作Action和属性Property**组成。属性特别是用Input、Output注解标记的决定了任务的“最新性”UP-TO-DATE检查这是Gradle增量构建的基石。如果任务的输入和输出都没有变化Gradle就会跳过该任务的执行极大提升构建速度。Extension这是插件提供给用户的“配置接口”。回想一下我们是如何配置AGP的是通过android { ... }这个DSL领域特定语言。这个android就是一个Extension。通过定义Extension你可以让插件的使用者以一种声明式、易于理解的方式来配置插件行为而不是硬编码在插件代码里。Extension本质上就是一个包含了一些属性的Java Bean或Kotlin数据类。2.3 插件如何与AGP协同工作对于Android插件开发我们几乎总是需要与AGP互动因为我们的插件通常是为了增强Android的构建流程。这里有几个关键点依赖AGP的API你的插件需要声明对AGP的依赖通常是compileOnly或implementation这样才能使用AGP提供的类如AppExtension即android、Variant等。在正确的时机介入AGP有自己复杂的任务图创建流程。如果你创建的任务需要依赖AGP的任务比如在打包APK之后执行你就必须在AGP创建完它的任务之后再去挂载你的任务。通常我们会在Project.afterEvaluate回调中或者在应用了android插件后通过project.extensions.findByType找到AppExtension然后监听它的applicationVariants或libraryVariants配置完成事件。使用变体Variant感知API现代Android项目通常有debug、release等多个构建变体。一个好的插件应该能感知这些变体并为每个变体创建相应的任务或处理相应的资源。AGP提供了ApplicationVariant、LibraryVariant等对象来访问变体信息。理解了这些概念我们就有了坚实的理论基础。下面我们将进入实战环节从零开始创建一个插件。3. 开发环境搭建与项目结构工欲善其事必先利其器。搭建一个高效的开发环境能让你在编码、调试、测试时事半功倍。3.1 环境准备与工具选型JDK建议使用JDK 11或17。这是目前Android开发和Gradle自身兼容性较好的版本。你可以在命令行输入java -version确认。Gradle版本这是最容易踩坑的地方。你的插件项目本身是用Gradle构建的它有一个gradle/wrapper/gradle-wrapper.properties文件里面指定了Gradle的版本。这个版本不需要和最终使用你插件的项目的Gradle版本一致。但你需要确保插件代码兼容较低版本的Gradle API。通常选择一个较新且稳定的版本如Gradle 7.4或8.x作为插件项目的构建工具即可。我们可以在插件中声明最低兼容的Gradle版本。开发IDE首推IntelliJ IDEA社区版或终极版均可。它对Gradle、Java/Kotlin的支持最为完善能提供最好的代码补全、导航和调试体验。Android Studio虽然基于IDEA但更专注于应用开发对纯Java/Kotlin库和插件开发的支持稍弱。构建语言选择你可以用Groovy、Kotlin或Java来编写插件。目前的主流和趋势是Kotlin。Kotlin语法更现代、更安全与AGP本身也用Kotlin重写了很多部分的交互也更顺畅。本文后续示例将主要使用Kotlin。3.2 创建插件项目我们有两种主要方式来开发插件BuildSrc目录在项目根目录创建一个名为buildSrc的目录。Gradle会自动识别并编译该目录下的代码并将其作为依赖提供给项目中的所有模块。这种方式非常适合开发仅在当前项目中使用的、快速迭代的插件。优点是修改立即生效无需发布缺点是无法在其他项目间复用。独立项目创建一个独立的Gradle项目来开发插件。这种方式适合开发需要跨项目共享、团队共用或计划开源的插件。我们需要将其打包并发布到Maven仓库本地、公司私服或公共仓库。这里我们以更通用的独立项目为例讲解完整流程。你可以用IDEA新建一个“Kotlin/JVM”项目。创建后的项目结构大致如下手动调整后my-gradle-plugin/ ├── build.gradle.kts // 插件项目的构建脚本 ├── settings.gradle.kts ├── gradle/ │ └── wrapper/ │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── src/ │ ├── main/ │ │ ├── kotlin/ // 放置插件源码 │ │ │ └── com/yourcompany/plugin/ │ │ │ └── MyAndroidPlugin.kt │ │ └── resources/ │ │ └── META-INF/gradle-plugins/ │ │ └── com.yourcompany.myplugin.properties // 插件声明文件 │ └── test/ │ └── kotlin/ // 测试代码 └── libs/ // 可放置第三方jar3.3 配置插件项目的构建脚本这是最关键的一步。build.gradle.kts文件需要正确配置才能产出合格的Gradle插件包。plugins { kotlin-dsl // 这是关键它提供了Gradle插件开发所需的DSL支持和依赖管理 maven-publish // 用于发布插件到Maven仓库 } group com.yourcompany version 1.0.0 repositories { google() // 需要添加google仓库来拉取AGP mavenCentral() } dependencies { // 编译时依赖Gradle API这样我们才能使用Project、Task等类 implementation(gradleApi()) // 编译时依赖Kotlin标准库 implementation(kotlin(stdlib)) // 重要依赖AGP。使用compileOnly因为AGP最终由应用项目提供。 // 这里指定一个版本范围提高插件兼容性。 compileOnly(com.android.tools.build:gradle:7.4.0) // 测试依赖 testImplementation(kotlin(test)) } // 配置发布到Maven本地仓库方便测试 publishing { publications { createMavenPublication(maven) { from(components[java]) // 可以在这里配置POM信息如artifactId等 // 默认artifactId是项目名通常需要显式设置 artifactId my-android-plugin } } repositories { maven { name local url uri(${buildDir}/repo) // 发布到项目build目录下 } } }kotlin-dsl插件是魔法发生的地方。它会自动帮你引入正确的Gradle开发依赖并配置好Kotlin编译任务。3.4 创建插件声明文件为了让Gradle能够识别你的插件你需要在src/main/resources/META-INF/gradle-plugins/目录下创建一个属性文件。文件名就是插件的ID用户将来在apply plugin: ‘xxx’中使用的就是它。例如创建文件com.yourcompany.myplugin.properties内容如下implementation-classcom.yourcompany.plugin.MyAndroidPlugin这行配置告诉Gradle当用户应用插件IDcom.yourcompany.myplugin时应该加载哪个实现类。环境搭建完毕项目结构清晰。接下来我们就可以开始编写第一个插件了。4. 编写你的第一个Android Gradle插件让我们从一个简单但实用的例子开始一个在构建完成后打印所有APK文件信息的插件。这个例子涵盖了插件的基本骨架、任务创建和扩展定义。4.1 定义插件主类在src/main/kotlin/com/yourcompany/plugin/目录下创建MyAndroidPlugin.kt。package com.yourcompany.plugin import com.android.build.gradle.AppExtension import org.gradle.api.Plugin import org.gradle.api.Project import org.gradle.api.tasks.TaskProvider class MyAndroidPlugin : PluginProject { override fun apply(project: Project) { // 1. 创建扩展让用户能配置插件 val extension project.extensions.create( apkInfo, // 用户在build.gradle中使用的DSL块名 ApkInfoExtension::class.java ) // 2. 确保项目应用了Android Application插件 project.plugins.withId(com.android.application) { // 3. 获取Android扩展 val android project.extensions.getByType(AppExtension::class.java) // 4. 监听变体配置完成。这是一个关键回调点 android.applicationVariants.all { variant - // 为每个变体创建一个任务 val taskName printApkInfo${variant.name.capitalize()} val printApkInfoTask project.tasks.register(taskName, PrintApkInfoTask::class.java) { task - task.group custom // 任务分组方便在gradle tasks中查看 task.description Prints APK info for ${variant.name} variant // 将变体信息传递给任务 task.variantName.set(variant.name) task.buildTypeName.set(variant.buildType.name) // 获取变体输出的APK文件可能有多个如支持不同ABI的 task.apkFiles.set(variant.outputs.map { it.outputFile }) // 从扩展中获取配置 task.shouldPrintDetails.set(extension.printDetails) } // 5. 将任务挂载到构建流程中在assemble任务之后执行 // variant.assembleProvider 是AGP为这个变体提供的assemble任务 variant.assembleProvider?.configure { assembleTask - assembleTask.finalizedBy(printApkInfoTask) } } } // 如果项目没有应用android application插件可以给出警告或做其他处理 project.afterEvaluate { if (!project.plugins.hasPlugin(com.android.application)) { project.logger.warn(com.yourcompany.myplugin is applied, but com.android.application plugin was not found. This plugin is designed for Android application projects.) } } } }代码解析project.extensions.create创建了一个名为apkInfo的扩展。用户可以在build.gradle里写apkInfo { printDetails true }来配置。project.plugins.withId这是一个安全且推荐的方式确保你的插件逻辑只在目标插件这里是Android应用插件应用后才执行。比在apply方法里直接写if (project.plugins.hasPlugin(...))更优雅。android.applicationVariants.all遍历所有应用变体debug, release等。all是一个回调每当有新的变体被创建时都会触发能保证兼容未来的AGP版本比如动态特性模块可能会动态添加变体。task.finalizedBy这是任务依赖关系的一种。finalizedBy意味着assembleTask执行之后无论成功与否都会执行printApkInfoTask。与之相对的是dependsOn表示前置依赖。这里我们想在APK打包完成后打印信息所以用finalizedBy。4.2 定义扩展Extension扩展就是一个简单的数据类用于接收用户配置。package com.yourcompany.plugin import org.gradle.api.provider.Property interface ApkInfoExtension { val printDetails: PropertyBoolean }在build.gradle.kts中我们通常会提供一个实现类但使用PropertyT接口并配合project.extensions.createGradle的DSL能自动为其生成实现。用户配置时直接赋值即可。4.3 定义自定义任务Task任务类封装了具体的执行逻辑。package com.yourcompany.plugin import org.gradle.api.DefaultTask import org.gradle.api.file.RegularFileProperty import org.gradle.api.provider.ListProperty import org.gradle.api.provider.Property import org.gradle.api.tasks.Input import org.gradle.api.tasks.OutputFiles import org.gradle.api.tasks.TaskAction import java.io.File abstract class PrintApkInfoTask : DefaultTask() { get:Input abstract val variantName: PropertyString get:Input abstract val buildTypeName: PropertyString get:OutputFiles // 这里标记为输出虽然我们不产生新文件但有助于增量构建理解 abstract val apkFiles: ListPropertyFile get:Input abstract val shouldPrintDetails: PropertyBoolean init { // 设置默认值 shouldPrintDetails.convention(false) } TaskAction fun execute() { logger.lifecycle( APK Info for Variant: ${variantName.get()} ) logger.lifecycle(Build Type: ${buildTypeName.get()}) val files apkFiles.get() if (files.isEmpty()) { logger.lifecycle(No APK files found for this variant.) } else { logger.lifecycle(APK Files (${files.size}):) files.forEachIndexed { index, file - logger.lifecycle( [$index] ${file.name}) if (shouldPrintDetails.get()) { logger.lifecycle( Path: ${file.absolutePath}) logger.lifecycle( Size: ${file.length() / 1024} KB) // 这里可以添加更多分析比如使用aapt2解析版本号等 } } } logger.lifecycle() } }关键点继承DefaultTask。使用abstract val配合Input、OutputFiles等注解来声明任务的输入/输出属性。这是实现增量构建的关键。如果这些属性值没有变化Gradle会标记任务为UP-TO-DATE并跳过执行。TaskAction注解标记的方法就是任务执行时运行的动作。使用logger.lifecycle输出信息它会显示在Gradle的控制台输出中与Gradle自身的日志风格一致。4.4 在测试项目中应用插件首先在插件项目根目录执行./gradlew publishToMavenLocal或使用IDEA的Gradle任务面板将插件发布到本地Maven仓库~/.m2/repository。然后在一个Android应用项目的根build.gradle文件中添加对本地插件的依赖和插件仓库// 根目录的 build.gradle buildscript { repositories { google() mavenCentral() mavenLocal() // 添加本地Maven仓库 } dependencies { classpath com.android.tools.build:gradle:7.4.0 // 依赖我们刚发布的插件 classpath com.yourcompany:my-android-plugin:1.0.0 } }在App模块的build.gradle中应用插件并配置// app/build.gradle plugins { id com.android.application id com.yourcompany.myplugin // 应用我们的插件 } android { // ... 你的Android配置 } // 配置我们的插件扩展 apkInfo { printDetails true // 开启详细打印 }现在当你执行./gradlew assembleDebug时在构建结束后控制台就会打印出类似以下的信息 APK Info for Variant: debug Build Type: debug APK Files (1): [0] app-debug.apk Path: /path/to/project/app/build/outputs/apk/debug/app-debug.apk Size: 15234 KB 恭喜你已经成功创建并运行了第一个自定义Android Gradle插件。这个插件虽然简单但已经包含了插件开发的核心模式。接下来我们要深入更复杂、更实用的场景。5. 进阶实战处理Android资源与Manifest一个更常见的插件需求是在构建过程中动态处理资源或AndroidManifest文件。例如根据构建渠道自动替换应用图标中的渠道标识或者向Manifest中注入一些元数据。下面我们以实现一个“资源占位符替换”插件为例。5.1 需求与设计假设我们有一个需求在res/values/strings.xml中定义一些占位符如string/app_name_template其值为MyApp {channel}。我们希望在构建时根据不同的渠道如huawei、xiaomi将{channel}替换为对应的渠道名生成最终的应用名MyApp Huawei。设计思路在assets或特定目录放置一个渠道配置文件。插件读取渠道配置。在资源合并之后、资源编译之前复制一份字符串资源文件并替换其中的占位符。让后续的AAPT2编译使用我们处理过的资源。难点在于如何找到正确的介入时机AGP的资源处理流程非常复杂。一个相对稳妥且兼容性较好的做法是在process*Resources任务例如processDebugResources之前插入我们自己的资源处理任务并修改该任务的输入。5.2 实现资源处理任务首先创建一个处理资源文件的任务。package com.yourcompany.plugin.resource import org.gradle.api.DefaultTask import org.gradle.api.file.DirectoryProperty import org.gradle.api.file.RegularFileProperty import org.gradle.api.provider.Property import org.gradle.api.tasks.* import java.io.File abstract class ProcessResourcesTask : DefaultTask() { get:InputFiles get:PathSensitive(PathSensitivity.RELATIVE) abstract val sourceDirs: SetPropertyFile // 原始资源目录 get:Input abstract val channel: PropertyString // 渠道名 get:OutputDirectory abstract val outputDir: DirectoryProperty // 处理后的资源输出目录 TaskAction fun process() { val channelValue channel.get() val outputRoot outputDir.get().asFile // 清空输出目录 outputRoot.deleteRecursively() outputRoot.mkdirs() sourceDirs.get().forEach { srcDir - if (srcDir.exists() srcDir.isDirectory) { // 复制整个资源目录结构 srcDir.copyRecursively(File(outputRoot, srcDir.name), overwrite true) // 处理values目录下的字符串文件 val valuesDir File(outputRoot, ${srcDir.name}/values) if (valuesDir.exists()) { valuesDir.walkTopDown() .filter { it.isFile it.name.endsWith(.xml) } .forEach { xmlFile - replacePlaceholdersInXml(xmlFile, channelValue) } } } } project.logger.lifecycle(Resources processed for channel: $channelValue, output to: $outputRoot) } private fun replacePlaceholdersInXml(xmlFile: File, channel: String) { var content xmlFile.readText() // 简单的占位符替换实际中可能需要更复杂的XML解析 content content.replace({channel}, channel) if (content ! xmlFile.readText()) { xmlFile.writeText(content) } } }5.3 在插件中集成并挂接任务修改主插件类在合适的时机创建并插入这个任务。// 在 MyAndroidPlugin.apply 方法内android.applicationVariants.all 循环中 android.applicationVariants.all { variant - val variantName variant.name.capitalize() // 1. 创建资源处理任务 val processResTask project.tasks.register( process${variantName}ResourcesWithChannel, ProcessResourcesTask::class.java ) { task - task.group custom task.description Processes resources for $variantName variant with channel replacement // 配置任务的输入输出 // 获取variant的合并后的资源目录这是一个简化实际可能更复杂 val mergeResourcesTask variant.mergeResourcesProvider.get() task.sourceDirs.set(mergeResourcesTask.sourceDirs) // 注意这里需要根据AGP版本调整 task.channel.set(project.provider { // 可以从项目属性、扩展等地方获取渠道名 project.findProperty(channel) as? String ?: default }) task.outputDir.set(project.layout.buildDirectory.dir(intermediates/processed-res/${variant.name})) } // 2. 找到AGP的资源处理任务并修改其输入 val processResourcesTask variant.processResourcesProvider.get() // 这里是一个关键技巧我们让AGP的processResources任务依赖于我们的处理任务 // 并且将其输入目录改为我们处理后的输出目录。 // 注意直接修改AGP任务的输入可能因版本不同而失效更稳健的做法是“劫持”sourceSet。 // 下面是一种思路但实际实现需要更精细地处理 // 思路A较复杂但稳健注册一个Transform如果AGP版本支持或使用Artifact APIAGP 3.5。 // 思路B较简单但可能脆弱在processResources任务执行前将处理后的资源复制到其预期的输入目录。 // 示例思路B的简化版 val copyProcessedResTask project.tasks.register(copyProcessedResFor$variantName, Copy::class.java) { it.from(processResTask.flatMap { it.outputDir }) it.into(processResourcesTask.sourceSets*.res.srcDirs.first()) // 这里需要精确找到目标目录 it.dependsOn(processResTask) } processResourcesTask.dependsOn(copyProcessedResTask) project.logger.lifecycle([Plugin] Registered resource processor for variant: $variantName) }重要警告直接操作AGP内部任务的输入输出是高风险行为因为AGP的内部API和任务结构在不同版本间可能发生不兼容的变更。上述代码只是一个概念演示。在生产环境中强烈建议使用AGP提供的公开API例如Artifact API (AGP 3.5)用于在构建过程中安全地消费、修改和生成中间文件Artifacts。这是官方推荐的、面向未来的方式。Transform API (已废弃)在AGP 7.0之前广泛使用但在AGP 8.0中已被标记为废弃将在未来版本移除。新项目应避免使用。TaskConfigurationAction或监听变体API的回调在一些简单场景下通过监听回调来添加任务依赖关系更安全。5.4 使用Artifact API进行安全操作AGP 7.0推荐以下是一个使用Artifact APIandroidComponents{ onVariants{ ... } }的更现代、更安全的示例框架project.plugins.withId(com.android.application) { val androidComponents project.extensions.getByType(AndroidComponentsExtension::class.java) androidComponents.onVariants { variant - // 为每个变体注册一个自定义的Artifact转换 variant.transform(TransformParameters::class.java) { params - params.from.set(ArtifactType.MERGED_RESOURCES) // 输入合并后的资源 params.to.set(ArtifactType.PROCESSED_RESOURCES) // 输出处理后的资源自定义类型 params.parameters { // 可以在这里定义配置参数比如渠道名 it.channel.set(project.provider { project.findProperty(channel) as? String ?: default }) } } { inputs, outputs, params - // 这里是实际的转换逻辑执行处 val channel params.channel.get() inputs.get(ArtifactType.MERGED_RESOURCES).forEach { inputDir - // ... 执行资源处理逻辑将结果写入 outputs.get(ArtifactType.PROCESSED_RESOURCES) } } } } // 注意你需要定义自己的ArtifactType.PROCESSED_RESOURCES并注册。 // 这需要更深入的AGP知识超出了基础教程范围但它代表了最规范的做法。处理资源和Manifest是插件开发中的高级主题需要对AGP的构建流程有较深的理解。建议从官方文档和AGP的源码样例开始研究。6. 插件调试、测试与发布开发插件离不开调试和测试。此外为了让团队或其他项目使用你需要将其发布。6.1 调试Gradle插件调试插件的最佳方式是在一个测试项目中应用你本地开发的插件。使用buildSrc模式快速迭代对于前期探索和调试强烈建议使用buildSrc。将插件代码直接放在主项目的buildSrc目录下修改后立即生效可以直接在测试项目的构建脚本中打断点调试。发布到本地Maven仓库进行集成测试在插件项目中运行publishToMavenLocal。在测试项目的build.gradle中引用mavenLocal()和你的插件依赖如classpath com.yourcompany:plugin:1.0.0-SNAPSHOT。在Android Studio中打开测试项目找到插件项目中的任务代码例如PrintApkInfoTask.execute()方法设置断点。在测试项目上右键点击Gradle任务如assembleDebug选择“Debug assembleDebug”。IDEA会以调试模式启动Gradle构建并在执行到你的插件代码断点时暂停。使用--no-daemon和--rerun-tasks在调试时有时需要禁用Gradle守护进程并强制重新运行所有任务以确保代码更改被加载。可以在调试配置的“命令行参数”中添加--no-daemon --rerun-tasks。6.2 编写单元测试与功能测试测试是保证插件质量的关键。单元测试测试插件类、任务类本身的逻辑。你可以使用Gradle TestKit它允许你在测试中模拟一个Gradle项目并运行构建。在插件项目的build.gradle.kts中添加依赖dependencies { testImplementation(gradleTestKit()) testImplementation(org.junit.jupiter:junit-jupiter:5.8.2) testImplementation(org.assertj:assertj-core:3.22.0) }编写测试类。一个简单的测试示例如下import org.gradle.testkit.runner.GradleRunner import org.junit.jupiter.api.Test import org.junit.jupiter.api.io.TempDir import java.io.File import kotlin.test.assertTrue class MyAndroidPluginTest { TempDir lateinit var testProjectDir: File Test fun plugin should be applied and task should exist() { // 1. 创建测试用的 build.gradle 文件 val buildFile testProjectDir.resolve(build.gradle) buildFile.writeText( plugins { id com.android.application id com.yourcompany.myplugin } android { compileSdkVersion 33 defaultConfig { applicationId com.test minSdkVersion 21 targetSdkVersion 33 } } .trimIndent()) // 2. 运行Gradle任务检查是否成功 val runner GradleRunner.create() .withProjectDir(testProjectDir) .withArguments(tasks, --all) // 执行tasks任务列出所有任务 .withPluginClasspath() // 这行是关键将当前插件加入测试的classpath .build() // 3. 断言输出中是否包含我们插件注册的任务 assertTrue(runner.output.contains(printApkInfo)) } }功能测试集成测试创建一个更完整的模拟Android项目运行完整的构建流程验证插件的最终效果如是否生成了正确的文件。这通常更复杂但更能发现集成问题。6.3 发布插件当你对插件感到满意后就可以发布它了。发布到Maven Local如前所述./gradlew publishToMavenLocal。适用于本地分享或初步验证。发布到内部Maven仓库大多数公司会有内部的Artifactory或Nexus仓库。你需要在build.gradle.kts中配置对应的publishing.repositories。publishing { publications { createMavenPublication(maven) { groupId com.yourcompany artifactId my-android-plugin version 1.0.0 from(components[java]) // 可选添加源码和Javadoc的artifact artifact(tasks.kotlinSourcesJar.get()) } } repositories { maven { name companyRepo url uri(https://your-company-repo.com/repository/maven-releases/) credentials { username project.findProperty(repoUser) as? String ?: password project.findProperty(repoPassword) as? String ?: } } } }然后运行./gradlew publish。发布到Gradle Plugin Portal如果你打算开源插件可以发布到Gradle官方插件门户。这需要你注册账号并按照其规范配置插件通常使用com.gradle.plugin-publish插件过程稍复杂但能获得最好的分发体验。6.4 版本管理与兼容性版本号遵循语义化版本控制SemVer。主版本.次版本.修订号。不兼容的API更改升主版本向后兼容的功能性新增升次版本向后兼容的问题修复升修订号。兼容性声明在插件的文档或README中明确声明其兼容的AGP版本和Gradle版本。你可以在插件代码中通过try-catch或检查版本来提供友好的错误提示。使用gradle.properties将插件版本、AGP版本等定义在gradle.properties中便于统一管理。7. 常见问题、避坑指南与性能优化在实际开发中你会遇到各种各样的问题。这里总结一些常见的“坑”和解决思路。7.1 插件未生效或找不到症状应用了插件但任务没出现或者配置了扩展没效果。排查检查插件ID确保apply plugin: ‘id’中的ID与resources/META-INF/gradle-plugins/下的属性文件名完全一致。检查依赖路径确保在buildscript.dependencies中正确引入了插件jar包。使用mavenLocal()时确认本地仓库路径正确~/.m2/repository。检查插件类路径运行./gradlew buildEnvironment可以查看项目的依赖树确认你的插件是否在classpath中。查看Gradle日志在gradle命令后添加--info或--debug标志查看详细的加载日志看是否有插件加载失败的错误信息。7.2 任务UP-TO-DATE检查失效症状任务每次都会执行即使输入没有变化。原因任务的输入/输出没有正确定义或使用了非确定性输入。解决确保任务的所有输入属性都用Input、InputFiles、InputDirectory等注解标记。确保输出属性用OutputFile、OutputDirectory等标记。对于文件集合使用PathSensitive(PathSensitivity.RELATIVE)或PathSensitivity.ABSOLUTE来指定路径敏感性。通常RELATIVE就够用。避免在TaskAction方法中读取外部动态变化的内容如当前时间、网络数据作为逻辑依据除非将其声明为输入。7.3 构建速度变慢插件使用不当会显著拖慢构建速度。避免在配置阶段执行耗时操作如前所述在build.gradle顶层或插件的apply方法中执行IO、网络请求等操作会导致每次Gradle调用即使是gradle tasks都变慢。应将这类逻辑移到任务的Action中。善用增量构建如上一点所述正确声明任务的输入输出。避免创建过多任务为每个变体、每个渠道都创建独立任务可能会导致任务图非常庞大。考虑使用更高效的任务组织方式例如使用单个参数化任务或者利用Gradle的Worker API在单个任务中并行处理多个工作项。使用Provider API进行惰性配置尽量使用PropertyT和ProviderT来配置任务属性而不是在配置阶段就计算好值。这允许Gradle延迟计算优化配置阶段性能。7.4 兼容不同AGP版本AGP版本迭代很快内部API变化频繁。坚守公开API尽可能只使用AGP中Incubating注解之外的公开API。在Android Studio中将鼠标悬停在类或方法上可以查看其来源。来自com.android.build.api或com.android.build.gradle.api等包下的通常是公开API。使用版本检测如果你的插件必须使用一些内部API务必进行版本检测并提供降级方案或清晰的错误提示。val agpVersion project.extensions.findByType(AppExtension::class.java)?.let { ext - try { ext::class.java.getDeclaredField(AGP_VERSION).get(ext) as? String } catch (e: Exception) { null } } if (agpVersion ! null agpVersion.startsWith(7.)) { // 针对AGP 7.x的代码 } else { project.logger.error(Unsupported AGP version: $agpVersion) }广泛测试在插件的CI流程中针对多个主流AGP版本如7.0, 7.4, 8.0进行测试。7.5 处理文件路径与操作使用Gradle的Project.file()和Project.files()而不是直接使用new File(String)。Gradle的方法能更好地处理相对路径和项目属性。使用ProviderAPI处理延迟计算文件路径可能在配置阶段还未确定使用DirectoryProperty和RegularFileProperty可以安全地处理这类延迟属性。注意文件系统监听在IntelliJ IDEA中开发时如果你直接操作build/目录下的文件IDE的文件系统监听可能会与Gradle构建产生冲突导致“文件已锁定”等错误。在任务中执行文件操作是安全的。开发一个健壮、高效、兼容性好的Gradle插件是一个需要耐心和细致活的过程。它要求你不仅理解Gradle的核心概念还要对Android构建链有深入的洞察。从简单的任务自动化开始逐步深入到资源处理、字节码操作等复杂领域你会逐渐感受到将重复劳动工具化所带来的巨大收益。记住好的插件不是功能的堆砌而是对开发流程的深刻理解和优雅封装。
1. 项目概述为什么我们需要掌握Gradle插件开发如果你是一名Android开发者那么Gradle对你来说就像空气一样无处不在却又常常被忽略其复杂性。每天我们都在build.gradle文件里添加依赖、配置渠道、开启混淆但你是否想过这些看似简单的配置背后到底是谁在执行当你在Android Studio里点击“Run”按钮从代码到APK这个漫长的构建流水线又是如何被组织和驱动的答案就是Gradle插件。更具体地说是Android Gradle PluginAGP。然而AGP虽然强大但它提供的是一套标准化的构建流程。当你的项目遇到一些特殊需求比如需要自动生成特定代码、在构建过程中处理资源文件、或者集成公司内部特有的质量检测工具时标准的AGP就显得力不从心了。这时开发自定义的Gradle插件就成了解决问题的钥匙。简单来说Gradle插件就是一段可以插入到Gradle构建生命周期中的可执行代码。它允许你扩展Gradle的能力自动化那些重复、繁琐的构建任务将团队的最佳实践固化为工具从而提升整个团队的开发效率和构建质量。我见过很多团队为了一个简单的资源检查或者版本号自动递增写了一大堆脆弱的Shell脚本或Python脚本散落在各个角落维护起来异常痛苦。而一个精心设计的Gradle插件可以将这些逻辑集中、标准化并且无缝集成到开发者最熟悉的IDE和命令行构建流程中。掌握Gradle插件开发意味着你从Gradle的“使用者”变成了“塑造者”。你能深入理解Android构建系统的脉络精准定位构建瓶颈甚至能创造一些提升团队生产力的“黑科技”工具。这不仅是技术深度的体现更是工程化能力的重要标志。接下来我将从一个实战者的角度带你从零开始拆解Android Gradle插件开发的核心要点、实操步骤以及那些官方文档里不会写的“坑”。2. 核心概念与工作原理拆解在动手写代码之前我们必须先搞清楚几个核心概念否则很容易陷入“照猫画虎却不知其所以然”的境地。理解这些原理是写出稳健、高效插件的基础。2.1 Gradle构建的生命周期Gradle构建过程分为三个阶段初始化Initialization、配置Configuration和执行Execution。这是理解插件何时介入的关键。初始化阶段Gradle确定哪些项目Projects将参与构建并为每个项目创建一个Project实例。对于单模块项目就只有一个Project对象。多模块项目则会有多个。我们的插件通常是在这个阶段之后被应用的。配置阶段这是插件“大显身手”的主要舞台。Gradle会解析所有项目的build.gradle脚本执行其中的代码。注意这个阶段是执行配置代码而不是执行任务。例如当你在脚本里写android { compileSdkVersion 33 }这行代码就是在配置阶段被执行它配置了android扩展的属性。插件在这个阶段的主要工作就是向项目添加新的任务Task、配置扩展Extension对象、添加依赖配置Configuration。通过“挂载”到已有的任务上来调整任务的执行顺序或输入输出。执行阶段在配置阶段结束后Gradle已经得到了一个完整的任务依赖关系图Task DAG。当你执行gradle assembleDebug时就进入了执行阶段。Gradle会根据命令行指定的任务名按依赖顺序执行所有相关的任务。我们插件中定义的任务其doLast或doFirst闭包或使用TaskAction注解的方法就是在这个阶段被调用的。关键理解很多新手会混淆配置阶段和执行阶段。记住在build.gradle文件顶层写的任何代码除了任务Action都是在配置阶段运行的。如果你在里面执行一个耗时操作比如网络请求那么每次运行任何Gradle命令即使是gradle tasks这个操作都会执行一次这通常不是你想要的效果。2.2 Project、Task、Extension 三位一体这是Gradle插件开发的三个核心模型。Project你可以把它理解为构建脚本的执行上下文。每个build.gradle文件都对应一个Project对象。插件通过实现PluginProject接口其apply(Project project)方法会接收到这个对象。它是你操作构建的入口你可以通过它来创建任务、管理依赖、获取属性等。Task任务是构建工作的最小单元代表一个原子性的操作比如编译Java类、打包资源、生成DEX文件。插件开发的核心工作之一就是定义新的Task。一个Task由**动作Action和属性Property**组成。属性特别是用Input、Output注解标记的决定了任务的“最新性”UP-TO-DATE检查这是Gradle增量构建的基石。如果任务的输入和输出都没有变化Gradle就会跳过该任务的执行极大提升构建速度。Extension这是插件提供给用户的“配置接口”。回想一下我们是如何配置AGP的是通过android { ... }这个DSL领域特定语言。这个android就是一个Extension。通过定义Extension你可以让插件的使用者以一种声明式、易于理解的方式来配置插件行为而不是硬编码在插件代码里。Extension本质上就是一个包含了一些属性的Java Bean或Kotlin数据类。2.3 插件如何与AGP协同工作对于Android插件开发我们几乎总是需要与AGP互动因为我们的插件通常是为了增强Android的构建流程。这里有几个关键点依赖AGP的API你的插件需要声明对AGP的依赖通常是compileOnly或implementation这样才能使用AGP提供的类如AppExtension即android、Variant等。在正确的时机介入AGP有自己复杂的任务图创建流程。如果你创建的任务需要依赖AGP的任务比如在打包APK之后执行你就必须在AGP创建完它的任务之后再去挂载你的任务。通常我们会在Project.afterEvaluate回调中或者在应用了android插件后通过project.extensions.findByType找到AppExtension然后监听它的applicationVariants或libraryVariants配置完成事件。使用变体Variant感知API现代Android项目通常有debug、release等多个构建变体。一个好的插件应该能感知这些变体并为每个变体创建相应的任务或处理相应的资源。AGP提供了ApplicationVariant、LibraryVariant等对象来访问变体信息。理解了这些概念我们就有了坚实的理论基础。下面我们将进入实战环节从零开始创建一个插件。3. 开发环境搭建与项目结构工欲善其事必先利其器。搭建一个高效的开发环境能让你在编码、调试、测试时事半功倍。3.1 环境准备与工具选型JDK建议使用JDK 11或17。这是目前Android开发和Gradle自身兼容性较好的版本。你可以在命令行输入java -version确认。Gradle版本这是最容易踩坑的地方。你的插件项目本身是用Gradle构建的它有一个gradle/wrapper/gradle-wrapper.properties文件里面指定了Gradle的版本。这个版本不需要和最终使用你插件的项目的Gradle版本一致。但你需要确保插件代码兼容较低版本的Gradle API。通常选择一个较新且稳定的版本如Gradle 7.4或8.x作为插件项目的构建工具即可。我们可以在插件中声明最低兼容的Gradle版本。开发IDE首推IntelliJ IDEA社区版或终极版均可。它对Gradle、Java/Kotlin的支持最为完善能提供最好的代码补全、导航和调试体验。Android Studio虽然基于IDEA但更专注于应用开发对纯Java/Kotlin库和插件开发的支持稍弱。构建语言选择你可以用Groovy、Kotlin或Java来编写插件。目前的主流和趋势是Kotlin。Kotlin语法更现代、更安全与AGP本身也用Kotlin重写了很多部分的交互也更顺畅。本文后续示例将主要使用Kotlin。3.2 创建插件项目我们有两种主要方式来开发插件BuildSrc目录在项目根目录创建一个名为buildSrc的目录。Gradle会自动识别并编译该目录下的代码并将其作为依赖提供给项目中的所有模块。这种方式非常适合开发仅在当前项目中使用的、快速迭代的插件。优点是修改立即生效无需发布缺点是无法在其他项目间复用。独立项目创建一个独立的Gradle项目来开发插件。这种方式适合开发需要跨项目共享、团队共用或计划开源的插件。我们需要将其打包并发布到Maven仓库本地、公司私服或公共仓库。这里我们以更通用的独立项目为例讲解完整流程。你可以用IDEA新建一个“Kotlin/JVM”项目。创建后的项目结构大致如下手动调整后my-gradle-plugin/ ├── build.gradle.kts // 插件项目的构建脚本 ├── settings.gradle.kts ├── gradle/ │ └── wrapper/ │ ├── gradle-wrapper.jar │ └── gradle-wrapper.properties ├── src/ │ ├── main/ │ │ ├── kotlin/ // 放置插件源码 │ │ │ └── com/yourcompany/plugin/ │ │ │ └── MyAndroidPlugin.kt │ │ └── resources/ │ │ └── META-INF/gradle-plugins/ │ │ └── com.yourcompany.myplugin.properties // 插件声明文件 │ └── test/ │ └── kotlin/ // 测试代码 └── libs/ // 可放置第三方jar3.3 配置插件项目的构建脚本这是最关键的一步。build.gradle.kts文件需要正确配置才能产出合格的Gradle插件包。plugins { kotlin-dsl // 这是关键它提供了Gradle插件开发所需的DSL支持和依赖管理 maven-publish // 用于发布插件到Maven仓库 } group com.yourcompany version 1.0.0 repositories { google() // 需要添加google仓库来拉取AGP mavenCentral() } dependencies { // 编译时依赖Gradle API这样我们才能使用Project、Task等类 implementation(gradleApi()) // 编译时依赖Kotlin标准库 implementation(kotlin(stdlib)) // 重要依赖AGP。使用compileOnly因为AGP最终由应用项目提供。 // 这里指定一个版本范围提高插件兼容性。 compileOnly(com.android.tools.build:gradle:7.4.0) // 测试依赖 testImplementation(kotlin(test)) } // 配置发布到Maven本地仓库方便测试 publishing { publications { createMavenPublication(maven) { from(components[java]) // 可以在这里配置POM信息如artifactId等 // 默认artifactId是项目名通常需要显式设置 artifactId my-android-plugin } } repositories { maven { name local url uri(${buildDir}/repo) // 发布到项目build目录下 } } }kotlin-dsl插件是魔法发生的地方。它会自动帮你引入正确的Gradle开发依赖并配置好Kotlin编译任务。3.4 创建插件声明文件为了让Gradle能够识别你的插件你需要在src/main/resources/META-INF/gradle-plugins/目录下创建一个属性文件。文件名就是插件的ID用户将来在apply plugin: ‘xxx’中使用的就是它。例如创建文件com.yourcompany.myplugin.properties内容如下implementation-classcom.yourcompany.plugin.MyAndroidPlugin这行配置告诉Gradle当用户应用插件IDcom.yourcompany.myplugin时应该加载哪个实现类。环境搭建完毕项目结构清晰。接下来我们就可以开始编写第一个插件了。4. 编写你的第一个Android Gradle插件让我们从一个简单但实用的例子开始一个在构建完成后打印所有APK文件信息的插件。这个例子涵盖了插件的基本骨架、任务创建和扩展定义。4.1 定义插件主类在src/main/kotlin/com/yourcompany/plugin/目录下创建MyAndroidPlugin.kt。package com.yourcompany.plugin import com.android.build.gradle.AppExtension import org.gradle.api.Plugin import org.gradle.api.Project import org.gradle.api.tasks.TaskProvider class MyAndroidPlugin : PluginProject { override fun apply(project: Project) { // 1. 创建扩展让用户能配置插件 val extension project.extensions.create( apkInfo, // 用户在build.gradle中使用的DSL块名 ApkInfoExtension::class.java ) // 2. 确保项目应用了Android Application插件 project.plugins.withId(com.android.application) { // 3. 获取Android扩展 val android project.extensions.getByType(AppExtension::class.java) // 4. 监听变体配置完成。这是一个关键回调点 android.applicationVariants.all { variant - // 为每个变体创建一个任务 val taskName printApkInfo${variant.name.capitalize()} val printApkInfoTask project.tasks.register(taskName, PrintApkInfoTask::class.java) { task - task.group custom // 任务分组方便在gradle tasks中查看 task.description Prints APK info for ${variant.name} variant // 将变体信息传递给任务 task.variantName.set(variant.name) task.buildTypeName.set(variant.buildType.name) // 获取变体输出的APK文件可能有多个如支持不同ABI的 task.apkFiles.set(variant.outputs.map { it.outputFile }) // 从扩展中获取配置 task.shouldPrintDetails.set(extension.printDetails) } // 5. 将任务挂载到构建流程中在assemble任务之后执行 // variant.assembleProvider 是AGP为这个变体提供的assemble任务 variant.assembleProvider?.configure { assembleTask - assembleTask.finalizedBy(printApkInfoTask) } } } // 如果项目没有应用android application插件可以给出警告或做其他处理 project.afterEvaluate { if (!project.plugins.hasPlugin(com.android.application)) { project.logger.warn(com.yourcompany.myplugin is applied, but com.android.application plugin was not found. This plugin is designed for Android application projects.) } } } }代码解析project.extensions.create创建了一个名为apkInfo的扩展。用户可以在build.gradle里写apkInfo { printDetails true }来配置。project.plugins.withId这是一个安全且推荐的方式确保你的插件逻辑只在目标插件这里是Android应用插件应用后才执行。比在apply方法里直接写if (project.plugins.hasPlugin(...))更优雅。android.applicationVariants.all遍历所有应用变体debug, release等。all是一个回调每当有新的变体被创建时都会触发能保证兼容未来的AGP版本比如动态特性模块可能会动态添加变体。task.finalizedBy这是任务依赖关系的一种。finalizedBy意味着assembleTask执行之后无论成功与否都会执行printApkInfoTask。与之相对的是dependsOn表示前置依赖。这里我们想在APK打包完成后打印信息所以用finalizedBy。4.2 定义扩展Extension扩展就是一个简单的数据类用于接收用户配置。package com.yourcompany.plugin import org.gradle.api.provider.Property interface ApkInfoExtension { val printDetails: PropertyBoolean }在build.gradle.kts中我们通常会提供一个实现类但使用PropertyT接口并配合project.extensions.createGradle的DSL能自动为其生成实现。用户配置时直接赋值即可。4.3 定义自定义任务Task任务类封装了具体的执行逻辑。package com.yourcompany.plugin import org.gradle.api.DefaultTask import org.gradle.api.file.RegularFileProperty import org.gradle.api.provider.ListProperty import org.gradle.api.provider.Property import org.gradle.api.tasks.Input import org.gradle.api.tasks.OutputFiles import org.gradle.api.tasks.TaskAction import java.io.File abstract class PrintApkInfoTask : DefaultTask() { get:Input abstract val variantName: PropertyString get:Input abstract val buildTypeName: PropertyString get:OutputFiles // 这里标记为输出虽然我们不产生新文件但有助于增量构建理解 abstract val apkFiles: ListPropertyFile get:Input abstract val shouldPrintDetails: PropertyBoolean init { // 设置默认值 shouldPrintDetails.convention(false) } TaskAction fun execute() { logger.lifecycle( APK Info for Variant: ${variantName.get()} ) logger.lifecycle(Build Type: ${buildTypeName.get()}) val files apkFiles.get() if (files.isEmpty()) { logger.lifecycle(No APK files found for this variant.) } else { logger.lifecycle(APK Files (${files.size}):) files.forEachIndexed { index, file - logger.lifecycle( [$index] ${file.name}) if (shouldPrintDetails.get()) { logger.lifecycle( Path: ${file.absolutePath}) logger.lifecycle( Size: ${file.length() / 1024} KB) // 这里可以添加更多分析比如使用aapt2解析版本号等 } } } logger.lifecycle() } }关键点继承DefaultTask。使用abstract val配合Input、OutputFiles等注解来声明任务的输入/输出属性。这是实现增量构建的关键。如果这些属性值没有变化Gradle会标记任务为UP-TO-DATE并跳过执行。TaskAction注解标记的方法就是任务执行时运行的动作。使用logger.lifecycle输出信息它会显示在Gradle的控制台输出中与Gradle自身的日志风格一致。4.4 在测试项目中应用插件首先在插件项目根目录执行./gradlew publishToMavenLocal或使用IDEA的Gradle任务面板将插件发布到本地Maven仓库~/.m2/repository。然后在一个Android应用项目的根build.gradle文件中添加对本地插件的依赖和插件仓库// 根目录的 build.gradle buildscript { repositories { google() mavenCentral() mavenLocal() // 添加本地Maven仓库 } dependencies { classpath com.android.tools.build:gradle:7.4.0 // 依赖我们刚发布的插件 classpath com.yourcompany:my-android-plugin:1.0.0 } }在App模块的build.gradle中应用插件并配置// app/build.gradle plugins { id com.android.application id com.yourcompany.myplugin // 应用我们的插件 } android { // ... 你的Android配置 } // 配置我们的插件扩展 apkInfo { printDetails true // 开启详细打印 }现在当你执行./gradlew assembleDebug时在构建结束后控制台就会打印出类似以下的信息 APK Info for Variant: debug Build Type: debug APK Files (1): [0] app-debug.apk Path: /path/to/project/app/build/outputs/apk/debug/app-debug.apk Size: 15234 KB 恭喜你已经成功创建并运行了第一个自定义Android Gradle插件。这个插件虽然简单但已经包含了插件开发的核心模式。接下来我们要深入更复杂、更实用的场景。5. 进阶实战处理Android资源与Manifest一个更常见的插件需求是在构建过程中动态处理资源或AndroidManifest文件。例如根据构建渠道自动替换应用图标中的渠道标识或者向Manifest中注入一些元数据。下面我们以实现一个“资源占位符替换”插件为例。5.1 需求与设计假设我们有一个需求在res/values/strings.xml中定义一些占位符如string/app_name_template其值为MyApp {channel}。我们希望在构建时根据不同的渠道如huawei、xiaomi将{channel}替换为对应的渠道名生成最终的应用名MyApp Huawei。设计思路在assets或特定目录放置一个渠道配置文件。插件读取渠道配置。在资源合并之后、资源编译之前复制一份字符串资源文件并替换其中的占位符。让后续的AAPT2编译使用我们处理过的资源。难点在于如何找到正确的介入时机AGP的资源处理流程非常复杂。一个相对稳妥且兼容性较好的做法是在process*Resources任务例如processDebugResources之前插入我们自己的资源处理任务并修改该任务的输入。5.2 实现资源处理任务首先创建一个处理资源文件的任务。package com.yourcompany.plugin.resource import org.gradle.api.DefaultTask import org.gradle.api.file.DirectoryProperty import org.gradle.api.file.RegularFileProperty import org.gradle.api.provider.Property import org.gradle.api.tasks.* import java.io.File abstract class ProcessResourcesTask : DefaultTask() { get:InputFiles get:PathSensitive(PathSensitivity.RELATIVE) abstract val sourceDirs: SetPropertyFile // 原始资源目录 get:Input abstract val channel: PropertyString // 渠道名 get:OutputDirectory abstract val outputDir: DirectoryProperty // 处理后的资源输出目录 TaskAction fun process() { val channelValue channel.get() val outputRoot outputDir.get().asFile // 清空输出目录 outputRoot.deleteRecursively() outputRoot.mkdirs() sourceDirs.get().forEach { srcDir - if (srcDir.exists() srcDir.isDirectory) { // 复制整个资源目录结构 srcDir.copyRecursively(File(outputRoot, srcDir.name), overwrite true) // 处理values目录下的字符串文件 val valuesDir File(outputRoot, ${srcDir.name}/values) if (valuesDir.exists()) { valuesDir.walkTopDown() .filter { it.isFile it.name.endsWith(.xml) } .forEach { xmlFile - replacePlaceholdersInXml(xmlFile, channelValue) } } } } project.logger.lifecycle(Resources processed for channel: $channelValue, output to: $outputRoot) } private fun replacePlaceholdersInXml(xmlFile: File, channel: String) { var content xmlFile.readText() // 简单的占位符替换实际中可能需要更复杂的XML解析 content content.replace({channel}, channel) if (content ! xmlFile.readText()) { xmlFile.writeText(content) } } }5.3 在插件中集成并挂接任务修改主插件类在合适的时机创建并插入这个任务。// 在 MyAndroidPlugin.apply 方法内android.applicationVariants.all 循环中 android.applicationVariants.all { variant - val variantName variant.name.capitalize() // 1. 创建资源处理任务 val processResTask project.tasks.register( process${variantName}ResourcesWithChannel, ProcessResourcesTask::class.java ) { task - task.group custom task.description Processes resources for $variantName variant with channel replacement // 配置任务的输入输出 // 获取variant的合并后的资源目录这是一个简化实际可能更复杂 val mergeResourcesTask variant.mergeResourcesProvider.get() task.sourceDirs.set(mergeResourcesTask.sourceDirs) // 注意这里需要根据AGP版本调整 task.channel.set(project.provider { // 可以从项目属性、扩展等地方获取渠道名 project.findProperty(channel) as? String ?: default }) task.outputDir.set(project.layout.buildDirectory.dir(intermediates/processed-res/${variant.name})) } // 2. 找到AGP的资源处理任务并修改其输入 val processResourcesTask variant.processResourcesProvider.get() // 这里是一个关键技巧我们让AGP的processResources任务依赖于我们的处理任务 // 并且将其输入目录改为我们处理后的输出目录。 // 注意直接修改AGP任务的输入可能因版本不同而失效更稳健的做法是“劫持”sourceSet。 // 下面是一种思路但实际实现需要更精细地处理 // 思路A较复杂但稳健注册一个Transform如果AGP版本支持或使用Artifact APIAGP 3.5。 // 思路B较简单但可能脆弱在processResources任务执行前将处理后的资源复制到其预期的输入目录。 // 示例思路B的简化版 val copyProcessedResTask project.tasks.register(copyProcessedResFor$variantName, Copy::class.java) { it.from(processResTask.flatMap { it.outputDir }) it.into(processResourcesTask.sourceSets*.res.srcDirs.first()) // 这里需要精确找到目标目录 it.dependsOn(processResTask) } processResourcesTask.dependsOn(copyProcessedResTask) project.logger.lifecycle([Plugin] Registered resource processor for variant: $variantName) }重要警告直接操作AGP内部任务的输入输出是高风险行为因为AGP的内部API和任务结构在不同版本间可能发生不兼容的变更。上述代码只是一个概念演示。在生产环境中强烈建议使用AGP提供的公开API例如Artifact API (AGP 3.5)用于在构建过程中安全地消费、修改和生成中间文件Artifacts。这是官方推荐的、面向未来的方式。Transform API (已废弃)在AGP 7.0之前广泛使用但在AGP 8.0中已被标记为废弃将在未来版本移除。新项目应避免使用。TaskConfigurationAction或监听变体API的回调在一些简单场景下通过监听回调来添加任务依赖关系更安全。5.4 使用Artifact API进行安全操作AGP 7.0推荐以下是一个使用Artifact APIandroidComponents{ onVariants{ ... } }的更现代、更安全的示例框架project.plugins.withId(com.android.application) { val androidComponents project.extensions.getByType(AndroidComponentsExtension::class.java) androidComponents.onVariants { variant - // 为每个变体注册一个自定义的Artifact转换 variant.transform(TransformParameters::class.java) { params - params.from.set(ArtifactType.MERGED_RESOURCES) // 输入合并后的资源 params.to.set(ArtifactType.PROCESSED_RESOURCES) // 输出处理后的资源自定义类型 params.parameters { // 可以在这里定义配置参数比如渠道名 it.channel.set(project.provider { project.findProperty(channel) as? String ?: default }) } } { inputs, outputs, params - // 这里是实际的转换逻辑执行处 val channel params.channel.get() inputs.get(ArtifactType.MERGED_RESOURCES).forEach { inputDir - // ... 执行资源处理逻辑将结果写入 outputs.get(ArtifactType.PROCESSED_RESOURCES) } } } } // 注意你需要定义自己的ArtifactType.PROCESSED_RESOURCES并注册。 // 这需要更深入的AGP知识超出了基础教程范围但它代表了最规范的做法。处理资源和Manifest是插件开发中的高级主题需要对AGP的构建流程有较深的理解。建议从官方文档和AGP的源码样例开始研究。6. 插件调试、测试与发布开发插件离不开调试和测试。此外为了让团队或其他项目使用你需要将其发布。6.1 调试Gradle插件调试插件的最佳方式是在一个测试项目中应用你本地开发的插件。使用buildSrc模式快速迭代对于前期探索和调试强烈建议使用buildSrc。将插件代码直接放在主项目的buildSrc目录下修改后立即生效可以直接在测试项目的构建脚本中打断点调试。发布到本地Maven仓库进行集成测试在插件项目中运行publishToMavenLocal。在测试项目的build.gradle中引用mavenLocal()和你的插件依赖如classpath com.yourcompany:plugin:1.0.0-SNAPSHOT。在Android Studio中打开测试项目找到插件项目中的任务代码例如PrintApkInfoTask.execute()方法设置断点。在测试项目上右键点击Gradle任务如assembleDebug选择“Debug assembleDebug”。IDEA会以调试模式启动Gradle构建并在执行到你的插件代码断点时暂停。使用--no-daemon和--rerun-tasks在调试时有时需要禁用Gradle守护进程并强制重新运行所有任务以确保代码更改被加载。可以在调试配置的“命令行参数”中添加--no-daemon --rerun-tasks。6.2 编写单元测试与功能测试测试是保证插件质量的关键。单元测试测试插件类、任务类本身的逻辑。你可以使用Gradle TestKit它允许你在测试中模拟一个Gradle项目并运行构建。在插件项目的build.gradle.kts中添加依赖dependencies { testImplementation(gradleTestKit()) testImplementation(org.junit.jupiter:junit-jupiter:5.8.2) testImplementation(org.assertj:assertj-core:3.22.0) }编写测试类。一个简单的测试示例如下import org.gradle.testkit.runner.GradleRunner import org.junit.jupiter.api.Test import org.junit.jupiter.api.io.TempDir import java.io.File import kotlin.test.assertTrue class MyAndroidPluginTest { TempDir lateinit var testProjectDir: File Test fun plugin should be applied and task should exist() { // 1. 创建测试用的 build.gradle 文件 val buildFile testProjectDir.resolve(build.gradle) buildFile.writeText( plugins { id com.android.application id com.yourcompany.myplugin } android { compileSdkVersion 33 defaultConfig { applicationId com.test minSdkVersion 21 targetSdkVersion 33 } } .trimIndent()) // 2. 运行Gradle任务检查是否成功 val runner GradleRunner.create() .withProjectDir(testProjectDir) .withArguments(tasks, --all) // 执行tasks任务列出所有任务 .withPluginClasspath() // 这行是关键将当前插件加入测试的classpath .build() // 3. 断言输出中是否包含我们插件注册的任务 assertTrue(runner.output.contains(printApkInfo)) } }功能测试集成测试创建一个更完整的模拟Android项目运行完整的构建流程验证插件的最终效果如是否生成了正确的文件。这通常更复杂但更能发现集成问题。6.3 发布插件当你对插件感到满意后就可以发布它了。发布到Maven Local如前所述./gradlew publishToMavenLocal。适用于本地分享或初步验证。发布到内部Maven仓库大多数公司会有内部的Artifactory或Nexus仓库。你需要在build.gradle.kts中配置对应的publishing.repositories。publishing { publications { createMavenPublication(maven) { groupId com.yourcompany artifactId my-android-plugin version 1.0.0 from(components[java]) // 可选添加源码和Javadoc的artifact artifact(tasks.kotlinSourcesJar.get()) } } repositories { maven { name companyRepo url uri(https://your-company-repo.com/repository/maven-releases/) credentials { username project.findProperty(repoUser) as? String ?: password project.findProperty(repoPassword) as? String ?: } } } }然后运行./gradlew publish。发布到Gradle Plugin Portal如果你打算开源插件可以发布到Gradle官方插件门户。这需要你注册账号并按照其规范配置插件通常使用com.gradle.plugin-publish插件过程稍复杂但能获得最好的分发体验。6.4 版本管理与兼容性版本号遵循语义化版本控制SemVer。主版本.次版本.修订号。不兼容的API更改升主版本向后兼容的功能性新增升次版本向后兼容的问题修复升修订号。兼容性声明在插件的文档或README中明确声明其兼容的AGP版本和Gradle版本。你可以在插件代码中通过try-catch或检查版本来提供友好的错误提示。使用gradle.properties将插件版本、AGP版本等定义在gradle.properties中便于统一管理。7. 常见问题、避坑指南与性能优化在实际开发中你会遇到各种各样的问题。这里总结一些常见的“坑”和解决思路。7.1 插件未生效或找不到症状应用了插件但任务没出现或者配置了扩展没效果。排查检查插件ID确保apply plugin: ‘id’中的ID与resources/META-INF/gradle-plugins/下的属性文件名完全一致。检查依赖路径确保在buildscript.dependencies中正确引入了插件jar包。使用mavenLocal()时确认本地仓库路径正确~/.m2/repository。检查插件类路径运行./gradlew buildEnvironment可以查看项目的依赖树确认你的插件是否在classpath中。查看Gradle日志在gradle命令后添加--info或--debug标志查看详细的加载日志看是否有插件加载失败的错误信息。7.2 任务UP-TO-DATE检查失效症状任务每次都会执行即使输入没有变化。原因任务的输入/输出没有正确定义或使用了非确定性输入。解决确保任务的所有输入属性都用Input、InputFiles、InputDirectory等注解标记。确保输出属性用OutputFile、OutputDirectory等标记。对于文件集合使用PathSensitive(PathSensitivity.RELATIVE)或PathSensitivity.ABSOLUTE来指定路径敏感性。通常RELATIVE就够用。避免在TaskAction方法中读取外部动态变化的内容如当前时间、网络数据作为逻辑依据除非将其声明为输入。7.3 构建速度变慢插件使用不当会显著拖慢构建速度。避免在配置阶段执行耗时操作如前所述在build.gradle顶层或插件的apply方法中执行IO、网络请求等操作会导致每次Gradle调用即使是gradle tasks都变慢。应将这类逻辑移到任务的Action中。善用增量构建如上一点所述正确声明任务的输入输出。避免创建过多任务为每个变体、每个渠道都创建独立任务可能会导致任务图非常庞大。考虑使用更高效的任务组织方式例如使用单个参数化任务或者利用Gradle的Worker API在单个任务中并行处理多个工作项。使用Provider API进行惰性配置尽量使用PropertyT和ProviderT来配置任务属性而不是在配置阶段就计算好值。这允许Gradle延迟计算优化配置阶段性能。7.4 兼容不同AGP版本AGP版本迭代很快内部API变化频繁。坚守公开API尽可能只使用AGP中Incubating注解之外的公开API。在Android Studio中将鼠标悬停在类或方法上可以查看其来源。来自com.android.build.api或com.android.build.gradle.api等包下的通常是公开API。使用版本检测如果你的插件必须使用一些内部API务必进行版本检测并提供降级方案或清晰的错误提示。val agpVersion project.extensions.findByType(AppExtension::class.java)?.let { ext - try { ext::class.java.getDeclaredField(AGP_VERSION).get(ext) as? String } catch (e: Exception) { null } } if (agpVersion ! null agpVersion.startsWith(7.)) { // 针对AGP 7.x的代码 } else { project.logger.error(Unsupported AGP version: $agpVersion) }广泛测试在插件的CI流程中针对多个主流AGP版本如7.0, 7.4, 8.0进行测试。7.5 处理文件路径与操作使用Gradle的Project.file()和Project.files()而不是直接使用new File(String)。Gradle的方法能更好地处理相对路径和项目属性。使用ProviderAPI处理延迟计算文件路径可能在配置阶段还未确定使用DirectoryProperty和RegularFileProperty可以安全地处理这类延迟属性。注意文件系统监听在IntelliJ IDEA中开发时如果你直接操作build/目录下的文件IDE的文件系统监听可能会与Gradle构建产生冲突导致“文件已锁定”等错误。在任务中执行文件操作是安全的。开发一个健壮、高效、兼容性好的Gradle插件是一个需要耐心和细致活的过程。它要求你不仅理解Gradle的核心概念还要对Android构建链有深入的洞察。从简单的任务自动化开始逐步深入到资源处理、字节码操作等复杂领域你会逐渐感受到将重复劳动工具化所带来的巨大收益。记住好的插件不是功能的堆砌而是对开发流程的深刻理解和优雅封装。
)
