Gradle 核心配置属性详解 - 新手指南(一)

一、Gradle 核心配置属性详解

1. 基础性能配置

属性	作用	建议值	版本要求
`org.gradle.parallel`	启用并行构建（多模块并行编译）	`true`	Gradle 4.10+
`org.gradle.caching`	启用构建缓存（复用历史构建输出）	`true`	Gradle 3.5+
`org.gradle.daemon`	启用守护进程（减少 JVM 启动开销）	`true`	Gradle 3.0+
`org.gradle.jvmargs`	调整 JVM 堆内存及 GC 策略	`-Xmx4g -XX:+UseG1GC`	根据机器配置调整

2. Android 专用配置

属性	作用	建议值	版本要求
`android.enableBuildCache`	启用 Android 构建缓存	`true`	AGP 3.2+
`android.nonTransitiveRClass`	禁用传递性 R 类（减少资源索引冗余）	`true`	AGP 7.0+
`android.enableJetifier`	自动迁移 Support 库到 AndroidX（旧项目过渡使用）	`false`	完成迁移后关闭
`android.defaults.buildfeatures.buildconfig`	禁用自动生成 BuildConfig（无自定义配置时）	`false`	AGP 4.1+

3. 高级优化配置

属性	作用	建议值	版本要求
`kotlin.incremental`	Kotlin 增量编译（仅编译改动部分）	`true`	Kotlin 1.3.20+
`android.useNewApkCreator`	启用新版 APK 打包工具（提升打包速度）	`true`	AGP 3.3+
`android.enableProfileJson`	生成构建分析报告（用于诊断性能瓶颈）	`true`	AGP 7.0+

二、构建速度优化方案（分阶段实施）

阶段 1：基础优化（所有项目适用）

properties 复制代码

# gradle.properties
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.daemon=true
org.gradle.jvmargs=-Xmx4g -XX:+UseG1GC -Dfile.encoding=UTF-8

# Android 配置
android.enableBuildCache=true
android.nonTransitiveRClass=true
android.defaults.buildfeatures.buildconfig=false

阶段 2：依赖优化

固定依赖版本 ：避免动态版本号（如 2.3.+ → 2.3.4）

启用依赖约束：

kotlin 复制代码

// build.gradle.kts
dependencies {
    implementation("com.squareup.retrofit2:retrofit:2.9.0") {
        version { strictly("2.9.0") }
    }
}

排除无用传递依赖：

kotlin 复制代码

implementation("com.example:lib:1.0") {
    exclude(group = "com.unused", module = "old-utils")
}

阶段 3：模块化与增量编译

拆分功能模块 ：将稳定模块设为 api，频繁修改模块设为 implementation

启用配置缓存（需兼容性检查）：

properties 复制代码

org.gradle.unsafe.configuration-cache=true
org.gradle.unsafe.configuration-cache.problems=warn

优化 Kotlin 编译：

kotlin 复制代码

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
    kotlinOptions {
        freeCompilerArgs = listOf("-Xjvm-default=all")
        jvmTarget = "11"
        incremental = true
    }
}

阶段 4：高级加速技巧

按需编译（实验性）：

properties 复制代码

# gradle.properties
android.experimental.try-with-resources=true

禁用 PNG 压缩（Debug 模式）：

groovy 复制代码

android {
    buildTypes {
        debug {
            crunchPngs false
        }
    }
}

使用预编译依赖（如 Google Play Services）：

kotlin 复制代码

dependencies {
    implementation("com.google.android.gms:play-services-maps:18.2.0") {
        isTransitive = false
    }
}

三、诊断与监控工具

1. 生成构建分析报告

bash 复制代码

./gradlew assembleDebug --profile --offline

查看 build/reports/profile/ 下的 HTML 报告

2. 使用 Gradle 构建扫描

bash 复制代码

./gradlew build --scan

访问 Gradle Build Scan 分析细节

3. 查看任务耗时

bash 复制代码

./gradlew tasks --all --timing

四、注意事项

版本兼容性：确保 AGP、Gradle、Kotlin 版本匹配（推荐使用最新稳定版）
增量问题 ：遇到编译异常时，尝试 ./gradlew clean
CI/CD 环境：统一本地与 CI 的 JDK 版本和 Gradle 配置

五、完整配置示例

properties 复制代码

# gradle.properties
# 基础性能
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.daemon=true
org.gradle.jvmargs=-Xmx4g -XX:+UseG1GC -Dfile.encoding=UTF-8

# Android 优化
android.enableBuildCache=true
android.nonTransitiveRClass=true
android.defaults.buildfeatures.buildconfig=false
android.enableJetifier=false

# Kotlin 优化
kotlin.incremental=true
kotlin.parallel.tasks.in.project=true

# 实验性配置
android.experimental.try-with-resources=true
org.gradle.unsafe.configuration-cache=true
org.gradle.unsafe.configuration-cache.problems=warn

通过以上配置和优化策略，可将构建时间 减少 30%-70%（视项目规模）。建议逐步实施并监控效果，优先处理耗时最长的构建阶段。