Android Gradle 基础

白瑞德
663 阅读18分钟

Android Gradle 是 Android 项目的构建工具，它基于 Gradle 构建系统，为 Android 应用的构建、测试、发布提供支持。Gradle 配置文件通常分为两个层级：项目级别的 build.gradle 文件 和 模块级别的 build.gradle 文件。

• 项目级 build.gradle：包含项目的全局配置。

• 模块级 build.gradle：针对特定模块（如 app 模块）进行配置。

接下来分别介绍这两个文件的作用、常用配置项，以及如何动态获取配置。

1. 项目级 build.gradle 文件

1.1 文件位置

项目级 build.gradle 文件位于项目根目录下，通常用于配置全局的插件和依赖、构建脚本仓库等。

1.2 常见配置

// 项目级别的 build.gradle 文件示例（AGP 8.x 推荐写法）

// 声明整个项目会用到的插件，apply false 表示此处只解析版本，
// 真正应用在各模块的 build.gradle 中进行。
plugins {
    id 'com.android.application' version '8.2.1' apply false
    id 'com.android.library'     version '8.2.1' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.22' apply false
}

// 统一所有子模块的编译选项（只作用于子模块，不作用于根项目）
subprojects {
    tasks.withType(JavaCompile).configureEach {
        options.encoding = 'UTF-8'
    }
}

// 自定义清理任务，删除根项目的 build 目录
tasks.register('clean', Delete) {
    delete rootProject.layout.buildDirectory
}

说明：AGP 7.0 之前常见的 buildscript { classpath ... } 写法仍然可用，但在 AGP 7.1+ 已不再推荐。现代项目中插件统一通过 plugins {} 声明，仓库统一在 settings.gradle 的 pluginManagement / dependencyResolutionManagement 中配置（详见 1.4 节）。下文会同时介绍新旧两种写法，便于读者维护老项目。

旧式 buildscript 写法（legacy，仅用于理解老项目）

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:7.2.0'
        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.6.10'
    }
}

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

1.3 配置项说明

1.3.1 buildscript（legacy）:

⚠️ 现代项目优先使用 plugins {} DSL + settings.gradle 的 pluginManagement，buildscript 块主要出现在老项目中。 这里保留介绍是为了读懂历史代码。

用于配置构建脚本本身的特定部分。它的作用是定义 构建脚本的依赖项 和 构建脚本所需的仓库，以及如何应用这些插件或依赖项。

buildscript 的作用：

  1. 定义构建脚本的依赖项（Classpath） ：

    buildscript 主要用来定义构建脚本本身所依赖的类路径（classpath）。这意味着构建过程中所需要的插件或者工具的依赖是通过 buildscript 中的 dependencies 来声明的。例如，Android 项目通常会在这里声明 Android Gradle 插件（com.android.tools.build:gradle）和 Kotlin 插件（org.jetbrains.kotlin:kotlin-gradle-plugin）等。

  2. 定义仓库（Repositories） ：

    repositories 作用是指定从哪里下载这些构建插件和依赖。通常会配置一些常用的仓库，如 google() 和 mavenCentral()。这些仓库包含了常见的插件和库。

  3. 为整个项目或子项目提供构建插件：

    buildscript 中配置的插件和依赖项通常会被用于构建项目，而不是在应用程序代码中使用。例如，Android Gradle 插件就在 buildscript 中声明，并且会影响整个项目的构建过程。

结构说明：

  • repositories 定义了构建过程中所需依赖的下载源。常用的仓库有：

    • google()：适用于 Android Gradle 插件等 Android 相关依赖。
    • mavenCentral()：适用于各种 Java 和 Kotlin 依赖。

必要性：

  • 插件管理：buildscript 使你能够指定构建过程所需要的插件和其版本，保证了构建环境中插件版本的统一性
  • 支持多模块构建：对于大型项目，可能会有多个模块（如应用模块、库模块等），buildscript 中的插件和依赖项会为所有这些模块提供共享的构建配置。
  • 构建环境的配置：通过 buildscript 配置，可以确保整个项目的构建过程使用的插件、工具和版本都是一致的，这有助于避免由于插件版本不一致导致的构建失败或异常。

1.3.2 allprojects:

⚠️ 在 AGP 7.1+，把仓库写在 allprojects { repositories {} } 已不再是推荐做法，应改为在 settings.gradle 中使用 dependencyResolutionManagement（详见 1.4 节）。此处保留介绍是为了读懂老项目，同时说明 allprojects 还能共享其他构建配置（编码、JVM 目标等）。

用于配置 所有项目（根项目与所有子模块）的构建设置。这些配置会应用到项目的所有子模块，允许在多个项目或模块之间共享。通常用于统一管理构建仓库、编译选项、任务等。

allprojects 的作用：

  1. 共享仓库配置（legacy）：

    allprojects 块曾用于为所有子模块配置共享的仓库。新项目应改用 settings.gradle 的 dependencyResolutionManagement。

  2. 统一构建设置：

    可用于为所有模块配置统一的编译选项、编码、JVM 目标、通用任务等，避免在每个子模块中重复配置。

⚠️ 注意：不要在 allprojects 中写 dependencies { implementation ... }。implementation 是由 Android/Java 插件引入的 configuration，根 project 没有应用这些插件，会直接报错。依赖应在各模块自身的 build.gradle 中声明。

必要性：

  • 统一的仓库配置：多模块项目统一配置所有模块使用相同的仓库，避免在每个模块中重复配置仓库。
  • 共享的依赖配置：为所有子项目统一配置共享的依赖，用于共享一些公共的库或插件
  • 统一的构建设置：用来统一所有模块的构建设置。例如，你可以配置所有模块的 Java 版本、Kotlin 编译选项等。
allprojects {
    tasks.withType(JavaCompile) {
        options.encoding = 'UTF-8'
    }

    tasks.withType(KotlinCompile) {
        kotlinOptions.jvmTarget = "1.8"
    }
}

1.3.3 subprojects

subprojects基本和allprojects一致，但是subprojects 只会影响子项目，而不会影响根项目：

  • allprojects：适用于根项目及其所有子项目。配置项会影响根项目和所有子项目。
  • subprojects：只会影响子项目（不包括根项目）。如果你有多个子模块，并且希望对子模块的构建配置进行统一管理，但不影响根项目，可以使用 subprojects。

如果你有多个子模块，并且希望对子模块的构建配置进行统一管理，但不影响根项目，可以使用 subprojects。

1.3.4 plugins

plugins 块用于声明和应用 Gradle 插件。这些插件扩展了 Gradle 构建系统的功能，允许使用特定的功能或任务，例如 Android 构建、Kotlin 编译、Java 编译等。使得管理插件的方式更加清晰简洁。

plugins的作用：

  1. 声明插件：

    声明构建过程中要使用的插件，插件通过 ID 和版本号来标识。与 buildscript 中使用 classpath 声明插件不同，plugins 更简单。

  2. 应用插件：

    插件是 Gradle 构建系统的核心扩展部分。通过 plugins 块，Gradle 会自动下载并应用所声明的插件，使得你可以使用该插件提供的任务、功能和配置。例如，Android 插件可以用来构建 Android 应用，Kotlin 插件可以用来编译 Kotlin 代码。

  3. 自动处理插件版本管理：

    使用 plugins 块时，插件的版本号可以直接指定，Gradle 会自动从插件仓库下载对应的插件，而不需要手动设置插件依赖。这使得版本管理更加简洁，避免了手动管理插件版本的复杂性。

  4. 提高可读性和可维护性：

    plugins 块声明插件的语法更直观和简洁，代码更加简洁、易懂，并且使得构建脚本的结构更清晰。

项目级的 Gradle 插件，一般用于全局配置。如插件定义、依赖管理等。可以跨多个子模块共享，减少了重复配置的需要。通过使用插件，Gradle 可以获得额外的功能。也能集中管理构建工具的版本，避免每个子项目都独立管理插件版本。

关键字段

  1. id：

    插件的唯一标识符。每个插件都必须有一个唯一的 id，通常这个 id 由插件的开发者指定。例如，com.android.application 用于 Android 应用构建插件，org.jetbrains.kotlin.android 用于 Kotlin 插件。

  2. version：

    插件的版本号。你可以指定插件的版本号，这样 Gradle 会确保使用指定版本的插件。例如，version '8.2.1' 表示使用该版本的插件。

  3. apply：

    指定插件是否被应用到项目中。apply false 用于在项目级 build.gradle 文件中声明插件，而实际应用插件的操作可能在子项目中进行，避免根项目直接应用插件。例如，apply false 表示插件不会自动应用到项目中，而是可以在子模块中按需使用。可以在模块级的 build.gradle 中选择性地启用插件。

必要性：

  • 语法更简洁：plugins 块的语法比传统的 buildscript 更简洁、直观。在 buildscript 中，你需要手动指定插件的类路径（classpath），而 plugins 块通过插件的 ID 和版本号来声明插件，Gradle 会自动管理依赖。
  • 更易于维护：不需要手动添加 classpath 依赖并管理插件版本，Gradle 会自动处理。
  • 减少冲突：通过指定插件的版本号，可以确保不同的模块或子项目使用一致的插件版本，避免了版本冲突的问题。
  • 减少重复配置：支持在多个模块中应用同样的插件，通过声明并共享插件配置，减少了重复代码。

plugins 与 buildscript 的区别：

  • plugins {}（现代推荐）：简洁的插件声明方式，通过 pluginManagement（在 settings.gradle 中）解析插件版本和仓库，Gradle 自动下载并应用。
  • buildscript {}（legacy）：通过 classpath 声明插件依赖，AGP 7.0 之前的标准做法。现代项目通常只保留一种写法（优先 plugins {}），两者不要混用在同一个 build.gradle 中。

1.3.5 task clean

  • 自定义 Gradle 任务，删除构建目录，通常用于清理构建结果。在该示例中，其作用如下：

    • task clean：这是一个自定义任务，用于删除构建目录 build。通常在执行 ./gradlew clean 命令时，Gradle 会调用这个任务来清理生成的构建文件。
    • type: Delete：指定该任务的类型是 Delete，表示删除文件或目录。
    • delete rootProject.buildDir：表示删除根项目的构建目录，即 rootProject/build。

1.4 settings.gradle（现代项目的真正入口）

AGP 7.1+ 把仓库和插件解析都移到了 settings.gradle，这是现代 Android 项目必看的文件。

// settings.gradle
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS：禁止各模块单独声明仓库，强制走统一配置
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

rootProject.name = "MyApp"
include ':app', ':core', ':feature:login'

关键字段：

  • pluginManagement：指定插件本身（如 AGP、Kotlin）从哪些仓库解析。
  • dependencyResolutionManagement：指定依赖库从哪些仓库下载。RepositoriesMode.FAIL_ON_PROJECT_REPOS 可防止子模块私自加仓库，保证依赖来源可控。
  • include：声明项目中包含哪些子模块。

1.5 动态获取配置的方式

1.5.1 Version Catalog（现代推荐，AGP 8.x 默认模板自带）

在 gradle/libs.versions.toml 中集中管理版本、依赖和插件：

[versions]
kotlin = "1.9.22"
agp = "8.2.1"
appcompat = "1.6.1"

[libraries]
androidx-appcompat = { module = "androidx.appcompat:appcompat", version.ref = "appcompat" }
kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

在模块 build.gradle 中通过类型安全访问器引用：

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
}

dependencies {
    implementation(libs.androidx.appcompat)
    implementation(libs.kotlin.stdlib)
}

优点：IDE 自动补全、类型安全、版本集中管理、跨模块共享、避免拼写错误。

1.5.2 ext 属性（legacy，仍在老项目中常见）

ext {
    kotlin_version = '1.9.22'
}

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
}

通过 ext 可以定义全局变量供各模块引用，但没有类型检查、容易拼错，新项目应优先使用 Version Catalog。

2. 模块级 build.gradle 文件

2.1 文件位置

每个 Android 模块（如 app）都有自己的 build.gradle 文件，用于配置该模块的构建选项和依赖。

2.2 常见配置

// 模块级别的 build.gradle 文件示例（Groovy DSL）
plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
}

android {
    namespace 'com.example.myapp'   // AGP 7.3+ 必须声明，替代 AndroidManifest 里的 package
    compileSdk 34                   // 编译 SDK 版本

    defaultConfig {
        applicationId "com.example.myapp"
        minSdk 21                   // 最小支持 SDK 版本
        targetSdk 34                // 目标 SDK 版本
        versionCode 1
        versionName "1.0"

        // 生成 BuildConfig 常量，代码中通过 BuildConfig.API_BASE 访问
        buildConfigField "String", "API_BASE", "\"https://api.example.com\""
        // Manifest 占位符
        manifestPlaceholders = [appLabel: "MyApp"]
    }

    signingConfigs {
        release {
            storeFile file("../keystore/release.jks")
            storePassword System.getenv("KS_PASS")
            keyAlias "my-key"
            keyPassword System.getenv("KEY_PASS")
        }
    }

    buildTypes {
        release {
            minifyEnabled true                       // 启用代码压缩/混淆
            shrinkResources true                     // 启用资源压缩
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
            signingConfig signingConfigs.release
        }
        debug {
            minifyEnabled false
            applicationIdSuffix ".debug"
        }
    }

    flavorDimensions += "tier"                       // 多维度渠道必须声明维度
    productFlavors {
        free { dimension "tier"; applicationIdSuffix ".free" }
        paid { dimension "tier"; applicationIdSuffix ".paid" }
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }

    buildFeatures {
        viewBinding true
        buildConfig  true                            // AGP 8.0+ 默认关闭，用到 BuildConfig 需显式开启
    }
}

dependencies {
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'org.jetbrains.kotlin:kotlin-stdlib:1.9.22'
    testImplementation 'junit:junit:4.13.2'
    androidTestImplementation 'androidx.test.ext:junit:1.1.5'
}

2.3 配置项说明

2.3.1 plugins

声明并应用 Gradle 插件。通过插件启用构建特性或任务。例如，com.android.application 用于构建 Android 应用，org.jetbrains.kotlin.android 用于在 Android 项目中使用 Kotlin。

plugins 既可以在项目级的 build.gradle 文件中配置，也可以在模块级的 build.gradle 文件中配置。虽然它们的配置方式有所不同，但主要的区别在于作用范围和功能。

其和根目录下项目级的plugins的区别如下：

1. 项目级 plugins

  • 作用范围：在项目级的 build.gradle 中配置的插件，通常用于定义整个项目的构建逻辑，或者应用于所有模块（子项目）中。

  • 作用：项目级插件配置主要用来为所有子模块提供构建工具、插件或库的版本管理。这些插件通常是全局插件，确保整个项目或所有模块使用相同的构建配置、版本等。

  • 常见用法：配置用于构建 Android 项目所需的插件、Kotlin 插件等。

  • 项目级插件的一些常见功能：

    • 插件版本管理：你可以在项目级别声明插件的版本，避免在每个模块中重复配置插件版本。
    • 全局插件配置：例如，Android 和 Kotlin 插件通常需要在项目级别声明。

2. 模块级 plugins

  • 作用范围：在模块级的 build.gradle 中配置的插件，作用仅限于该模块。每个模块的 build.gradle 文件通常会指定与该模块相关的插件。

  • 作用：模块级插件用于具体化某个模块的构建逻辑。例如，如果某个模块是 Android 应用模块，则可以在该模块的 build.gradle 文件中启用 com.android.application 插件。如果是库模块，则启用 com.android.library 插件。

  • 常见用法：在各个模块中配置 Android 插件、Kotlin 插件，或其他库插件等。

  • 模块级插件的一些常见功能：

    • Android 构建插件：根据模块的性质，使用 com.android.application 或 com.android.library 插件来构建 Android 应用或库。
    • Kotlin 插件：启用 Kotlin 支持并为模块提供编译和其他 Kotlin 特性。

3. 区别总结

项 目项目级 plugins 配置模块级 plugins 配置
作用范围整个项目（包括所有子模块）仅限于当前模块（子模块）
配置方式通常在项目根目录的 build.gradle 文件中配置每个模块的 build.gradle 文件中配置
插件类型一般为全局性插件，例如 Android、Kotlin 等与模块构建相关的插件，例如 com.android.application，com.android.library 等
常见用途管理插件版本、全局配置插件针对每个模块的具体构建任务，如构建 Android 应用或库

4. 插件的应用

  • 项目级插件配置：主要目的是统一插件版本，确保所有模块使用相同的版本。例如，Android Gradle 插件和 Kotlin 插件的版本需要在项目级别一致。
  • 模块级插件配置：在模块级的 build.gradle 中，针对不同的模块选择相应的插件并应用。例如，一个模块可能是 Android 应用模块 (com.android.application)，另一个模块可能是 Android 库模块 (com.android.library)。

2.3.2 android 配置

  • namespace：AGP 7.3+ 起必须声明，替代原来写在 AndroidManifest 里的 package，用于生成 R 类和 BuildConfig 的包名。

  • compileSdk（旧名 compileSdkVersion）：指定应用编译时使用的 Android SDK 版本。

  • defaultConfig：模块的基本配置。

    常用字段：

    • applicationId：应用的唯一标识符。
    • minSdk（旧名 minSdkVersion）：最低支持的 Android SDK 版本。
    • targetSdk（旧名 targetSdkVersion）：应用优化支持的目标 SDK 版本。
    • versionCode：版本号，唯一且递增，用于标识不同版本的应用。
    • versionName：版本名称，通常是用户可见的版本号（如 1.0）。
    • buildConfigField：在 BuildConfig 中注入常量（AGP 8.0+ 需 buildFeatures.buildConfig = true）。
    • manifestPlaceholders：AndroidManifest 占位符，用于根据构建类型/渠道动态替换 Manifest 值。

  • buildTypes：配置不同的构建类型，如 debug 和 release。每个构建类型可以有不同的设置，如是否混淆代码、是否启用调试信息等。

    常用字段（Groovy DSL 名称；Kotlin DSL 需前缀 is，如 isMinifyEnabled）：

    • minifyEnabled：是否启用代码压缩和混淆。
    • shrinkResources：是否启用资源压缩（需与 minifyEnabled 配合使用）。
    • proguardFiles：指定混淆配置文件，getDefaultProguardFile 获取默认的 ProGuard 配置，通常用于 release 构建类型。
    • signingConfig：签名配置，引用自 signingConfigs {} 块。

  • signingConfigs：定义签名配置。敏感信息（密码、别名）建议通过环境变量或 local.properties 注入，切勿硬编码进版本控制。

  • productFlavors：定义产品类别，可以用来区分不同的产品版本（如 free 和 paid，或者 mobile 和 pad）。AGP 3.0+ 必须通过 flavorDimensions 声明至少一个维度，每个 flavor 必须指定 dimension。

    常用字段：

    • dimension：所属维度（必填）。
    • applicationIdSuffix：应用 ID 后缀，不同的类型可以有不同的应用 ID。
    • versionNameSuffix：版本名称后缀，用于区分不同版本。

  • compileOptions：用于配置 Java 编译选项，确保项目兼容性和提升构建性能。

  • buildFeatures：用于启用或禁用 Android 构建系统中的某些特性的一部分。它允许开发者开启或关闭一些构建功能，比如 ViewBinding、DataBinding、Jetpack Compose 等。这些功能帮助简化开发过程，提升开发效率，并且提高项目的可维护性。

    配置项

    • viewBinding:启用或禁用 ViewBinding，它是一种自动生成视图绑定类的功能，可以避免 findViewById 操作，简化代码，提升开发效率。默认情况下，viewBinding 是禁用的。

    • dataBinding:启用或禁用 DataBinding，允许将 UI 元素和数据对象绑定在一起，简化 UI 更新的代码。

    • compose: 启用或禁用 Jetpack Compose，这是 Android 的声明式 UI 框架，用于更简洁地构建用户界面。

    • buildConfig:启用或禁用 BuildConfig 文件的自动生成。它允许在构建时生成一些常用的构建常量（如版本号、构建类型等）。

    • customBuildFeatures:一些特定于插件的功能，允许你开启或关闭其他的构建功能。

      示例：

android {
    compileSdkVersion 34

    defaultConfig {
        applicationId "com.example.app"
        minSdkVersion 21
        targetSdkVersion 34
    }

    buildFeatures {
        viewBinding = true        // 启用 ViewBinding
        dataBinding = false       // 禁用 DataBinding
        compose = true            // 启用 Jetpack Compose
        buildConfig = true        // 启用 BuildConfig
    }
}

  • dependencies：用于声明项目所依赖的外部库或模块。它指定了哪些依赖项需要在构建过程中被包括到 APK 或 AAB 中。通过声明这些依赖项，Gradle 会自动下载、编译并将其打包到项目中 常用配置：

    • implementation：它表示库或模块是项目的实现依赖（即运行时和编译时都需要）,引入的库不会传递给其他模块，意味着它们不会作为依赖暴露给依赖此项目的其他模块。
    • api：通常用于库模块。当库模块依赖其他库时，这些库会暴露给依赖该库的其他模块,它们会成为公共的依赖。
    • compileOnly：表示只在编译时需要，但不会包含在最终的 APK 中，适用于那些只在编译时需要存在的库（例如编译器插件或注解处理器）。
    • runtimeOnly：表示只在运行时需要的库，不会在编译时提供。适用于运行时才需要的库，例如数据库驱动程序等。
    • testImplementation：声明仅在测试代码中使用的依赖。它只影响测试构建过程，不会包含在主应用程序的构建中。适用于测试库、测试框架等。
    • androidTestImplementation：声明仅在 Android 测试代码中使用的依赖。它只影响 Android 单元测试和 UI 测试。适用于 Android 测试框架。
    • kapt：Kotlin 的注解处理工具（Kotlin Annotation Processing Tool），用来处理需要编译时注解的库或模块。新项目推荐使用 KSP（Kotlin Symbol Processing）替代，编译速度通常快 2 倍以上。

⚠️ 关于动态版本：implementation 'com.squareup.okhttp3:okhttp:4.+' 这种写法（+、[1.0, 2.0) 等）虽然合法，但会破坏构建可复现性——同一份源码在不同时间构建出的产物可能不同，线上故障难以复现。生产项目应始终锁定具体版本，统一版本管理建议使用 Version Catalog（见 1.5.1 节）。

2.4 动态获取配置的方式

  • 获取环境变量：

    可以通过 Gradle 内置的 project 对象获取动态配置。例如，从外部文件或环境变量获取版本号。

def versionCode = project.hasProperty('versionCode') ? project.versionCode : 1

defaultConfig {
    versionCode versionCode
}

  • 动态加载属性文件：

    使用 Properties 类动态加载版本号或其他配置。

def properties = new Properties()
file("local.properties").withInputStream { stream ->
    properties.load(stream)
}

defaultConfig {
    versionCode properties['versionCode'].toInteger()
    versionName properties['versionName']
}

  • 在 gradle.properties 文件中定义全局属性：

    可以在 gradle.properties 文件中定义配置，并在 build.gradle 文件中引用。

# gradle.properties
VERSION_CODE=1
VERSION_NAME=1.0

然后在 build.gradle 中引用：

defaultConfig {
    versionCode project.VERSION_CODE
    versionName project.VERSION_NAME
}

总结

Android 项目的 Gradle 配置由三个文件协作完成，初学者常忽略 settings.gradle，但在 AGP 7.1+ 中它才是真正的入口：

  • settings.gradle（AGP 7.1+ 必看）：

    • pluginManagement 负责插件的仓库与版本解析。
    • dependencyResolutionManagement 统一管理所有模块的依赖仓库（推荐配合 FAIL_ON_PROJECT_REPOS 禁止子模块私自加仓库）。
    • include 声明项目中包含的子模块。

  • 项目级 build.gradle：

    • 使用 plugins {} 声明项目用到的插件（apply false 只解析版本，不应用）。
    • 可用 subprojects {} 统一所有子模块的编译选项、编码等。
    • buildscript {} 与 allprojects { repositories {} } 是 legacy 写法，只在维护老项目时才需要。

  • 模块级 build.gradle：

    • 配置模块自身的构建：namespace、compileSdk、defaultConfig、buildTypes、signingConfigs、productFlavors、buildFeatures、dependencies 等。
    • AGP 8.0+ 起 BuildConfig 默认关闭，需 buildFeatures.buildConfig = true 开启。
    • 多渠道必须先声明 flavorDimensions。

  • 统一版本与配置的最佳实践：

    • 首选 Version Catalog（gradle/libs.versions.toml）：类型安全、IDE 补全、跨模块共享。
    • 老项目可用 ext、gradle.properties 或 local.properties 作为过渡方案。
    • 避免动态版本（4.+、latest.release），生产构建应锁定具体版本以保证可复现性。
    • 签名密码、密钥库路径等敏感信息应通过环境变量或 local.properties 注入，不入库。
avatar
文章
阅读
粉丝