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 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 在构建期间创建的共享缓存(例如,构件转换)。
未使用的资源的默认保留期限为 7 天。
-
构建缓存:本地构建缓存(例如,build-cache-1)。
未使用的构建缓存条目的默认保留期限为 7 天。
每个类别的保留期限都可以通过 Gradle 用户主目录中的 init 脚本 独立配置
beforeSettings {
caches {
releasedWrappers.setRemoveUnusedEntriesAfterDays(45)
snapshotWrappers.setRemoveUnusedEntriesAfterDays(10)
downloadedResources.setRemoveUnusedEntriesAfterDays(45)
createdResources.setRemoveUnusedEntriesAfterDays(10)
buildCache.setRemoveUnusedEntriesAfterDays(5)
}
}
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:在每个构建会话结束时执行清理。
这在希望确保在继续之前已发生清理的情况下很有用。
但是,这会在构建期间(而不是在后台)执行缓存清理,这可能会很耗时,因此只有在必要时才应使用此选项。
要禁用缓存清理
beforeSettings {
caches {
cleanup = Cleanup.DISABLED
}
}
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 目录以外的其他位置(例如子目录),因此它不会自动应用。 |
以版本安全的方式配置缓存清理
if (GradleVersion.current() >= GradleVersion.version("8.0")) {
apply(from = "gradle8/cache-settings.gradle.kts")
}
if (GradleVersion.current() >= GradleVersion.version('8.0')) {
apply from: "gradle8/cache-settings.gradle"
}
符合版本的缓存配置脚本
beforeSettings {
caches {
releasedWrappers { setRemoveUnusedEntriesAfterDays(45) }
snapshotWrappers { setRemoveUnusedEntriesAfterDays(10) }
downloadedResources { setRemoveUnusedEntriesAfterDays(45) }
createdResources { setRemoveUnusedEntriesAfterDays(10) }
buildCache { setRemoveUnusedEntriesAfterDays(5) }
}
}
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 用户主目录中的 init 脚本配置缓存标记功能
beforeSettings {
caches {
// Disable cache marking for all caches
markingStrategy = MarkingStrategy.NONE
}
}
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 | 此项目的 build 目录,Gradle 将所有构建构件生成到其中。 |
4 | 包含 Gradle Wrapper 的 JAR 文件和配置。 |
5 | 项目特定的 Gradle 配置属性。 |
6 | 使用 Gradle Wrapper 执行构建的脚本。 |
7 | 项目的settings 文件,其中定义了子项目列表。 |
8 | 通常,一个项目被组织成一个或多个子项目。 |
9 | 每个子项目都有自己的 Gradle 构建脚本。 |
项目缓存清理
从 4.10 版本开始,Gradle 会自动清理项目特定的缓存目录。
构建项目后,会定期(最多每 24 小时一次)检查 .gradle/8.13/
中的版本特定缓存目录,以确定它们是否仍在使用。如果它们已 7 天未使用,则会被删除。
下一步: 了解 Gradle 构建生命周期 >>