IDEA 大型单体项目编译慢怎么配置 Gradle 并行构建优化？

对于 IDEA 中编译缓慢的大型单体 Gradle 项目，核心优化手段是在项目根目录的 gradle.properties 中开启并行构建并合理分配 JVM 内存。需注意 Gradle 7.0+ 已废弃部分旧参数，且大型项目内存需求远高于默认值，配置不当极易引发 OOM。

先说结论：开启并行构建能利用多核 CPU 同时编译独立模块，但必须配合足够的内存设置，并移除已废弃的配置项。

关键配置：设置 org.gradle.parallel=true 并将 JVM 堆内存提升至 4GB 以上。
IDEA 同步：确保 IDEA 使用的 Gradle JVM 与配置文件中的内存设置匹配。
验证方式：通过 IDEA Build 工具窗口观察任务并发数，或使用 `--profile` 生成性能报告。

核心配置参数（gradle.properties）

在项目根目录创建或编辑 gradle.properties 文件。以下配置适用于 Gradle 7.0+ 及大型单体项目，已移除废弃参数。

# 开启并行构建
org.gradle.parallel=true
# 开启构建缓存，加速增量构建
org.gradle.caching=true
# 设置 Gradle Daemon JVM 内存，大型项目建议 4g 起步，根据物理内存调整
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m -XX:+HeapDumpOnOutOfMemoryError
# 设置并行工作线程数，默认为 CPU 核心数，可根据实际情况固定
# org.gradle.workers.max=8

注意：org.gradle.configureondemand 在 Gradle 8.0+ 已完全无效，7.0+ 已废弃，请勿添加以免误导。

IDEA 具体设置步骤

仅修改配置文件可能不会立即生效，需确保 IDEA 的 Gradle 插件设置与配置文件一致。

打开设置面板
点击菜单栏 File > Settings (Mac 为 IntelliJ IDEA > Settings)，导航至 Build, Execution, Deployment > Build Tools > Gradle。
配置 Gradle JVM
找到 Gradle JVM 选项，确保选择的 JDK 版本与项目一致。若此处指定了特定 JVM，其内存设置可能覆盖 gradle.properties 中的部分参数，建议保持默认或确保内存充足。
构建委托设置
勾选 Delegate IDE build/run actions to gradle。
说明：勾选后，IDEA 的 Make Project 等操作将委托给 Gradle 执行，确保 gradle.properties 中的并行配置生效。若不勾选，IDEA 可能使用内部构建系统，导致配置无效。
应用并重启
点击 Apply 和 OK，建议重启 IDEA 或执行 Gradle > Stop Daemon 后重新构建，确保新内存参数加载。

验证与性能分析

配置完成后，需验证并行构建是否真正生效。

1. IDEA 构建窗口观察

执行 Build > Rebuild Project，观察底部 Build 工具窗口。开启并行后，日志输出会呈现交错状态，且多个模块的 Task 会同时处于执行状态。

2. 生成性能报告

在 Terminal 中执行以下命令生成详细报告：

gradle clean build `--profile`

构建完成后，打开 build/reports/profile 目录下的 HTML 文件。查看 Parallelism 章节，确认平均并发任务数是否大于 1，且总耗时相比之前有明显下降。

故障排查与常见坑

内存溢出（OOM）：
现象：构建过程中报错 Java heap space 或 Metaspace。
解决：逐步调高 org.gradle.jvmargs 中的 -Xmx 值（如 6144m），并确保物理内存充足。添加 -XX:+HeapDumpOnOutOfMemoryError 便于分析。
并行构建失败：
现象：某些任务报错文件占用或顺序错误。
排查：使用以下命令获取详细堆栈，定位具体冲突任务：
```
gradle build `--stacktrace` `--info`
```
若发现任务竞争，需在 build.gradle 中为相关任务添加显式依赖（mustRunAfter）或禁用该任务的并行。
配置未生效：
现象：构建速度无变化。
检查：确认未勾选 Delegate IDE build/run actions to gradle，或 IDEA 缓存干扰。尝试执行 Gradle > Stop Daemon 强制重启守护进程。
静态状态污染：
部分老旧插件依赖全局静态变量，并行环境下可能出错。若遇到诡异编译错误，尝试临时关闭 org.gradle.parallel=true 排查是否为插件兼容性问题。

参考来源

Gradle Official Documentation - Performance: https://docs.gradle.org/current/userguide/performance.html
JetBrains IntelliJ IDEA Documentation - Gradle Settings: https://www.jetbrains.com/help/idea/gradle-settings.html