gradle-build-performance

Gradle 构建性能

适用场景

• 构建耗时较长（干净构建或增量构建）
• 调查构建性能回退
• 分析 Gradle Build Scan
• 识别配置与执行阶段的瓶颈
• 优化 CI/CD 构建耗时
• 启用 Gradle Configuration Cache
• 减少不必要的重新编译
• 调试 kapt/KSP 注解处理

示例提示词

• “我的构建很慢，怎样才能加快速度？”
• “如何分析 Gradle 构建扫描？”
• “为什么配置要花这么长时间？”
• “为什么我的项目总是重新编译所有内容？”
• “如何启用配置缓存？”
• “为什么 kapt 这么慢？”

---

工作流

1. 测量基准 — 记录干净构建和增量构建的耗时
2. 生成构建扫描 — ./gradlew assembleDebug --scan
3. 确定阶段 — 配置？执行？依赖解析？
4. 应用一项优化 — 不要批量更改
5. 测量改进 — 与基准进行比较
6. 在构建扫描中验证 — 通过可视化确认

---

快速诊断

生成构建扫描

./gradlew assembleDebug --scan

在本地分析构建

./gradlew assembleDebug --profile
# Opens report in build/reports/profile/

构建耗时摘要

./gradlew assembleDebug --info | grep -E "^\:.*"
# Or view in Android Studio: Build > Analyze APK Build

---

构建阶段

阶段	执行内容	常见问题
初始化	对 settings.gradle.kts 求值	include() 语句过多
配置	对所有 build.gradle.kts 文件求值	开销大的插件、急切创建任务
执行	根据输入/输出运行任务	缓存未命中、非增量任务

确定瓶颈

Build scan → Performance → Build timeline

• 配置阶段耗时长：重点优化插件和构建脚本
• 执行阶段耗时长：重点优化任务缓存和并行化
• 依赖解析缓慢：重点优化仓库配置

---

12 种优化模式

1. 启用配置缓存

跨构建缓存配置阶段（AGP 8.0+）：

# gradle.properties
org.gradle.configuration-cache=true
org.gradle.configuration-cache.problems=warn

2. 启用构建缓存

在不同构建和机器间复用任务输出：

# gradle.properties
org.gradle.caching=true

3. 启用并行执行

同时构建彼此独立的模块：

# gradle.properties
org.gradle.parallel=true

4. 增加 JVM 堆内存

为大型项目分配更多内存：

# gradle.properties
org.gradle.jvmargs=-Xmx4g -XX:+UseParallelGC

5. 使用非传递 R 类

减小 R 类和编译规模（AGP 8.0+ 默认启用）：

# gradle.properties
android.nonTransitiveRClass=true

6. 将 kapt 迁移到 KSP

对于 Kotlin，KSP 的速度比 kapt 快 2 倍：

// Before (slow)
kapt("com.google.dagger:hilt-compiler:2.51.1")

// After (fast)
ksp("com.google.dagger:hilt-compiler:2.51.1")

7. 避免动态依赖

固定依赖版本：

// BAD: Forces resolution every build
implementation("com.example:lib:+")
implementation("com.example:lib:1.0.+")

// GOOD: Fixed version
implementation("com.example:lib:1.2.3")

8. 优化仓库顺序

将最常用的仓库放在前面：

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()      // First: Android dependencies
        mavenCentral() // Second: Most libraries
        // Third-party repos last
    }
}

9. 对本地模块使用 includeBuild

对于大型单体仓库，复合构建比 project() 更快：

// settings.gradle.kts
includeBuild("shared-library") {
    dependencySubstitution {
        substitute(module("com.example:shared")).using(project(":"))
    }
}

10. 启用增量注解处理

# gradle.properties
kapt.incremental.apt=true
kapt.use.worker.api=true

11. 避免在配置时执行 I/O

不要在配置期间读取文件或进行网络调用：

// BAD: Runs during configuration
val version = file("version.txt").readText()

// GOOD: Defer to execution
val version = providers.fileContents(file("version.txt")).asText

12. 使用延迟任务配置

避免使用 create()，改用 register()：

// BAD: Eagerly configured
tasks.create("myTask") { ... }

// GOOD: Lazily configured
tasks.register("myTask") { ... }

---

常见瓶颈分析

配置阶段缓慢

症状：构建扫描显示“Configuring build”耗时较长

原因与解决方法：

原因	解决方法
急切创建任务	使用 tasks.register() 替代 tasks.create()
buildSrc 依赖过多	使用 includeBuild 迁移到约定插件
构建脚本中的文件 I/O	使用 providers.fileContents()
插件中的网络调用	缓存结果或使用离线模式

编译缓慢

症状：:app:compileDebugKotlin 耗时过长

原因与解决方法：

原因	解决方法
非增量更改	避免修改会导致缓存失效的 build.gradle.kts
模块过大	拆分为更小的功能模块
kapt 使用过多	迁移到 KSP
Kotlin 编译器内存不足	增加 kotlin.daemon.jvmargs

缓存未命中

症状：即使没有更改，任务也总是重新运行

原因与解决方法：

原因	解决方法
任务输入不稳定	使用 @PathSensitive、@NormalizeLineEndings
输出中包含绝对路径	使用相对路径
缺少 @CacheableTask	为自定义任务添加注解
JDK 版本不同	在各个环境中统一 JDK

---

CI/CD 优化

远程构建缓存

// settings.gradle.kts
buildCache {
    local { isEnabled = true }
    remote<HttpBuildCache> {
        url = uri("https://cache.example.com/")
        isPush = System.getenv("CI") == "true"
        credentials {
            username = System.getenv("CACHE_USER")
            password = System.getenv("CACHE_PASS")
        }
    }
}

Gradle Enterprise / Develocity

用于高级构建分析：

// settings.gradle.kts
plugins {
    id("com.gradle.develocity") version "3.17"
}

develocity {
    buildScan {
        termsOfUseUrl.set("https://gradle.com/help/legal-terms-of-use")
        termsOfUseAgree.set("yes")
        publishing.onlyIf { System.getenv("CI") != null }
    }
}

在 CI 中跳过不必要的任务

# Skip tests for UI-only changes
./gradlew assembleDebug -x test -x lint

# Only run affected module tests
./gradlew :feature:login:test

---

Android Studio 设置

文件 → 设置 → 构建 → Gradle

• Gradle JDK：与项目的 JDK 保持一致
• 使用以下方式构建和运行：Gradle（而非 IntelliJ）
• 使用以下方式运行测试：Gradle

文件 → 设置 → 构建 → 编译器

• 并行编译独立模块：✅ 已启用
• 按需配置：❌ 已禁用（已弃用）

---

验证清单

优化后，请确认：

• 已启用配置缓存且运行正常
• 构建缓存命中率 > 80%（检查构建扫描）
• 没有动态依赖版本
• 在可行时使用 KSP 替代 kapt
• 已启用并行执行
• JVM 内存已适当调整
• 已配置 CI 远程缓存
• 配置阶段没有 I/O 操作

---

参考资料

• 优化构建速度
• Gradle 配置缓存
• Gradle 构建缓存
• 从 kapt 迁移到 KSP
• Gradle 构建扫描