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

在浏览器里把内容写回用户选中的文件，关键不是直接拿到本地路径，而是先让用户通过文件选择器授予访问范围，再用返回的 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 等安全上下文中。

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;
  }
}

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

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

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

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';
}

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

用五个问题复查实现

1. 是否由用户动作触发：文件选择器放在按钮等明确交互路径中，而不是页面加载时自动弹出。
2. 是否满足安全上下文：部署环境使用 HTTPS 等受支持条件，并把能力检测放在实际入口。
3. 是否等待 close：只有写入和流关闭都完成后，才显示保存成功。
4. 是否区分异常：用户取消、权限不足、浏览器不支持和写入失败分别给出可理解的处理。
5. 是否准备降级：不支持本地句柄写入时，使用下载或上传方案，不伪造原地保存能力。

File System Access API 的价值是把用户授权后的本地文件读写接入网页应用，但它不会替应用解决权限、兼容性、取消和数据恢复问题。把句柄、可写流、写入动作和 close 收尾分开设计，代码更容易维护，用户也更容易理解当前到底发生了什么。

相关问题

createWritable() 会直接返回本地文件路径吗？
不会。它返回的是与文件句柄关联的可写流，应用通过流写入内容，不需要也不应该依赖本地路径字符串。

为什么选择器调用没有弹出？
先检查是否在安全上下文中，再确认调用是否来自用户手势，并查看当前浏览器是否支持该 API。

写入后为什么还要调用 close()？
close() 是可写流的收尾动作。等待它完成后，调用方才适合把结果状态显示为保存成功。

参考资料：https://developer.mozilla.org/en-US/docs/Web/API/File_System_API、https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle、https://developer.mozilla.org/en-US/docs/Web/API/Window/showOpenFilePicker。