在 Android 开发中，build.gradle 文件是项目构建的核心。它不仅管理依赖和编译配置，还支持自动化、多环境构建、性能优化等高级功能。本文将系统梳理 Gradle 的基础配置与高级用法，帮助你打造高效、可维护、灵活的 Android 构建体系。
一、核心配置概览配置文件
核心配置项
作用说明
项目根目录 build.gradle
buildscript、allprojects
定义插件仓库、全局依赖和模块共享仓库
模块级 build.gradle
plugins、android、dependencies
配置编译参数、构建类型、依赖管理
gradle.properties
性能相关属性
提升构建速度（并行、缓存、JVM 参数）
自定义脚本（如 config.gradle）
ext 扩展属性
统一管理版本号和常量
二、基础配置详解1. 项目根目录 build.gradle代码语言：javascript复制buildscript {
repositories {
google()
mavenCentral()
// 国内可使用阿里云镜像
// maven { url 'https://maven.aliyun.com/repository/google' }
}
dependencies {
classpath 'com.android.tools.build:gradle:8.1.0' // AGP 版本
// classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.9.0'
}
}
allprojects {
repositories {
google()
mavenCentral()
// 第三方库仓库（如 JitPack）
// maven { url 'https://jitpack.io' }
}
}
// 清理任务
task clean(type: Delete) {
delete rootProject.buildDir
} 建议：使用固定版本号，避免因自动升级导致兼容性问题。
2. 模块级 build.gradle插件声明代码语言：javascript复制plugins {
id 'com.android.application'
id 'org.jetbrains.kotlin.android' // 如果使用 Kotlin
} ⚠️ 注意：从 AGP 7.0+ 推荐使用 plugins {} 块替代旧的 apply plugin: 语法。
android 闭包配置代码语言：javascript复制android {
namespace 'com.example.myapp' // 新命名空间（AGP 7.0+ 必须）
compileSdk 34
defaultConfig {
applicationId "com.example.myapp"
minSdk 21
targetSdk 34
versionCode 1
versionName "1.0"
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
// 多 dex 支持
multiDexEnabled true
// 环境变量传递给应用
buildConfigField "boolean", "IS_DEBUG_BUILD", "true"
}
// 构建类型
buildTypes {
release {
minifyEnabled true
shrinkResources true
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
}
debug {
applicationIdSuffix ".debug"
debuggable true
}
}
// 编译选项
compileOptions {
sourceCompatibility JavaVersion.VERSION_17
targetCompatibility JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget = '17'
}
// 资源压缩配置
packagingOptions {
resources {
excludes += ['/META-INF/*.kotlin_module']
}
}
}依赖管理代码语言：javascript复制dependencies {
implementation 'androidx.core:core-ktx:1.12.0'
implementation 'androidx.appcompat:appcompat:1.6.1'
implementation 'com.google.android.material:material:1.10.0'
testImplementation 'junit:junit:4.13.2'
androidTestImplementation 'androidx.test.ext:junit:1.1.5'
androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'
} 💡 依赖关键字区别：
implementation：仅本模块可见，依赖不传递 → 编译更快api：依赖会暴露给依赖该模块的其他模块 → 谨慎使用compileOnly：只参与编译，不打包进 APK（如注解处理器）runtimeOnly：运行时才需要（如数据库驱动）三、高级用法与最佳实践1. 统一依赖管理（推荐方式）1.使用 ext + config.gradle（适用于老项目）
创建 config.gradle：
代码语言：javascript复制ext {
android = [
compileSdk: 34,
minSdk : 21,
targetSdk : 34
]
versions = [
appcompat: '1.6.1',
material : '1.10.0',
ktx : '1.12.0'
]
libs = [
appcompat: "androidx.appcompat:appcompat:$versions.appcompat",
material : "com.google.android.material:material:$versions.material",
ktx : "androidx.core:core-ktx:$versions.ktx"
]
}在根 build.gradle 中引入：
代码语言：javascript复制apply from: 'config.gradle'在模块中使用：
代码语言：javascript复制android {
compileSdk rootProject.ext.android.compileSdk
}
dependencies {
implementation rootProject.ext.libs.appcompat
}2.使用 gradle/libs.versions.toml（AGP 7.0+ 推荐）
gradle/libs.versions.toml：
代码语言：javascript复制[versions]
appcompat = "1.6.1"
material = "1.10.0"
ktx = "1.12.0"
[libraries]
appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }
material = { group = "com.google.android.material", name = "material", version.ref = "material" }
core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "ktx" }在 build.gradle 中使用：
代码语言：javascript复制dependencies {
implementation libs.appcompat
implementation libs.material
implementation libs."core-ktx"
} 优势：类型安全、自动补全、集中管理、官方推荐。
2. 多环境构建（Flavors & Build Types）
代码语言：javascript复制android {
flavorDimensions "environment"
productFlavors {
dev {
dimension "environment"
applicationIdSuffix ".dev"
versionNameSuffix "-dev"
buildConfigField "String", "API_URL", "\"https://api.dev.example.com\""
}
staging {
dimension "environment"
applicationIdSuffix ".staging"
versionNameSuffix "-staging"
buildConfigField "String", "API_URL", "\"https://api.staging.example.com\""
}
prod {
dimension "environment"
buildConfigField "String", "API_URL", "\"https://api.example.com\""
}
}
buildTypes {
debug {
debuggable true
}
release {
minifyEnabled true
proguardFiles ...
}
}
}生成的构建变体：
devDebug、devReleasestagingDebug、stagingReleaseprodDebug、prodRelease 💡 可结合 resValue 设置不同环境的资源：
代码语言：javascript复制dev {
resValue "string", "app_name", "MyApp Dev"
}
prod {
resValue "string", "app_name", "MyApp"
}3. 动态配置与任务定制1. 自定义 Gradle 任务代码语言：javascript复制task printBuildInfo {
doLast {
println "App: ${android.defaultConfig.applicationId}"
println "Version: ${android.defaultConfig.versionName}"
println "Build Time: ${new Date()}"
}
}运行：./gradlew printBuildInfo
2.构建前自动修改版本号代码语言：javascript复制android.applicationVariants.all { variant ->
variant.outputs.all {
def versionName = variant.versionName
def buildTime = new Date().format('yyyyMMdd-HHmm')
outputFileName = "app-${variant.name}-${versionName}-${buildTime}.apk"
}
}4. 构建优化：gradle.properties代码语言：javascript复制# 并行构建（多模块项目）
org.gradle.parallel=true
# 启用构建缓存
org.gradle.caching=true
# 守护进程（减少 JVM 启动开销）
org.gradle.daemon=true
# JVM 参数（根据机器调整）
org.gradle.jvmargs=-Xmx6g -XX:MaxMetaspaceSize=2g -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
# 开启配置缓存（AGP 7.4+，显著提升配置阶段速度）
org.gradle.configuration-cache=true
# 开启增量注解处理（KAPT）
kapt.incremental.apt=true5. 依赖冲突排查使用命令查看依赖树：
代码语言：javascript复制./gradlew app:dependencies
./gradlew app:dependencies --configuration debugCompileClasspath排除传递依赖：
代码语言：javascript复制implementation('some.library:1.0') {
exclude group: 'com.google.guava', module: 'guava'
}强制统一版本：
代码语言：javascript复制configurations.all {
resolutionStrategy {
force 'com.google.guava:guava:31.1-android'
}
}四、注意事项版本兼容性
AGP 8.1 → Gradle 8.0+Kotlin 1.9 → 需匹配 Kotlin 插件版本查阅官方 兼容性矩阵避免动态版本
代码语言：javascript复制// ❌ 危险
implementation 'com.squareup.retrofit2:retrofit:2.+'
// ✅ 安全
implementation 'com.squareup.retrofit2:retrofit:2.9.0'国内加速
代码语言：javascript复制repositories {
maven { url 'https://maven.aliyun.com/repository/google' }
maven { url 'https://maven.aliyun.com/repository/central' }
maven { url 'https://maven.aliyun.com/repository/jcenter' }
maven { url 'https://jitpack.io' }
}清理缓存
代码语言：javascript复制./gradlew clean
./gradlew --stop # 停止守护进程五、总结功能
推荐做法
依赖管理
使用 libs.versions.toml
多环境构建
productFlavors + buildTypes
构建加速
parallel, caching, configuration-cache
版本控制
固定版本号，避免 +
项目结构
分离配置，统一管理
建议：
新项目优先使用 libs.versions.toml合理使用 productFlavors 实现多环境部署持续优化 gradle.properties 提升开发体验