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

以下是使用這些機制的參考

機制 資訊 範例

命令列介面

設定建置行為和 Gradle 功能的旗標

--rerun

專案屬性

專屬於 Gradle 專案的屬性

TestFilter::isFailOnNoMatchingTests=false

系統屬性

傳遞給 Gradle 執行時期 (JVM) 的屬性

systemProp.http.proxyHost=somehost.org

Gradle 屬性

設定 Gradle 設定的屬性

org.gradle.caching=true

環境變數

根據環境設定建置行為的屬性

JAVA_HOME

設定優先順序

設定 Gradle 行為時，可以使用這些方法，但必須考慮其優先順序。下表列出這些方法，從最高優先順序到最低優先順序 (第一個優先)

優先順序 方法 位置 範例 詳細資料

1

命令列旗標

命令列

--build-cache

這些優先於屬性和環境變數。

2

系統屬性

專案根目錄

systemProp.http.proxyPort=443

儲存在 gradle.properties 檔案中。

3

Gradle 屬性

GRADLE_USER_HOME
專案根目錄
GRADLE_HOME

org.gradle.logging.level=quiet

儲存在 gradle.properties 檔案中。

4

環境變數

環境

GRADLE_OPTS

由執行 Gradle 的環境提供。

專案屬性

專案屬性專屬於您的 Gradle 專案。它們使用組塊在您的建置指令碼或直接在 project 物件中定義。

例如，專案屬性 myProperty 在建置檔案中建立

build.gradle
ext {
    myProperty = findProperty('myProperty') ?: 'Hello, world!'
}

println "My property value: ${project.ext.myProperty}"

您有兩個選項可以新增專案屬性，其優先順序如下

  1. 命令列：您可以透過 -P 命令列選項直接將屬性新增到您的 Project 物件。

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

  2. 系統屬性或環境變數：您可以使用特別命名的系統屬性或環境變數設定專案屬性。

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

如果環境變數名稱看起來像 ORG_GRADLE_PROJECT_prop=somevalue，則 Gradle 會在您的專案物件上設定一個 prop 屬性，其值為 somevalue。Gradle 也支援系統屬性，但命名模式不同，看起來像 org.gradle.project.prop。

下列範例會將您的專案物件上的 foo 屬性設定為 "bar"。

範例 1：透過命令列設定專案屬性。

$ ./gradlew build -Pfoo=bar

範例 2：透過系統屬性設定專案屬性。

gradle.properties
org.gradle.project.foo=bar

範例 3：透過環境變數設定專案屬性。

$ export ORG_GRADLE_PROJECT_foo=bar

這個功能在您沒有連續整合伺服器的管理員權限，而且需要設定不容易看到的屬性值時非常有用。由於您無法在該情境中使用 -P 選項，也無法變更系統層級的設定檔，因此正確的策略是變更連續整合建置作業的設定，新增符合預期模式的環境變數設定。這對於系統上的一般使用者來說不會是可見的。

您可以在建置指令碼中使用專案屬性的名稱來存取該屬性，就像變數一樣。

命令列旗標

命令列介面和可用的旗標說明於 其專屬區段 中。

系統屬性

系統屬性是在 JVM 層級設定的變數，且可供 Gradle 建置程序存取。系統屬性可以使用建置指令碼中的 System 類別存取。常見的系統屬性如下列出。

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

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

    $ ./gradlew build -Dgradle.wrapperUser=myuser

  2. gradle.properties 檔案：您也可以在 gradle.properties 檔案中設定系統屬性，其字首為 systemProp

    gradle.properties
    systemProp.gradle.wrapperUser=myuser
systemProp.gradle.wrapperPassword=mypassword

以下是常見的系統屬性

gradle.wrapperUser=(myuser)

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

gradle.wrapperPassword=(mypassword)

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

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

指定 GRADLE_USER_HOME 目錄。

https.protocols

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

其他 Java 系統屬性列於 此處。

在多專案建置中，在根目錄專案以外的任何專案中設定的 systemProp 屬性將會略過。只有根目錄專案的 gradle.properties 檔案會檢查以 systemProp 開頭的屬性。

下列範例示範如何使用系統屬性

範例 1：使用 gradle.properties 檔案設定系統屬性

gradle.properties
systemProp.system=gradlePropertiesValue

範例 2：在組態時間讀取系統屬性

init.gradle.kts
// Using the Java API
println(System.getProperty("system"))
settings.gradle.kts
// Using the Java API
println(System.getProperty("system"))

// Using the Gradle API, provides a lazy Provider<String>
println(providers.systemProperty("system").get())
build.gradle.kts
// Using the Java API
println(System.getProperty("system"))

// Using the Gradle API, provides a lazy Provider<String>
println(providers.systemProperty("system").get())
init.gradle
// Using the Java API
println System.getProperty('system')
settings.gradle
// Using the Java API
println System.getProperty('system')

// Using the Gradle API, provides a lazy Provider<String>
println providers.systemProperty('system').get()
build.gradle
// Using the Java API
println System.getProperty('system')

// Using the Gradle API, provides a lazy Provider<String>
println providers.systemProperty('system').get()

範例 3：讀取系統屬性以在執行時間使用

build.gradle.kts
tasks.register<PrintValue>("printProperty") {
    // Using the Gradle API, provides a lazy Provider<String> wired to a task input
    inputValue = providers.systemProperty("system")
}
build.gradle
tasks.register('printProperty', PrintValue) {
    // Using the Gradle API, provides a lazy Provider<String> wired to a task input
    inputValue = providers.systemProperty('system')
}

範例 4：從命令列設定系統屬性 -D gradle.wrapperUser=username

$ gradle -Dsystem=commandLineValue

Gradle 屬性

Gradle 提供了多種選項，讓您可以輕鬆設定用於執行建置的 Java 程序。雖然您可以透過 `GRADLE_OPTS` 或 `JAVA_OPTS` 在您的本機環境中設定這些選項，但將某些設定（例如 JVM 記憶體設定和 `JAVA_HOME` 位置）儲存在版本控制中非常有用，這樣整個團隊就可以在一致的環境中工作。

您有一個選項可以新增 Gradle 屬性

  1. `gradle.properties` 檔案：將這些設定放入 `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 屬性

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 執行時期環境 的 Java 版本。

如果未指定設定，預設值會從您的環境（JAVA_HOME 或 java 的路徑）取得。

org.gradle.jvmargs=(JVM 引數)

指定用於 Gradle Daemon 的 JVM 引數。此設定對於 設定 JVM 記憶體設定 以提升建置效能特別有用。這不會影響 Gradle 執行時期環境的 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.unsafe.isolated-projects=(true,false)

啟用專案隔離，這會啟用設定快取。

預設為 `false`。

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

在 監控檔案系統 時設定詳細記錄。

預設為 `false`。

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

切換監控檔案系統。啟用時，Gradle 會在建置之間重複使用它從檔案系統收集的資訊。

預設為 true，適用於 Gradle 支援此功能的操作系統。

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

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

預設為 summary。

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

設定後，Gradle 會使用給定的工作程序數量作為上限。

預設為 CPU 處理器的數量。

下列範例示範如何使用 Gradle 屬性。

範例 1：使用 gradle.properties 檔案設定 Gradle 屬性

gradle.properties
gradlePropertiesProp=gradlePropertiesValue
gradleProperties.with.dots=gradlePropertiesDottedValue

範例 2：在設定時間讀取 Gradle 屬性

settings.gradle.kts
// Using the API, provides a lazy Provider<String>
println(providers.gradleProperty("gradlePropertiesProp").get())

// Using Kotlin delegated properties on `settings`
val gradlePropertiesProp: String by settings
println(gradlePropertiesProp)
build.gradle.kts
// Using the API, provides a lazy Provider<String>
println(providers.gradleProperty("gradlePropertiesProp").get())

// Using Kotlin delegated properties on `project`
val gradlePropertiesProp: String by project
println(gradlePropertiesProp)
settings.gradle
// Using the API, provides a lazy Provider<String>
println providers.gradleProperty('gradlePropertiesProp').get()

// Using Groovy dynamic names
println gradlePropertiesProp
println settings.gradlePropertiesProp

// Using Groovy dynamic array notation on `settings`
println settings['gradlePropertiesProp']
build.gradle
// Using the API, provides a lazy Provider<String>
println providers.gradleProperty('gradlePropertiesProp').get()

// Using Groovy dynamic names
println gradlePropertiesProp
println project.gradlePropertiesProp

// Using Groovy dynamic array notation on `project`
println project['gradlePropertiesProp']

Kotlin 委派屬性是 Gradle Kotlin DSL 的一部分。您需要明確指定類型為 String。如果您需要根據屬性的存在與否進行分支，您也可以使用 String? 並檢查 null。

請注意，如果 Gradle 屬性的名稱包含句點，則無法使用動態 Groovy 名稱。您必須改用 API 或動態陣列表示法。

範例 3：讀取 Gradle 屬性以供執行時間使用

build.gradle.kts
tasks.register<PrintValue>("printProperty") {
    // Using the API, provides a lazy Provider<String> wired to a task input
    inputValue = providers.gradleProperty("gradlePropertiesProp")
}
build.gradle
tasks.register('printProperty', PrintValue) {
    // Using the API, provides a lazy Provider<String> wired to a task input
    inputValue = providers.gradleProperty('gradlePropertiesProp')
}

範例 4：從命令列設定 Gradle 屬性

$ gradle -DgradlePropertiesProp=commandLineValue

請注意，初始化指令碼無法直接讀取 Gradle 屬性。在初始化指令碼中最早可以讀取 Gradle 屬性的時間是在 settingsEvaluated {}

範例 5：從初始化指令碼讀取 Gradle 屬性

init.gradle.kts
settingsEvaluated {
    // Using the API, provides a lazy Provider<String>
    println(providers.gradleProperty("gradlePropertiesProp").get())

    // Using Kotlin delegated properties on `settings`
    val gradlePropertiesProp: String by this
    println(gradlePropertiesProp)
}
init.gradle
settingsEvaluated { settings ->
    // Using the API, provides a lazy Provider<String>
    println settings.providers.gradleProperty('gradlePropertiesProp').get()

    // Using Groovy dynamic names
    println settings.gradlePropertiesProp

    // Using Groovy dynamic array notation on `settings`
    println settings['gradlePropertiesProp']
}

在子專案目錄中宣告的 gradle.properties 檔案中的屬性僅對該專案及其子專案可用。

環境變數

Gradle 提供多個環境變數，如下所列。您可以在建置指令碼中使用 System.getenv() 方法，將環境變數存取為屬性。

下列環境變數可供 gradle 命令使用。

GRADLE_HOME

Gradle 的安裝目錄。

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

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

JAVA_OPTS

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

GRADLE_OPTS

指定啟動 Gradle 客户端 VM 時要使用的 JVM 參數。

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

實際建置由 Gradle 守護程式執行，不受此環境變數影響。

GRADLE_USER_HOME

指定 Gradle 儲存其全域組態屬性、初始化指令碼、快取、記錄檔等內容的 GRADLE_USER_HOME 目錄。

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

JAVA_HOME

指定要供客户端 VM 使用的 JDK 安裝目錄。

此 VM 也用於守護程式，除非在 Gradle 屬性檔中使用 org.gradle.java.home 指定不同的 VM。

GRADLE_LIBS_REPO_OVERRIDE

覆寫預設 Gradle 函式庫儲存庫。

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

若您的公司使用防火牆/代理伺服器，則可使用此覆寫來指定內部主機的儲存庫。

以下範例說明如何使用環境變數。

範例 1：在組態時讀取環境變數

init.gradle.kts
// Using the Java API
println(System.getenv("ENVIRONMENTAL"))
settings.gradle.kts
// Using the Java API
println(System.getenv("ENVIRONMENTAL"))

// Using the Gradle API, provides a lazy Provider<String>
println(providers.environmentVariable("ENVIRONMENTAL").get())
build.gradle.kts
// Using the Java API
println(System.getenv("ENVIRONMENTAL"))

// Using the Gradle API, provides a lazy Provider<String>
println(providers.environmentVariable("ENVIRONMENTAL").get())
init.gradle
// Using the Java API
println System.getenv('ENVIRONMENTAL')
settings.gradle
// Using the Java API
println System.getenv('ENVIRONMENTAL')

// Using the Gradle API, provides a lazy Provider<String>
println providers.environmentVariable('ENVIRONMENTAL').get()
build.gradle
// Using the Java API
println System.getenv('ENVIRONMENTAL')

// Using the Gradle API, provides a lazy Provider<String>
println providers.environmentVariable('ENVIRONMENTAL').get()

範例 2：在執行時讀取環境變數以供使用

build.gradle.kts
tasks.register<PrintValue>("printValue") {
    // Using the Gradle API, provides a lazy Provider<String> wired to a task input
    inputValue = providers.environmentVariable("ENVIRONMENTAL")
}
build.gradle
tasks.register('printValue', PrintValue) {
    // Using the Gradle API, provides a lazy Provider<String> wired to a task input
    inputValue = providers.environmentVariable('ENVIRONMENTAL')
}