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 8 或更高版本

    • Red Hat Enterprise Linux (RHEL) 8 或更高版本

    • Amazon Linux 2 或更高版本

  • macOS 10.14（Mojave）或更高版本（在 Intel 和 ARM 架构上）

支持的文件系统

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

  • APFS

  • btrfs

  • ext3

  • ext4

  • XFS

  • HFS+

  • NTFS

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

不支持网络文件系统，例如 Samba 和 NFS。

符号链接

文件系统监控与符号链接不兼容。如果您的项目文件包含符号链接，符号链接文件将无法从文件系统监控优化中受益。

不支持的文件系统

默认情况下，当文件系统监控遇到不支持的文件系统上的内容时，它会保守地运行。如果您从网络驱动器挂载项目目录或子目录，则可能会发生这种情况。默认情况下，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 上告知我们。这意味着您的构建无法从以下原因之一受益于文件系统监控

  • Daemon 收到未知的文件系统事件

  • 发生了太多更改，监控 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 的内存。在内存受限的环境中，您可能需要禁用文件系统监控。