配置建置環境是自訂建置程序的強大方法。有許多可用的機制。透過利用這些機制，您可以讓 Gradle 建置更具彈性，並更能適應不同的環境和需求。

可用的機制

Gradle 提供多種機制來配置 Gradle 本身和特定專案的行為

機制 資訊 範例

命令列介面

配置建置行為和 Gradle 功能的旗標

--rerun

專案屬性

特定於 Gradle 專案的屬性

TestFilter::isFailOnNoMatchingTests=false

系統屬性

傳遞至 Gradle 執行階段 (JVM) 的屬性

http.proxyHost=somehost.org

Gradle 屬性

配置 Gradle 設定和執行建置之 Java 程序的屬性

org.gradle.logging.level=quiet

環境變數

根據環境配置建置行為的屬性

JAVA_HOME

組態的優先順序

配置 Gradle 行為時，您可以使用這些方法，但您必須考慮其優先順序。

下表列出這些方法的優先順序，從最高到最低（第一個優先）

優先順序 方法 位置 注意事項

1

命令列

> 命令列

旗標的優先順序高於屬性和環境變數

2

系統屬性

> 專案根目錄

儲存在 gradle.properties 檔案中

3

Gradle 屬性

> GRADLE_USER_HOME
> 專案根目錄
> GRADLE_HOME

儲存在 gradle.properties 檔案中

4

環境變數

> 環境

由執行 Gradle 的環境提供來源

以下是指定 JDK 安裝目錄的所有可能組態，依優先順序排列

  1. 命令列

    $ ./gradlew exampleTask -Dorg.gradle.java.home=/path/to/your/java/home --scan

  2. Gradle 屬性檔案

    gradle.properties
    org.gradle.java.home=/path/to/your/java/home

  3. 環境變數

    $ export JAVA_HOME=/path/to/your/java/home

gradle.properties 檔案

Gradle 屬性、系統屬性和專案屬性可以在 gradle.properties 檔案中找到

gradle.properties
# Gradle properties
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.jvmargs=-Duser.language=en -Duser.country=US -Dfile.encoding=UTF-8

# System properties
systemProp.pts.enabled=true
systemProp.log4j2.disableJmx=true
systemProp.file.encoding = UTF-8

# Project properties
kotlin.code.style=official
android.nonTransitiveRClass=false
spring-boot.version = 2.2.1.RELEASE

您可以將 gradle.properties 檔案放在專案的根目錄、Gradle 使用者主目錄 (GRADLE_USER_HOME) 或 Gradle 選擇性安裝的目錄 (GRADLE_HOME) 中。

解析屬性時，Gradle 首先在專案層級的 gradle.properties 檔案中尋找，然後在位於 GRADLE_USER_HOME 的使用者層級 gradle.properties 檔案中尋找，最後在位於 GRADLE_HOME 的 gradle.properties 檔案中尋找，其中專案層級屬性的優先順序高於使用者層級和安裝層級屬性。

專案屬性

專案屬性特定於您的 Gradle 專案，它們可以用於自訂您的建置。專案屬性可以在您的建置檔案中存取，並在執行建置時從外部來源傳遞進來。專案屬性可以使用 providers.gradleProperty() 延遲檢索。

設定專案屬性

您有四個選項可以新增專案屬性，依優先順序排列

  1. 命令列： 您可以使用 -P 命令列選項直接將專案屬性新增至您的 Project 物件。

    $ ./gradlew build -PmyProperty='Hi, world'

  2. 系統屬性： Gradle 為專案屬性建立特別命名的系統屬性，您可以使用 -D 命令列旗標或 gradle.properties 檔案來設定這些屬性。對於專案屬性 myProperty，建立的系統屬性稱為 org.gradle.project.myProperty。

    $ ./gradlew build -Dorg.gradle.project.myProperty='Hi, world'
    gradle.properties
    org.gradle.project.myProperty='Hi, world'

  3. Gradle 屬性檔案： 您也可以在 gradle.properties 檔案中設定專案屬性。

    gradle.properties
    myProperty='Hi, world'

  4. 環境變數： 您可以使用環境變數設定專案屬性。如果環境變數名稱看起來像 ORG_GRADLE_PROJECT_myProperty='Hi, world'，則 Gradle 會在您的專案物件上設定 myProperty 屬性，值為 Hi, world。

    $ export ORG_GRADLE_PROJECT_myProperty='Hi, world'

    這通常是提供專案屬性（尤其是機密資訊）給無人值守建置（例如在 CI 伺服器上執行的建置）的慣用方法。

可以根據在調用時指定的專案屬性來變更工作的行為。假設您想要確保僅由 CI 觸發發行版本建置。處理此問題的簡單方法是透過 isCI 專案屬性

build.gradle.kts
tasks.register("performRelease") {
    val isCI = providers.gradleProperty("isCI")
    doLast {
        if (isCI.isPresent) {
            println("Performing release actions")
        } else {
            throw InvalidUserDataException("Cannot perform release outside of CI")
        }
    }
}
build.gradle
tasks.register('performRelease') {
    def isCI = providers.gradleProperty("isCI")
    doLast {
        if (isCI.present) {
            println("Performing release actions")
        } else {
            throw new InvalidUserDataException("Cannot perform release outside of CI")
        }
    }
}
$ ./gradlew performRelease -PisCI=true --quiet
Performing release actions

請注意，只要您的 gradle.properties 檔案包含 isCI=true，執行 ./gradlew performRelease 就會產生相同的結果

gradle.properties
isCI=true
$ ./gradlew performRelease --quiet
Performing release actions

命令列旗標

命令列介面和可用的旗標在 其自己的章節 中描述。

系統屬性

系統屬性是在 JVM 層級設定的變數，可供 Gradle 建置程序存取。系統屬性可以使用 providers.systemProperty() 延遲檢索。

設定系統屬性

您有兩個選項可以新增系統屬性，依優先順序排列

  1. 命令列： 使用 -D 命令列選項，您可以將系統屬性傳遞至執行 Gradle 的 JVM。gradle 命令的 -D 選項與 java 命令的 -D 選項具有相同的效果。

    $ ./gradlew build -Dgradle.wrapperUser=myuser

  2. Gradle 屬性檔案： 您也可以在 gradle.properties 檔案中使用字首 systemProp 設定系統屬性。

    gradle.properties
    systemProp.gradle.wrapperUser=myuser

系統屬性參考

為了快速參考，以下是常見的系統屬性

gradle.wrapperUser=(myuser)

指定使用者名稱以使用 HTTP 基本驗證從伺服器下載 Gradle 發行版本。

gradle.wrapperPassword=(mypassword)

指定密碼以使用 Gradle Wrapper 下載 Gradle 發行版本。

gradle.user.home=(目錄路徑)

指定 GRADLE_USER_HOME 目錄。

https.protocols

以逗號分隔的格式指定支援的 TLS 版本。例如，TLSv1.2,TLSv1.3。

其他 Java 系統屬性列在這裡。

在多專案建置中，除了根專案之外，在任何專案中設定的 systemProp 屬性都將被忽略。只會檢查根專案的 gradle.properties 檔案中以 systemProp 開頭的屬性。

Gradle 屬性

Gradle 屬性配置 Gradle 本身，通常具有名稱 org.gradle.\*。Gradle 屬性不應在建置邏輯中使用，其值不應讀取/檢索。

設定 Gradle 屬性

您有兩個選項可以新增 Gradle 屬性，依優先順序排列

  1. 命令列： 使用 -D 命令列選項，您可以傳遞 Gradle 屬性

    $ ./gradlew build -Dorg.gradle.caching.debug=false

  2. Gradle 屬性檔案： 將這些設定放入 gradle.properties 檔案並提交到您的版本控制系統。

    gradle.properties
    org.gradle.caching.debug=false

Gradle 考慮的最終組態是命令列和您的 gradle.properties 檔案中設定的所有 Gradle 屬性的組合。如果在多個位置配置選項，則在任何這些位置找到的第一個選項獲勝

優先順序 方法 位置 詳細資訊

1

命令列介面

.

在命令列中使用 -D。

2

gradle.properties 檔案

GRADLE_USER_HOME

儲存在 GRADLE_USER_HOME 中的 gradle.properties 檔案中。

3

gradle.properties 檔案

專案根目錄

儲存在專案目錄中的 gradle.properties 檔案中，然後是其父專案的目錄，直到專案的根目錄。

4

gradle.properties 檔案

GRADLE_HOME

儲存在 GRADLE_HOME 中的 gradle.properties 檔案中，這是 Gradle 的選擇性安裝目錄。
GRADLE_USER_HOME 的位置可能已事先透過在命令列上傳遞的 -Dgradle.user.home 系統屬性變更。

Gradle 屬性參考

為了參考，以下屬性是常見的 Gradle 屬性

org.gradle.caching=(true,false)

當設定為 true 時，Gradle 將在可能的情況下重複使用先前建置的工作輸出，從而加快建置速度。

預設值為 false；建置快取未啟用。

org.gradle.caching.debug=(true,false)

當設定為 true 時，每個工作的個別輸入屬性雜湊和建置快取金鑰都會記錄在主控台上。

預設值為 false。

org.gradle.configuration-cache=(true,false)

啟用組態快取。Gradle 將嘗試重複使用先前建置中的建置組態。

預設值為 false。

org.gradle.configureondemand=(true,false)

啟用孵化中的隨需配置，其中 Gradle 將嘗試僅配置必要的專案。

預設值為 false。

org.gradle.console=(auto,plain,rich,verbose)

自訂主控台輸出色彩或詳細程度。

預設值取決於 Gradle 的調用方式。

org.gradle.continue=(true,false)

如果啟用，則在工作失敗後繼續工作執行，否則在工作失敗後停止工作執行。

預設值為 false。

org.gradle.daemon=(true,false)

當設定為 true 時，Gradle Daemon 用於執行建置。

預設值為 true。

org.gradle.daemon.idletimeout=(# 個閒置毫秒)

Gradle Daemon 將在指定的閒置毫秒數後自行終止。

預設值為 10800000（3 小時）。

org.gradle.debug=(true,false)

當設定為 true 時，Gradle 將在啟用遠端偵錯的情況下執行建置，並在埠 5005 上接聽。請注意，這相當於將 -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 新增至 JVM 命令列，並將暫停虛擬機器，直到附加偵錯工具為止。

預設值為 false。

org.gradle.java.home=(JDK 首頁路徑)

指定 Gradle 建置程序的 Java 首頁。該值可以設定為 jdk 或 jre 位置；但是，根據您的建置執行操作，使用 JDK 更安全。這不會影響用於啟動 Gradle 用戶端 VM 的 Java 版本。

您也可以使用 Daemon JVM 準則來控制用於執行 Gradle 本身的 JVM。

如果未指定設定，則預設值衍生自您的環境 (JAVA_HOME 或 java 路徑)。

org.gradle.jvmargs=(JVM 引數)

指定用於 Gradle Daemon 的 JVM 引數。此設定對於配置 JVM 記憶體設定以提高建置效能特別有用。這不會影響 Gradle 用戶端 VM 的 JVM 設定。

預設值為 -Xmx512m "-XX:MaxMetaspaceSize=384m"。

org.gradle.logging.level=(quiet,warn,lifecycle,info,debug)

當設定為 quiet、warn、info 或 debug 時，Gradle 將使用此記錄層級。這些值不區分大小寫。

預設值為 lifecycle 層級。

org.gradle.parallel=(true,false)

配置後，Gradle 將分支最多 org.gradle.workers.max 個 JVM 以平行執行專案。

預設值為 false。

org.gradle.priority=(low,normal)

指定 Gradle Daemon 和其啟動的所有程序的排程優先順序。

預設值為 normal。

org.gradle.projectcachedir=(目錄)

指定專案特定的快取目錄。預設為根專案目錄中的 .gradle。」

預設值為 .gradle。

org.gradle.problems.report=(true|false)

啟用 (true) 或停用 (false) build/reports/problems-report.html 的產生。true 是預設值。報告是使用提供給Problems API 的問題產生的。

org.gradle.unsafe.isolated-projects=(true,false)

啟用專案隔離，從而啟用組態快取。

預設值為 false。

org.gradle.vfs.verbose=(true,false)

在監看檔案系統時，配置詳細記錄。

預設值為 false。

org.gradle.vfs.watch=(true,false)

切換監看檔案系統。啟用後，Gradle 會重複使用在建置之間收集的有關檔案系統的資訊。

在 Gradle 支援此功能的作業系統上，預設值為 true。

org.gradle.warning.mode=(all,fail,summary,none)

當設定為 all、summary 或 none 時，Gradle 將使用不同的警告類型顯示。

預設值為 summary。

org.gradle.workers.max=(最大工作程序數)

配置後，Gradle 將最多使用給定數量的 Worker。

預設值為 CPU 處理器數量。

環境變數

Gradle 提供許多環境變數，如下所示。環境變數可以使用 providers.environmentVariable() 延遲檢索。

設定環境變數

讓我們舉一個設定 $JAVA_HOME 環境變數的範例

$ set JAVA_HOME=C:\Path\To\Your\Java\Home   // Windows
$ export JAVA_HOME=/path/to/your/java/home  // Mac/Linux

您可以使用 System.getenv() 方法在建置腳本中以屬性形式存取環境變數

task printEnvVariables {
    doLast {
        println "JAVA_HOME: ${System.getenv('JAVA_HOME')}"
    }
}

環境變數參考

以下環境變數可用於 gradle 命令

GRADLE_HOME

Gradle 的安裝目錄。

可用於指定本機 Gradle 版本，而不是使用 Wrapper。

您可以將 GRADLE_HOME/bin 新增至您的 PATH 以用於特定應用程式和使用案例（例如測試 Gradle 的早期版本）。

JAVA_OPTS

用於將 JVM 選項和自訂設定傳遞至 JVM。

export JAVA_OPTS="-Xmx18928m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Dkotlin.daemon.jvm.options=-Xmx6309m"

GRADLE_OPTS

指定在啟動 Gradle 用戶端 VM 時要使用的 JVM 引數。

用戶端 VM 僅處理命令列輸入/輸出，因此很少需要變更其 VM 選項。

實際的建置由 Gradle Daemon 執行，不受此環境變數的影響。

GRADLE_USER_HOME

指定 GRADLE_USER_HOME 目錄，供 Gradle 儲存其全域組態屬性、初始化腳本、快取、記錄檔等。

如果未設定，則預設為 USER_HOME/.gradle。

JAVA_HOME

指定用於用戶端 VM 的 JDK 安裝目錄。

除非在 Gradle 屬性檔案中使用 org.gradle.java.home 或使用 Daemon JVM 準則指定不同的 JDK 安裝目錄，否則此 VM 也用於 Daemon。

GRADLE_LIBS_REPO_OVERRIDE

預設 Gradle 程式庫儲存庫的覆寫。

可用於在 org.gradle.plugins.ide.internal.resolver 中指定預設 Gradle 儲存庫 URL。

如果您公司使用防火牆/Proxy，則此覆寫對於指定內部託管的儲存庫非常有用。