Gradle/Android…

当 Android/Gradle 构建慢、需要分析 Build Scan、排查配置/执行瓶颈或优化 CI/CD 构建时间时使用。

适用场景

解决思路

1. 测量基线：记录 clean build 和 incremental build 的耗时，作为后续对比基准。
2. 生成 Build Scan：运行 `./gradlew assembleDebug --scan`，用于分析各阶段耗时和缓存命中。
3. 本地性能分析：运行 `./gradlew assembleDebug --profile`，报告位于 `build/reports/profile/`。
4. 构建计时摘要：运行 `./gradlew assembleDebug --info | grep -E "^\:.*"`，或在 Android Studio 中使用 Build > Analyze APK Build。
5. 按构建阶段定位：Initialization 阶段检查 `settings.gradle.kts` 是否包含过多 `include()`；Configuration 阶段检查昂贵插件和急切任务创建；Execution 阶段检查缓存未命中和非增量任务。
6. 识别瓶颈阶段：在 Build Scan 中查看 Performance → Build timeline；长配置阶段重点优化插件和 buildscript，长执行阶段重点优化任务缓存和并行化，依赖解析慢则优化仓库配置。
7. 每次只应用一个优化，不要批量修改；应用后测量改进并与基线对比，最后在 Build Scan 中视觉确认效果。
8. 启用配置缓存：在 `gradle.properties` 设置 `org.gradle.configuration-cache=true` 和 `org.gradle.configuration-cache.problems=warn`。
9. 启用构建缓存：在 `gradle.properties` 设置 `org.gradle.caching=true`，跨构建和机器复用任务输出。
10. 启用并行执行：在 `gradle.properties` 设置 `org.gradle.parallel=true`，同时构建独立模块。
11. 增加 JVM 堆内存：在 `gradle.properties` 设置 `org.gradle.jvmargs=-Xmx4g -XX:+UseParallelGC`。
12. 使用非传递 R 类：在 `gradle.properties` 设置 `android.nonTransitiveRClass=true`，减少 R 类大小和编译量（AGP 8.0+ 默认）。
13. 将 kapt 迁移到 KSP：把 `kapt("com.google.dagger:hilt-compiler:2.51.1")` 改为 `ksp("com.google.dagger:hilt-compiler:2.51.1")`，KSP 对 Kotlin 约快 2 倍。
14. 避免动态依赖：不要使用 `implementation("com.example:lib:+")` 或 `implementation("com.example:lib:1.0.+")`，改为固定版本如 `implementation("com.example:lib:1.2.3")`。
15. 优化仓库顺序：在 `settings.gradle.kts` 的 `dependencyResolutionManagement.repositories` 中把最常用的仓库放前面，例如 `google()` 第一、`mavenCentral()` 第二、第三方仓库最后。
16. 对本地模块使用 `includeBuild`：在 `settings.gradle.kts` 配置 `includeBuild("shared-library")` 并用 `dependencySubstitution` 替代 `project()`，适合大型 monorepo。
17. 启用增量注解处理：在 `gradle.properties` 设置 `kapt.incremental.apt=true` 和 `kapt.use.worker.api=true`。
18. 避免配置时 I/O：不要在配置阶段读文件或发起网络调用；用 `providers.fileContents(file("version.txt")).asText` 等延迟到执行阶段。
19. 使用懒任务配置：用 `tasks.register("myTask") { ... }` 替代 `tasks.create("myTask") { ... }`。
20. 慢配置阶段修复：用 `tasks.register()` 替代 `tasks.create()`；将含大量依赖的 buildSrc 迁移为 Convention Plugins 并结合 `includeBuild`；用 `providers.fileContents()` 替代构建脚本中的文件 I/O；缓存插件网络调用结果或使用离线模式。
21. 慢编译修复：避免改动 `build.gradle.kts` 导致缓存失效；将大模块拆分为更小的 feature 模块；将 kapt 迁移到 KSP；增加 `kotlin.daemon.jvmargs`。
22. 缓存未命中修复：对不稳定任务输入使用 `@PathSensitive`、`@NormalizeLineEndings`；输出使用相对路径而非绝对路径；为自定义任务添加 `@CacheableTask`；在不同环境统一 JDK 版本。
23. 配置远程构建缓存：在 `settings.gradle.kts` 的 `buildCache` 中启用 `local`，并配置 `remote<HttpBuildCache>`，设置 `url`、`isPush = System.getenv("CI") == "true"`、用户名和密码从环境变量读取。
24. 配置 Develocity/Gradle Enterprise：在 `settings.gradle.kts` 应用 `id("com.gradle.develocity") version "3.17"`，设置 `develocity.buildScan` 的 `termsOfUseUrl`、`termsOfUseAgree`，并仅在 CI 中发布构建扫描。
25. 在 CI 中跳过不必要任务：例如 UI 变更时运行 `./gradlew assembleDebug -x test -x lint`；只运行受影响模块测试，例如 `./gradlew :feature:login:test`。
26. Android Studio Gradle 设置：File → Settings → Build → Gradle 中，`Gradle JDK` 匹配项目 JDK，`Build and run using` 选择 Gradle（不是 IntelliJ），`Run tests using` 选择 Gradle。
27. Android Studio Compiler 设置：File → Settings → Build → Compiler 中，启用 `Compile independent modules in parallel`，禁用已废弃的 `Configure on demand`。
28. 优化后验证：确认配置缓存已启用并正常工作；构建缓存命中率 > 80%（查看 Build Scan）；无动态依赖版本；尽可能用 KSP 替代 kapt；并行执行已启用；JVM 内存已适当调优；CI 远程缓存已配置；无配置时 I/O。

适用边界 · 注意事项

• 不适用于非 Gradle/Android 构建系统（如 Maven、Bazel、Xcode）的项目。
• 当项目使用的 Gradle/AGP 版本或插件不兼容配置缓存时，不要直接忽略问题强制开启，而应先用 `org.gradle.configuration-cache.problems=warn` 排查并解决。
• 不要在未建立构建基线和 Build Scan 数据时一次性批量应用优化，否则无法判断单项优化效果。