Node.js fs.watch(filename[, options][, listener])用法及代碼示例

fs.watch(filename[, options][, listener])

參數

• filename <string> | <Buffer> | <URL>
• options <string>|<Object>
  • persistent <boolean> 指示隻要正在監視文件，進程是否應繼續運行。 默認： true 。
  • recursive <boolean> 指示是應監視所有子目錄，還是僅監視當前目錄。這適用於指定目錄時，並且僅適用於受支持的平台(請參閱caveats)。 默認： false 。
  • encoding <string> 指定用於傳遞給偵聽器的文件名的字符編碼。 默認： 'utf8' 。
  • signal <AbortSignal> 允許使用 AbortSignal 關閉觀察程序。
• listener <Function>|<undefined> 默認： undefined
  • eventType <string>
  • filename <string> | <Buffer>
• 返回： <fs.FSWatcher>

注意 filename 上的更改，其中 filename 是文件或目錄。

第二個參數是可選的。如果 options 作為字符串提供，則它指定 encoding 。否則 options 應作為對象傳遞。

偵聽器回調獲取兩個參數 (eventType, filename) 。 eventType 是 'rename' 或 'change' ，而 filename 是觸發事件的文件的名稱。

在大多數平台上，隻要文件名在目錄中出現或消失，就會發出'rename'。

偵聽器回調附加到由 <fs.FSWatcher> 觸發的 'change' 事件，但它與 eventType 的 'change' 值不同。

如果傳遞了 signal，則中止相應的 AbortController 將關閉返回的 <fs.FSWatcher> 。

注意事項#

fs.watch API 並非 100% 跨平台一致，並且在某些情況下不可用。

遞歸選項僅在 macOS 和 Windows 上受支持。在不支持該選項的平台上使用該選項時，將引發 ERR_FEATURE_UNAVAILABLE_ON_PLATFORM 異常。

在 Windows 上，如果監視的目錄被移動或重命名，則不會發出任何事件。刪除監視目錄時會報告EPERM錯誤。

可用性#

此函數取決於底層操作係統，它提供了一種通知文件係統更改的方法。

• 在 Linux 係統上，這使用 inotify(7) 。
• 在 BSD 係統上，這使用 kqueue(2) 。
• 在 macOS 上，這對文件使用 kqueue(2) ，對目錄使用 FSEvents 。
• 在 SunOS 係統(包括 Solaris 和 SmartOS)上，這使用 event ports 。
• 在 Windows 係統上，此函數取決於 ReadDirectoryChangesW 。
• 在 AIX 係統上，此函數取決於必須啟用的 AHAFS 。
• 在 IBM i 係統上，不支持此函數。

如果由於某種原因底層函數不可用，則fs.watch() 將無法運行並可能引發異常。例如，在使用 Vagrant 或 Docker 等虛擬化軟件時，在網絡文件係統(NFS、SMB 等)或主機文件係統上監視文件或目錄可能不可靠，在某些情況下是不可能的。

仍然可以使用 fs.watchFile() ，它使用 stat 輪詢，但這種方法速度較慢且可靠性較低。

索引節點#

在 Linux 和 macOS 係統上，fs.watch() 將路徑解析為 inode 並監視 inode。如果監視的路徑被刪除並重新創建，則會為其分配一個新的 inode。 watch 會發出一個刪除事件，但會繼續觀察原來的 inode。不會發出新 inode 的事件。這是預期的行為。

AIX 文件在文件的生命周期內保留相同的 inode。在 AIX 上保存和關閉監視的文件將產生兩個通知(一個用於添加新內容，一個用於截斷)。

文件名參數#

僅 Linux、macOS、Windows 和 AIX 支持在回調中提供 filename 參數。即使在受支持的平台上，也不能始終保證提供filename。因此，不要假設 filename 參數總是在回調中提供，如果是 null 則有一些回退邏輯。

import { watch } from 'node:fs';
watch('somedir', (eventType, filename) => {
  console.log(`event type is: ${eventType}`);
  if (filename) {
    console.log(`filename provided: ${filename}`);
  } else {
    console.log('filename not provided');
  }
});