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：基础优化（所有项目适用）

# 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：依赖优化

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

2. 启用依赖约束：

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

3. 排除无用传递依赖：

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

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

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

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

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

3. 优化 Kotlin 编译：

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

阶段 4：高级加速技巧

1. 按需编译（实验性）：

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

2. 禁用 PNG 压缩（Debug 模式）：

   android {
       buildTypes {
           debug {
               crunchPngs false
           }
       }
   }
   

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

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

三、诊断与监控工具

1. 生成构建分析报告

./gradlew assembleDebug --profile --offline

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

2. 使用 Gradle 构建扫描

./gradlew build --scan

• 访问 Gradle Build Scan 分析细节

3. 查看任务耗时

./gradlew tasks --all --timing

四、注意事项

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

五、完整配置示例

# 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%（视项目规模）。建议逐步实施并监控效果，优先处理耗时最长的构建阶段。