源私有文件系统

文件系统标准引入了一个源专用文件系统 (OPFS)，作为对页面来源专用且对用户不可见的存储端点，该系统可让您选择访问针对性能进行了高度优化的特殊文件。

Thomas Steiner

浏览器支持

现代浏览器支持源私有文件系统，并且 Web 超文本应用技术工作组 (WHATWG) 在文件系统 Living Standard 中对其进行了标准化。

浏览器支持

  • Chrome：86。
  • Edge：86.
  • Firefox：111.
  • Safari：15.2。

来源

设计初衷

当您想到计算机上的文件时，可能想到的是文件层次结构：文件按文件夹整理，您可以使用操作系统的文件浏览器浏览这些文件夹。例如，在 Windows 上，对于名为 Tom 的用户，其待办事项列表可能位于 C:\Users\Tom\Documents\ToDo.txt 中。在此示例中，ToDo.txt 是文件名，Users、Tom 和 Documents 是文件夹名称。在 Windows 上，“C:”表示驱动器的根目录。

在 Web 上处理文件的传统方式

如需在 Web 应用中修改待办事项列表，通常流程如下：

  1. 用户使用 <input type="file"> 将文件上传到服务器，或在客户端上打开该文件。
  2. 用户进行更改，然后下载生成的文件，其中包含通过 JavaScript 以编程方式click()注入的 <a download="ToDo.txt>。
  3. 如需打开文件夹，您可以在 <input type="file" webkitdirectory> 中使用一个特殊属性，尽管该属性具有专有名称，但实际上几乎所有浏览器都支持它。

在网络上处理文件的新方法

此流程并不能代表用户对编辑文件的看法，这意味着用户最终会获得输入文件的下载副本。因此，File System Access API 引入了三个选择器方法：showOpenFilePicker()、showSaveFilePicker() 和 showDirectoryPicker()，其用途正是它们的名称所暗示的。它们支持以下流程：

  1. 使用 showOpenFilePicker() 打开 ToDo.txt，并获取 FileSystemFileHandle 对象。
  2. 从 FileSystemFileHandle 对象中，通过调用文件句柄的 getFile() 方法获取 File。
  3. 修改文件，然后对句柄调用 requestPermission({mode: 'readwrite'})。
  4. 如果用户接受权限请求，则将更改保存回原始文件。
  5. 或者，调用 showSaveFilePicker() 并让用户选择新文件。（如果用户选择之前打开的文件，其内容将被覆盖。）对于重复保存，您可以保留文件句柄，这样就不必再次显示文件保存对话框。

在 Web 上处理文件的限制

可通过这些方法访问的文件和文件夹位于所谓的用户可见文件系统中。从网络保存的文件（尤其是可执行文件）会带有网络标记，因此在执行可能危险的文件之前，操作系统会显示一条额外的警告。作为一项额外的安全功能，从网络获取的文件还受安全浏览保护。为简单起见，在本文中，您可以将安全浏览视为基于云的病毒扫描。当您使用 File System Access API 将数据写入文件时，系统不会就地写入，而是使用临时文件。除非文件本身通过所有这些安全检查，否则系统不会对其进行修改。正如您所想，尽管我们在可能的情况下进行了改进（例如在 macOS 上），但这项工作会导致文件操作速度相对较慢。不过，每个 write() 调用都是独立的，因此在后台，它会打开文件、跳转到给定偏移量，最后写入数据。

文件是处理的基础

同时，文件也是记录数据的绝佳方式。例如，SQLite 会将整个数据库存储在单个文件中。另一个示例是图片处理中使用的 mipmap。mipmap 是预先计算的经过优化的图像序列，其中每个图像都是前一个图像的分辨率逐渐降低的表示，这使得许多操作（例如缩放）的速度更快。那么，Web 应用如何才能获得文件的优势，而无需承担基于 Web 的文件处理的性能开销？答案是源私有文件系统。

用户可见与源私有文件系统

与使用操作系统的文件浏览器浏览的用户可见文件系统不同，原始私有文件系统不应供用户查看，其中的文件和文件夹无法读取、写入、移动和重命名。顾名思义，源专用文件系统中的文件和文件夹是不公开的，更具体地说，对网站的来源是不公开的。通过在开发者工具控制台中输入 location.origin 来了解页面的来源。例如，网页 https://developer.chrome.com/articles/ 的来源是 https://developer.chrome.com（即，部分 /articles 不属于来源）。如需详细了解源站理论，请参阅了解“same-site”和“same-origin”。共享相同源的所有网页都可以看到相同源的私有文件系统数据，因此 https://developer.chrome.com/docs/extensions/mv3/getstarted/extensions-101/ 可以看到与前面的示例相同的详细信息。每个源都有自己的独立源私有文件系统，这意味着 https://developer.chrome.com 的源私有文件系统与 https://web.dev 的源私有文件系统完全不同。在 Windows 上，可见于用户的文件系统的根目录为 C:\\。源私有文件系统的等效项是每个源的初始空根目录，通过调用异步方法 navigator.storage.getDirectory() 进行访问。如需查看用户可见文件系统和源私有文件系统的比较，请参阅下图。该图显示，除了根目录之外，其他所有内容在概念上都相同，并具有文件和文件夹的层次结构，可以根据您的数据和存储需求进行整理和排列。

显示用户可见文件系统和源私有文件系统的示意图，其中包含两个示例文件层次结构。用户可见文件系统的入口点是符号硬盘，源专用文件系统的入口点会调用“navigator.storage.getDirectory”方法。

源私有文件系统的具体信息

与浏览器中的其他存储机制（例如 localStorage 或 IndexedDB）一样，源私有文件系统也受浏览器配额限制。当用户清除所有浏览数据或所有网站数据时，源私有文件系统也会一并删除。调用 navigator.storage.estimate()，然后在生成的响应对象中查看 usage 条目，了解您的应用已占用多少存储空间，该信息会按存储机制在 usageDetails 对象中进行细分，您需要专门查看 fileSystem 条目。由于用户无法看到来源私有文件系统，因此系统不会显示权限提示，也不会进行安全浏览检查。

获取根目录的访问权限

如需获取对根目录的访问权限，请运行以下命令。最终，您会得到一个空目录句柄，更具体地说，是一个 FileSystemDirectoryHandle。

const opfsRoot = await navigator.storage.getDirectory();
// A FileSystemDirectoryHandle whose type is "directory"
// and whose name is "".
console.log(opfsRoot);

主线程或 Web Worker

您可以通过两种方式使用源私有文件系统：在主线程上或在 Web Worker 中。Web Worker 无法阻塞主线程，这意味着在这种情况下，API 可以是同步的，而主线程通常不允许这种模式。同步 API 的速度可能更快，因为它们不必处理 promise，并且文件操作在可编译为 WebAssembly 的 C 等语言中通常是同步的。

// This is synchronous C code.
FILE *f;
f = fopen("example.txt", "w+");
fputs("Some text\n", f);
fclose(f);

如果您需要尽可能快速地执行文件操作，或者要处理 WebAssembly，请跳至在 Web Worker 中使用源私有文件系统。否则，你可以继续阅读。

在主线程中使用源私有文件系统

创建新文件和文件夹

创建根文件夹后，分别使用 getFileHandle() 和 getDirectoryHandle() 方法创建文件和文件夹。通过传递 {create: true}，如果文件或文件夹不存在，系统会创建该文件或文件夹。使用新创建的目录作为起点调用这些函数，以构建文件层次结构。

const fileHandle = await opfsRoot
    .getFileHandle('my first file', {create: true});
const directoryHandle = await opfsRoot
    .getDirectoryHandle('my first folder', {create: true});
const nestedFileHandle = await directoryHandle
    .getFileHandle('my first nested file', {create: true});
const nestedDirectoryHandle = await directoryHandle
    .getDirectoryHandle('my first nested folder', {create: true});

上一个代码示例生成的文件层次结构。

访问现有文件和文件夹

如果您知道文件和文件夹的名称，可以通过调用 getFileHandle() 或 getDirectoryHandle() 方法并传入文件或文件夹的名称来访问之前创建的文件和文件夹。

const existingFileHandle = await opfsRoot.getFileHandle('my first file');
const existingDirectoryHandle = await opfsRoot
    .getDirectoryHandle('my first folder');

获取与文件句柄关联的文件以进行读取

FileSystemFileHandle 表示文件系统中的文件。如需获取关联的 File，请使用 getFile() 方法。File 对象是一种特定类型的 Blob，可在 Blob 可用的任何上下文中使用。具体而言，FileReader、URL.createObjectURL()、createImageBitmap() 和 XMLHttpRequest.send() 同时接受 Blobs 和 Files。从 FileSystemFileHandle 获取 File 会“释放”数据，以便您访问该数据并将其提供给可见的用户文件系统。

const file = await fileHandle.getFile();
console.log(await file.text());

通过流式传输写入文件

通过调用 createWritable() 将数据流式传输到文件中，该方法会创建一个 FileSystemWritableFileStream，然后write()内容。最后，您需要 close() 该数据流。

const contents = 'Some text';
// Get a writable stream.
const writable = await fileHandle.createWritable();
// Write the contents of the file to the stream.
await writable.write(contents);
// Close the stream, which persists the contents.
await writable.close();

删除文件和文件夹

通过调用文件或目录句柄的特定 remove() 方法来删除文件和文件夹。如需删除包含所有子文件夹的文件夹，请传递 {recursive: true} 选项。

await fileHandle.remove();
await directoryHandle.remove({recursive: true});

或者，如果您知道目录中要删除的文件或文件夹的名称，请使用 removeEntry() 方法。

directoryHandle.removeEntry('my first nested file');

移动和重命名文件和文件夹

使用 move() 方法重命名和移动文件和文件夹。移动和重命名可以同时进行，也可以单独进行。

// Rename a file.
await fileHandle.move('my first renamed file');
// Move a file to another directory.
await fileHandle.move(nestedDirectoryHandle);
// Move a file to another directory and rename it.
await fileHandle
    .move(nestedDirectoryHandle, 'my first renamed and now nested file');

解析文件或文件夹的路径

如需了解给定文件或文件夹相对于参考目录的位置，请使用 resolve() 方法，并将 FileSystemHandle 作为参数传递给该方法。如需获取源私有文件系统中文件或文件夹的完整路径，请将根目录用作通过 navigator.storage.getDirectory() 获取的参考目录。

const relativePath = await opfsRoot.resolve(nestedDirectoryHandle);
// `relativePath` is `['my first folder', 'my first nested folder']`.

检查两个文件或文件夹句柄是否指向同一文件或文件夹

有时，您有两个句柄，但不知道它们是否指向同一文件或文件夹。如需检查是否存在这种情况，请使用 isSameEntry() 方法。

fileHandle.isSameEntry(nestedFileHandle);
// Returns `false`.

列出文件夹的内容

FileSystemDirectoryHandle 是一个异步迭代器，您可以使用 for await…of 循环对其进行迭代。作为异步迭代器，它还支持 entries()、values() 和 keys() 方法，您可以根据需要从中进行选择：

for await (let [name, handle] of directoryHandle) {}
for await (let [name, handle] of directoryHandle.entries()) {}
for await (let handle of directoryHandle.values()) {}
for await (let name of directoryHandle.keys()) {}

以递归方式列出文件夹和所有子文件夹的内容

处理与递归搭配使用的异步循环和函数时，很容易出错。以下函数可用作列出文件夹及其所有子文件夹内容（包括所有文件及其大小）的起点。如果您不需要文件大小，则可以简化该函数，只需在 directoryEntryPromises.push 处直接推送 handle，而不是 handle.getFile() promise。

  const getDirectoryEntriesRecursive = async (
    directoryHandle,
    relativePath = '.',
  ) => {
    const fileHandles = [];
    const directoryHandles = [];
    const entries = {};
    // Get an iterator of the files and folders in the directory.
    const directoryIterator = directoryHandle.values();
    const directoryEntryPromises = [];
    for await (const handle of directoryIterator) {
      const nestedPath = `${relativePath}/${handle.name}`;
      if (handle.kind === 'file') {
        fileHandles.push({ handle, nestedPath });
        directoryEntryPromises.push(
          handle.getFile().then((file) => {
            return {
              name: handle.name,
              kind: handle.kind,
              size: file.size,
              type: file.type,
              lastModified: file.lastModified,
              relativePath: nestedPath,
              handle
            };
          }),
        );
      } else if (handle.kind === 'directory') {
        directoryHandles.push({ handle, nestedPath });
        directoryEntryPromises.push(
          (async () => {
            return {
              name: handle.name,
              kind: handle.kind,
              relativePath: nestedPath,
              entries:
                  await getDirectoryEntriesRecursive(handle, nestedPath),
              handle,
            };
          })(),
        );
      }
    }
    const directoryEntries = await Promise.all(directoryEntryPromises);
    directoryEntries.forEach((directoryEntry) => {
      entries[directoryEntry.name] = directoryEntry;
    });
    return entries;
  };

在 Web Worker 中使用源私有文件系统

如前所述，Web Worker 无法阻塞主线程，因此在这种情况下允许使用同步方法。

获取同步访问句柄

可尽可能快速执行文件操作的入口点是 FileSystemSyncAccessHandle，可通过调用 createSyncAccessHandle() 从常规 FileSystemFileHandle 获取。

const fileHandle = await opfsRoot
    .getFileHandle('my highspeed file.txt', {create: true});
const syncAccessHandle = await fileHandle.createSyncAccessHandle();

同步就地文件方法

获得同步访问句柄后，您就可以使用快速的原地文件方法，这些方法都是同步的。

  • getSize()：返回文件的大小（以字节为单位）。
  • write()：将缓冲区的内容写入文件（可选择在给定偏移处），并返回已写入的字节数。通过检查返回的已写入字节数，调用方可以检测和处理错误和部分写入。
  • read()：将文件内容读取到缓冲区（可选择在给定偏移处）。
  • truncate()：将文件大小调整为指定大小。
  • flush()：确保文件的内容包含通过 write() 完成的所有修改。
  • close()：关闭访问句柄。

以下示例使用了上述所有方法。

const opfsRoot = await navigator.storage.getDirectory();
const fileHandle = await opfsRoot.getFileHandle('fast', {create: true});
const accessHandle = await fileHandle.createSyncAccessHandle();

const textEncoder = new TextEncoder();
const textDecoder = new TextDecoder();

// Initialize this variable for the size of the file.
let size;
// The current size of the file, initially `0`.
size = accessHandle.getSize();
// Encode content to write to the file.
const content = textEncoder.encode('Some text');
// Write the content at the beginning of the file.
accessHandle.write(content, {at: size});
// Flush the changes.
accessHandle.flush();
// The current size of the file, now `9` (the length of "Some text").
size = accessHandle.getSize();

// Encode more content to write to the file.
const moreContent = textEncoder.encode('More content');
// Write the content at the end of the file.
accessHandle.write(moreContent, {at: size});
// Flush the changes.
accessHandle.flush();
// The current size of the file, now `21` (the length of
// "Some textMore content").
size = accessHandle.getSize();

// Prepare a data view of the length of the file.
const dataView = new DataView(new ArrayBuffer(size));

// Read the entire file into the data view.
accessHandle.read(dataView);
// Logs `"Some textMore content"`.
console.log(textDecoder.decode(dataView));

// Read starting at offset 9 into the data view.
accessHandle.read(dataView, {at: 9});
// Logs `"More content"`.
console.log(textDecoder.decode(dataView));

// Truncate the file after 4 bytes.
accessHandle.truncate(4);

将文件从源私有文件系统复制到用户可见的文件系统

如上所述，您无法将文件从源私有文件系统移至用户可见的文件系统，但可以复制文件。由于 showSaveFilePicker() 仅在主线程上公开，而未在 Worker 线程中公开，因此请务必在主线程上运行代码。

// On the main thread, not in the Worker. This assumes
// `fileHandle` is the `FileSystemFileHandle` you obtained
// the `FileSystemSyncAccessHandle` from in the Worker
// thread. Be sure to close the file in the Worker thread first.
const fileHandle = await opfsRoot.getFileHandle('fast');
try {
  // Obtain a file handle to a new file in the user-visible file system
  // with the same name as the file in the origin private file system.
  const saveHandle = await showSaveFilePicker({
    suggestedName: fileHandle.name || ''
  });
  const writable = await saveHandle.createWritable();
  await writable.write(await fileHandle.getFile());
  await writable.close();
} catch (err) {
  console.error(err.name, err.message);
}

调试源私有文件系统

在内置 DevTools 支持添加之前（请参阅 crbug/1284595），请使用 OPFS Explorer Chrome 扩展程序调试源私有文件系统。顺便提一下，上面的新建文件和文件夹部分的屏幕截图是直接从该扩展程序截取的。

Chrome 应用商店中的 OPFS Explorer Chrome DevTools 扩展程序。

安装扩展程序后，打开 Chrome 开发者工具，选择 OPFS Explorer 标签页，然后就可以检查文件层次结构了。点击文件名，将文件从源专用文件系统保存到用户可见的文件系统，点击垃圾桶图标删除文件和文件夹。

演示

在演示中查看原始私有文件系统的运作方式（如果您安装了 OPFS Explorer 扩展程序），该演示将其用作编译为 WebAssembly 的 SQLite 数据库的后端。请务必查看 Glitch 上的源代码。请注意，下面嵌入的版本如何不使用源私有文件系统后端（因为 iframe 是跨源的），但当您在单独的标签页中打开该演示时，它会使用该后端。

总结

WHATWG 指定的源私有文件系统塑造了我们在 Web 上使用和与文件互动的方式。它支持了一些无法通过面向用户的文件系统实现的新用例。所有主要浏览器供应商（Apple、Mozilla 和 Google）均已加入该计划，并拥有共同愿景。源私有文件系统的开发是一项协作工作，开发者和用户的反馈对其进展至关重要。我们会不断优化和改进该标准，欢迎您以问题或拉取请求的形式对 whatwg/fs 代码库提供反馈。

致谢

本文由 Austin Sully、Etienne Noël 和 Rachel Andrew 审核。主打图片，由 Christina Rumpf 在 Unshot 中使用。