配置缓存

当启用配置缓存并且您为特定任务集运行 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 构建的根目录中名为 .gradle/configuration-cache 的目录中。如果您需要使缓存无效，只需删除该目录

会定期（最多每 24 小时）检查配置缓存条目是否仍在使用中。如果它们已 7 天未使用，则会被删除。

在 IntelliJ IDEA 或 Android Studio 中，可以通过两种方式完成此操作，全局或按运行配置。

要为整个构建启用它，请转到 Run > Edit configurations…​。这将打开 IntelliJ IDEA 或 Android Studio 对话框以配置 Run/Debug 配置。选择 Templates > Gradle 并将必要的系统属性添加到 VM options 字段。

例如，要启用配置缓存，将问题转换为警告，请添加以下内容

您也可以选择仅为给定的运行配置启用它。在这种情况下，保持 Templates > Gradle 配置不变，并根据需要编辑每个运行配置。

结合这两种方式，您可以全局启用并为某些运行配置禁用，反之亦然。

在 Eclipse IDE 中，您可以通过 Buildship 以两种方式启用和配置配置缓存，全局或按运行配置。

要全局启用它，请转到 Preferences > Gradle。您可以使用上面描述的属性作为系统属性。例如，要启用配置缓存，将问题转换为警告，请添加以下 JVM 参数

要为给定的运行配置启用它，请转到 Run configurations…​，找到您要更改的配置，转到 Project Settings，勾选 Override project settings 复选框，并将相同的系统属性添加为 JVM argument。

结合这两种方式，您可以全局启用并为某些运行配置禁用，反之亦然。

并非所有核心 Gradle 插件都支持配置缓存。

请参考 issue gradle/gradle#13490 以了解社区插件的状态。

可以通过 Task.notCompatibleWithConfigurationCache() 方法声明特定任务与配置缓存不兼容。

在标记为不兼容的任务中发现的配置缓存问题将不再导致构建失败。

并且，当计划运行不兼容的任务时，Gradle 会在构建结束时丢弃配置状态。您可以使用此功能来帮助迁移，方法是暂时选择退出某些难以更改以与配置缓存一起工作的任务。

查看方法文档以获取更多详细信息。

构建逻辑或插件实现可以检测到是否为给定的构建启用了配置缓存，并做出相应的反应。active 配置缓存的状态在相应的构建功能中提供。您可以通过注入 BuildFeatures 服务在您的代码中访问它。

您可以使用此信息以不同的方式配置插件的功能，或禁用尚未兼容的可选功能。另一个示例包括为您的用户提供额外的指导，如果他们需要调整其设置或被告知临时限制。

Gradle 版本发布增强了配置缓存功能，使其能够检测到更多配置逻辑与环境交互的情况。这些变更通过消除潜在的错误缓存命中，提高了缓存的正确性。另一方面，它们也施加了更严格的规则，插件和构建逻辑需要遵循这些规则，以尽可能频繁地被缓存。

如果某些配置输入的结果不影响已配置的任务，则它们可能被认为是“良性的”。由于这些输入而导致新的配置未命中对于构建用户来说可能是不希望看到的，而消除它们的建议策略是

在以下情况下，可以暂时选择退出配置输入检测

谨慎地忽略配置输入，并且仅当它们不影响配置逻辑生成的任务时才这样做。对这些选项的支持将在未来的版本中移除。

任务实例不得从其字段中引用许多类型。这同样适用于任务动作，如闭包 doFirst {} 或 doLast {}。

这些类型分为以下几类

在所有情况下，禁止使用这些类型的原因是它们的状态不容易被配置缓存存储或重新创建。

Live 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() 来获得这样的 provider。同样，如果你引用一些 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()

对于更复杂的情况，可以使用具有注入的 ExecOperations 的自定义 ValueSource 实现。此 ExecOperations 实例可以在配置时不受限制地使用。

你还可以使用标准的 Java/Kotlin/Groovy 进程 API，如 java.lang.ProcessBuilder 在 ValueSource 中。

然后可以使用 providers.of 使用 ValueSource 实现创建一个 provider

在这两种方法中，如果在配置时使用 provider 的值，它将成为构建配置输入。外部进程将在每次构建时执行，以确定配置缓存是否是最新的，因此建议仅在配置时调用快速运行的进程。如果值发生更改，则缓存将失效，并且在此构建期间，该进程将作为配置阶段的一部分再次运行。

插件和构建脚本可以在配置时使用标准的 Java、Groovy 或 Kotlin API 或值提供器 API 直接读取系统属性和环境变量。这样做会使此类变量或属性成为构建配置输入，因此更改值会使配置缓存失效。配置缓存报告包含这些构建配置输入的列表，以帮助跟踪它们。

一般来说，你应该避免在配置时读取系统属性和环境变量的值，以避免在值更改时出现缓存未命中。相反，你可以将 providers.systemProperty() 或 providers.environmentVariable() 返回的 Provider 连接到任务属性。

某些可能枚举所有环境变量或系统属性的访问模式（例如，调用 System.getenv().forEach() 或使用其 keySet() 的迭代器）是不鼓励的。在这种情况下，Gradle 无法找出哪些属性是实际的构建配置输入，因此每个可用的属性都变成一个输入。即使添加新属性，如果使用此模式，也会使缓存失效。

使用自定义谓词过滤环境变量是这种不鼓励的模式的一个示例

谓词中的逻辑对于配置缓存是不透明的，因此所有环境变量都被视为输入。减少输入数量的一种方法是始终使用查询具体变量名称的方法，例如 getenv(String) 或 getenv().get()

然而，上面修复的代码与原始代码并不完全等效，因为仅支持显式变量列表。基于前缀的过滤是一种常见的场景，因此存在基于 provider 的 API 来访问系统属性和环境变量

请注意，配置缓存不仅在变量的值更改或变量被删除时失效，而且在另一个具有匹配前缀的变量添加到环境时也会失效。

对于更复杂的使用情况，可以使用自定义 ValueSource 实现。在 ValueSource 代码中引用的系统属性和环境变量不会成为构建配置输入，因此可以应用任何处理。相反，每次构建运行时都会重新计算 ValueSource 的值，并且仅当值发生更改时，配置缓存才会失效。例如，ValueSource 可用于获取名称包含子字符串 JDK 的所有环境变量

插件和构建脚本不应在配置时使用 Java、Groovy 或 Kotlin API 直接读取文件。相反，使用值提供器 API 将文件声明为潜在的构建配置输入。

此问题是由类似于以下的构建逻辑引起的

要解决此问题，请使用 providers.fileContents() 读取文件

一般来说，你应该避免在配置时读取文件，以避免在文件内容更改时使配置缓存条目失效。相反，你可以将 providers.fileContents() 返回的 Provider 连接到任务属性。

为了检测配置输入，Gradle 修改了构建脚本类路径上类的字节码，如插件及其依赖项。Gradle 使用 Java 代理来修改字节码。由于更改的字节码或代理的存在，某些库的完整性自检可能会失败。

为了解决这个问题，你可以使用Worker API，并使用类加载器或进程隔离来封装库代码。worker 类路径的字节码不会被修改，因此自检应该通过。当使用进程隔离时，worker 动作在一个单独的 worker 进程中执行，该进程没有安装 Gradle Java 代理。

在简单的情况下，当库也提供命令行入口点（public static void main() 方法）时，你也可以使用 JavaExec 任务来隔离库。

默认情况下，Gradle 自动生成和管理加密密钥，作为存储在 GRADLE_USER_HOME 目录下的 Java 密钥库。

对于不希望这样做的环境（例如，当 GRADLE_USER_HOME 目录在多台机器之间共享时），你可以通过 GRADLE_ENCRYPTION_KEY 环境变量向 Gradle 提供在读取或写入缓存的配置数据时要使用的确切加密密钥。

为了使 Gradle 使用用户指定的加密密钥加密配置缓存，你必须在设置了 GRADLE_ENCRYPTION_KEY 环境变量（其中包含有效的 AES 密钥，编码为 Base64 字符串）的情况下运行 Gradle。

生成 Base64 编码的 AES 兼容密钥的一种方法是使用如下命令

如果使用 Cygwin 之类的工具，则此命令应在 Linux、Mac OS 或 Windows 上工作。

然后，你可以使用该命令生成的 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。