最有效、最优先的操作是调大org.gradle.jvmargs，需组合配置：-Xmx4096m -Xms2048m -XX:MaxMetaspaceSize=1g -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8，并确保项目级gradle.properties生效且Daemon重启。
直接调大 org.gradle.jvmargs 是最有效、最优先的操作，90% 的内存不足退出都靠这一步解决。
gradle.properties 里怎么配 org.gradle.jvmargs
项目根目录下的 gradle.properties 是第一生效位置。不要只写 -Xmx2048m，要组合设置：
-
-Xmx4096m：必须设，这是最大堆内存，低配机器（如 4GB 物理内存）建议先设为3072m，避免启动失败 -
-Xms2048m：建议显式指定初始堆大小，减少运行中扩容次数 -
-XX:MaxMetaspaceSize=1g：Java 8+ 必须用这个替代已废弃的-XX:MaxPermSize，否则可能报OutOfMemoryError: Metaspace -
-XX:+HeapDumpOnOutOfMemoryError：加了它，OOM 时会自动生成java_pid*.hprof文件，方便后续分析 -
-Dfile.encoding=UTF-8：避免因编码问题引发隐性资源加载失败
完整示例：
org.gradle.jvmargs=-Xmx4096m -Xms2048m -XX:MaxMetaspaceSize=1g -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8
为什么改了 gradle.properties 还没生效
Gradle 会按优先级加载 JVM 参数，顺序是：命令行参数 > 全局配置（~/.gradle/gradle.properties）> 项目级配置（项目根目录）。常见失效原因：
- 全局配置里已有
org.gradle.jvmargs，且值更小，把项目级的覆盖了 - IDE（如 Android Studio）自带的 Gradle 运行配置里硬编码了 JVM 参数，优先级高于文件配置
- 用了
./gradlew --stop或杀掉了所有gradle进程，但新参数只在下次 Daemon 启动时读取——得等 Daemon 重建才生效 - 某些 CI 环境禁用了 Daemon（
org.gradle.daemon=false），导致每次都是全新 JVM，根本不会读gradle.properties
验证是否生效：执行 ./gradlew --status，看输出中 “JVM args” 是否包含你设的值；或者跑一次 ./gradlew build --no-daemon -Dorg.gradle.jvmargs="-Xmx1024m" 强制测试。
Android 项目还要额外处理 DEX 阶段内存
Gradle 守护进程的内存和 DEX 编译（D8/R8）用的 JVM 是两套独立进程。即使 org.gradle.jvmargs 调得再大，UNEXPECTED TOP-LEVEL ERROR 或 java.lang.OutOfMemoryError: Java heap space 仍可能在 DEX 阶段爆发。
- AGP 4.2–7.x：在
app/build.gradle的android { }块内加：dexOptions { javaMaxHeapSize "4g" } - AGP 7.0+：该配置已被弃用，应升级 R8 并改用：
android { compileOptions { } }或直接在gradle.properties中增加：android.useAndroidX=true+android.enableJetifier=true（确保兼容性） - 如果构建日志里出现类似
3797897216 > 3263168512的数字对比，说明 JVM 启动时申请堆内存失败——这不是代码问题，是系统可用内存不足，需清理后台进程或升级硬件
真正卡住人的地方，往往不是参数写错，而是忘了 Daemon 重启不自动加载新配置，或者混淆了 Gradle 进程和 DEX 工具进程的内存边界。改完配置后，别急着重试，先 ./gradlew --stop 再跑一次构建，让新参数落地。低配设备上，宁可关掉 org.gradle.parallel=true，也别盲目堆内存。
