首页 > 文章 > 前端

JavaScript File System Access API 怎样从文件句柄创建可写流

来源：17golang原创

时间：2026-11-02 14:50:51 260浏览收藏

在浏览器里把内容写回用户选中的文件，关键不是直接拿到本地路径，而是先让用户通过文件选择器授予访问范围，再用返回的 FileSystemFileHandle 创建 FileSystemWritableFileStream。写入可以是字符串、Blob 或其他支持的数据，最后必须等待 close() 完成收尾。

最小可靠路径是：用户点击按钮触发选择器，拿到文件句柄，调用 createWritable()，执行一次或多次 write()，在成功或失败收尾中处理流。这个 API 只在安全上下文等受支持条件下可用，不能把“拿到句柄”理解成永久绕过权限。

本文围绕一个浏览器 API 展开，官方资料地址为 https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle/createWritable。示例是原创说明代码，不代表在某个具体浏览器组合中已经完成运行验证。

先取得用户明确授权的文件句柄

File System API 的对象不是文件路径字符串，而是代表文件入口的句柄。常见入口是 showOpenFilePicker() 或 showSaveFilePicker()：用户在选择器中选定文件后，页面才获得对应的 FileSystemFileHandle。文件选择器通常应由按钮点击等用户手势触发，并且页面要运行在 HTTPS 等安全上下文中。

用户手势、文件选择器、FileSystemFileHandle、createWritable、可写流和本地文件之间的静态关系说明图 — 图1：文件句柄到可写流的静态模块关系说明图；它展示 API 职责边界，不是浏览器截图或运行证据。

const chooseButton = document.querySelector('#choose-file');
const status = document.querySelector('#file-status');

chooseButton.addEventListener('click', async () => {
  try {
    // 让选择器由用户点击触发，避免脱离用户手势直接请求文件权限。
    const [fileHandle] = await window.showOpenFilePicker({ multiple: false });
    // 句柄只代表用户选择的入口，后续写入仍要经过权限和流的处理。
    status.textContent = `已选择：${fileHandle.name}`;
  } catch (error) {
    // 用户关闭选择器通常属于取消，不应被页面当成写入成功。
    status.textContent = error.name === 'AbortError' ? '用户取消选择' : '选择文件失败';
  }
});

如果用户直接关闭选择器，常见结果是 AbortError；如果调用不符合安全上下文或用户交互条件，也可能进入异常分支。不要在页面加载时偷偷调用选择器，也不要把文件句柄序列化成一个看似永久有效的路径。

用 createWritable 创建异步可写流

取得句柄后，真正负责写入的是 createWritable() 返回的可写流。可以把职责拆成三层：句柄描述“写哪个文件”，可写流描述“如何提交写入”，而 write() 的参数描述“写入什么内容”。这样定位问题时，不会把权限失败、流创建失败和数据格式问题混为一谈。

async function writeTextFile(fileHandle, text) {
  // createWritable 返回 FileSystemWritableFileStream，而不是普通字符串缓冲区。
  const writable = await fileHandle.createWritable();
  try {
    // write 接受字符串、Blob 等可写入数据；这里写入编辑器产生的文本。
    await writable.write(text);
    // close 完成流的收尾，等待它结束后再提示用户保存成功。
    await writable.close();
  } catch (error) {
    // 写入或关闭失败时，调用方可以根据异常类型显示不同的恢复提示。
    throw new Error('文件写入未完成', { cause: error });
  }
}

成功提示应放在 close() 完成之后。只等待 write() 而不关闭流，会让调用方无法把“数据已经交给流”与“文件写入已经收尾”区分开。

按数据类型和写入模式组织内容

最常见的输入是字符串和 Blob。例如文本编辑器可以直接写字符串，导出的图片、压缩包或二进制结果则适合先组织成 Blob。如果需要修改文件中的某个位置，写入参数还可以表达 seek、带位置的 write 或 truncate；这些动作要和产品的数据格式一起设计，不能把可写流当成自动合并器。

async function writeExport(fileHandle, title, bytes) {
  // Blob 让导出的二进制内容带上明确的 MIME 类型。
  const payload = new Blob([title, bytes], { type: 'application/octet-stream' });
  const writable = await fileHandle.createWritable();
  try {
    // 一次写入完整导出结果，适合文件内容已经在内存中准备好的场景。
    await writable.write(payload);
    await writable.close();
  } catch (error) {
    // close 也可能失败，因此统一把原始异常交给上层处理。
    throw error;
  }
}

如果应用要分段写入，应明确每段的顺序、偏移和失败后的恢复策略。小文件可以一次性准备好数据；大文件则要关注内存占用、取消操作以及用户是否仍然保留写入权限。

把取消、权限和异常收成闭环

拿到句柄并不等于每次操作都能成功。权限可能需要重新确认，用户也可能在选择器里取消，写入过程还可能受到磁盘或浏览器状态影响。写入函数要让异常向上层传递，同时在已经创建流之后尽量执行关闭或清理动作。

FileSystemFileHandle、queryPermission、createWritable、write、close、AbortError 和 NotAllowedError 的静态职责关系说明图 — 图2：write、close 与权限及异常边界的结构说明图；它用于理解收尾职责，不是运行结果截图。

async function saveWithPermission(fileHandle, contents, signal) {
  // 先读取权限状态；实际写入仍可能再次失败，所以不能只依赖这个判断。
  const permission = await fileHandle.queryPermission({ mode: 'readwrite' });
  if (permission !== 'granted') {
    throw new DOMException('没有写入权限', 'NotAllowedError');
  }

  const writable = await fileHandle.createWritable();
  try {
    // 在真正写入前检查取消，避免把已放弃的任务继续提交给流。
    signal?.throwIfAborted();
    await writable.write(contents);
    signal?.throwIfAborted();
    await writable.close();
  } catch (error) {
    // 取消、权限失败和其他写入错误交给调用方决定提示或重试策略。
    throw error;
  }
}

queryPermission() 是状态检查，不是永久授权。若页面刷新、相关标签页关闭或用户撤销权限，后续调用仍可能需要重新处理。取消操作也不会自动撤销已经写入的内容，界面需要明确显示“已取消”“保存失败”或“已保存”这几种不同状态。

准备能力检测与降级方案

File System Access API 不是所有浏览器都提供一致支持，文件选择器还受到安全上下文和用户交互限制。入口按钮可以先检测能力；不支持时，改用生成下载链接、传统上传接口或提示用户更换环境，不要让按钮无响应。

function canUseFileSystemAccess() {
  // 同时检查选择器和句柄方法，避免只检测一个入口就误判能力完整。
  return typeof window.showSaveFilePicker === 'function'
    && typeof FileSystemFileHandle !== 'undefined'
    && typeof FileSystemFileHandle.prototype.createWritable === 'function';
}

async function saveOrDownload(contents) {
  if (!canUseFileSystemAccess()) {
    // 兼容分支不伪装成本地覆盖写入，而是明确提供下载结果。
    const blob = new Blob([contents], { type: 'text/plain;charset=utf-8' });
    const url = URL.createObjectURL(blob);
    const link = document.createElement('a');
    link.href = url;
    link.download = 'export.txt';
    link.click();
    URL.revokeObjectURL(url);
    return 'download';
  }
  const fileHandle = await window.showSaveFilePicker();
  await writeTextFile(fileHandle, contents);
  return 'saved';
}

降级路径的语义要说清：下载是生成一个新文件交给用户保存，不等同于直接覆盖原文件。这样用户才能根据产品目标选择合适的交互，而不是把兼容性差异藏在一个模糊的“保存成功”提示里。