File System Access API 实现浏览器本地文件读写教程

想用Ja vaScript直接读写用户本地文件？File System Access API确实提供了这种可能，但它远非一个“即插即用”的简单功能。从运行环境到调用时机，从权限管理到数据落盘，每一步都有明确的规则和容易踩坑的细节。下面，我们就来拆解一下，如何安全、正确地使用这个强大的API。

首先得明确一个核心概念：这个API无法通过HTML标签或属性来启用。它必须由Ja vaScript代码，在用户主动交互（如点击）后触发调用。并且，它只在安全的上下文中生效——即HTTPS协议或本地的localhost环境。当你调用window.showOpenFilePicker()时，它返回的是一个FileSystemFileHandle对象（文件句柄），而非传统的文件路径字符串。这也意味着，你无法通过这个句柄自动读取同一目录下的其他文件。

必须满足的运行前提条件

别指望写了代码就能跑。如果环境不满足要求，浏览器会直接抛出错误：

• 安全协议是硬门槛：页面如果运行在file://协议下（比如直接双击打开的HTML文件），或者被嵌套在一个非安全上下文的iframe里，都会触发SecurityError。必须是https://或http://localhost，连http://127.0.0.1都不行。
• 用户手势触发：所有API调用都必须由用户的明确操作引发，比如绑定在按钮的onclick事件或文件输入的onchange事件上。在DOMContentLoaded或setTimeout中自动执行是行不通的。
• 浏览器兼容性参差不齐：Chrome和Edge从115版本开始提供完整支持，Firefox 125+仅部分支持，而Safari则完全未实现。跨浏览器“开箱即用”目前还不太现实。

showOpenFilePicker() 之后怎么读内容

拿到文件句柄只是万&里长征第一步。这个句柄本身并不包含文件内容，你需要通过fileHandle.getFile()方法来获取一个只读的File对象——这和通过拿到的对象是一致的。

• 必须显式调用：只有执行了const file = await fileHandle.getFile()，才能读取文件当前状态的快照。
• 读取方法：之后，你可以使用file.text()、file.arrayBuffer()或file.stream()来获取内容。但要注意，这个File对象是静态的，不会自动反映文件被其他程序修改后的内容。
• 常见误区：很多人误以为fileHandle能直接读取，实际上必须经过getFile()这一步。
• 如何感知变更：如果你需要实时知道文件是否被外部编辑器修改了，目前没有原生事件可以监听。通常的做法是结合fileHandle.queryPermission({ mode: 'readwrite' })检查权限，然后通过轮询等方式重新获取文件。

createWritable() 写入必须配 close()

这是新手最容易栽跟头的地方：调用了write()，却发现文件内容没变，或者只写入了部分数据。问题的关键往往在于漏掉了close()。

• 打开的是流通道：const writable = await fileHandle.createWritable()这行代码，打开的是一个流式的写入通道，而不是一个覆盖写入的命令。
• 写入缓冲区：当你执行await writable.write('hello')时，数据只是被送到了缓冲区，并没有真正写入磁盘。
• 提交的关键：必须调用await writable.close()，才能将缓冲区中的所有数据提交到磁盘，并释放文件句柄。忘记这一步，前面的写入操作就白费了。
• 追加内容：API没有提供直接的append模式。如果你想在文件末尾追加内容，需要手动将写入位置定位到文件末尾：await writable.write({ type: 'seek', position: file.size })。

如何安全保存而不覆盖误操作

当用户点击“保存”时，直接使用之前打开的句柄进行写入可能会带来风险，尤其是文件可能已经被其他程序修改过。

• 谨慎打开：首次使用showOpenFilePicker时，可以考虑设置{ excludeAcceptAllOption: true }选项，避免用户误选了“所有文件”类型，从而授予过宽的权限。
• 保存策略：保存时，应优先尝试重用已有的fileHandle。但务必做好错误捕获，处理NotAllowedError（用户撤销了权限）和NotFoundError（文件被删除或移动）等情况。
• 失败回退：如果重用句柄失败，应该有一个fallback方案，例如自动调用showSa veFilePicker()弹出新的保存对话框，而不是让操作静默失败。
• 句柄的持久化：文件句柄本身不能在不同页面间直接持久化，但可以通过structuredClone()进行序列化，然后传递给Web Worker或存储到IndexedDB中。下次使用时，需要先通过queryPermission检查其是否仍然有效。

说到底，真正的挑战往往不在于API语法本身，而在于权限和状态的不确定性。用户可能中途撤销授权，文件可能被系统锁定，句柄也可能过期失效。一个健壮的做法是，在每次进行写入操作前，都检查一下权限状态：await fileHandle.queryPermission({ mode: 'readwrite' }) === 'granted'。永远不要假设上一次的成功操作，在这一次依然有效。