企业官网建设流程全解析

1. 为什么非得自己写 Gradle Plugin，而不是直接写脚本或用现成插件？

“自定义 Gradle Plugin”这个标题乍看平淡，甚至有点学院气——不就是写个插件吗？但如果你在某公司参与过三个以上中大型 Android 或 JVM 系统的构建演进，你就会发现：真正卡住团队交付节奏的，从来不是业务代码写得慢，而是构建流程越来越像一锅熬糊了的八宝粥。我见过最典型的一个案例：某跨平台项目初期用gradle.properties控制开关、用buildSrc写 Kotlin 脚本、后期又引入了十几个社区插件（kotlinx-serialization,detekt,spotbugs,nexus-staging…），结果每次升级 Gradle 版本，光是解决插件兼容性冲突就要花两天；CI 构建日志里满屏Configuration cache may not be supported的警告，没人敢动；更糟的是，新同学入职后连./gradlew clean build都跑不通——因为本地环境缺一个被硬编码在 CI 机器上的keystore.path，而这个路径藏在某个build.gradle里嵌套了四层if (System.getenv("CI") != null)判断中。

这时候，“写个自定义 Plugin”就不是技术炫技，而是构建治理的刚需动作。它解决的不是“能不能做”，而是“能不能管得住、改得动、看得清、传得下去”。

很多人第一反应是：“我直接在build.gradle里写个 task 不就行了？”
比如：

task generateApiDoc { doLast { def outputDir = file("$buildDir/api-docs") outputDir.mkdirs() // 调用 Swagger Codegen 或自定义逻辑 } }

这当然能跑通。但它带来三个隐性成本：

• 复用不可控：A 模块写了，B 模块想用？得复制粘贴整段代码，改错一个参数，两个地方全崩；
• 配置不收敛：outputDir、apiSpecPath、templateName这些参数散落在各处，没有统一入口，也没有默认值兜底；
• 生命周期不透明：这个 task 是该在compileJava前还是后？和test有没有依赖？谁来触发它？没人定义，全靠口头约定。

而一个真正的自定义 Plugin，本质是把“构建逻辑”从“脚本片段”升格为“可版本化、可依赖、可配置、可测试的一等公民”。它不是多此一举，而是把构建这件事，从“手工作坊模式”推进到“现代工程模式”的关键分水岭。

提示：Gradle Plugin 不是 Java 库，也不是 Spring Bean。它的核心契约只有两条：1）提供一组可声明式配置的 Extension；2）注册一组有明确执行时机和依赖关系的 Task。其余所有“高级功能”，都是在这两条地基上长出来的枝叶。

你可能会问：“那为什么不直接用buildSrc？”
buildSrc确实能封装逻辑，但它有硬伤：它只对当前项目可见，无法发布到 Maven 仓库供其他项目复用；它和项目源码混在一起，导致构建脚本体积膨胀、IDE 索引变慢；更重要的是，buildSrc的编译本身会拖慢 Gradle 的配置阶段（Configuration Phase），尤其当它依赖大量外部库时——而一个 Plugin 的plugin-development-plugin机制，天然支持二进制分发、按需加载、独立编译缓存。

所以，当你看到“自定义 Gradle Plugin”这个标题时，请先抛开语法细节，先问自己三个问题：

1. 我是否正在重复解决同一类构建问题（如统一资源压缩、标准化签名配置、自动化文档生成）？
2. 这些解决方案是否已开始在多个模块/项目间“野蛮生长”，缺乏统一入口和版本管理？
3. 是否已有同事因修改构建逻辑而误伤他人任务，或因环境差异导致本地与 CI 行为不一致？

如果其中任意一条为“是”，那么——你不是在学一个 Gradle 技术点，你是在接手一项构建基础设施的运维权。这活儿干好了，团队提效看得见；干砸了，就是下一个“构建黑洞”的制造者。

2. 插件类型选择：Build Logic Plugin vs. Precompiled Script Plugin，选错等于重写一半

Gradle 官方文档里把插件分成三类：Script Plugins（.gradle脚本）、Binary Plugins（Java/Kotlin 编写的 jar 包）、Precompiled Script Plugins（Kotlin DSL 的.gradle.kts文件）。但实际工程中，真正值得投入的只有两种：Build Logic Plugin（传统二进制插件）和Precompiled Script Plugin（预编译脚本插件）。它们不是并列选项，而是面向不同成熟度阶段的构建治理方案。

2.1 Build Logic Plugin：适合需要长期维护、跨项目复用、强约束力的场景

这是最“正统”的插件形态，用 Java 或 Kotlin 编写，打包成jar，通过plugins { id("com.example.myplugin") version "1.0.0" }声明式引入。它的结构非常清晰：

my-plugin/ ├── src/main/kotlin/ │ ├── MyPlugin.kt // 实现 Plugin<Project> 接口 │ ├── MyExtension.kt // 定义可配置项（Extension） │ └── tasks/ // 自定义 Task 类 │ └── GenerateApiTask.kt ├── build.gradle.kts // 使用 plugin-development-plugin └── settings.gradle.kts

关键在于：它强制你把“做什么”（Task）、“怎么做”（Task Action）、“怎么配”（Extension）彻底解耦。比如MyExtension可能长这样：

open class MyExtension @Inject constructor( private val objects: ObjectFactory ) { val apiSpecPath: Property<String> = objects.property(String::class) val outputDir: DirectoryProperty = objects.directoryProperty() val enableValidation: Property<Boolean> = objects.property(Boolean::class).convention(true) }

注意三点：

• 所有属性必须用Property<T>或DirectoryProperty等惰性容器包装，这是 Gradle 延迟求值（lazy evaluation）的基石；
• convention()设置默认值，确保用户不配置时也能安全运行；
• 构造函数用@Inject标记，由 Gradle DI 容器注入ObjectFactory，而非手动 new。

这种设计带来的好处是：配置即契约。当你在build.gradle.kts中写：

myPlugin { apiSpecPath.set("src/main/resources/openapi.yaml") outputDir.set(layout.buildDirectory.dir("generated-api")) }

Gradle 就知道：这个配置块只影响myPlugin插件，且apiSpecPath必须是字符串，outputDir必须是目录路径——IDE 能自动补全，类型错误在编译期暴露，而不是运行时报MissingPropertyException。

我曾在一个金融类 SDK 项目中用这种方式统一了所有子模块的javadocJar生成逻辑。过去每个build.gradle都要手写：

task javadocJar(type: Jar, dependsOn: javadoc) { archiveClassifier = 'javadoc' from javadoc.destinationDir } artifacts { archives javadocJar }

结果某次升级 Gradle 7.x 后，archiveClassifier被废弃，十几个模块全报错。改成 Plugin 后，只需升级插件版本，所有模块自动适配新 API，零修改。

2.2 Precompiled Script Plugin：适合快速验证、轻量封装、单项目内收敛的场景

这是 Gradle 6.0 引入的“轻量级插件”，本质是一个.gradle.kts文件，放在gradle/plugin/目录下，内容就是一个标准的build.gradle.kts脚本，但被 Gradle 编译成 class 并缓存。例如gradle/plugin/api-docs.gradle.kts：

plugins { kotlin("jvm") version "1.9.20" apply false } val apiSpecPath: String by project val outputDir: String by project tasks.register<Exec>("generateApiDocs") { commandLine("java", "-jar", "swagger-codegen-cli.jar", "generate", "-i", apiSpecPath, "-l", "html", "-o", outputDir) }

然后在settings.gradle.kts中声明：

pluginManagement { includeBuild("gradle/plugin") }

并在build.gradle.kts中使用：

plugins { id("api-docs") }

它的好处是：零学习成本、开发极快、调试直观。你写的几乎就是普通构建脚本，没有Extension、没有Task类、不用处理ObjectFactory。特别适合以下场景：

• 团队刚起步，构建逻辑还在试错期，不确定最终形态；
• 某个模块有特殊需求（如专用于测试环境的资源混淆），不值得单独发版；
• 需要快速给 CI 流程注入一段逻辑，且只在当前项目生效。

但它有硬伤：无法跨项目复用，无法设置默认值，无法做类型校验，无法被其他插件依赖。它更像是“带名字的脚本片段”，而非真正的插件。

注意：Precompiled Script Plugin 的id必须与文件名严格一致（如api-docs.gradle.kts→id("api-docs")），且不能包含点号（.），否则 Gradle 会找不到。这是新手踩坑率最高的地方之一。

2.3 为什么不用 Script Plugin（.gradle）？

.gradle脚本（Groovy 或 Kotlin）是最早的插件形式，现在官方已明确标记为legacy。它的问题很致命：

• 每次应用都重新解析执行，无编译缓存，构建速度慢；
• 无法声明Extension，配置只能靠project.ext或全局变量，类型完全失控；
• IDE 支持差，几乎没有代码提示；
• 无法被pluginManagement统一管理版本。

我见过最离谱的案例：某项目把整个 CI 流程逻辑写在一个ci-setup.gradle里，里面用project.ext.versionCode = System.getenv("BUILD_NUMBER") ?: "0"获取环境变量，结果在 Windows 上BUILD_NUMBER是大写，Linux 上是小写，导致构建产物版本号随机乱跳。换成 Binary Plugin 后，用Provider<String>封装环境变量读取逻辑，一次修复，全平台生效。

所以结论很明确：

• 如果你的插件要活过三个月、服务超过一个模块、或可能被其他团队借鉴——选Build Logic Plugin；
• 如果你只是想把五段重复的copy任务抽出来，让build.gradle.kts更清爽——选Precompiled Script Plugin；
• 其他所有选项，包括.gradle脚本、buildSrc中的匿名闭包，都应视为临时方案，写完立刻标注// TODO: migrate to binary plugin。

3. 从零落地：一个可运行、可调试、可发布的完整插件工程

纸上谈兵不如真刀真枪。下面我带你从空目录开始，搭建一个真实可用的 Gradle Plugin 工程。它不是一个玩具 Demo，而是我在某图像处理 SDK 项目中实际落地的res-optimizer-plugin的精简版——功能是：自动检测res/drawable-*/下的 PNG 文件，对大于 100KB 的图片执行pngcrush压缩，并生成压缩报告。整个过程严格遵循 Gradle 最佳实践，每一步都有其不可替代的理由。

3.1 初始化工程：为什么必须用plugin-development-plugin？

不要用gradle init创建 Java Library，也不要手动建build.gradle。Gradle 官方提供了专用插件plugin-development-plugin，它会自动配置：

• 正确的 source set（src/main/kotlin对应插件逻辑，src/test/kotlin对应测试）；
• 必需的依赖（gradleApi()、kotlin-gradle）；
• 插件元信息生成（META-INF/gradle-plugins/com.example.res-optimizer.properties）；
• 发布任务（publishPlugins）。

创建build.gradle.kts：

plugins { `kotlin-dsl` // 启用 Kotlin DSL 支持 `maven-publish` // 启用发布能力 id("org.gradle.plugin.development") version "8.5"" // 关键：启用 Gradle Plugin Development 插件 id("org.gradle.plugin.development") version "8.5" } group = "com.example" version = "1.0.0" repositories { mavenCentral() } dependencies { // 插件自身需要的 API implementation(gradleApi()) // Gradle 核心 API implementation(kotlin("stdlib")) // Kotlin 标准库 implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.20") // Kotlin DSL 支持 }

注意gradleApi()—— 这不是普通依赖，而是 Gradle 运行时提供的所有类（Project,Task,Extension等）的桥接包。它不包含具体实现，只提供接口，因此你的插件能兼容多个 Gradle 版本（只要 API 兼容）。永远不要用compileOnly或api替代它，否则在低版本 Gradle 上会 ClassNotFoundError。

3.2 编写核心插件类：ResOptimizerPlugin.kt

路径：src/main/kotlin/com/example/ResOptimizerPlugin.kt

package com.example import org.gradle.api.Plugin import org.gradle.api.Project import org.gradle.api.tasks.Copy import java.io.File // 插件主类，实现 Plugin<Project> class ResOptimizerPlugin : Plugin<Project> { override fun apply(project: Project) { // 1. 创建 Extension，命名为 "resOptimizer" val extension = project.extensions.create("resOptimizer", ResOptimizerExtension::class.java, project.objects) // 2. 注册 Task，命名为 "optimizeResources" project.tasks.register("optimizeResources", OptimizeResourcesTask::class.java) { task -> // 3. 将 Extension 属性绑定到 Task 输入 task.inputDir.set(extension.inputDir) task.outputDir.set(extension.outputDir) task.maxSizeBytes.set(extension.maxSizeBytes) task.reportFile.set(extension.reportFile) } // 4. 让 optimizeResources 在 processResources 之后执行（Android 项目常用） project.afterEvaluate { project.tasks.named("processResources").configure { it.dependsOn("optimizeResources") } } } }

这里的关键设计点：

• project.extensions.create(...)是注册 Extension 的唯一正确方式，project.objects是创建Property的工厂；
• project.tasks.register(...)是创建 Task 的推荐方式（比create更安全，支持延迟配置）；
• afterEvaluate是处理“任务依赖动态绑定”的经典模式：因为processResources可能在apply时还未创建（尤其在 Android 插件中），必须等项目配置完成后再关联。

3.3 定义可配置项：ResOptimizerExtension.kt

路径：src/main/kotlin/com/example/ResOptimizerExtension.kt

package com.example import org.gradle.api.file.DirectoryProperty import org.gradle.api.model.ObjectFactory import org.gradle.api.provider.Property import javax.inject.Inject open class ResOptimizerExtension @Inject constructor( private val objects: ObjectFactory ) { // 输入目录，默认为 src/main/res val inputDir: DirectoryProperty = objects.directoryProperty() .convention(objects.layout.projectDirectory.dir("src/main/res")) // 输出目录，默认为 build/optimized-res val outputDir: DirectoryProperty = objects.directoryProperty() .convention(objects.layout.buildDirectory.dir("optimized-res")) // 最大文件大小（字节），默认 100KB val maxSizeBytes: Property<Long> = objects.property(Long::class) .convention(100 * 1024L) // 压缩报告路径 val reportFile: Property<File> = objects.property(File::class) .convention(objects.layout.buildDirectory.file("res-optimize-report.txt")) }

convention()的价值在此刻凸显：用户不配置任何东西，插件也能跑通。而DirectoryProperty和Property<File>的使用，保证了路径解析的健壮性——它会自动处理相对路径、环境变量、Gradle layout 规则，而不是简单拼字符串。

3.4 实现核心任务：OptimizeResourcesTask.kt

路径：src/main/kotlin/com/example/tasks/OptimizeResourcesTask.kt

package com.example.tasks 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 org.gradle.api.tasks.incremental.IncrementalTaskInputs import org.gradle.api.tasks.incremental.InputFileDetails import java.io.File import java.nio.file.Files import java.nio.file.Paths @CacheableTask // 启用构建缓存 abstract class OptimizeResourcesTask : DefaultTask() { // 输入目录（必须） @get:InputDirectory @get:PathSensitive(PathSensitivity.RELATIVE) abstract val inputDir: DirectoryProperty // 输出目录（必须） @get:OutputDirectory abstract val outputDir: DirectoryProperty // 最大大小（输入参数） @get:Input abstract val maxSizeBytes: Property<Long> // 报告文件（输出） @get:OutputFile abstract val reportFile: RegularFileProperty // 任务主体 @TaskAction fun execute(inputs: IncrementalTaskInputs) { val inputRoot = inputDir.get().asFile val outputRoot = outputDir.get().asFile val maxSize = maxSizeBytes.get() val report = reportFile.get().asFile // 清空输出目录 outputRoot.deleteRecursively() outputRoot.mkdirs() // 准备报告 val reportLines = mutableListOf<String>() reportLines += "=== Resource Optimization Report ===" reportLines += "Input: ${inputRoot.absolutePath}" reportLines += "Output: ${outputRoot.absolutePath}" reportLines += "Max size: ${maxSize} bytes" // 遍历所有 PNG 文件 val pngFiles = inputRoot.walkTopDown() .filter { it.isFile && it.name.endsWith(".png", ignoreCase = true) } .toList() pngFiles.forEach { file -> val relativePath = inputRoot.toRelativeString(file) val outputPath = outputRoot.resolve(relativePath) // 创建父目录 outputPath.parentFile.mkdirs() if (file.length() > maxSize) { // 执行压缩（此处简化为 copy + log，实际调用 pngcrush） Files.copy(file.toPath(), outputPath.toPath()) reportLines += "COMPRESSED: $relativePath (${file.length()} -> ${outputPath.length()})" } else { // 直接复制 Files.copy(file.toPath(), outputPath.toPath()) reportLines += "COPIED: $relativePath (${file.length()} bytes)" } } // 写入报告 report.writeText(reportLines.joinToString("\n")) logger.lifecycle("Resource optimization completed. Report: ${report.absolutePath}") } }

重点解析：

• @CacheableTask：告诉 Gradle 这个任务支持构建缓存。只要inputDir、maxSizeBytes等输入没变，下次构建直接复用输出，极大提升速度；
• @InputDirectory+@PathSensitive：精确声明输入目录的敏感性。RELATIVE表示只关心文件内容和相对路径，忽略绝对路径，这对 CI 多机构建至关重要；
• @OutputDirectory：声明输出目录，Gradle 会自动清理旧输出、校验增量；
• IncrementalTaskInputs：支持增量构建。inputs.outOfDate只返回被修改的文件，避免全量扫描；
• logger.lifecycle()：用 Gradle 日志系统输出，而非println，确保日志级别可控、格式统一。

3.5 配置插件 ID 和元信息

在src/main/resources/META-INF/gradle-plugins/com.example.res-optimizer.properties中写：

implementation-class=com.example.ResOptimizerPlugin

这个文件名com.example.res-optimizer.properties必须与你在build.gradle.kts中声明的plugins { id("com.example.res-optimizer") }完全一致。Gradle 就是靠这个路径找到你的插件主类的。

3.6 本地测试：如何在真实项目中验证插件？

别急着发版。先在本机验证。Gradle 提供了includeBuild机制，让你把插件工程当作一个“本地 Maven 仓库”。

步骤：

1. 在插件工程根目录运行./gradlew publishToMavenLocal，将插件发布到本地 Maven（~/.m2/repository）；
2. 在待测试的 Android 项目settings.gradle.kts中添加：

pluginManagement { repositories { mavenLocal() // 优先查本地 gradlePluginPortal() mavenCentral() } }

3. 在app/build.gradle.kts中应用：

plugins { id("com.example.res-optimizer") version "1.0.0" } resOptimizer { inputDir.set(layout.projectDirectory.dir("src/main/res")) outputDir.set(layout.buildDirectory.dir("optimized-res")) maxSizeBytes.set(50 * 1024L) // 50KB reportFile.set(layout.buildDirectory.file("res-optimize-report.txt")) }

4. 运行./gradlew optimizeResources，观察输出和报告。

提示：如果遇到Plugin [id: 'com.example.res-optimizer'] was not found，90% 是mavenLocal()没加对位置，或publishToMavenLocal没成功。用ls ~/.m2/repository/com/example/确认 jar 是否存在。

4. 生产级加固：测试、发布、版本兼容与常见陷阱

写完能跑的插件只是起点。一个真正可交付的生产级插件，必须经受住三重拷问：是否可测试？是否可发布？是否可演进？下面逐条拆解。

4.1 单元测试：为什么不能只靠手动验证？

很多开发者认为：“插件跑在 Gradle 里，怎么写单元测试？”答案是：Gradle 提供了TestKit，它能在内存中启动一个真实的 Gradle 运行时，模拟完整构建生命周期。这不是 mock，而是真机测试。

在src/test/kotlin/com/example/ResOptimizerPluginTest.kt中：

package com.example import org.gradle.testkit.runner.GradleRunner import org.gradle.testkit.runner.TaskOutcome import org.junit.jupiter.api.Test import org.junit.jupiter.api.io.TempDir import java.io.File import java.nio.file.Files class ResOptimizerPluginTest { @Test fun `plugin applies and runs successfully`(tempDir: @TempDir File) { // 1. 创建测试项目结构 val testProjectDir = File(tempDir, "test-project") testProjectDir.mkdirs() // build.gradle.kts Files.writeString( testProjectDir.toPath().resolve("build.gradle.kts"), """ plugins { id("com.example.res-optimizer") version "1.0.0" } resOptimizer { inputDir.set(layout.projectDirectory.dir("src/main/res")) outputDir.set(layout.buildDirectory.dir("optimized-res")) } """.trimIndent() ) // src/main/res/drawable-hdpi/test.png (10KB dummy file) val resDir = File(testProjectDir, "src/main/res/drawable-hdpi") resDir.mkdirs() Files.write(resDir.toPath().resolve("test.png"), ByteArray(10 * 1024)) // 2. 启动 GradleRunner val runner = GradleRunner.create() .withProjectDir(testProjectDir) .withPluginClasspath() // 加载当前插件的 classpath .withArguments("optimizeResources", "--stacktrace") .withDebug(true) // 3. 执行并断言 val result = runner.build() assert(result.task(":optimizeResources")?.outcome == TaskOutcome.SUCCESS) assert(File(testProjectDir, "build/optimized-res/drawable-hdpi/test.png").exists()) } }

TestKit的价值在于：

• 它验证了插件在真实 Gradle 环境中的行为，包括 Extension 绑定、Task 依赖、输入输出路径解析；
• 它能捕获GradleException、ConfigurationException等运行时错误；
• 它支持多 Gradle 版本测试（通过withGradleVersion("8.4")）。

注意：TestKit测试会下载对应 Gradle 版本的 distribution，首次运行较慢。建议在 CI 中固定 Gradle 版本，避免因网络波动失败。

4.2 发布到 Gradle Plugin Portal：不是可选项，而是信任背书

mavenLocal()只适用于本地验证。要让团队其他成员或开源社区使用，必须发布到Gradle Plugin Portal（GPP）。这是 Gradle 官方认证的插件市场，所有通过审核的插件都会获得https://plugins.gradle.org/plugin/{id}的专属页面，并支持plugins { id("...") }直接引用。

发布前准备：

• 注册 GPP 账号（用 GitHub 登录即可）；
• 在 GPP 后台申请插件 ID（如com.example.res-optimizer），获取API Key；
• 在插件工程gradle.properties中添加：

# gradle.properties gradle.publish.key=your-gpp-api-key gradle.publish.secret=your-gpp-secret

在build.gradle.kts中添加发布配置：

publishing { publications { create<MavenPublication>("pluginMaven") { from(components["java"]) groupId = "com.example" artifactId = "res-optimizer-plugin" version = "1.0.0" } } repositories { maven { url = uri("https://plugins.gradle.org/m2/") credentials { username = project.findProperty("gradle.publish.key") as String? ?: "" password = project.findProperty("gradle.publish.secret") as String? ?: "" } } } }

运行./gradlew publishPlugins，等待邮件通知审核通过（通常 1-2 个工作日）。审核通过后，任何人只需：

plugins { id("com.example.res-optimizer") version "1.0.0" }

即可使用，无需额外repositories声明——这就是 GPP 的威力：它把插件分发变成了 Gradle 的原生能力。

4.3 版本兼容性：Gradle 的 API 不是向后兼容的，但你可以做到

Gradle 官方承诺：Minor 版本（如 8.0 → 8.5）保持 API 兼容，Major 版本（7.x → 8.x）不保证。但现实更复杂：某些 API 在 8.0 标记@Incubating，到 8.4 才稳定；某些 Task 属性在 7.6 被废弃，但直到 8.2 才真正移除。

我的经验是：一个插件至少要声明支持两个 Gradle 主版本（如 7.6+ 和 8.0+），并通过gradlePlugin块显式声明：

gradlePlugin { plugins { create("resOptimizer") { id = "com.example.res-optimizer" implementationClass = "com.example.ResOptimizerPlugin" displayName = "Resource Optimizer Plugin" description = "Optimizes PNG resources in Android projects" tags = listOf("android", "resources", "optimization") } } }

更重要的是，在代码中做运行时检查：

// 在 ResOptimizerPlugin.apply() 中 if (project.gradle.gradleVersion.startsWith("7.")) { // 使用 Gradle 7.x 的 API project.tasks.named("processResources").configure { it.dependsOn("optimizeResources") } } else if (project.gradle.gradleVersion.startsWith("8.")) { // 使用 Gradle 8.x 的新 API（如 Configuration Cache 兼容） project.tasks.named("processResources").configure { it.finalizedBy("optimizeResources") } }

或者更优雅的方式：用Provider封装不同版本逻辑，让 Gradle 自动选择。

4.4 那些年踩过的坑：血泪总结的 5 条铁律

1. 永远不要在Plugin.apply()中执行耗时操作
   apply()方法在配置阶段（Configuration Phase）执行，此时所有 Task 还未创建。如果你在这里调用File.list()或网络请求，会严重拖慢./gradlew tasks等命令。所有 IO 操作必须放到@TaskAction中。

2. Property的set()和convention()不能混用

   // 错误！convention 会被 set 覆盖，且无法恢复 extension.inputDir.convention(...).set(...) // 正确：先 set，再 convention 作为 fallback extension.inputDir.set(...) // 用户显式配置 extension.inputDir.convention(...) // 用户未配置时的默认值

3. Task 输入输出必须用@Input/@Output显式声明
   否则 Gradle 无法判断哪些文件变化需要重新执行任务，导致增量构建失效。我曾因漏标@Input，导致 PNG 文件修改后optimizeResources任务被跳过，线上包体积暴增。

4. 不要在 Plugin 中硬编码路径分隔符
   File.separator或Paths.get("a", "b")是唯一安全方式。"src/main/res"在 Windows 上会变成src\main\res，导致路径解析失败。

5. buildSrc不是插件的替代品，而是插件的孵化器
   我的习惯是：所有新构建逻辑先在buildSrc中快速验证，跑通后再迁移到独立插件工程。buildSrc是你的沙盒，插件工程是你的产品。

5. 进阶思考：当插件遇上构建缓存、Configuration Cache 与 Kotlin DSL

一个插件写完能跑，只是及格线。要让它真正融入现代 Gradle 工程，还需跨越三道高墙：构建缓存（Build Cache）、配置缓存（Configuration Cache）和Kotlin DSL 的深度集成。这三者不是锦上添花，而是决定插件能否在大型项目中存活的关键。

5.1 构建缓存：让 CI 构建速度提升 300% 的秘密武器

构建缓存的核心思想是：如果两个构建的输入完全相同，那么它们的输出也必然相同，因此可以直接复用。Gradle 默认开启本地构建缓存，而远程缓存（如 Gradle Enterprise）能让整个团队共享缓存。

要让你的插件支持构建缓存，只需两步：

1. 在 Task 类上加@CacheableTask；
2. 确保所有@Input和@Output声明完整、准确。

但陷阱在于：某些看似无害的操作会破坏缓存命中率。例如：

// 危险！System.currentTimeMillis() 每次都不同，导致缓存失效 @Input val timestamp: Long = System.currentTimeMillis() // 危险！File.lastModified() 返回毫秒级时间戳，不同机器、不同构建时间不同 @Input val lastModified: Long = file.lastModified()

正确做法是：

• 用@Input声明确定性输入（如文件内容哈希、配置参数）；
• 用@Internal标记非确定性值（如时间戳、随机数）；
• 对于文件时间戳，改用@InputFile+@PathSensitive(PathSensitivity.NONE)，让 Gradle 只比较文件内容。

我在某电商 App 项目中启用构建缓存后，CI 的assembleRelease时间从 12 分钟降到 3 分半，其中optimizeResources任务的缓存命中率高达 92%——因为 PNG 资源很少改动，而插件完美支持缓存。

5.2 配置缓存：Gradle 7.0+ 的终极性能优化，但也是最大雷区

配置缓存的目标是：将 Gradle 的配置阶段（Configuration Phase）的结果序列化并复用，避免每次构建都重新解析build.gradle。它能让./gradlew build的总时间减少 20%-40%，尤其对大型多模块项目效果显著。

但启用配置缓存（--configuration-cache）后，你的插件会面临严苛审查：

• 所有Plugin、Extension、Task类必须是public且可序列化；
• 不能访问Project的project.rootDir等非序列化属性；
• 不能在apply()中调用project.tasks.create()（必须用register()）；
• Extension的Property必须用ObjectFactory创建，不能new。

Gradle 会自动检测违规，并给出精准错误定位。例如：

Configuration cache problems found in this build. - Task `:app:optimizeResources` of type `com.example.tasks.OptimizeResourcesTask`: - Field `inputDir` of type `org.gradle.api.file.DirectoryProperty` is not serializable.

解决方案：确保DirectoryProperty是通过objects.directoryProperty()创建的，而非new DirectoryProperty()。

提示：在插件工程的gradle.properties中添加org.gradle.configuration-cache=true，让 Gradle 在每次构建时自动验证配置缓存兼容性。这是上线前的必做检查。

5.3 Kotlin DSL 的深度集成：不只是语法糖，而是类型安全革命

Groovy DSL 的ext机制是弱类型的，而 Kotlin DSL 通过Extension的@DslMarker和Property的泛型，实现了真正的类型安全。例如：