"File System Access API 浏览器端文件读写与权限实践"

File System Access API 浏览器端文件读写与权限实践概述File System Access API 允许 Web 应用在用户授权后直接读写本地文件或目录，适合富文本编辑器、图像/视频处理、项目文件管理等场景。适配性与限制支持：Chromium 系（Chrome/Edge）稳定；Safari（部分版本）与 Firefox 暂不支持或需实验标志。前提：需用户手势触发（如点击按钮）才能弹出文件或目录选择器。权限：文件/目录的授权可持久；可通过 `queryPermission`/`requestPermission` 查询与请求。核心内容打开文件与读取// 需在用户手势内触发 const [handle] = await (window as any).showOpenFilePicker({ types: [{ description: '文本', accept: { 'text/plain': ['.txt', '.log'] } }], excludeAcceptAllOption: false, multiple: false, }) const file = await handle.getFile() const text = await file.text() 保存文件与写入// 新建或另存为 const handle = await (window as any).showSaveFilePicker({ suggestedName: 'output.txt', types: [{ description: '文本', accept: { 'text/plain': ['.txt'] } }], }) const writable = await handle.createWritable() await writable.write('Hello, FSA!') await writable.close() // 原子写入，关闭时提交 目录选择与遍历const dir = await (window as any).showDirectoryPicker() for await (const [name, entry] of (dir as any)) { // entry 可能是 FileSystemFileHandle 或 FileSystemDirectoryHandle } 权限查询与请求async function ensurePermission(handle: FileSystemHandle) { const state = await (handle as any).queryPermission?.({ mode: 'readwrite' }) if (state === 'granted') return true const req = await (handle as any).requestPermission?.({ mode: 'readwrite' }) return req === 'granted' } 技术参数与验证用户手势：`showOpenFilePicker`/`showSaveFilePicker`/`showDirectoryPicker` 必须在用户交互事件中调用。写入行为：`createWritable()` 返回 `FileSystemWritableFileStream`，`write()` 支持字符串、`Blob`、`ArrayBuffer`，`close()` 提交原子写入。权限状态：`queryPermission`/`requestPermission` 返回 `granted`/`prompt`/`denied`；目录授权可持久。错误处理：权限拒绝抛出 `DOMException`；文件被外部删除需重新选择。验证环境：Chrome 121、Windows/macOS；文本/二进制读写、目录遍历与权限状态均通过手动与自动化用例验证。注意事项兼容回退：不支持浏览器回退至 `<input type="file">`、OPFS 或 IndexedDB。安全与隐私：仅访问用户主动选择的路径；避免存储敏感数据明文。大文件：优先流式写入与分块；必要时结合 OPFS 持久缓存。常见问题Q1: 如何保持持久授权？用户选择目录后，可获得持久授权；后续通过 `queryPermission` 检查，无需重复弹窗。Q2: 与 OPFS 的关系？FSA 面向用户可见路径；OPFS 提供站点私有存储。可在导入/导出场景配合使用。参考资料MDN: File System Access APIChromium Docs: File System Access ExplainerWeb 平台权限与用户手势要求---发布信息发布日期: 2025-11-18最后更新: 2025-11-18作者: 前端技术团队状态: 已发布技术验证: 已验证阅读时间: 16分钟版权: CC BY-SA 4.0