mcpField
A
android-gradle-logic

android-gradle-logic

github.com/rcosteira79开发172159 次安装7 周前更新
代码仓库

关于 android-gradle-logic

面向 Android 团队的 Gradle 构建逻辑参考，介绍如何在复合构建中用约定插件复用配置。内容涵盖版本目录接线、共享配置及 AGP 9 所需调整。

主要功能

  1. 01在 build-logic 中使用约定插件
  2. 02设置版本目录
  3. 03匹配插件别名与 ID
  4. 04共享 Android 和 JVM 配置
  5. 05AGP 9 迁移注意事项

适用场景

  1. 01集中管理各 Android 模块的配置
  2. 02解决 build-logic 中 libs 引用缺失
  3. 03为 AGP 9 更新约定插件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rcosteira79/android-skills --skill android-gradle-logic

安装后在 Claude Code 中输入/android-gradle-logic确认已加载。

详细介绍

Android Gradle 构建逻辑

在 build-logic/ 组合构建中，通过可复用的 约定插件 集中管理构建配置，这样每个模块的 build.gradle.kts 就能精简为 plugins { alias(libs.plugins.myapp.android.library) }，再加上一个 namespace。

典型示例是 nowinandroid 的 build-logic/——从它入手，而不是从头手动编写。本指南涵盖容易出错的接线细节，以及 AGP 9 的变化。

接线时容易忽略的问题

build-logic 不会继承根目录的版本目录——需要重新创建。 组合构建有自己的 settings.gradle.kts；在声明版本目录之前，根目录的 libs 在 build-logic 中不可见。否则，约定插件无法引用 libs.*，并会因 Unresolved reference: libs 而编译失败：

// build-logic/settings.gradle.kts
dependencyResolutionManagement {
    versionCatalogs {
        create("libs") { from(files("../gradle/libs.versions.toml")) }
    }
}

从目录中应用插件

在 [plugins] 中声明约定插件的 id，以便模块通过别名应用它们。id 必须与在 build-logic 中通过 register(...) 注册的 id 相同——别名无法解析，通常就是因为两者不匹配：

# gradle/libs.versions.toml
[plugins]
myapp-android-application = { id = "myapp.android.application" }
myapp-android-library     = { id = "myapp.android.library" }
myapp-android-compose     = { id = "myapp.android.compose" }

本地注册的插件不需要版本——包含的构建会提供该插件，因此别名无论目录中是否声明版本，都能解析。nowinandroid 会显式写上 version = "unspecified"，这样做没问题，也有助于自我说明，但并非必需。

在约定插件中一次性设置共享配置——compileSdk / minSdk / Compose / JVM 工具链，而不是在每个模块中分别设置。对于 Kotlin Android 模块，kotlin { jvmToolchain(21) } 是惯用的简洁写法，并会为 Kotlin 和 Java 编译设置工具链：

kotlin { jvmToolchain(21) }

AGP 9 的影响

上述约定插件模式面向 AGP 8。AGP 9 的多项变更会直接影响构建逻辑：移除独立的 org.jetbrains.kotlin.android 插件（Kotlin 已内置于 com.android.application / com.android.library），移除 BaseExtension 和旧版变体 API（applicationVariants → androidComponents { onVariants { … } }），将 kotlinOptions {} 移至顶层的 kotlin { compilerOptions { … } }，并使 kapt 不再兼容（迁移到 KSP）。任何涉及这些内容的约定插件都需要更新。

有关具体操作，请参考专门的迁移指南，而不是在此重复步骤：纯 Android 项目请参考 Google 的 agp-9-upgrade，KMP 请参考 JetBrains 的 kotlin-tooling-agp9-migration，而 kapt → KSP 迁移步骤请参考本仓库的 gradle-build-performance 技能。

检查清单

  • 在根目录的 settings.gradle.kts 中将 build-logic 包含为组合构建（includeBuild("build-logic")）
  • build-logic/settings.gradle.kts 通过 from(files("../gradle/libs.versions.toml")) 重新创建 libs 目录
  • 使用稳定的 id 注册约定插件，并确保 [plugins] 别名 id 与其完全一致
  • 在插件中一次性设置 compileSdk / minSdk / Compose / JVM 工具链，而不是在每个模块中设置

评论

支持 Markdown