Gradle Build Performance 是一套面向 Android/Gradle 构建性能的调试与优化指南，适用于构建缓慢、排查构建性能回归、分析 Gradle Build Scan、识别配置阶段与执行阶段瓶颈、优化 CI/CD 构建时间、启用 Gradle 配置缓存、减少不必要的重编译以及调试 kapt/KSP 注解处理等场景。
主要能力与工作流： 该技能建议按以下流程操作：先测量基线（干净构建与增量构建时间），再生成 Build Scan（./gradlew assembleDebug --scan），然后识别瓶颈阶段（配置、执行还是依赖解析），每次只应用一项优化，测量改进并与基线对比，最后在 Build Scan 中验证效果。
快速诊断命令： 生成 Build Scan：./gradlew assembleDebug --scan 本地性能分析：./gradlew assembleDebug --profile（报告位于 build/reports/profile/） 构建计时摘要：./gradlew assembleDebug --info | grep -E "^:.*"，或在 Android Studio 中通过 Build > Analyze APK Build 查看。
构建阶段与常见问题： 初始化阶段评估 settings.gradle.kts，常见问题是 include() 语句过多；配置阶段评估所有 build.gradle.kts 文件，常见问题是昂贵的插件和急切任务创建；执行阶段根据输入/输出运行任务，常见问题是缓存未命中和非增量任务。通过 Build Scan 的 Performance → Build timeline 可定位瓶颈：配置阶段过长应优化插件和 buildscript；执行阶段过长应优化任务缓存和并行化；依赖解析慢应优化仓库配置。
12 种优化模式：
- 启用配置缓存（AGP 8.0+）：org.gradle.configuration-cache=true，org.gradle.configuration-cache.problems=warn
- 启用构建缓存：org.gradle.caching=true
- 启用并行执行：org.gradle.parallel=true
- 增加 JVM 堆内存：org.gradle.jvmargs=-Xmx4g -XX:+UseParallelGC
- 使用非传递 R 类：android.nonTransitiveRClass=true（AGP 8.0+ 默认）
- 从 kapt 迁移到 KSP：将 kapt("com.google.dagger:hilt-compiler:2.51.1") 改为 ksp("com.google.dagger:hilt-compiler:2.51.1")
- 避免动态依赖：使用固定版本 implementation("com.example:lib:1.2.3")，而非 implementation("com.example:lib:+")
- 优化仓库顺序：在 settings.gradle.kts 的 dependencyResolutionManagement 中把 google() 放首位，mavenCentral() 次之，第三方仓库最后
- 对本地模块使用 includeBuild：复合构建在大规模 monorepo 中比 project() 更快
- 启用增量注解处理：kapt.incremental.apt=true，kapt.use.worker.api=true
- 避免配置期 I/O：使用 providers.fileContents(file("version.txt")).asText 而非 file("version.txt").readText()
- 使用惰性任务配置：使用 tasks.register() 而非 tasks.create()
常见瓶颈分析： 配置阶段慢：原因包括急切任务创建（改用 tasks.register()）、buildSrc 依赖过多（迁移到 Convention Plugins 配合 includeBuild）、构建脚本中的文件 I/O（改用 providers.fileContents()）、插件中的网络调用（缓存结果或使用离线模式）。 编译慢：原因包括非增量变更（避免修改会失效缓存的 build.gradle.kts）、模块过大（拆分为更小的功能模块）、kapt 使用过多（迁移到 KSP）、Kotlin 编译器内存不足（增加 kotlin.daemon.jvmargs）。 缓存未命中：原因包括任务输入不稳定（使用 @PathSensitive、@NormalizeLineEndings）、输出中使用绝对路径（改用相对路径）、缺少 @CacheableTask（为自定义任务添加注解）、JDK 版本不一致（统一各环境的 JDK）。
CI/CD 优化： 远程构建缓存：在 settings.gradle.kts 中配置 buildCache，启用 local 并配置 remote<HttpBuildCache>，设置 url、isPush（CI 环境为 true）以及凭据。 Gradle Enterprise / Develocity：通过插件 id("com.gradle.develocity") version "3.17" 启用高级构建分析，配置 buildScan 的 termsOfUseUrl、termsOfUseAgree 和 publishing.onlyIf。 跳过 CI 中不必要的任务：例如 ./gradlew assembleDebug -x test -x lint，或只运行受影响模块的测试 ./gradlew :feature:login:test。
Android Studio 设置建议： File → Settings → Build → Gradle：Gradle JDK 与项目 JDK 匹配；Build and run using 选择 Gradle（而非 IntelliJ）；Run tests using 选择 Gradle。 File → Settings → Build → Compiler：启用 Compile independent modules in parallel；禁用 Configure on demand（已弃用）。
验证清单： 优化后需确认：配置缓存已启用且正常工作；构建缓存命中率大于 80%（查看 Build Scan）；无动态依赖版本；尽可能使用 KSP 替代 kapt；已启用并行执行；JVM 内存已适当调整；CI 远程缓存已配置；无配置期 I/O。
参考资料： Optimize Build Speed、Gradle Configuration Cache、Gradle Build Cache、Migrate from kapt to KSP、Gradle Build Scans。