原生移动开发 / 系统课时
Gradle Kotlin DSL 基础
Gradle Kotlin DSL 基础
Android 项目的构建配置分散在多个 .gradle.kts 文件中。本课要解决的是“每个文件到底管什么、Kotlin DSL 怎么读”的问题:你会从构建边界、仓库、插件到 app 模块配置串起完整关系,并用 Gradle 命令确认模块是否被正确识别。
学习目标
- 区分
settings.gradle.kts、根项目build.gradle.kts与模块build.gradle.kts的职责 - 读懂 Kotlin DSL 中的属性赋值、函数调用和嵌套配置块
- 使用 Gradle Wrapper 验证项目与模块配置是否生效
三类构建脚本如何协作
settings.gradle.kts 决定“这次构建包含谁”,通常还集中配置插件仓库和依赖仓库;根项目 build.gradle.kts 适合声明供各模块共享的插件版本或构建约定;app/build.gradle.kts 则配置 Android 应用模块本身,例如命名空间、SDK、构建类型和依赖。
Gradle 会先处理 Settings,再配置根项目和被 include 的子项目。把仓库边界放在 Settings 层,可以避免每个模块各写一套仓库规则;把 Android 专属配置留在模块层,则能保持职责清晰。

用 settings.gradle.kts 定义构建边界
下面是一份可直接放在项目根目录的 Settings 配置。它声明插件解析仓库、普通依赖仓库、根项目名称,并把 app 模块纳入当前构建。
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
}
}
dependencyResolutionManagement {
// 禁止子项目自行添加仓库,统一从这里解析依赖。
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
}
}
rootProject.name = "AndroidBasics"
include(":app")pluginManagement 负责“到哪里找 Gradle 插件”,dependencyResolutionManagement 负责“到哪里找应用和库依赖”,两者不要混为一谈。include(":app") 对应项目中的 app 子目录;如果遗漏它,Gradle 不会把该目录当成当前构建中的项目。
这类配置文件本身不会打印业务输出。生效后的关键行为是:Gradle 能识别根项目 AndroidBasics 和子项目 :app,且模块若私自声明仓库会因 FAIL_ON_PROJECT_REPOS 被拒绝。
读懂模块级 Kotlin DSL
下面是 app/build.gradle.kts 的片段示例,前提是根项目已经提供 com.android.application 插件版本。重点不是记住所有 Android 参数,而是理解 Kotlin DSL 的写法。
plugins {
id("com.android.application")
}
android {
namespace = "com.example.androidbasics"
compileSdk = 36
defaultConfig {
applicationId = "com.example.androidbasics"
minSdk = 23
targetSdk = 36
versionCode = 1
versionName = "1.0"
}
}namespace = "..." 是 Kotlin 属性赋值,id("...") 是函数调用,android { ... } 与 defaultConfig { ... } 是类型安全的嵌套配置块。与 Groovy DSL 相比,Kotlin DSL 更依赖明确的属性和函数语法,因此从旧教程复制 compileSdk 36 这类 Groovy 写法时要先转换语法。
用 Gradle Wrapper 验证配置
在项目根目录执行 Wrapper,而不是依赖机器上全局安装的 Gradle。这样实际运行的 Gradle 版本由项目自己的 Wrapper 配置决定。
./gradlew projects预期输出
> Task :projects
Root project 'AndroidBasics'
\--- Project ':app'
BUILD SUCCESSFUL in <TIME><TIME> 会随机器和缓存状态变化;部分 Gradle 版本还会输出额外的任务统计。验收重点是根项目名称正确、结果中出现 Project ':app',并最终显示 BUILD SUCCESSFUL。
如果命令提示找不到 :app,先检查 settings.gradle.kts 是否包含 include(":app"),再检查目录名是否真的是 app。如果因为模块内声明 repositories {} 而失败,则要么删除模块仓库声明,要么明确调整 Settings 中的 repositoriesMode;不要为了“先跑起来”同时维护两套仓库来源。