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 上告知我們。 這表示您的建置無法從檔案系統監看中受益，原因如下

  • 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。在記憶體受限的環境中，您可能想要停用檔案系統監看。

檢查 Linux 上的 inotify 實例限制

檔案系統監看每個 Daemon 初始化一個 inotify 實例。您可以透過執行以下命令來查看每個使用者的 inotify 實例目前限制

cat /proc/sys/fs/inotify/max_user_instances

預設的每個使用者實例限制應該足夠高，因此我們不建議手動增加該值。