build-logic是Gradle 8.0+推荐的buildSrc替代方案，为独立、可缓存、可测试、可发布的插件工程，解决buildSrc污染构建缓存、同步慢、IDE卡顿等固有缺陷。
build-logic 是什么，为什么不用 buildSrc
build-logic 是 Gradle 8.0+ 推荐的替代 buildSrc 的复合构建方案，它把构建逻辑（插件、任务、依赖版本）抽成独立的、可缓存、可测试、可发布的小型 Gradle 项目。相比 buildSrc，它不会污染主项目构建缓存，修改后只重建自身，不触发整个项目重同步。
如果你还在用 buildSrc，尤其在大型多模块工程中频繁改构建逻辑，会明显感知到 Gradle 同步变慢、缓存失效、IDE 卡顿——这些不是错觉，是 buildSrc 的固有限制。
怎么创建和配置 build-logic 模块
在项目根目录下新建 build-logic 目录，并按标准 Gradle 插件结构组织：
build-logic/
├── settings.gradle.kts
├── build.gradle.kts
└── src/
└── main/
└── kotlin/
└── com/example/gradle/
├── AndroidApplicationConventionPlugin.kt
└── JavaLibraryConventionPlugin.kt
settings.gradle.kts 必须启用预览特性并声明为插件构建：
enableFeaturePreview("VERSION_CATALOGS")
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
pluginManagement {
repositories {
gradlePluginPortal()
google()
mavenCentral()
}
}
build.gradle.kts 中声明插件开发依赖：
plugins {
`kotlin-dsl`
}
repositories {
gradlePluginPortal()
google()
mavenCentral()
}
dependencies {
implementation(gradleApi())
implementation(kotlin("stdlib"))
implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.24")
}
如何在子模块中应用 convention 插件
写好一个 JavaLibraryConventionPlugin 后，需要在子模块的 build.gradle.kts 中启用它。关键点有三个：
- 必须在
plugins块顶部用alias或id引入，不能放在dependencies里 - 插件 ID 默认是
com.example.gradle.java-library（由包名 + 文件名推导），不是文件路径 - 如果插件定义了
configureEach，它会在所有匹配模块上自动生效，无需每个模块手动 apply
示例（子模块 app/build.gradle.kts）：
plugins {
alias(libs.plugins.com.example.gradle.android.application) // 来自 version catalog
}
android {
namespace = "com.example.app"
compileSdk = 34
}
注意：libs.plugins.com.example.gradle.android.application 这个别名需提前在 gradle/libs.version.toml 中声明，否则会报 Unknown plugin: 'libs.plugins.com.example.gradle.android.application' 错误。
常见错误和兼容性坑点
实际落地时最容易卡住的地方集中在三类：
-
Could not resolve plugin：没在settings.gradle.kts的pluginManagement.repositories里加gradlePluginPortal()，或插件未正确发布到本地 Maven（build-logic本身要先./gradlew publishToMavenLocal） -
Unresolved reference: android：插件代码里用了android {}但没声明com.android.tools.build:gradle依赖，或版本与主项目不匹配（比如主项目用 AGP 8.4，插件却依赖 8.2） -
Cannot access 'xxx' which is a module-private declaration：Kotlin 插件类用了internal修饰符，导致外部模块不可见；一律改用public或删掉修饰符 - Android 模块中
android {}块不生效：Convention 插件必须在plugins块中 apply，且不能晚于com.android.application——顺序错了就等于没配
build-logic 的真正复杂点不在写法，而在“边界感”：它和主项目之间是松耦合的构建时依赖，不是运行时依赖。任何想从插件里读取子模块源码、调用业务类、或动态生成 Java 类的行为，都会越界失败。
