Build on zed的博客

Gradle Convention Plugins：多模块构建逻辑组织

Fri, 24 Oct 2025 03:52:15 +0800

多模块 Android 项目如果每个模块都手写一遍插件、Android 配置、Kotlin 配置、Compose 配置和通用依赖，构建脚本很快会失控。Convention Plugins 的价值就是把这些重复配置收敛到 build-logic 中，让业务模块只声明“我是什么类型的模块”。

核心结论

Convention Plugin 是项目内部的 Gradle 插件，用来封装约定配置。
它适合管理多模块项目的 Android、Kotlin、Compose、Hilt、测试等重复配置。
业务模块的 build.gradle.kts 应该尽量薄，只表达模块身份和少量特有依赖。
build-logic 本身也要保持边界清晰，避免变成新的复杂中心。

核心思想

Convention Plugins是一种通过预配置的Gradle插件来标准化和复用构建逻辑的方法，核心理念是：

约定优于配置（Convention over Configuration）
DRY原则（Don’t Repeat Yourself）
构建逻辑集中管理
类型安全的配置

典型项目结构

project/
├── build-logic/ # 构建逻辑模块
│ ├── settings.gradle.kts
│ └── convention/ # 约定插件模块
│ ├── build.gradle.kts
│ └── src/main/kotlin/
│ ├── AndroidApplicationConventionPlugin.kt
│ ├── AndroidLibraryConventionPlugin.kt
│ ├── AndroidFeatureConventionPlugin.kt
│ └── KotlinLibraryConventionPlugin.kt
├── settings.gradle.kts
├── app/
├── feature/
│ ├── feature-foryou/
│ └── feature-bookmarks/
└── core/
├── core-ui/
└── core-data/

解决的问题

如果不使用Convention Plugins会怎么样，项目中有10个feature模块（比如:feature:foryou,:feature:bookmarks,feature:settings等）。在传统的做法中，每个模块的build.gradle.kts文件都会包含大量相似的配置：

// 在 :feature:foryou/build.gradle.kts 文件中
plugins {
 id("com.android.library")
 id("kotlin-android")
 id("dagger.hilt.android.plugin")
 // ...可能还有其他插件
}

android {
 // ...大量通用的安卓配置
}

dependencies {
 implementation(project(":core:designsystem"))
 implementation(project(":core:ui"))
 implementation("androidx.lifecycle:lifecycle-viewmodel-compose:...")
 // ...可能还有10个以上所有feature模块都需要的通用依赖
}

现在，如果你需要为所有feature模块添加一个新的通用依赖库，或者修改一个通用的编译选项，你就必须手动去修改10个不同的build.gradle.kts文件。这不仅繁琐，而且极易出错，非常难以维护。

实现方式

1. 设置build-logic模块

build-logic/settings.gradle.kts

pluginManagement {
 repositories {
 gradlePluginPortal()
 google()
 }
}

dependencyResolutionManagement {
 repositories {
 google {
 content {
 includeGroupByRegex("com\\.android.*")
 includeGroupByRegex("com\\.google.*")
 includeGroupByRegex("androidx.*")
 }
 }
 mavenCentral()
 }
 versionCatalogs {
 create("libs") {
 from(files("../gradle/libs.versions.toml"))
 }
 }
}

rootProject.name = "build-logic"
include(":convention")

build-logic/convention/build.gradle.kts

plugins {
 `kotlin-dsl`
}

dependencies {
 compileOnly(libs.android.gradlePlugin)
 compileOnly(libs.kotlin.gradlePlugin)
 compileOnly(libs.ksp.gradlePlugin)
}

gradlePlugin {
 plugins {
 register("androidApplicationCompose") {
 id = libs.plugins.nowinandroid.android.application.compose.get().pluginId
 implementationClass = "AndroidApplicationComposeConventionPlugin"
 }
 register("androidApplication") {
 id = libs.plugins.nowinandroid.android.application.asProvider().get().pluginId
 implementationClass = "AndroidApplicationConventionPlugin"
 }
 register("androidLibraryCompose") {
 id = libs.plugins.nowinandroid.android.library.compose.get().pluginId
 implementationClass = "AndroidLibraryComposeConventionPlugin"
 }
 register("androidLibrary") {
 id = libs.plugins.nowinandroid.android.library.asProvider().get().pluginId
 implementationClass = "AndroidLibraryConventionPlugin"
 }
 register("androidFeature") {
 id = libs.plugins.nowinandroid.android.feature.get().pluginId
 implementationClass = "AndroidFeatureConventionPlugin"
 }
 }
}

2. 创建约定插件

AndroidApplicationConventionPlugin.kt

class AndroidApplicationConventionPlugin : Plugin<Project> {
 override fun apply(target: Project) {
 with(target) {
 apply(plugin = "com.android.application")
 apply(plugin = "org.jetbrains.kotlin.android")
 apply(plugin = "nowinandroid.android.lint")
 apply(plugin = "com.dropbox.dependency-guard")

 extensions.configure<ApplicationExtension> {
 configureKotlinAndroid(this)
 defaultConfig.targetSdk = 35
 @Suppress("UnstableApiUsage")
 testOptions.animationsDisabled = true
 configureGradleManagedDevices(this)
 }
 extensions.configure<ApplicationAndroidComponentsExtension> {
 configurePrintApksTask(this)
 configureBadgingTasks(extensions.getByType<ApplicationExtension>(), this)
 }
 }
 }
}

AndroidApplicationComposeConventionPlugin.kt

class AndroidApplicationComposeConventionPlugin : Plugin<Project> {
 override fun apply(target: Project) {
 with(target) {
 apply(plugin = "com.android.application")
 apply(plugin = "org.jetbrains.kotlin.plugin.compose")

 val extension = extensions.getByType<ApplicationExtension>()
 configureAndroidCompose(extension)
 }
 }

}

AndroidLibraryComposeConventionPlugin.kt

class AndroidLibraryComposeConventionPlugin : Plugin<Project> {
 override fun apply(target: Project) {
 with(target) {
 apply(plugin = "com.android.library")
 apply(plugin = "org.jetbrains.kotlin.plugin.compose")

 val extension = extensions.getByType<LibraryExtension>()
 configureAndroidCompose(extension)
 }
 }

}

AndroidLibraryConventionPlugin.kt

class AndroidLibraryConventionPlugin : Plugin<Project> {
 override fun apply(target: Project) {
 with(target) {
 apply(plugin = "com.android.library")
 apply(plugin = "org.jetbrains.kotlin.android")
 apply(plugin = "nowinandroid.android.lint")

 extensions.configure<LibraryExtension> {
 configureKotlinAndroid(this)
 testOptions.targetSdk = 35
 lint.targetSdk = 35
 defaultConfig.testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
 testOptions.animationsDisabled = true
 configureFlavors(this)
 configureGradleManagedDevices(this)
 // The resource prefix is derived from the module name,
 // so resources inside ":core:module1" must be prefixed with "core_module1_"
 resourcePrefix =
 path.split("""\W""".toRegex()).drop(1).distinct().joinToString(separator = "_")
 .lowercase() + "_"
 }
 extensions.configure<LibraryAndroidComponentsExtension> {
 configurePrintApksTask(this)
 disableUnnecessaryAndroidTests(target)
 }
 dependencies {
 "androidTestImplementation"(libs.findLibrary("kotlin.test").get())
 "testImplementation"(libs.findLibrary("kotlin.test").get())

 "implementation"(libs.findLibrary("androidx.tracing.ktx").get())
 }
 }
 }
}

AndroidFeatureConvention.kt

class AndroidFeatureConventionPlugin : Plugin<Project> {
 override fun apply(target: Project) {
 with(target) {
 apply(plugin = "nowinandroid.android.library")
 apply(plugin = "nowinandroid.hilt")
 apply(plugin = "org.jetbrains.kotlin.plugin.serialization")

 extensions.configure<LibraryExtension> {
 testOptions.animationsDisabled = true
 configureGradleManagedDevices(this)
 }

 dependencies {
 "implementation"(project(":core:ui"))
 "implementation"(project(":core:designsystem"))

 "implementation"(libs.findLibrary("androidx.hilt.navigation.compose").get())
 "implementation"(libs.findLibrary("androidx.lifecycle.runtimeCompose").get())
 "implementation"(libs.findLibrary("androidx.lifecycle.viewModelCompose").get())
 "implementation"(libs.findLibrary("androidx.navigation.compose").get())
 "implementation"(libs.findLibrary("androidx.tracing.ktx").get())
 "implementation"(libs.findLibrary("kotlinx.serialization.json").get())

 "testImplementation"(libs.findLibrary("androidx.navigation.testing").get())
 "androidTestImplementation"(
 libs.findLibrary("androidx.lifecycle.runtimeTesting").get(),
 )
 }
 }
 }
}

3. 核心方法：`apply`

当你将这个插件引用到一个模块时（例如，在:feature:foryou中应用它），Gradle就会执行这个插件类中的apply方法。逐行分析这个方法做了什么：

// 在 AndroidFeatureConventionPlugin.kt 中

class AndroidFeatureConventionPlugin : Plugin<Project> {
 override fun apply(target: Project) { // 'target' 就是应用这个插件的模块, 比如 :feature:foryou
 with(target) {
 // --- 动作一：应用其他更基础的约定插件 ---
 // 这行代码在说：“一个 `feature` 模块，首先它是一个 `library` 模块，
 // 并且它也需要 Hilt 依赖注入和序列化功能。”
 // 这体现了插件的组合能力。
 apply(plugin = "nowinandroid.android.library")
 apply(plugin = "nowinandroid.hilt")
 apply(plugin = "org.jetbrains.kotlin.plugin.serialization")

 // --- 动作二：配置通用的 Android 属性 ---
 // 这里统一为所有 feature 模块配置 'android' 代码块。
 // 比如，统一关闭测试中的动画，统一配置测试设备。
 extensions.configure<LibraryExtension> {
 testOptions.animationsDisabled = true
 configureGradleManagedDevices(this)
 }

 // --- 动作三：添加所有 feature 模块都需要的通用依赖 ---
 // 这是最强大的部分。它声明了“每一个” feature 模块都会自动获得这些依赖。
 // 无需在各自的 build.gradle.kts 中重复添加。
 dependencies {
 "implementation"(project(":core:ui"))
 "implementation"(project(":core:designsystem"))

 "implementation"(libs.findLibrary("androidx.hilt.navigation.compose").get())
 "implementation"(libs.findLibrary("androidx.lifecycle.viewModelCompose").get())
 // ... 以及其他所有通用依赖
 }
 }
 }
}

4. 共享配置函数

KotlinAndroid.kt

import com.android.build.api.dsl.CommonExtension
import org.gradle.api.JavaVersion
import org.gradle.api.Project
import org.gradle.kotlin.dsl.dependencies
import org.gradle.kotlin.dsl.withType
import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

internal fun Project.configureKotlinAndroid(
 commonExtension: CommonExtension<*, *, *, *, *, *>,
) {
 commonExtension.apply {
 compileSdk = 34

 defaultConfig {
 minSdk = 24
 }

 compileOptions {
 sourceCompatibility = JavaVersion.VERSION_17
 targetCompatibility = JavaVersion.VERSION_17
 }
 }

 configureKotlin()
}

private fun Project.configureKotlin() {
 tasks.withType<KotlinCompile>().configureEach {
 kotlinOptions {
 jvmTarget = JavaVersion.VERSION_17.toString()

 freeCompilerArgs = freeCompilerArgs + listOf(
 "-opt-in=kotlin.RequiresOptIn",
 "-opt-in=kotlinx.coroutines.ExperimentalCoroutinesApi",
 )
 }
 }
}

5. 在根项目中引入

settings.gradle.kts

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

6. 在模块中引入

app/build.gradle.kts

plugins {
 id("myapp.android.application")
 id("myapp.android.application.compose")
}

android {
 namespace = "com.example.myapp"

 // 只需配置特定于此模块的内容
 defaultConfig {
 applicationId = "com.example.myapp"
 }
}

dependencies {
 implementation(project(":feature:home"))
 implementation(project(":feature:profile"))
}

feature/feature-home/build.gradle.kts

plugins {
 id("myapp.android.feature")
}

android {
 namespace = "com.example.myapp.feature.home"
}

dependencies {
 // Feature 特定的依赖
}

Convention Plugin的优势

DRY (Don’t Repeat Yourself) 原则：消除了在几十个文件中复制粘贴的构建逻辑。
单一事实来源 (Single Source of Truth)：如果需要更新一个所有 feature 模块都在用的库版本（比如 Lifecycle），你只需要在 AndroidFeatureConventionPlugin.kt 这一个文件里修改即可。
简洁与清晰：每个模块的构建脚本变得非常短，只包含对该模块独一无二的配置，可读性大大提高。
类型安全与 IDE 支持：因为这些插件是用 Kotlin 编写的，你可以享受到 IDE 的自动补全、编译时类型检查和方便的导航跳转，这比传统的 Groovy 脚本要强大得多。

这些都是now-in-android所应用的，更详细的可以通过此项目学习

Android Gradle 基础：插件、依赖和版本目录

Sun, 29 Jun 2025 15:26:57 +0800

Gradle 配置最容易混乱的地方，是把“构建时用的东西”和“运行时用的东西”混在一起。理解插件、依赖配置和版本目录之后，很多报错会变得容易定位。

核心结论

插件改变构建过程，例如 Android 插件会添加编译、打包、签名等任务。
库参与代码编译或运行，例如 Retrofit、Room、JUnit。
implementation 默认优先使用，api 只在需要暴露依赖给下游模块时使用。
classpath 是旧式 buildscript 插件依赖，和业务代码依赖不是一回事。
Version Catalog 负责集中管理版本，适合多模块项目。

插件和库的区别

维度	插件	库
本质	构建逻辑扩展	可被代码调用的依赖
作用	添加任务、扩展 DSL、改变构建流程	提供 API、运行时代码或测试能力
声明位置	`plugins {}`	`dependencies {}`
影响阶段	配置期和构建期	编译期、运行期或测试期
示例	`com.android.application`、`org.jetbrains.kotlin.android`	Retrofit、Gson、JUnit

插件示例：

plugins {
 id("com.android.application")
 id("org.jetbrains.kotlin.android")
}

依赖示例：

dependencies {
 implementation("androidx.core:core-ktx:1.12.0")
 testImplementation("junit:junit:4.13.2")
}

implementation

implementation 是最常用的依赖配置。

特点：

当前模块可以使用该依赖；
下游模块不会直接看到该依赖；
有利于减少不必要的重编译；
适合绝大多数业务依赖。

dependencies {
 implementation("com.squareup.retrofit2:retrofit:2.9.0")
}

如果 feature-a 依赖 core-network，而 core-network 使用 implementation 引入 Retrofit，那么 feature-a 不应该直接使用 Retrofit 类型。

api

api 会把依赖暴露给下游模块。

适合场景：

当前模块的公开接口里出现了该依赖的类型；
SDK 或公共基础库需要让使用方感知这个依赖；
你明确希望依赖传递。

dependencies {
 api("com.google.dagger:dagger:2.48")
}

使用原则：

能用 implementation 就不要用 api，只有当公开 API 真的需要暴露依赖类型时再使用 api。

classpath

classpath 常见于旧式 Gradle 配置：

buildscript {
 dependencies {
 classpath("com.android.tools.build:gradle:8.1.0")
 }
}

它的作用是让 Gradle 构建脚本能加载插件。它不参与 App 业务代码编译，也不会进入 APK。

现代项目更推荐使用 plugins {} 和 pluginManagement 管理插件版本。

Version Catalog

Version Catalog 通常位于：

gradle/libs.versions.toml

它解决的问题是：多模块项目里依赖版本分散、重复、难统一。

示例：

[versions]
androidxCore = "1.12.0"

[libraries]
androidx-core-ktx = {
 group = "androidx.core",
 name = "core-ktx",
 version.ref = "androidxCore"
}

[plugins]
android-application = {
 id = "com.android.application",
 version = "8.1.0"
}

使用方式：

dependencies {
 implementation(libs.androidx.core.ktx)
}

排错思路

遇到 Gradle 依赖问题时，先问几个问题：

报错发生在配置期、编译期、运行期还是测试期？
这个东西是插件还是库？
当前模块是否真的需要直接访问该依赖？
是否因为用了 implementation，下游模块访问不到类型？
是否因为用了过宽的 api，导致构建变慢和依赖污染？

回看清单

插件扩展构建流程，库提供代码能力。
implementation 隐藏依赖，api 暴露依赖。
classpath 是给 Gradle 构建脚本加载插件用的。
Version Catalog 解决多模块依赖版本集中管理。
构建问题先判断发生阶段，再看依赖边界。

Android APK 打包流程：从源码到可安装文件

Sat, 28 Jun 2025 12:15:42 +0800

Android 打包流程的本质，是把源码、资源、Manifest、依赖和原生库转换成系统可以安装和加载的产物。日常点击 “Run” 很简单，但理解构建链路能帮助定位资源冲突、依赖问题、签名问题和包体积问题。

核心结论

资源先经过 AAPT2 编译和链接，生成 R、resources.arsc 和二进制资源。
Kotlin/Java 源码先编译成 JVM 字节码，再由 D8/R8 转成 Dex。
Manifest 会合并主工程、依赖库和变体配置。
Release 包需要签名和 zipalign，签名保证来源可信，zipalign 优化运行时读取。
AAB 是上传给应用商店的发布格式，最终安装到设备上的仍是按设备拆分后的 APK。

总体流程

Kotlin / Java 源码
 -> kotlinc / javac
 -> .class
 -> D8 / R8
 -> classes.dex

res / AndroidManifest.xml
 -> AAPT2 compile
 -> .flat
 -> AAPT2 link
 -> resources.arsc / R / 合并后 Manifest

assets / jniLibs / resources / dex
 -> 打包
 -> zipalign
 -> apksigner
 -> APK

资源编译：AAPT2

AAPT2 分成两个阶段：

compile

把 res/ 下的资源单独编译成 .flat 中间文件。
link

合并所有资源，生成 resources.arsc、R 类、最终资源表和处理后的 Manifest。

这种分阶段设计的好处是支持增量编译。修改一个资源文件时，不一定要重新处理整个资源目录。

代码编译：Kotlin/Java 到 Dex

代码链路可以分成两段：

Kotlin / Java
 -> .class
 -> .dex

其中：

kotlinc / javac 负责生成 JVM 字节码；
D8 负责把 .class 转成 Dex；
R8 在 Release 构建中负责裁剪、优化、混淆，并最终产出 Dex。

可以粗略理解为：

D8 = 字节码到 Dex
R8 = D8 + shrink + optimize + obfuscate

Manifest 合并

最终 APK 中只有一个 AndroidManifest.xml，但它来自多个来源：

app 主 Manifest；
product flavor / build type 配置；
library module 的 Manifest；
第三方 SDK 的 Manifest。

Manifest 合并常见问题：

权限重复或冲突；
provider authorities 冲突；
minSdk / targetSdk 约束冲突；
组件属性被依赖库注入。

排查入口：

build/intermediates/merged_manifest/

打包内容

一个 APK 通常包含：

AndroidManifest.xml
classes.dex
resources.arsc
res/
assets/
lib/<abi>/*.so
META-INF/

其中：

classes.dex 是运行在 ART 上的字节码；
resources.arsc 是资源索引表；
lib/<abi> 存放 Native 库；
assets 原样打包；
META-INF 和签名相关。

签名与 zipalign

zipalign

zipalign 会调整 APK 中未压缩资源的对齐方式，让系统可以更高效地通过内存映射读取资源。

核心价值：

减少运行时额外拷贝；
优化资源读取；
是 Release APK 的标准步骤。

签名

签名用于证明 APK 来源，并保护包内容不被篡改。

常见签名方案：

V1：基于 JAR 签名，兼容老系统；
V2：对整个 APK 签名；
V3：支持密钥轮换；
V4：服务于增量安装。

APK 和 AAB

格式	用途
APK	设备可直接安装
AAB	上传到 Google Play，由商店按设备生成拆分 APK

AAB 的优势是可以按设备拆分：

ABI；
屏幕密度；
语言；
动态功能模块。

因此 AAB 能降低用户实际下载体积，但本地调试和部分渠道发布仍会直接使用 APK。

回看清单

AAPT2 处理资源，D8/R8 处理 Dex。
Manifest 是多来源合并的结果，冲突要看合并产物。
Release 包要关注 R8、签名和 zipalign。
APK 是安装格式，AAB 是应用商店分发格式。
构建问题要先判断出在资源、代码、Manifest、签名还是打包阶段。

Build on zed的博客

Gradle Convention Plugins：多模块构建逻辑组织

核心结论

核心思想

典型项目结构

解决的问题

实现方式

1. 设置build-logic模块

2. 创建约定插件

3. 核心方法：apply

4. 共享配置函数

5. 在根项目中引入

6. 在模块中引入

Convention Plugin的优势

Android Gradle 基础：插件、依赖和版本目录

核心结论

插件和库的区别

implementation

api

classpath

Version Catalog

排错思路

回看清单

Android APK 打包流程：从源码到可安装文件

核心结论

总体流程

资源编译：AAPT2

代码编译：Kotlin/Java 到 Dex

Manifest 合并

打包内容

签名与 zipalign

zipalign

签名

APK 和 AAB

回看清单

3. 核心方法：`apply`