Gradle 管理的目录 - Gradle 中文

Gradle 使用两个主目录来执行和管理其工作：Gradle 用户主目录和项目根目录。

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	共享缓存（例如，用于依赖项的工件）。
4	Gradle Daemon的注册表和日志。
5	全局初始化脚本。
6	工具链支持下载的 JDK。
7	Gradle Wrapper下载的发行版。
8	全局Gradle 配置属性。

缓存和发行版的清理

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

默认情况下，清理会在 Gradle 守护进程停止或关闭时在后台运行。

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

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

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

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

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

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

删除未使用的发行版。

配置缓存和发行版的清理

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

缓存分为四类

已发布的包装器发行版：与已发布版本（例如 `4.6.2` 或 `8.0`）对应的发行版和相关特定版本缓存。

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

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

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

未使用的资源的默认保留期为 7 天。

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

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

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

gradleUserHome/init.d/cache-settings.gradle

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

还可以配置调用缓存清理的频率。

有三种可能的设置

默认：定期在后台执行清理（当前每 24 小时一次）。
禁用：从不清理 Gradle 用户目录。

这在 Gradle 用户目录为临时目录或希望延迟清理到明确时间点的情况下很有用。
始终：在每个构建会话结束时执行清理。

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

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

禁用缓存清理

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
    }
}

缓存清理设置只能通过 init 脚本配置，并且应放置在 Gradle 用户目录中的 init.d 目录下。这实际上将缓存清理配置与那些设置适用的 Gradle 用户目录耦合在一起，并限制了将来自不同项目的不同冲突设置应用于同一目录的可能性。

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

在多个 Gradle 版本之间共享一个 Gradle 用户目录很常见。

如上所述，Gradle 用户目录中的缓存是特定于版本的。不同版本的 Gradle 将只对与每个版本关联的特定于版本的缓存执行维护。

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

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

这意味着

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

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

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

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

符合版本的脚本应位于 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) }
    }
}

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

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

缓存标记

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

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

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

配置缓存标记

可以通过 Gradle 用户主页中的 init 脚本配置缓存标记功能

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
    }
}

缓存标记设置只能通过 init 脚本配置，并且应放在 Gradle 用户主页中的 init.d 目录下。这实际上将缓存标记的配置与那些设置适用的 Gradle 用户主页相关联，并限制了将来自不同项目的不同冲突设置应用到同一目录的可能性。

项目根目录

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

它还包含 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 将所有构建工件生成到此目录中。
4	包含 Gradle Wrapper 的 JAR 文件和配置。
5	项目特定的 Gradle 配置属性。
6	用于使用 Gradle Wrapper 执行构建的脚本。
7	项目的设置文件，其中定义了子项目的列表。
8	通常，一个项目被组织成一个或多个子项目。
9	每个子项目都有自己的 Gradle 构建脚本。

项目缓存清理

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

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

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

此页面有帮助吗？