原生移动开发 / 系统课时

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 专属配置留在模块层,则能保持职责清晰。

Gradle Kotlin DSL 文件职责与配置关系

用 settings.gradle.kts 定义构建边界

下面是一份可直接放在项目根目录的 Settings 配置。它声明插件解析仓库、普通依赖仓库、根项目名称,并把 app 模块纳入当前构建。

kotlin
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 的写法。

kotlin
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 配置决定。

bash
./gradlew projects

预期输出

text
> 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;不要为了“先跑起来”同时维护两套仓库来源。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Gradle Kotlin DSL 基础

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通