File System Access API：让 Web 应用像桌面应用一样操作本地文件

浏览器里操作本地文件，为什么值得再谈一次

Web 应用在文件操作这件事上，一直被桌面应用压着打。早年浏览器只能通过 <input type="file"> 选择文件，或者用拖拽拿一个只读的 File 对象，想要写入、编辑、维护目录结构几乎不可能。直到 File System Access API 出现，情况才真正发生变化。

这个 API 让浏览器里的应用可以像桌面软件那样，读取、编辑、甚至把更改保存回本地文件。前端团队终于能把一些原本只能靠 Electron 或原生应用解决的问题，搬回浏览器里做。但它也不是许多文章里写的那么完美——权限模型、浏览器兼容性、沙箱限制，每一个都可能让项目踩坑。

这篇文章想从工程视角把 File System Access API 讲透：它解决了什么、底层怎么运作、在真实系统里怎么用，以及哪些场景其实不应该用它。

File System Access API 到底解决了什么问题

过去十年，网页应用处理文件的典型方式是：用户上传一个文件，服务器处理，再下载回来。哪怕是纯前端工具，也只能把整个文件读进内存，改完再手动下载新文件。这种模式有两个明显的痛点：

• 文件一大的时候，内存容易撑不住，应用体验断崖式下降。
• 没有“原地保存”的概念，改完只能另存为一份，多步操作特别难受。

File System Access API 把文件句柄这个概念带进了浏览器。用户授权之后，应用就能持有一个指向真实文件或目录的引用，既能读也能写，还能监听外部修改。对于在线编辑器、图表工具、IDE 这类应用，它是一个真正的转折点。

举个最常见的场景：一个在线流程图工具。老实现里用户导出一次就得下载一个文件；而新实现可以让用户直接“打开”本地的某个工程文件，改完按 Ctrl+S 就写回原文件，流程和桌面软件几乎没差别。很多团队想用浏览器替代桌面应用，卡住的正是这个“文件原地保存”的能力。

核心概念：文件句柄、权限与用户意图

File System Access API 的三个核心对象：FileSystemFileHandle、FileSystemDirectoryHandle 和 FileSystemWritableFileStream。每个句柄都对应磁盘上的一个真实条目，而你想要访问任何句柄，都必须先经过用户手势触发的授权流程。

用户激活是安全的底线

浏览器不会让页面静默读取本地文件。唯一的入口是 window.showOpenFilePicker() 或 window.showDirectoryPicker() 这类方法，它们必须被放在用户点击事件回调里调用，之后弹出一个原生的文件选择框。用户一旦选择并确认，页面才拿到对应句柄。这个设计把“页面有能力”和“用户同意”绑定在一起。

权限是可以持久化的。用 requestPermission() 请求读写权限后，浏览器会记住当前源（origin）对这个句柄的授权状态，下次打开页面时通过 indexedDB 存下句柄，就能直接恢复权限，不用再次弹窗。但也有个容易被忽略的细节：如果页面修改了文件的内容，浏览器会把句柄变成“脏状态”，这时再次调用 requestPermission() 可能会被拒绝，除非用户显式重新授权。这个行为在不同浏览器有差异，代码里必须做好错误处理。

句柄存储与会话恢复

文件句柄的结构化克隆算法支持存入 IndexedDB，这意味着你可以实现“上次打开过哪些文件”的功能。典型的恢复流程是：

// 存储句柄
const handle = await window.showOpenFilePicker();
const db = await openDatabase();
await db.put('handles', handle);

// 恢复句柄
const saved = await db.get('handles');
const permission = await saved.queryPermission();
if (permission === 'granted') {
  const file = await saved.getFile();
  // 直接使用
} else {
  const request = await saved.requestPermission();
  if (request === 'granted') {
    // 继续
  }
}

不过要注意，IndexedDB 本身是异步的，恢复操作不应该阻塞首屏渲染。更稳妥的做法是先把界面渲染出来，后台恢复句柄，再提示用户重新授权。很多开发者为了省事在 DOMContentLoaded 里同步恢复，结果碰到权限问题导致整个应用卡死。

文件写入：原地保存背后的机制

File System Access API 没有直接提供 write(file, data) 这种简单接口，而是通过创建可写流（writable stream）来完成。

// 获取一个写权限
const writable = await fileHandle.createWritable();

// 写入新内容
await writable.write('新内容');

// 关闭流，触发磁盘写入
await writable.close();

这段代码里，createWritable() 会先构建一个临时文件，直到 close() 被调用才真正替换原文件。这样做的好处是：即使写入过程中浏览器崩溃了，原文件不容易被写坏。代价是你需要管理这个临时状态，尤其是文件很大的时候，磁盘占用可能翻倍。

许多实现通过写整个文件内容到 writable 来完成保存，这在小文件场景没问题。但在大文件处理时，更合理的方式是：只把变更的字节写入特定位置，或者采用增量快照策略。这个 API 本身支持 write(position, data) 这种按偏移量写入的方法，但在浏览器里的实际支持程度并不一致，生产环境最好封装一层。

目录句柄：从单文件走向整个工程

目录操作是 File System Access API 最被低估的能力。通过 showDirectoryPicker() 拿到目录句柄后，可以遍历目录、创建子目录、重命名、删除文件，甚至递归地读取整个目录树。

const dirHandle = await window.showDirectoryPicker();
for await (const [name, handle] of dirHandle.entries()) {
  if (handle.kind === 'file') {
    console.log('文件：', name);
  } else {
    console.log('子目录：', name);
  }
}

这让浏览器具备了操作“整个项目”的能力。比如一个纯前端的代码编辑器，可以打开一个本地目录，读取里面的所有源文件，修改后保存回去。Git 操作、批量替换、多文件搜索，这些以前想都不敢想的功能，现在都有了实现的基础。

目录句柄也带来更复杂的权限问题。你只对一个目录有权限，页面只能看到这个目录内的条目，无法跨越到上层目录。如果目录被移动或删除，原有句柄可能失效，必须在代码中处理这类异常。

三个真实场景里的坑

理论和 API 文档看起来都不复杂，一上生产环境问题就开始浮现。

坑一：大文件的读入内存问题

很多团队实现了“打开文件”后，习惯性地用 await file.text() 或 await file.arrayBuffer() 把整个文件读进内存。文件一旦超过几百 MB，页面会直接卡死。正确做法是使用 FileStream 配合流式处理，或者保持文件的引用，按需读取某一段数据，避免一次性加载。

坑二：权限状态不是静态的

用户在系统文件管理器里改了文件权限，或者把文件移动到了别的目录，浏览器中的句柄状态可能变成“不再拥有权限”。有些团队只在实际写操作前才检查权限，结果用户点击“保存”后才发现没有权限，体验非常差。更好的做法是每进行一次关键操作前都重新查询权限，并且在没有权限时快速引导用户重新授权。

坑三：移动端 Safari 根本不支持

File System Access API 目前主要在 Chromium 内核的桌面浏览器中完整支持。Safari 和 Firefox 都有过实验性实现，但离可用还有距离。如果你做的是跨平台 Web 应用，就必须为不支持的环境提供降级方案：比如回归到传统的文件上传下载，或者提示用户使用桌面版 Chrome。忽略兼容性而把 API 直接铺到生产环境，几乎必然收到一堆用户反馈“我的浏览器打不开”。

不同方案怎么选：从原生到纯前端

如果 File System Access API 让你心动了，先别急着重构。不同的技术路线适合不同阶段的团队。

我见过不少团队因为 Electron 打包体积太大、自动更新太麻烦，想用 File System Access API 替代一部分原生功能。这个思路是可行的，但前提是你的目标用户基本使用 Chromium 系浏览器，并且应用本身不需要太底层的系统集成（比如访问串口、读取系统级快捷键）。如果你需要跨浏览器和无缝覆盖，传统上传下载仍是兜底方案。

落地建议：从一句话需求到可靠实现

真要落地，下面这几个建议大概率能帮你避开多数问题。

• 先做功能开关。 用特性检测判断是否支持 File System Access API，不支持就走传统文件选择器。不要假定“现代浏览器都有”。
• 封装一个 storage 层。 所有文件读写都通过自己的模块进行，内存态和磁盘态分离，后面换实现或加缓存都容易。
• 处理并发保存。 用户可能打开多个文件，或者同一个文件被外部修改。保存前最好比较文件修改时间，避免覆盖外部变更。
• 建立错误恢复机制。 写文件失败或者权限丢失时，至少让用户能导出备份，不要把用户数据锁死。

从更长远的角度看，浏览器正在逐渐打破系统能力的边界。File System Access API 是这座桥的一块重要桥墩，但它的权限模型和兼容性决定了它不会完全替代桌面应用。对多数 Web 团队来说，与其把它当成银弹，不如当作一种提升体验的渐进增强手段。理解它的边界，合理设计降级路径，才能让 Web 应用真正迈出“操作本地文件”这一步，又不至于被坑到原地返工。