MDN Web API 教程：深入理解 File System API

概述

File System API 是现代 Web 开发中一个强大的文件系统访问接口，它允许网页应用以安全的方式读写用户设备上的文件系统。这个 API 的出现填补了 Web 平台长期缺乏本地文件系统交互能力的空白，为开发者提供了更多可能性。

核心概念

文件系统访问方式

File System API 提供了两种主要的访问模式：

1. 用户可见文件系统：通过文件选择器让用户明确选择文件或目录
2. 源私有文件系统(OPFS)：一个对用户不可见的沙盒文件系统，专为当前网站源保留

核心接口

API 的核心是几个关键接口：

• FileSystemHandle：基础接口，表示文件系统中的一个条目
• FileSystemFileHandle：表示文件句柄
• FileSystemDirectoryHandle：表示目录句柄
• FileSystemWritableFileStream：用于写入文件的流接口
• FileSystemSyncAccessHandle：高性能同步访问接口（仅在 Worker 中可用）

实际应用场景

常见使用案例

1. 文件编辑器：实现类似记事本的功能，允许用户打开、编辑和保存文件
2. 媒体管理器：让用户选择并管理本地图片、视频或音乐文件
3. 数据导出：将应用数据导出为用户选择的文件格式
4. 项目工具：在浏览器中管理本地项目文件结构

OPFS 的特殊用途

源私有文件系统特别适合以下场景：

• 需要高性能文件操作的应用程序（如视频编辑器）
• 需要离线缓存大量数据的应用
• 需要临时存储大文件的场景（如邮件客户端附件）
• 游戏资源管理

基本用法详解

获取文件访问权限

要访问用户文件，首先需要获取文件句柄。最常见的方式是使用文件选择器：

async function pickFile() {
  try {
    const [fileHandle] = await window.showOpenFilePicker();
    const file = await fileHandle.getFile();
    console.log('文件内容:', await file.text());
  } catch (err) {
    console.error('用户取消选择或发生错误:', err);
  }
}

目录操作

处理目录时，可以递归遍历内容：

async function listDirectory(directoryHandle) {
  const entries = [];
  for await (const entry of directoryHandle.values()) {
    entries.push({
      name: entry.name,
      kind: entry.kind,
      handle: entry
    });
  }
  return entries;
}

文件写入操作

写入文件需要创建可写流：

async function writeFile(fileHandle, contents) {
  const writableStream = await fileHandle.createWritable();
  await writableStream.write(contents);
  await writableStream.close();
}

高级特性：同步访问

对于性能敏感的操作，可以使用同步访问接口（仅在 Worker 中）：

// 在 Worker 中
async function processFile() {
  const root = await navigator.storage.getDirectory();
  const fileHandle = await root.getFileHandle('data.bin', { create: true });
  const accessHandle = await fileHandle.createSyncAccessHandle();
  
  // 同步读写操作
  const buffer = new DataView(new ArrayBuffer(1024));
  accessHandle.read(buffer, { at: 0 });
  
  // ...处理数据...
  
  accessHandle.write(new Uint8Array([1, 2, 3]), { at: 0 });
  accessHandle.flush();
  accessHandle.close();
}

安全与权限考虑

File System API 设计时特别注重安全性：

1. 用户显式授权：必须通过用户交互（如点击事件）才能触发文件选择器
2. 权限持久化：用户可以选择记住权限，减少重复授权
3. 沙盒限制：OPFS 完全隔离，无法访问用户其他文件

最佳实践

1. 优雅降级：检测 API 可用性并提供替代方案

   if (!('showOpenFilePicker' in window)) {
     // 提供传统文件上传方式
   }
   

2. 错误处理：妥善处理用户取消操作等情况

3. 性能优化：对大文件使用流式处理

4. 内存管理：及时关闭文件和流

浏览器兼容性

目前主流现代浏览器都已支持 File System API 的核心功能，但某些高级特性可能仍有差异。开发时应：

• 检查具体接口的支持情况
• 考虑渐进增强策略
• 必要时提供 polyfill 或替代方案

总结

File System API 为 Web 应用带来了前所未有的本地文件系统交互能力，使 Web 应用能够实现以前只有原生应用才能做到的文件操作功能。通过合理使用这个 API，开发者可以创建更强大、更贴近用户需求的 Web 应用，同时保持良好的安全性和用户体验。