启用配置缓存

默认情况下，Gradle 不使用配置缓存。

要在构建时启用它，请使用 configuration-cache 标志

❯ ./gradlew --configuration-cache

要永久启用缓存，请在 gradle.properties 中设置 org.gradle.configuration-cache 属性

org.gradle.configuration-cache=true

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

❯ ./gradlew --no-configuration-cache

忽略配置缓存问题

默认情况下，如果出现配置缓存问题，Gradle 将使构建失败。但是，在逐步更新插件或构建逻辑以支持配置缓存时，通过启用警告模式将问题暂时转换为警告可能很有用。

要在构建时更改此行为，请使用以下标志

❯ ./gradlew --configuration-cache-problems=warn
这不能保证构建会成功。

或者，在 gradle.properties 中进行配置

gradle.properties
org.gradle.configuration-cache.problems=warn

警告模式是一种迁移和故障排除辅助工具，不旨在作为一种永久忽略不兼容性的方式。它也不会阻止以后意外地将新的不兼容性添加到您的构建中。

相反，我们建议明确将有问题任务标记为不兼容。

允许的最大问题数量

当配置缓存问题被视为警告时，如果默认发现 512 个问题，Gradle 将使构建失败。

您可以通过在命令行上指定允许的最大问题数量来调整此限制

❯ ./gradlew -Dorg.gradle.configuration-cache.max-problems=5

或者在 gradle.properties 文件中进行配置

org.gradle.configuration-cache.max-problems=5

启用并行配置缓存

默认情况下，配置缓存的存储和加载是顺序的。启用并行存储和加载可以提高性能，但并非所有构建都兼容。

要在构建时启用并行配置缓存，请使用

❯ ./gradlew -Dorg.gradle.configuration-cache.parallel=true

或在 gradle.properties 文件中永久启用

org.gradle.configuration-cache.parallel=true

并行配置缓存功能是孵化中，某些构建可能无法正常工作。不兼容的常见症状是在配置阶段期间出现 ConcurrentModificationException 错误。但是，此功能预计对解耦的多项目构建运行良好。

启用配置缓存功能标志

为了帮助团队为配置缓存的稳定做准备，Gradle 提供了一个专用功能标志后面的严格模式。

您可以使用以下配置在构建中启用此功能标志

settings.gradle.kts
enableFeaturePreview("STABLE_CONFIGURATION_CACHE")
settings.gradle
enableFeaturePreview "STABLE_CONFIGURATION_CACHE"

启用 STABLE_CONFIGURATION_CACHE 功能标志会激活更严格的验证并引入以下行为

未声明的共享构建服务使用

如果任务使用共享构建服务而没有使用 Task.usesService 方法明确声明要求，Gradle 将发出弃用警告。

没有配置缓存的弃用强制执行

即使未启用配置缓存，如果存在功能标志，Gradle 也会强制执行以下要求的弃用

我们建议尽早启用此标志，以便在未来版本中更严格的行为成为默认行为之前检测和解决潜在问题。

使配置缓存失效

当配置阶段的输入发生变化时，配置缓存会自动失效。但是，某些输入尚未被跟踪，这意味着当未跟踪的输入发生变化时，您可能需要手动使缓存失效。如果您忽略了问题，则更有可能发生这种情况。

有关更多详细信息，请参阅 configuration_cache_requirements.html 和 configuration_cache_status.html 部分。

配置缓存状态存储在 Gradle 构建根目录下的 .gradle/configuration-cache 目录中。

要手动使缓存失效，请删除此目录

❯ rm -rf .gradle/configuration-cache

Gradle 会定期检查（最多每 24 小时一次）缓存条目是否仍在被使用。7 天未使用的条目将自动删除。

采用配置缓存

以下阶段概述了采用配置缓存的推荐路径。这些步骤适用于构建和插件

  1. 不使用/未启用

  2. 本地使用

  3. 在 CI 上使用/随处启用

1. 不使用/未启用

一个重要的先决条件是保持您的 Gradle 版本和插件最新。

在遵循此过程时，请参阅 HTML 报告和要求页面中解释的解决方案。

如果发现任何缓存或重用配置的问题，将生成 HTML 报告以帮助您诊断和修复问题。该报告还会显示在配置阶段读取的检测到的构建配置输入，例如系统属性、环境变量和值提供者。

有关更多信息，请参阅调试页面。

configuration cache 5

2. 本地使用

  1. 从 help 开始

    始终从测试您的构建或插件的最简单任务开始：help。这会练习您的构建或插件的最小配置阶段。

  2. 逐步定位有用的任务

    避免立即运行 build。相反

    • 使用 --dry-run 首先识别配置时问题。

    • 在构建时，关注您的开发反馈循环，例如修改源代码后运行测试。

    • 在插件上工作时，逐步定位贡献或配置的任务。

  3. 通过将问题转换为警告来探索

    不要在第一次构建失败时停止——将问题转换为警告以更好地了解您的构建和插件的行为。如果构建失败

    • 使用 HTML 报告分析报告的问题。

    • 继续测试更多任务，以全面了解影响您的构建和插件的问题。

    • 请记住，在将问题转换为警告时，如果出现意外行为，您可能需要手动使缓存失效。

    • 如果需要，使用 myTask.notCompatibleWithConfigurationCache("because") 将任务标记为不兼容。

  4. 退一步，迭代修复问题

    一旦您清楚地了解了这些问题，就可以开始迭代修复它们。使用 HTML 报告和此文档来指导您的过程

    • 从报告配置缓存存储时的问题开始。

    • 一旦这些问题得到修复，就可以解决在加载配置缓存时遇到的任何问题。

  5. 报告遇到的问题

    如果您遇到Gradle 功能或此文档未涵盖的核心 Gradle 插件的问题，请向gradle/gradle报告。

    对于社区 Gradle 插件，请检查问题是否已在gradle/gradle#13490中列出，并在必要时向插件的问题跟踪器报告。

    一个好的错误报告应包括

    • 指向此文档的链接。

    • 您测试的插件版本。

    • 任何自定义插件配置，或者理想情况下是一个可复现的构建。

    • 失败的描述（例如，特定任务的问题）。

    • 构建失败输出的副本。

    • 自包含的 configuration-cache-report.html 文件。

  6. 测试，测试，再测试

    为您的构建逻辑添加测试，以便及早发现问题。有关测试配置缓存兼容性的详细信息，请参阅测试您的构建逻辑。这将有助于迭代并防止回归。

3. 在 CI 上使用/随处启用

一旦您的开发人员工作流（例如，从 IDE 运行测试）稳定，请考虑为您的团队启用配置缓存

  • 最初，将其作为可选功能引入。

  • 如有必要，将问题转换为警告，并在您的 gradle.properties 文件中设置允许的最大问题数量。

  • 默认情况下禁用配置缓存，并鼓励团队成员通过配置其 IDE 运行设置来选择启用。

  • 当更多工作流稳定时，反转此方法

    • 默认启用配置缓存。

    • 配置 CI 以在需要时禁用它。

    • 传达任何需要禁用配置缓存的不受支持的工作流。

一旦一切在本地和您的团队内稳定，请考虑在 CI 上启用配置缓存

  • 确保您的构建保持符合 CC，开发人员不能意外引入问题！

  • CC 开销由项目内任务并行性补偿。

  • 最初可能无法获得缓存命中（这是正常的）。

当您准备好专注于命中率时

在构建中响应配置缓存

构建逻辑或插件实现可以检测给定构建是否启用了配置缓存，并相应地调整行为。

配置缓存的活动状态在相应的构建功能中提供。您可以通过注入BuildFeatures服务到您的代码中来访问它。

此信息可用于

  • 在启用配置缓存时以不同方式配置插件功能。

  • 禁用尚未与配置缓存兼容的可选功能。

  • 向用户提供额外指导，例如告知他们临时限制或建议调整其设置。

采用配置缓存行为的变化

Gradle 版本通过检测更多配置逻辑与环境交互的情况来不断增强配置缓存。这些改进通过防止错误的缓存命中提高了缓存的正确性，但也引入了插件和构建逻辑必须遵循的更严格的规则，以实现最佳缓存。

一些新检测到的配置输入可能不会影响配置的任务，但仍然会导致缓存失效。为了最大限度地减少不必要的缓存未命中，请遵循以下步骤

  • 使用配置缓存报告识别有问题的配置输入。

    • 修复项目构建逻辑访问的未声明配置输入。

    • 将第三方插件引起的问题报告给其维护者，并在修复后更新插件。

  • 在特定情况下使用可选退出选项，以暂时恢复到早期行为并防止 Gradle 跟踪某些输入。这有助于缓解由过时插件引起的性能问题。

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

  1. Gradle 现在将文件系统交互（包括 File.exists() 或 File.isFile() 等检查）作为配置输入进行跟踪。

    为了防止输入跟踪因这些文件系统检查而使缓存失效，请在 gradle.properties 中使用 org.gradle.configuration-cache.inputs.unsafe.ignore.file-system-checks 属性。列出要忽略的路径，相对于根项目目录，并用 ; 分隔。支持通配符（* 表示段，** 表示多个段）。以 ~/ 为前缀的路径相对于用户的主目录。例如

    gradle.properties
    org.gradle.configuration-cache.inputs.unsafe.ignore.file-system-checks=\
    ~/.third-party-plugin/*.lock;\
    ../../externalOutputDirectory/**;\
    build/analytics.json

  2. 在 Gradle 8.4 之前，一些未声明的配置输入在配置期间从未使用过，但在配置缓存序列化任务图时仍可能被读取。但是，这些更改不会使缓存失效。

    从 Gradle 8.4 开始，这些未声明的输入被正确跟踪，现在会导致缓存失效。

    要暂时恢复到以前的行为，请将 Gradle 属性 org.gradle.configuration-cache.inputs.unsafe.ignore.in-serialization 设置为 true。

随着配置缓存的演变，Gradle 可能会对构建逻辑施加额外的限制。为了使采用更顺畅，在特定情况下可以暂时选择退出这些限制

  1. 从 Gradle 9.0 开始，将除从 BuildServiceRegistry.registerIfAbsent 或 BuildServiceRegistration.getService 返回的 BuildService 提供者之外的任何提供者用作 BuildEventsListenerRegistry.onTaskCompletion 的参数是错误的。

    在 Gradle 9 之前，不支持的提供者在缓存命中构建期间会被静默丢弃，并且永远不会接收事件。

    要暂时恢复到以前的行为，请设置 Gradle 属性

    org.gradle.configuration-cache.unsafe.ignore.unsupported-build-events-listeners=true

请谨慎使用这些选择退出选项，并且仅当它们不影响任务执行结果时才使用。这些选项旨在作为临时解决方法，并将在未来的 Gradle 版本中删除。