Gradle 管理的目录 - Gradle 构建系统

Gradle 使用两个主要目录来执行和管理其工作

1. Gradle 用户主目录

默认情况下，Gradle 用户主目录（~/.gradle 或 C:\Users\<USERNAME>\.gradle）存储全局配置属性、初始化脚本、缓存和日志文件。

可以通过环境变量 GRADLE_USER_HOME 进行设置。

不要与 GRADLE_HOME 混淆，后者是 Gradle 的可选安装目录。

它的结构大致如下：

├── caches              (1)
│   ├── 4.8         (2)
│   ├── 4.9             (2)
│   ├── ⋮
│   ├── jars-3      (3)
│   └── modules-2       (3)
├── daemon          (4)
│   ├── ⋮
│   ├── 4.8
│   └── 4.9
├── init.d              (5)
│   └── my-setup.gradle
├── jdks                (6)
│   ├── ⋮
│   └── jdk-14.0.2+12
├── wrapper
│   └── dists           (7)
│       ├── ⋮
│       ├── gradle-4.8-bin
│       ├── gradle-4.9-all
│       └── gradle-4.9-bin
└── gradle.properties   (8)

1	全局缓存目录（用于非项目特定的所有内容）。
2	版本特定的缓存（例如，支持增量构建）。
3	共享缓存（例如，用于依赖项的 artifact）。
4	Gradle Daemon 的注册表和日志。
5	全局初始化脚本。
6	工具链支持下载的 JDK。
7	Gradle Wrapper 下载的发布版。
8	全局Gradle 配置属性。

缓存和发布版的清理

Gradle 会自动清理其用户主目录。

默认情况下，当 Gradle daemon 停止或关闭时，清理在后台运行。

如果使用 --no-daemon，它将在构建会话结束后在前台运行。

以下清理策略会定期应用（默认情况下，每 24 小时一次）

检查所有 caches/<GRADLE_VERSION>/ 目录中的版本特定缓存是否仍在使用中。

如果不是，则发布版本的目录在不活动 30 天后删除，快照版本在 7 天后删除。
检查 caches/ 中的共享缓存（例如 jars-*）是否仍在使用中。

如果没有 Gradle 版本仍在使用它们，它们将被删除。
检查当前 Gradle 版本在 caches/ 中使用的共享缓存中的文件（例如 jars-3 或 modules-2）上次访问的时间。

根据文件是否可以在本地重新创建或从远程仓库下载，它将分别在 7 天或 30 天后删除。
检查 wrapper/dists/ 中的 Gradle 发布版是否仍在使用中，即是否存在相应的版本特定缓存目录。

未使用的发布版将被删除。

配置缓存和发布版的清理

可以配置各种缓存的保留期限。

缓存分为五类

已发布的 Wrapper 发布版： 对应已发布版本（例如 4.6.2 或 8.0）的发布版和相关的版本特定缓存。

未使用的版本的默认保留期限为 30 天。
快照 Wrapper 发布版： 对应快照版本（例如 7.6-20221130141522+0000）的发布版和相关的版本特定缓存。

未使用的版本的默认保留期限为 7 天。
已下载的资源： 从远程仓库下载的共享缓存（例如，缓存的依赖项）。

未使用的资源的默认保留期限为 30 天。
已创建的资源： Gradle 在构建期间创建的共享缓存（例如，artifact 转换）。

未使用的资源的默认保留期限为 7 天。
构建缓存： 本地构建缓存（例如，build-cache-1）。

未使用的构建缓存条目的默认保留期限为 7 天。

每个类别的保留期限可以通过 Gradle 用户主目录中的初始化脚本独立配置

gradleUserHome/init.d/cache-settings.gradle.kts

beforeSettings {
    caches {
        releasedWrappers.setRemoveUnusedEntriesAfterDays(45)
        snapshotWrappers.setRemoveUnusedEntriesAfterDays(10)
        downloadedResources.setRemoveUnusedEntriesAfterDays(45)
        createdResources.setRemoveUnusedEntriesAfterDays(10)
        buildCache.setRemoveUnusedEntriesAfterDays(5)
    }
}

gradleUserHome/init.d/cache-settings.gradle

beforeSettings { settings ->
    settings.caches {
        releasedWrappers.removeUnusedEntriesAfterDays = 45
        snapshotWrappers.removeUnusedEntriesAfterDays = 10
        downloadedResources.removeUnusedEntriesAfterDays = 45
        createdResources.removeUnusedEntriesAfterDays = 10
        buildCache.removeUnusedEntriesAfterDays = 5
    }
}

调用缓存清理的频率也是可配置的。

有三种可能的设置

DEFAULT: 清理在后台定期执行（目前是每 24 小时一次）。
DISABLED: 从不清理 Gradle 用户主目录。

这在 Gradle 用户主目录是临时性的或希望将清理延迟到明确的时间点的情况下很有用。
ALWAYS: 清理在每个构建会话结束时执行。

这在希望确保在继续之前已进行清理的情况下很有用。

但是，这会在构建期间（而不是在后台）执行缓存清理，这可能会很耗时，因此此选项只应在必要时使用。

要禁用缓存清理

gradleUserHome/init.d/cache-settings.gradle.kts

beforeSettings {
    caches {
        cleanup = Cleanup.DISABLED
    }
}

gradleUserHome/init.d/cache-settings.gradle

beforeSettings { settings ->
    settings.caches {
        cleanup = Cleanup.DISABLED
    }
}

缓存清理设置只能通过初始化脚本配置，并且应放置在 Gradle 用户主目录的 init.d 目录下。这有效地将缓存清理的配置与这些设置所适用的 Gradle 用户主目录耦合起来，并限制了不同项目之间的不同冲突设置应用于同一目录的可能性。

多个 Gradle 版本共享一个 Gradle 用户主目录

多个 Gradle 版本共享一个 Gradle 用户主目录是很常见的。

如上所述，Gradle 用户主目录中的缓存是版本特定的。不同版本的 Gradle 将只对其各自版本相关的版本特定缓存执行维护。

另一方面，有些缓存是版本之间共享的（例如，依赖项 artifact 缓存或 artifact 转换缓存）。

从 Gradle 8.0 版本开始，缓存清理设置可以配置为自定义保留期限。但是，旧版本有固定的保留期限（7 或 30 天，取决于缓存）。这些共享缓存可以被具有不同设置的 Gradle 版本访问以保留缓存 artifact。

这意味着

如果保留期限未自定义，则所有执行清理的版本将具有相同的保留期限。由于与多个版本共享 Gradle 用户主目录，因此不会产生任何影响。
如果将 Gradle 版本大于或等于 8.0 的保留期限自定义为使用比以前固定期限更短的保留期限，则也不会产生任何影响。

了解这些设置的 Gradle 版本将比以前固定的保留期限更早地清理 artifact，而旧版本将有效地不参与共享缓存的清理。
如果将 Gradle 版本大于或等于 8.0 的保留期限自定义为使用比以前固定期限更长的保留期限，则旧版本的 Gradle 可能会比配置的更早地清理共享缓存。

在这种情况下，如果希望为新版本保留这些共享缓存条目更长时间，它们将无法与旧版本共享 Gradle 用户主目录。它们将需要使用单独的目录。

与 8.0 版本之前的 Gradle 版本共享 Gradle 用户主目录时需要考虑的另一个问题是，用于配置缓存保留设置的 DSL 元素在早期版本中不可用，因此必须在版本之间共享的任何初始化脚本中考虑这一点。这可以通过有条件地应用符合版本的脚本轻松处理。

符合版本的脚本应位于 init.d 目录之外的其他位置（例如子目录），这样它就不会自动应用。

以版本安全的方式配置缓存清理

gradleUserHome/init.d/cache-settings.gradle.kts

if (GradleVersion.current() >= GradleVersion.version("8.0")) {
    apply(from = "gradle8/cache-settings.gradle.kts")
}

gradleUserHome/init.d/cache-settings.gradle

if (GradleVersion.current() >= GradleVersion.version('8.0')) {
    apply from: "gradle8/cache-settings.gradle"
}

符合版本的缓存配置脚本

gradleUserHome/init.d/gradle8/cache-settings.gradle.kts

beforeSettings {
    caches {
        releasedWrappers { setRemoveUnusedEntriesAfterDays(45) }
        snapshotWrappers { setRemoveUnusedEntriesAfterDays(10) }
        downloadedResources { setRemoveUnusedEntriesAfterDays(45) }
        createdResources { setRemoveUnusedEntriesAfterDays(10) }
        buildCache { setRemoveUnusedEntriesAfterDays(5) }
    }
}

gradleUserHome/init.d/gradle8/cache-settings.gradle

beforeSettings { settings ->
    settings.caches {
        releasedWrappers.removeUnusedEntriesAfterDays = 45
        snapshotWrappers.removeUnusedEntriesAfterDays = 10
        downloadedResources.removeUnusedEntriesAfterDays = 45
        createdResources.removeUnusedEntriesAfterDays = 10
        buildCache.removeUnusedEntriesAfterDays = 5
    }
}

缓存标记

从 Gradle 8.1 版本开始，Gradle 支持使用 CACHEDIR.TAG 文件标记缓存。

它遵循缓存目录标记规范中描述的格式。此文件的目的是允许工具识别不需要搜索或备份的目录。

默认情况下，Gradle 用户主目录中的 caches、wrapper/dists、daemon 和 jdks 目录都使用此文件进行标记。

配置缓存标记

可以通过 Gradle 用户主目录中的初始化脚本配置缓存标记功能

gradleUserHome/init.d/cache-settings.gradle.kts

beforeSettings {
    caches {
        // Disable cache marking for all caches
        markingStrategy = MarkingStrategy.NONE
    }
}

gradleUserHome/init.d/cache-settings.gradle

beforeSettings { settings ->
    settings.caches {
        // Disable cache marking for all caches
        markingStrategy = MarkingStrategy.NONE
    }
}

缓存标记设置只能通过初始化脚本配置，并且应放置在 Gradle 用户主目录的 init.d 目录下。这有效地将缓存标记的配置与这些设置所适用的 Gradle 用户主目录耦合起来，并限制了不同项目之间的不同冲突设置应用于同一目录的可能性。

2. 项目根目录

项目根目录包含项目的所有源文件。

它还包含 Gradle 生成的文件和目录，例如 .gradle 和 build。

虽然前者通常会检入版本控制，但后者是 Gradle 用于支持增量构建等功能的临时文件。

典型项目根目录的结构如下：

├── .gradle                 (1)
│   ├── 4.8             (2)
│   ├── 4.9                 (2)
│   └── ⋮
├── build               (3)
├── gradle
│   └── wrapper             (4)
├── gradle.properties   (5)
├── gradlew                 (6)
├── gradlew.bat         (6)
├── settings.gradle.kts     (7)
├── subproject-one      (8)
|   └── build.gradle.kts    (9)
├── subproject-two      (8)
|   └── build.gradle.kts    (9)
└── ⋮

1	Gradle 生成的特定于项目的缓存目录。
2	版本特定的缓存（例如，支持增量构建）。
3	该项目的构建目录，Gradle 将所有构建 artifact 生成到其中。
4	包含Gradle 包装器的 JAR 文件和配置。
5	项目特定的Gradle 配置属性。
6	使用Gradle Wrapper 执行构建的脚本。
7	项目的设置文件，其中定义了子项目列表。
8	通常，一个项目被组织成一个或多个子项目。
9	每个子项目都有自己的 Gradle 构建脚本。

项目缓存清理

从 4.10 版本开始，Gradle 会自动清理项目特定的缓存目录。

构建项目后，会定期检查 .gradle/9.0.0/ 中的版本特定缓存目录（最多每 24 小时一次），以确定它们是否仍在使用中。如果它们已闲置 7 天，则会被删除。

下一步： 了解 Gradle 构建生命周期 >>

此页面有帮助吗？