Gradle 维护一个虚拟文件系统 (VFS)，以计算项目重复构建时需要重建的内容。通过监控文件系统，Gradle 使 VFS 在构建之间保持最新。

启用

自 Gradle 7 起，对于支持的操作系统，Gradle 默认启用文件系统监控。

使用 '--watch-fs' 标志运行构建，以强制对构建进行文件系统监控。

要强制对所有构建启用文件系统监控（除非使用 --no-watch-fs 禁用），请将以下值添加到 gradle.properties

gradle.properties
org.gradle.vfs.watch=true

禁用

要禁用文件系统监控

  • 使用 --no-watch-fs 标志

  • 在 gradle.properties 中设置 org.gradle.vfs.watch=false

支持的操作系统

Gradle 使用原生操作系统功能来监控文件系统。Gradle 在以下操作系统上支持文件系统监控

  • Windows 10，版本 1709 及更高版本

  • Linux，已在以下发行版上测试

    • Ubuntu 16.04

    • CentOS Stream 9

    • Red Hat Enterprise Linux (RHEL) 8

    • Amazon Linux 2

    • Alpine Linux 3.20

  • macOS 12 (Monterey) 或更高版本，在 Intel 和 ARM 架构上

支持的文件系统

文件系统监控支持以下文件系统类型

  • APFS

  • btrfs

  • ext3

  • ext4

  • XFS

  • HFS+

  • NTFS

Gradle 还支持 VirtualBox 的共享文件夹。

不支持像 Samba 和 NFS 这样的网络文件系统。也不支持 Microsoft Dev Drives (ReFS)。

不支持的文件系统

当默认启用时，文件系统监控在遇到不支持的文件系统上的内容时会保守地运行。如果您从网络驱动器挂载项目目录或子目录，则可能会发生这种情况。当默认启用时，Gradle 不会在构建之间保留有关不支持的文件系统的信息。如果您显式启用文件系统监控，Gradle 会在构建之间保留有关不支持的文件系统的信息。

通过符号链接访问的项目中的文件和目录无法从文件系统监控优化中获益。

日志记录

要在构建开始和结束时查看有关虚拟文件系统 (VFS) 更改的信息，请启用详细 VFS 日志记录。

将 org.gradle.vfs.verbose Daemon 选项设置为 true 以启用详细日志记录。

您可以使用以下命令在命令行中执行此操作

$ gradle <task> -Dorg.gradle.vfs.verbose=true

或者在项目根目录或您的 Gradle 用户主目录的 gradle.properties 文件中配置该属性

gradle.properties
org.gradle.vfs.verbose=true

这将在构建开始和结束时生成以下输出

$ gradle assemble --watch-fs -Dorg.gradle.vfs.verbose=true
Received 3 file system events since last build while watching 1 locations
Virtual file system retained information about 2 files, 2 directories and 0 missing files since last build
> Task :compileJava NO-SOURCE
> Task :processResources NO-SOURCE
> Task :classes UP-TO-DATE
> Task :jar UP-TO-DATE
> Task :assemble UP-TO-DATE

BUILD SUCCESSFUL in 58ms
1 actionable task: 1 up-to-date
Received 5 file system events during the current build while watching 1 locations
Virtual file system retains information about 3 files, 2 directories and 2 missing files until next build

在 Windows 和 macOS 上，即使您没有更改任何内容，Gradle 也可能会报告自上次构建以来收到的更改。这些是关于 Gradle 缓存更改的无害通知，可以安全地忽略。

问题排查

Gradle 未检测到某些更改

请在 Gradle 社区 Slack 上告知我们。 如果构建正确声明了其输入和输出，则不应发生这种情况。因此，这要么是我们必须修复的错误，要么是您的构建缺少对某些输入或输出的声明。

VFS 状态因状态丢失而丢弃

您在构建期间收到一条消息，内容为 Dropped VFS state due to lost state 吗？请在 Gradle 社区 Slack 上告知我们。 这意味着您的构建由于以下原因之一而无法从文件系统监控中获益

  • 守护进程收到一个未知的文件系统事件

  • 发生了太多更改，监控 API 无法处理

macOS 上打开的文件过多

如果您在 macOS 上收到 java.io.IOException: Too many open files 错误，请提高您的打开文件限制。有关更多详细信息，请参阅 这篇文章。

调整 Linux 上的 inotify 监视限制

文件系统监控在 Linux 上使用 inotify。根据您的构建大小，可能需要增加 inotify 限制。如果您正在使用 IDE，那么您可能过去已经不得不增加限制。

文件系统监控为每个被监控的目录使用一个 inotify 监视。您可以通过运行以下命令查看当前每个用户的 inotify 监视限制

cat /proc/sys/fs/inotify/max_user_watches

要将限制增加到例如 512K 监视，请运行以下命令

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p --system

每个使用的 inotify 监视最多占用 1KB 内存。假设 inotify 使用所有 512K 监视，那么文件系统监控最多可能使用 500MB。在内存受限的环境中，您可能需要禁用文件系统监控。

检查 Linux 上的 inotify 实例限制

文件系统监控为每个守护进程初始化一个 inotify 实例。您可以通过运行以下命令查看当前每个用户的 inotify 实例限制

cat /proc/sys/fs/inotify/max_user_instances

默认的每个用户实例限制应该足够高，因此我们不建议手动增加该值。