File System Access API 和 Origin Private File System API 都允许开发者访问用户设备上的文件和目录。前者允许开发者读取和写入对用户可见的常规文件系统，而后者会打开一个特殊的文件系统，该文件系统对用户隐藏，仅供每个网站的来源使用，并且具有一定的性能优势。在这两种情况下，开发者与文件和目录交互的方式都是通过 FileSystemHandle 对象，更具体地说，对于文件，是通过 FileSystemFileHandle，对于目录，是通过 FileSystemDirectoryHandle。到目前为止，若要了解任一文件系统中文件或目录的更改，都需要进行某种形式的轮询并比较 lastModified 时间戳，甚至文件内容本身。
从 Chrome 129 开始，File System Observer API 的源试用版会改变这一点，并让开发者在发生更改时自动收到提醒。本指南介绍了该功能的运作方式以及如何试用该功能。
使用场景
在需要在可能发生文件系统更改时立即收到通知的应用中使用 File System Observer API。
- 基于 Web 的集成开发环境 (IDE)，用于显示项目的文件系统树的表示法。
- 与服务器同步文件系统更改的应用。例如，SQLite 数据库文件。
- 需要通过工作器或其他标签页向主线程通知文件系统更改的应用。
- 监控资源目录的应用，例如自动优化图片。
- 可从热重载中受益的体验，例如基于 HTML 的幻灯片演示文稿，其中文件更改会触发重新加载。
如何使用 File System Observer API
功能检测
如需查看是否支持文件系统观察器 API，请运行功能测试，如以下示例所示。
if ('FileSystemObserver' in self) {
// The File System Observer API is supported.
}
初始化文件系统观察器
通过调用 new FileSystemObserver() 初始化文件系统观察器，并将 callback 函数作为参数提供给它。
const observer = new FileSystemObserver(callback);
开始观察文件或目录
如需开始观察文件或目录，请调用 FileSystemObserver 实例的异步 observe() 方法。将所选文件或目录的 FileSystemHandle 作为参数提供给此方法。在观察目录时，有一个可选的 options 参数，可让您选择是否要以递归方式（即目录本身以及所有包含的子目录和文件）接收目录更改通知。默认选项是仅观察目录本身及其直接包含的文件。
// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});
回调函数
当文件系统发生更改时，系统会调用回调函数，并将文件系统更改 records 和 observer 本身作为其参数。例如，您可以使用 observer 参数在您感兴趣的文件全部被删除时断开观察器（请参阅停止观察文件系统）。
const callback = (records, observer) => {
for (const record of records) {
console.log('Change detected', record);
}
};
文件系统更改记录
每个文件系统更改记录都采用以下结构。所有字段均为只读字段。
root（一个FileSystemHandle）：传递给FileSystemObserver.observe()函数的句柄。changedHandle（一个FileSystemHandle）：受文件系统更改影响的句柄。对于"errored"、"unknown"和"disappeared"类型事件，此字段将为null。如需查看哪些文件或目录已消失，请使用relativePathComponents。relativePathComponents（一个Array）：changedHandle相对于root的路径。type（一个String）：更改的类型。可能出现的类型如下："appeared"：文件或目录已创建或移至root。"disappeared"：文件或目录已被删除或移出root。"modified"：文件或目录已修改。"moved"：文件或目录在root中移动。"unknown"：表示错过了零个或多个事件。开发者应对此轮询所监控的目录。"errored"：观察结果已失效。在这种情况下，您可能需要停止观察文件系统。当每个来源的观察值达到上限时，系统也会发送此值。此限制取决于操作系统，无法事先得知。如果发生这种情况，网站可能会决定重试，但无法保证操作系统已释放足够的资源。当被观察的句柄（即观察的根）被删除或移动时，系统也会发送此值。在这种情况下，系统会先发送"disappeared"事件，然后再发送"errored"事件，以指示观察结果已失效。最后，当目录或文件句柄的权限被移除时，系统会发送此事件。
relativePathMovedFrom（一个Array，可选）：移动的手柄的旧位置。仅当type为"moved"时可用。
停止观察文件或目录
如需停止观察 FileSystemHandle，请调用 unobserve() 方法，并将句柄作为参数传递给该方法。
observer.unobserve(fileHandle);
停止观察文件系统
如需停止观察文件系统，请按如下所示断开 FileSystemObserver 实例的连接。
observer.disconnect();
试用 API
如需在本地测试文件系统观察器 API，请在 about:flags 中设置 #file-system-observer 标志。如需使用真实用户测试该 API，请注册源试用，然后按照 Chrome 源试用指南中的说明操作。源试用将从 Chrome 129（2024 年 9 月 11 日）持续到 Chrome 134（2025 年 2 月 26 日）。
演示
您可以在嵌入的演示版中查看文件系统观察器 API 的实际运作方式。查看源代码，或在 Glitch 上对演示代码进行混剪。该演示会在受监视的目录中随机创建、删除或修改文件，并在应用窗口的上半部分记录其活动。然后，它会在应用窗口底部发生更改时记录这些更改。如果您是在不支持 File System Observer API 的浏览器上阅读本文，请查看演示的屏幕截图。
反馈
如果您对文件系统观察器 API 的形状有任何反馈，请对 WHATWG/fs 代码库中的第 123 个问题发表评论。
相关链接
致谢
本文档由 Daseul Lee、Nathan Memmott、Etienne Noël 和 Rachel Andrew 审核。