組態快取

當組態快取啟用且您為特定任務集執行 Gradle 時，例如透過執行 gradlew check，Gradle 會檢查是否有可用的組態快取條目用於請求的任務集。如果可用，Gradle 會使用此條目，而不是執行組態階段。快取條目包含有關要執行的任務集的資訊，以及它們的組態和依賴關係資訊。

當您第一次執行特定任務集時，這些任務的組態快取中將沒有條目，因此 Gradle 將照常執行組態階段

在組態階段之後，Gradle 會將任務圖的快照寫入新的組態快取條目，以供稍後的 Gradle 調用使用。然後 Gradle 從組態快取載入任務圖，以便它可以將最佳化應用於任務，然後照常執行執行階段。組態時間仍然會在您第一次執行特定任務集時花費。但是，您應該立即看到建置效能的提升，因為任務將平行執行。

當您後續使用相同的任務集執行 Gradle 時，例如再次執行 gradlew check，Gradle 將直接從組態快取載入任務及其組態，並完全略過組態階段。在使用組態快取條目之前，Gradle 會檢查條目的任何「建置組態輸入」（例如建置腳本）是否已變更。如果建置組態輸入已變更，Gradle 將不會使用該條目，並將再次執行組態階段，如上所述，並儲存結果以供稍後重複使用。

建置組態輸入包括

Gradle 使用其自身最佳化的序列化機制和格式來儲存組態快取條目。它會自動序列化任意物件圖的狀態。如果您的任務持有對具有簡單狀態或支援類型的物件的參考，您無需執行任何操作即可支援序列化。

作為後備方案，並為了協助遷移現有任務，支援Java 序列化的某些語義。但不建議依賴它，主要是為了效能考量。

除了略過組態階段外，組態快取還提供了一些額外的效能提升

預設情況下，Gradle 不使用組態快取。若要在建置時啟用快取，請使用 configuration-cache 旗標

您也可以在 gradle.properties 檔案中使用 org.gradle.configuration-cache 屬性以持久方式啟用快取

如果在 gradle.properties 檔案中啟用，您可以覆寫該設定，並在建置時使用 no-configuration-cache 旗標停用快取

預設情況下，如果遇到任何組態快取問題，Gradle 將會使建置失敗。當逐步改善您的外掛或建置邏輯以支援組態快取時，暫時將問題轉為警告可能會很有用，但無法保證建置會運作。

這可以從命令列完成

或在 gradle.properties 檔案中完成

當組態快取問題轉為警告時，如果預設情況下發現 512 個問題，Gradle 將會使建置失敗。

這可以透過在命令列上指定允許的最大問題數量來調整

或在 gradle.properties 檔案中完成

組態快取的儲存和載入預設循序完成。平行儲存和載入提供更好的效能，但並非所有建置都與之相容。

若要在命令列上啟用平行組態快取

或在 gradle.properties 檔案中完成

平行組態快取功能是孵化中，因為無法保證所有建置都能正確運作。常見的症狀是在組態階段期間出現 ConcurrentModificationException 例外狀況。此功能應適用於解耦的多專案建置。

當組態階段的輸入變更時，組態快取會自動失效。但是，某些輸入尚未追蹤，因此當組態階段的未追蹤輸入變更時，您可能需要手動使組態快取失效。如果您忽略了問題，可能會發生這種情況。請參閱下面的需求和尚未實作章節以取得更多資訊。

組態快取狀態儲存在磁碟上的目錄中，該目錄名為 .gradle/configuration-cache，位於使用的 Gradle 建置的根目錄中。如果您需要使快取失效，只需刪除該目錄即可

組態快取條目會定期檢查（最多每 24 小時一次）是否仍在使用中。如果它們已 7 天未使用，則會被刪除。

在 IntelliJ IDEA 或 Android Studio 中，可以透過兩種方式完成此操作，即全域方式或每個執行組態方式。

若要為整個建置啟用它，請前往 Run > Edit configurations…​。這將開啟 IntelliJ IDEA 或 Android Studio 對話方塊以組態執行/偵錯組態。選取 Templates > Gradle，並將必要的系統屬性新增至 VM options 欄位。

例如，若要啟用組態快取，將問題轉為警告，請新增以下內容

您也可以選擇僅為給定的執行組態啟用它。在這種情況下，請保持 Templates > Gradle 組態不變，並根據您的需要編輯每個執行組態。

結合這兩種方式，您可以全域啟用並為某些執行組態停用，反之亦然。

在 Eclipse IDE 中，您可以透過 Buildship 以兩種方式啟用和組態組態快取，即全域方式或每個執行組態方式。

若要全域啟用它，請前往 Preferences > Gradle。您可以使用上述屬性作為系統屬性。例如，若要啟用組態快取，將問題轉為警告，請新增以下 JVM 引數

若要為給定的執行組態啟用它，請前往 Run configurations…​，找到您要變更的組態，前往 Project Settings，勾選 Override project settings 核取方塊，並新增與 JVM argument 相同的系統屬性。

結合這兩種方式，您可以全域啟用並為某些執行組態停用，反之亦然。

並非所有核心 Gradle 外掛都支援組態快取。

請參閱問題 gradle/gradle#13490 以了解社群外掛的狀態。

可以透過 Task.notCompatibleWithConfigurationCache() 方法宣告特定任務與組態快取不相容。

在標記為不相容的任務中發現的組態快取問題將不再導致建置失敗。

並且，當排程執行不相容的任務時，Gradle 會在建置結束時捨棄組態狀態。您可以使用此功能來協助遷移，方法是暫時選擇退出某些難以變更以使用組態快取的任務。

請查看方法文件以取得更多詳細資訊。

建置邏輯或外掛實作可以偵測組態快取是否已針對給定的建置啟用，並據此做出回應。作用中組態快取的狀態在對應的建置功能中提供。您可以透過將BuildFeatures 服務注入到您的程式碼中來存取它。

您可以使用此資訊以不同方式組態您的外掛的功能，或停用尚未相容的可選功能。另一個範例涉及為您的使用者提供額外指導，如果他們需要調整其設定或被告知臨時限制。

Gradle 版本為組態快取帶來了增強功能，使其能夠偵測更多組態邏輯與環境互動的情況。這些變更透過消除潛在的錯誤快取命中，提高了快取的正確性。另一方面，它們也對外掛程式和建置邏輯施加了更嚴格的規則，以盡可能頻繁地進行快取。

如果某些組態輸入的結果不影響已組態的任務，則可以將它們視為「良性」。由於這些輸入而導致新的組態未命中，對於建置使用者來說可能是不希望發生的，而消除它們的建議策略是

在以下情況下，可以暫時選擇退出組態輸入偵測

請謹慎地忽略組態輸入，並且僅在它們不影響組態邏輯產生的任務時才忽略。對這些選項的支援將在未來的版本中移除。

任務實例不得從其欄位參考許多類型。同樣適用於任務動作，如閉包，例如 doFirst {} 或 doLast {}。

這些類型可分為以下幾類

在所有情況下，不允許使用這些類型的原因是它們的狀態不易被組態快取儲存或重新建立。

即時 JVM 狀態類型（例如 ClassLoader、Thread、OutputStream、Socket 等...）是被明確禁止的。這些類型幾乎從不代表任務輸入或輸出。唯一的例外是標準流：System.in、System.out 和 System.err。這些流可以用作參數，例如，用於 Exec 和 JavaExec 任務。

Gradle 模型類型（例如 Gradle、Settings、Project、SourceSet、Configuration 等...）通常用於攜帶一些任務輸入，這些輸入應明確且精確地宣告。

例如，如果您參考 Project 以在執行時取得 project.version，則應改為直接將專案版本宣告為任務的輸入，使用 Property<String>。另一個範例是參考 SourceSet 以稍後取得來源檔案、編譯類別路徑或來源集的輸出。您應該改為將這些宣告為 FileCollection 輸入，並僅參考該輸入。

相同的需求適用於依賴管理類型，但有一些細微差別。

某些類型，例如 Configuration 或 SourceDirectorySet，不能作為良好的任務輸入參數，因為它們包含大量不相關的狀態，最好將這些輸入建模為更精確的內容。我們不打算使這些類型可序列化。例如，如果您參考 Configuration 以稍後取得已解析的檔案，則應改為宣告 FileCollection 作為任務的輸入。同樣地，如果您參考 SourceDirectorySet，則應改為宣告 FileTree 作為任務的輸入。

也不允許參考依賴解析結果（例如 ArtifactResolutionQuery、ResolvedArtifact、ArtifactResult 等...）。例如，如果您參考某些 ResolvedComponentResult 實例，則應改為宣告 Provider<ResolvedComponentResult> 作為任務的輸入。此提供者可以透過調用 ResolutionResult.getRootComponent() 取得。同樣地，如果您參考某些 ResolvedArtifactResult 實例，則應改為使用 ArtifactCollection.getResolvedArtifacts()，它會傳回 Provider<Set<ResolvedArtifactResult>>，可以將其對應為任務的輸入。經驗法則是，任務不得參考已解析的結果，而應參考延遲規格，以便在執行時進行依賴解析。

某些類型，例如 Publication 或 Dependency，不可序列化，但可能是可序列化的。如有必要，我們可能會允許直接將這些類型用作任務輸入。

以下是一個有問題的任務類型範例，它參考了 SourceSet

以下是應該如何做的

同樣地，如果您在腳本中宣告的臨時任務中遇到相同的問題，如下所示

您仍然需要滿足相同的需求，即不參考不允許的類型。以下是如何修正上述任務宣告的方法

請注意，有時不允許的類型是間接參考的。例如，您的任務可能會參考外掛程式中的某些類型，這是允許的。該類型可能會參考另一個允許的類型，而該類型又參考了不允許的類型。問題的 HTML 報告中提供的物件圖層次結構視圖應有助於您找出違規者。

任務在執行時不得使用任何 Project 物件。這包括在任務執行時呼叫 Task.getProject()。

某些情況可以像不允許的類型一樣修正。

通常，Project 和 Task 上都有類似的東西。例如，如果您在任務動作中需要 Logger，則應使用 Task.logger 而不是 Project.logger。

否則，您可以使用注入的服務來代替 Project 的方法。

以下是一個有問題的任務類型範例，它在執行時使用了 Project 物件

以下是應該如何做的

同樣地，如果您在腳本中宣告的臨時任務中遇到相同的問題，如下所示

以下是如何修正上述任務宣告的方法

如您在上面看到的，修正在腳本中宣告的臨時任務需要相當多的儀式。現在是考慮將您的任務宣告提取為適當的任務類別（如先前所示）的好時機。

下表顯示了應使用哪些 API 或注入的服務來替代每個 Project 方法。

任務不應直接存取另一個任務實例的狀態。相反，任務應使用輸入和輸出關係連接。

請注意，此需求使得在執行時設定其他任務的任務不受支援。

將任務儲存到組態快取時，所有透過任務欄位直接或間接參考的物件都會被序列化。在大多數情況下，反序列化會保留參考相等性：如果兩個欄位 a 和 b 在組態時參考相同的實例，則在反序列化後，它們將再次參考相同的實例，因此 a == b（或 Groovy 和 Kotlin 語法中的 a === b）仍然成立。但是，為了效能考量，某些類別，尤其是 java.lang.String、java.io.File 和許多 java.util.Collection 介面的實作，在序列化時不會保留參考相等性。在反序列化後，參考此類別物件的欄位可能會參考不同的但相等的物件。

讓我們看一個在任務欄位中儲存使用者定義物件和 ArrayList 的任務。

在沒有組態快取的情況下執行建置表明，參考相等性在兩種情況下都得到保留。

但是，在啟用組態快取的情況下，只有使用者定義的物件參考是相同的。列表參考是不同的，儘管參考的列表是相等的。

一般而言，不建議在組態和執行階段之間共享可變物件。如果您需要這樣做，您應始終將狀態包裝在您定義的類別中。不能保證標準 Java、Groovy 和 Kotlin 類型或 Gradle 定義的類型的參考相等性會被保留。

請注意，任務之間不會保留參考相等性：每個任務都是其自己的「領域」，因此不可能在任務之間共享物件。相反，您可以使用建置服務來包裝共享狀態。

任務在執行時不應存取慣例和擴充功能，包括額外屬性。相反，與任務執行相關的任何值都應建模為任務屬性。

外掛程式和建置腳本不得註冊任何建置監聽器。也就是在組態時註冊，但在執行時收到通知的監聽器。例如 BuildListener 或 TaskExecutionListener。

這些應替換為建置服務，如果需要接收有關任務執行的資訊，則註冊建置服務。使用資料流動作來處理建置結果，而不是 buildFinished 監聽器。

外掛程式和建置腳本應避免在組態時執行外部程序。一般而言，最好在具有正確宣告的輸入和輸出的任務中執行外部程序，以避免在任務為最新狀態時進行不必要的工作。但是，如果需要，您應僅使用以下描述的與組態快取相容的 API，而不是 Java 和 Groovy 標準 API，或 Gradle 提供的 Project.exec、Project.javaexec、ExecOperations.exec 和 ExecOperations.javaexec 方法。這些方法的靈活性使 Gradle 無法確定呼叫如何影響建置組態，因此難以確保可以安全地重複使用組態快取條目。

對於更簡單的情況，當擷取程序的輸出就足夠時，可以使用 providers.exec() 和 providers.javaexec()

對於更複雜的情況，可以使用自訂的 ValueSource 實作，並注入 ExecOperations。此 ExecOperations 實例可以在組態時不受限制地使用。

您也可以在 ValueSource 中使用標準 Java/Kotlin/Groovy 程序 API，例如 java.lang.ProcessBuilder。

然後可以使用 providers.of，使用 ValueSource 實作來建立提供者

在這兩種方法中，如果在組態時使用提供者的值，它將成為建置組態輸入。外部程序將針對每個建置執行，以確定組態快取是否為最新狀態，因此建議僅在組態時呼叫快速執行的程序。如果值變更，則快取會失效，並且程序將在此建置期間再次執行，作為組態階段的一部分。

外掛程式和建置腳本可以在組態時直接使用標準 Java、Groovy 或 Kotlin API 或值供應器 API 讀取系統屬性和環境變數。這樣做會使此類變數或屬性成為建置組態輸入，因此變更值會使組態快取失效。組態快取報告包含這些建置組態輸入的列表，以協助追蹤它們。

一般而言，您應避免在組態時讀取系統屬性和環境變數的值，以避免值變更時發生快取未命中。相反，您可以將 providers.systemProperty() 或 providers.environmentVariable() 傳回的 Provider 連接到任務屬性。

不鼓勵某些可能列舉所有環境變數或系統屬性的存取模式（例如，呼叫 System.getenv().forEach() 或使用其 keySet() 的迭代器）。在這種情況下，Gradle 無法找出哪些屬性是實際的建置組態輸入，因此每個可用的屬性都變成一個輸入。即使新增一個新的屬性，如果使用此模式，也會使快取失效。

使用自訂述詞來篩選環境變數是這種不鼓勵的模式的一個範例

述詞中的邏輯對於組態快取是不透明的，因此所有環境變數都被視為輸入。減少輸入數量的一種方法是始終使用查詢具體變數名稱的方法，例如 getenv(String) 或 getenv().get()

但是，上面修正的程式碼與原始程式碼並不完全等效，因為僅支援明確的變數列表。基於字首的篩選是一種常見的場景，因此有基於提供者的 API 可以存取系統屬性和環境變數

請注意，不僅當變數的值變更或變數被移除時，組態快取會失效，而且當另一個具有相符字首的變數新增到環境中時，組態快取也會失效。

對於更複雜的用例，可以使用自訂的 ValueSource 實作。在 ValueSource 程式碼中參考的系統屬性和環境變數不會成為建置組態輸入，因此可以應用任何處理。相反，ValueSource 的值會在每次建置執行時重新計算，並且僅當值變更時，組態快取才會失效。例如，ValueSource 可以用於取得名稱包含子字串 JDK 的所有環境變數

外掛程式和建置腳本不應在組態時使用 Java、Groovy 或 Kotlin API 直接讀取檔案。相反，應使用值供應器 API 將檔案宣告為潛在的建置組態輸入。

此問題是由類似於以下的建置邏輯引起的

若要修正此問題，請改為使用 providers.fileContents() 讀取檔案

一般而言，您應避免在組態時讀取檔案，以避免在檔案內容變更時使組態快取條目失效。相反，您可以將 providers.fileContents() 傳回的 Provider 連接到任務屬性。

為了偵測組態輸入，Gradle 會修改建置腳本類別路徑上類別的位元組碼，例如外掛程式及其依賴項。Gradle 使用 Java Agent 來修改位元組碼。由於變更的位元組碼或 Agent 的存在，某些程式庫的完整性自我檢查可能會失敗。

若要解決此問題，您可以使用具有類別載入器或程序隔離的 Worker API 來封裝程式庫程式碼。Worker 類別路徑的位元組碼未被修改，因此自我檢查應通過。當使用程序隔離時，Worker 動作會在沒有安裝 Gradle Java Agent 的單獨 Worker 程序中執行。

在簡單的情況下，當程式庫也提供命令列進入點（public static void main() 方法）時，您也可以使用 JavaExec 任務來隔離程式庫。

預設情況下，Gradle 會自動產生和管理加密金鑰，作為儲存在 GRADLE_USER_HOME 目錄下的 Java 金鑰庫。

對於不希望這樣做的環境（例如，當 GRADLE_USER_HOME 目錄在多個機器之間共享時），您可以透過 GRADLE_ENCRYPTION_KEY 環境變數向 Gradle 提供在讀取或寫入快取組態資料時要使用的確切加密金鑰。

若要讓 Gradle 使用使用者指定的加密金鑰來加密組態快取，您必須在執行 Gradle 時，將 GRADLE_ENCRYPTION_KEY 環境變數設定為有效的 AES 金鑰，並以 Base64 字串編碼。

產生 Base64 編碼、與 AES 相容金鑰的一種方法是使用像這樣的命令

這個命令應該可以在 Linux、Mac OS 或 Windows 上運作，如果使用像 Cygwin 這樣的工具。

接著您可以使用該命令產生的 Base64 編碼金鑰，並將其設定為 GRADLE_ENCRYPTION_KEY 環境變數的值。

組態快取目前僅在本機儲存。它可以被熱或冷的本機 Gradle 常駐程式重複使用。但它無法在開發人員或 CI 機器之間共用。

請參閱 gradle/gradle#13510。

尚未實作 原始碼相依性 的支援。啟用組態快取後，不會回報問題，但建置會失敗。

請參閱 gradle/gradle#13506。

當使用 TestKit 執行建置時，組態快取可能會干擾應用於這些建置的 Java Agent，例如 Jacoco agent。

請參閱 gradle/gradle#25979。

目前，所有 Gradle 屬性的外部來源（專案目錄和 GRADLE_USER_HOME 中的 gradle.properties、設定屬性的環境變數和系統屬性，以及使用命令列旗標指定的屬性）都被視為建置組態輸入，無論在組態時實際使用了哪些屬性。但是，這些來源不包含在組態快取報告中。

請參閱 gradle/gradle#20969。

Gradle 允許支援 Java 物件序列化 協定的物件儲存在組態快取中。

實作目前僅限於可序列化類別，這些類別要麼實作 java.io.Externalizable 介面，要麼實作 java.io.Serializable 介面並定義以下方法組合之一

以下 Java 物件序列化 功能不受支援

請參閱 gradle/gradle#13588。

在建置腳本中重複使用邏輯和資料的常見方法是將重複位元提取到頂層方法和變數中。但是，如果啟用組態快取，則目前不支援在執行時期呼叫這些方法。

對於以 Groovy 撰寫的建置腳本，任務會失敗，因為找不到該方法。以下程式碼片段在 listFiles 任務中使用了頂層方法

啟用組態快取執行任務會產生以下錯誤

為了防止任務失敗，請將引用的頂層方法轉換為類別中的靜態方法

以 Kotlin 撰寫的建置腳本完全無法在組態快取中儲存參考執行時期頂層方法或變數的任務。此限制存在的原因是捕獲的腳本物件參考無法序列化。首次執行 Kotlin 版本的 listFiles 任務會因組態快取問題而失敗。

為了使此任務的 Kotlin 版本與組態快取相容，請進行以下變更

請參閱 gradle/gradle#22879。

目前，如果 ValueSource 的值在組態時被存取，則無法將 BuildServiceProvider 或從其衍生的提供者與 map 或 flatMap 一起用作 ValueSource 的參數。當在作為組態階段一部分執行的任務中取得此類 ValueSource 時，情況也是如此，例如 buildSrc 建置或包含貢獻外掛程式的建置的任務。請注意，使用 @ServiceReference 或將 BuildServiceProvider 儲存在任務的 @Internal 註解屬性中是安全的。一般來說，此限制使得無法使用 BuildService 使組態快取失效。

請參閱 gradle/gradle#24085。