buildSrc 体系与 Convention Plugin：构建逻辑复用与模块化管理

buildSrc 曾经是 Gradle 复用构建逻辑的默认答案，但在大型 Android 工程里，更推荐把构建约定放进独立的 included build，例如 build-logic。

原因不是 buildSrc 不能用，而是它太“自动”：只要根目录存在 buildSrc，Gradle 就会把它当作特殊构建先编译，并把产物加入所有构建脚本 classpath。小项目很方便，大项目会让构建逻辑变成隐式全局依赖。

Convention Plugin 的目标是把重复配置变成可命名、可测试、可组合的构建能力。模块不再复制 android {}、kotlin {}、dependencies {}，而是应用符合自身类型的插件。

buildSrc 的工作机制

目录结构：

buildSrc/
├── build.gradle.kts
└── src/main/kotlin/
    └── AndroidLibraryConventionPlugin.kt

Gradle 会在主构建之前先构建 buildSrc：

settings.gradle.kts
  |
  |-- detect buildSrc
  |-- compile buildSrc
  |-- put buildSrc outputs on buildscript classpath
  v
evaluate main build scripts

这让你可以在主构建中直接使用 buildSrc 里的类。但代价是，buildSrc 对整个构建是一个宽泛输入。里面的实现变化可能导致大量脚本 classpath 失效。

included build 的边界更清晰

更推荐的结构：

.
├── settings.gradle.kts
├── build-logic/
│   ├── settings.gradle.kts
│   ├── build.gradle.kts
│   └── src/main/kotlin/
│       ├── zerobug.android.library.gradle.kts
│       └── zerobug.android.application.gradle.kts
└── feature/article/build.gradle.kts

根 settings.gradle.kts：

pluginManagement {
    includeBuild("build-logic")
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

build-logic/build.gradle.kts：

plugins {
    `kotlin-dsl`
}

repositories {
    google()
    mavenCentral()
    gradlePluginPortal()
}

业务模块：

plugins {
    id("zerobug.android.library")
}

included build 的优势是显式：它是一个普通 Gradle 构建，可以独立测试、独立依赖管理，也不会像 buildSrc 那样带着特殊规则混在主构建里。

Precompiled Script Plugin 的命名规则

预编译脚本插件的 ID 来自文件名和包名：

src/main/kotlin/zerobug.android.library.gradle.kts
  -> plugin id: zerobug.android.library

如果文件带 .settings.gradle.kts 后缀，它就是 Settings 插件，只能应用在 settings.gradle.kts 的 plugins 块中。

这套规则让 convention plugin 非常适合表达工程约定：

// zerobug.android.library.gradle.kts
plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

android {
    compileSdk = 36

    defaultConfig {
        minSdk = 26
    }
}

注意：预编译脚本插件的 plugins {} 块中不能像业务脚本那样使用 version "..." apply false 管插件版本。外部插件版本应在 build-logic 自己的构建文件或 plugin management 中声明。

Catalog 在 build-logic 中的使用边界

很多工程迁移时会遇到：业务模块能用 libs.xxx，但 build-logic 里的 Kotlin 源码不能直接用。

原因是 Version Catalog 类型安全访问器是某个构建的输入，不是天然跨构建共享的全局对象。build-logic 作为 included build，有自己的 settings、自己的依赖解析和自己的脚本编译。

可选策略：

• 在 build-logic/settings.gradle.kts 中导入同一份 catalog。
• 在预编译脚本插件里使用 libs 访问构建脚本依赖。
• 在二进制插件 Kotlin 代码里用常量、插件扩展或自定义版本模型传递。

不要为了方便，在各处复制版本字符串。那会让 build-logic 变成第二套依赖声明中心。

Convention Plugin 的职责划分

一个健康的 convention plugin 不追求“大而全”，而是让模块按能力组合：

plugins {
    id("zerobug.android.library")
    id("zerobug.android.hilt")
    id("zerobug.android.room")
}

这种组合比一个 zerobug.android.all 更稳定。模块使用了 Room 才引入 Room 编译器，使用了 Hilt 才接入 Hilt 插件，不让所有模块承担同一套构建成本。

什么时候保留 buildSrc

buildSrc 仍然可以用于：

• 小型项目的少量构建辅助类。
• 临时迁移阶段。
• 不值得单独建 included build 的实验逻辑。

但只要构建逻辑开始承载 Android/Kotlin 多模块约定、插件组合、测试工具、发布逻辑，就应该迁到 build-logic。这不是形式主义，而是为了让构建逻辑拥有正常模块边界。

工程风险与观测清单

buildSrc 体系与 Convention Plugin：构建逻辑复用与模块化管理 一旦进入真实 Android 工程，最大的风险不是单个 API 写错，而是构建行为失去可解释性：一次小改动触发大面积重编译，CI 偶发超时，缓存命中却产物不可信，或者发布后才发现某条 variant 管线没有被覆盖。

因此，学习这个主题时要同时建立两套模型：一套解释底层机制，一套解释工程风险、观测信号、回滚策略和审计边界。前者让你知道系统为什么这样运行，后者让你在生产环境里能证明它确实按预期运行。

关键风险矩阵

需要持续观测的指标

• 配置阶段耗时是否随模块数量线性或超线性增长。
• 单次本地 debug 构建的关键路径任务是谁。
• CI clean build 与 incremental build 的耗时差距。
• 远程 Build Cache 的 hit rate、miss 原因和下载耗时。
• Configuration Cache 的命中率和失效原因。
• Kotlin/Java 编译任务是否被不相关资源或依赖变化触发。
• 资源合并、DEX、R8、打包任务是否在小改动后全量重跑。
• 自定义插件是否提前实现了无关任务。
• 构建日志中是否出现未声明输入、重叠输出、deprecated API。
• 发布产物是否能追溯到唯一的源码提交、依赖锁和构建扫描。
• 失败是否可稳定复现，还是只在特定机器、特定并发下出现。
• 变更是否影响开发构建、测试构建和发布构建三条路径。

回滚与降级策略

• 构建逻辑变更与业务代码变更分开提交，便于二分定位。
• Gradle、AGP、Kotlin、JDK 升级必须保留兼容矩阵和回滚版本。
• 新插件能力先只接入一个低风险模块，再扩大到全工程。
• 远程缓存先 pull 后 push，确认产物稳定后再允许 CI 写入。
• 新增插桩、生成代码、资源处理逻辑必须提供开关。
• 发布构建失败时，优先回滚构建逻辑版本，而不是清空所有缓存碰运气。
• 对 CI 超时设置分阶段日志，确认卡在配置、依赖解析还是任务执行。
• 对不可恢复的构建产物变更记录迁移步骤，避免开发者本地状态残留。

最小验证矩阵

审计问题

1. 这段构建逻辑是否有明确所有者，还是散落在多个模块脚本里。
2. 它是否读取了没有声明为输入的文件、环境变量或系统属性。
3. 它是否在配置阶段执行了本应放到任务动作里的工作。
4. 它是否对所有 variant 生效，还是只应该对某些 variant 生效。
5. 它是否可以在没有网络、没有本地 IDE 状态的 CI 中运行。
6. 它是否把权限、密钥、签名文件路径写进了仓库。
7. 它是否破坏了并发执行，例如多个任务写同一个目录。
8. 它是否能在失败时输出足够日志，帮助定位根因。
9. 它是否能通过一个开关降级，避免阻塞全工程构建。
10. 它是否有最小复现样例或 TestKit/集成测试覆盖。
11. 它是否会让下游模块承担不必要的依赖或任务成本。
12. 它是否能在升级 Gradle/AGP 后继续工作，还是依赖内部 API。

反模式清单

• 用 clean 掩盖输入输出声明错误。
• 用 afterEvaluate 修补本可以用 Provider 表达的依赖关系。
• 用动态版本解决依赖冲突，却让构建不可复现。
• 把所有公共配置塞进一个巨型 convention plugin。
• 在 debug 构建默认开启 release 级别的重型优化。
• 在任务动作里读取 project 或全局 configuration。
• 在多个任务中共享同一个临时目录。
• 缓存命中率异常时只重启 CI，不分析 miss reason。
• 把构建扫描链接当作可选附件，而不是性能回归证据。
• 用本地 IDE 成功运行证明 CI 发布链路安全。

最小实操脚本

./gradlew help --scan
./gradlew :app:assembleDebug --scan --info
./gradlew :app:assembleDebug --build-cache --info
./gradlew :app:assembleDebug --configuration-cache
./gradlew :app:dependencies --configuration debugRuntimeClasspath
./gradlew :app:dependencyInsight --dependency <module> --configuration debugRuntimeClasspath

这组命令覆盖配置期、执行期、缓存、配置缓存和依赖解析五条主线。任何 buildSrc 体系与 Convention Plugin：构建逻辑复用与模块化管理 相关的改动，都应该能用其中至少一条命令解释它带来的行为变化。

延伸阅读

• Gradle Pre-compiled Script Plugins
• Gradle Plugin Implementation Options
• Gradle Composite Builds