配置缓存

当启用配置缓存并且您为特定任务集运行 Gradle 时，例如通过运行 gradlew check ，Gradle 会检查配置缓存条目是否可用于所请求的任务集。如果可用，Gradle 使用此条目而不是运行配置阶段。缓存条目包含有关要运行的任务集的信息，以及它们的配置和依赖信息。

第一次运行一组特定的任务时，这些任务的配置缓存中将没有条目，因此 Gradle 将正常运行配置阶段：

在配置阶段之后，Gradle 将任务图的快照写入新的配置缓存条目，供以后的 Gradle 调用使用。 Gradle 然后从配置缓存加载任务图，以便它可以对任务应用优化，然后正常运行执行阶段。配置时间仍将花费在您第一次运行一组特定任务时。但是，您应该会立即看到构建性能的提升，因为 任务将并行运行。

当您随后使用同一组任务运行 Gradle 时，例如再次运行 gradlew check，Gradle 将直接从配置缓存加载任务及其配置，并完全跳过配置阶段。在使用配置缓存条目之前，Gradle 会检查条目的“构建配置输入”（例如构建脚本）是否已更改。如果构建配置输入已更改，Gradle 将不会使用该条目，并将像上面一样再次运行配置阶段，保存结果供以后重用。

构建配置输入包括：

Gradle 使用自己优化的序列化机制和格式来存储配置缓存条目。它自动序列化任意对象图的状态。如果您的任务持有对具有简单状态或受支持类型的对象的引用，您无需执行任何操作来支持序列化。

作为回退并为迁移现有任务提供一些帮助，支持 Java序列化 的某些语义。但不建议依赖它，主要是出于性能原因。

除了跳过配置阶段外，配置缓存还提供了一些额外的性能改进：

默认情况下，Gradle 不使用配置缓存。要在构建时启用缓存，请使用 configuration-cache 标志：

您还可以使用 org.gradle.configuration-cache 属性在 gradle.properties 文件中永久启用缓存：

如果在 gradle.properties 文件中启用，您可以覆盖该设置并在构建时使用 no-configuration-cache 标志禁用缓存：

默认情况下，如果遇到任何配置缓存问题，Gradle 将导致构建失败。当逐渐改进您的插件或构建逻辑以支持配置缓存时，暂时将问题转化为警告会很有用。

这可以从命令行完成：

或者在 gradle.properties 文件中：

当配置缓存问题变成警告时，如果默认发现512问题，Gradle 将导致构建失败。

这可以通过在命令行上指定允许的最大问题数来调整：

或者在 gradle.properties 文件中：

当配置阶段的输入发生变化时，配置缓存会自动失效。但是，某些输入尚未被跟踪，因此当配置阶段未跟踪的输入发生变化时，您可能必须手动使配置缓存无效。如果你 被忽略的问题 就会发生这种情况。有关详细信息，请参阅下面的 要求 和 尚未实现 部分。

配置缓存状态存储在磁盘上名为 .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 插件 都支持配置缓存。

请参阅问题 渐变/渐变#13490 以了解社区插件的状态。

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

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

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

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

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

这些类型分为以下几类：

在所有情况下，不允许使用这些类型的原因是配置缓存无法轻松存储或重新创建它们的状态。

Live JVM 状态类型（例如 ClassLoader 、 Thread 、 OutputStream 、 Socket 等…）是不允许的。这些类型几乎从不代表任务输入或输出。

Gradle 模型类型（例如 Gradle 、 Settings 、 Project 、 SourceSet 、 Configuration 等……）通常用于携带一些应该明确和精确声明的任务输入。

例如，如果您引用 Project 以便在执行时获取 project.version，则您应该使用 Property<String> 直接将 project version 声明为任务的输入。另一个示例是引用 SourceSet 以稍后获取源文件、编译类路径或源集的输出。您应该改为将它们声明为 FileCollection 输入并仅引用它。

同样的要求适用于依赖管理类型，但有一些细微差别。

某些类型，如 Configuration 或 SourceDirectorySet ，不能成为好的任务输入参数，因为它们包含很多不相关的状态，最好将这些输入建模为更精确的东西。我们根本不打算使这些类型可序列化。例如，如果您引用 Configuration 以稍后获取已解析的文件，您应该改为将 FileCollection 声明为任务的输入。同样，如果您引用 SourceDirectorySet，您应该改为将 FileTree 声明为任务的输入。

引用依赖项解析结果也是不允许的（例如 ArtifactResolutionQuery 、 ResolvedArtifact 、 ArtifactResult 等……）。例如，如果您引用一些 ResolvedComponentResult 实例，您应该声明一个 Provider<ResolvedComponentResult> 作为您任务的输入。这样的提供者可以通过调用 ResolutionResult.getRootComponent() 获得。同样，如果您引用一些 ResolvedArtifactResult 实例，您应该改用 ArtifactCollection.getResolvedArtifacts() 返回一个 Provider<Set<ResolvedArtifactResult>> 可以映射为您的任务的输入。经验法则是任务不得引用 resolved 结果，而是惰性规范，以便在执行时进行依赖性解析。

某些类型，如 Publication 或 Dependency 不可序列化，但可以序列化。如有必要，我们可能会允许将这些直接用作任务输入。

以下是引用 SourceSet 的有问题任务类型的示例：

以下是应该如何完成：

同样，如果您在脚本中声明的临时任务遇到相同的问题，如下所示：

您仍然需要满足相同的要求，即不引用不允许的类型。以下是如何修复上面的任务声明：

请注意，有时会间接引用不允许的类型。例如，您可以让任务从允许的插件中引用某种类型。该类型可以引用另一个允许的类型，而该类型又引用一个不允许的类型。 HTML 问题报告中提供的对象图的层次结构视图应该可以帮助您查明违规者。

任务在执行时不得使用任何 Project 对象。这包括在任务运行时调用 Task.getProject()。

有些情况可以用与 不允许的类型 相同的方式修复。

通常，Project 和 Task 上都有类似的东西。例如，如果您在任务操作中需要 Logger，则应使用 Task.logger 而不是 Project.logger。

否则，您可以使用 注入服务 而不是 Project 的方法。

以下是在执行时使用 Project 对象的有问题任务类型的示例：

以下是应该如何完成：

同样，如果您在脚本中声明的临时任务遇到相同的问题，如下所示：

以下是如何修复上面的任务声明：

正如您在上面看到的，修复脚本中声明的临时任务需要相当多的仪式。现在是考虑将任务声明提取为正确任务类的好时机，如前所示。

下表显示了应该使用哪些 API 或注入的服务来替代每个 Project 方法。

任务不应直接访问另一个任务实例的状态。相反，任务应该使用 输入和输出关系 连接。

请注意，此要求使其不支持编写在执行时配置其他任务的任务。

任务不应在执行时访问约定和扩展，包括额外的属性。相反，任何与任务执行相关的值都应建模为任务属性。

插件和构建脚本不得注册任何构建侦听器。即在配置时注册的侦听器在执行时得到通知。例如 BuildListener 或 TaskExecutionListener 。

这些应由 构建服务 替换，注册以在需要时接收有关 任务执行 的信息。使用 数据流操作 来处理构建结果而不是 buildFinished 侦听器。

插件和构建脚本应避免在配置时运行外部进程。通常，最好在具有正确声明的输入和输出的任务中运行外部进程，以避免在任务为最新时进行不必要的工作。如有必要，应仅使用与配置缓存兼容的 API，而不是 Java 和 Groovy 标准 API 或现有的 ExecOperations、Project.exec、Project.javaexec 以及设置和初始化脚本中的类似 API。对于更简单的情况，当获取进程的输出就足够时，可以使用 providers.exec() 和 providers.javaexec()：

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

然后可以使用 ValueSource 实现来创建带有 providers.of 的提供程序：

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

插件和构建脚本可以在配置时使用标准 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/configuration-cache 下。

为了降低意外暴露的风险，Gradle 对配置缓存进行了加密。 Gradle 透明地根据需要生成机器特定的密钥，将其缓存在 GRADLE_USER_HOME 目录下，并使用它来加密项目特定缓存中的数据。

要进一步增强安全性，请确保：

参见 渐变/渐变#22618。

配置缓存当前仅存储在本地。它可以被热或冷的本地 Gradle 守护进程重用。但它不能在开发人员或 CI 机器之间共享。

参见 渐变/渐变#13510。

对 源依赖 的支持尚未实现。启用配置缓存后，不会报任何问题，构建也会失败。

参见 渐变/渐变#13506。

使用 TestKit 运行构建时，配置缓存会干扰应用于这些构建的 Java 代理，例如 Jacoco 代理。

目前，Gradle 属性的所有外部来源（项目目录和 GRADLE_USER_HOME 中的 gradle.properties 、设置属性的环境变量和系统属性以及使用命令行标志指定的属性）都被视为构建配置输入，无论配置中实际使用了哪些属性时间。但是，这些来源不包含在配置缓存报告中。

Gradle 允许将支持 Java 对象序列化 协议的对象存储在配置缓存中。

该实现目前仅限于实现 java.io.Serializable 接口并定义以下方法组合之一的可序列化类：

以下 Java Object Serialization 功能是不是支持的：

参见 渐变/渐变#13588。

在构建脚本中重用逻辑和数据的一种常见方法是将重复位提取到顶级方法和变量中。但是，如果启用了配置缓存，则当前不支持在执行时调用此类方法。

对于用 Groovy 编写的构建脚本，任务失败，因为找不到方法。以下代码段使用 listFiles 任务中的顶级方法：

在启用配置缓存的情况下运行任务会产生以下错误：

为防止任务失败，将引用的顶级方法转换为类中的静态方法：

用 Kotlin 编写的构建脚本根本无法在配置缓存中存储在执行时引用顶级方法或变量的任务。存在此限制是因为无法序列化捕获的脚本对象引用。第一次运行 Kotlin 版本的 listFiles 任务失败，出现配置缓存问题。

要使此任务的 Kotlin 版本与配置缓存兼容，请进行以下更改：

参见 渐变/渐变#22879。

当前，如果在配置时访问 ValueSource 的值，则不可能将 BuildServiceProvider 或从其派生的提供程序与 map 或 flatMap 一起用作 ValueSource 的参数。当在作为配置阶段的一部分执行的任务中获得这样的 ValueSource 时，这同样适用，例如 buildSrc 构建的任务或包含的构建贡献插件。请注意，在任务的 @Internal 注释属性中使用 @ServiceReference 或存储 BuildServiceProvider 是安全的。一般来说，这个限制使得无法使用BuildService来使配置缓存失效。

参见 渐变/渐变#24085。