Gradle 執行失敗：Unknown command-line option '-X' 解決實錄

在 Android Studio / IntelliJ IDEA 中建置專案時，控制台輸出 Error: Failed to complete Gradle execution. Cause: Unknown command-line option '-X'。這通常是因為在 Settings → Build, Execution, Deployment → Compiler → Command-line Options 中填入了 JVM 參數（如 -Xmx750m -XX:MaxPermSize=512m ...），但 Gradle 編譯器並不直接識別這些選項。

錯誤原因分析

• IDE 的 Compiler → Command-line Options 欄位是傳遞給 javac 編譯器的參數，而 -Xmx、-XX:* 是 Java 執行器（java 命令） 的參數，javac 不支援，故報 Unknown command-line option。
• Gradle 建置過程中，編譯任務由 JavaCompile 執行，其 compilerArgs 對應 javac 參數；JVM 參數應設定在 gradle.properties 或 build.gradle 的 javaOptions / dexOptions 中。

正確配置方式

方法一：gradle.properties（全域生效，推薦）

org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

重啟 Gradle Daemon 即可生效（./gradlew --stop 後再建置）。

方法二：build.gradle（專案級）

android {
    compileOptions {
        // ...
    }
    dexOptions {
        javaMaxHeapSize "2g"
    }
}
tasks.withType(JavaCompile) {
    options.fork = true
    options.forkOptions.jvmArgs << "-Xmx2048m" << "-XX:MaxMetaspaceSize=512m" << "-Dfile.encoding=UTF-8"
}

方法三：Android Studio 設定（僅影響 IDE 內建建置）

路徑：Settings → Build, Execution, Deployment → Build Tools → Gradle → Gradle VM options，填入：

-Xmx2048m -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

避坑指南

1. 切勿 在 Compiler → Command-line Options 填寫 JVM 參數。
2. -XX:MaxPermSize 在 Java 8+ 已廢棄，改用 -XX:MaxMetaspaceSize。
3. 若專案使用本地 Gradle 發佈，確認 gradle-wrapper.properties 版本與本地一致。
4. 部分網路環境下首次建置需下載依賴，若卡住可嘗試開啟 VPN 或配置阿里雲 Maven 鏡像：

// build.gradle repositories 區塊
maven { url 'https://maven.aliyun.com/repository/public' }
maven { url 'https://maven.aliyun.com/repository/google' }

實測有效方案

筆者實測：刪除 Compiler → Command-line Options 中的 JVM 參數，改在 gradle.properties 設定 org.gradle.jvmargs，並配置阿里雲鏡像後，建置恢復正常，且無需每日開啟 VPN。