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');
  }
});