如何在 Web 应用中安全访问并操作本地文件系统

现代 web 应用（如 vscode.dev）可通过 file system access api 直接读写用户本地文件与目录，无需 后端 代理或 `` 上传，但需 https 环境、用户显式授权及 浏览器 支持。

Web 应用传统上无法直接访问本地文件系统——这是浏览器沙箱安全模型的核心原则。然而，随着 File System Access API 的成熟（Chrome 86+、Edge 91+、Firefox 125+ 支持），前端 now 可以在用户明确授权的前提下，以安全、可控的方式操作本地文件和目录，真正实现“类桌面应用”的体验。

✅ 核心能力概览

• 单文件读写：通过 showOpenFilePicker() 获取 FileSystemFileHandle，再调用 getFile() 读取内容，或 createWritable() 写入新数据；
• 目录遍历与管理：使用 showDirectoryPicker() 获得 FileSystemDirectoryHandle，可递归遍历子项、创建 / 重命名 / 删除文件或子目录；
• 持久化权限：调用 requestPermission({mode: ‘readwrite’}) 并启用 persisted 属性后，可在后续会话中复用句柄（需用户确认）。

? 基础示例：打开并修改一个文本文件

// 1. 请求打开单个文件（支持多选）async function openAndEditFile() {   try {     const [fileHandle] = await window.showOpenFilePicker({types: [{         description: 'Text files',         accept: { 'text/plain': ['.txt', '.md'] }       }]     });      // 2. 读取当前内容     const file = await fileHandle.getFile();     const content = await file.text();     console.log('Current content:', content);      // 3. 写入新内容（覆盖）const writable = await fileHandle.createWritable();     await writable.write('Hello from the web!nUpdated at' + new Date().toISOString());     await writable.close();      alert('File updated successfully!');   } catch (err) {console.error('Operation failed:', err.name, err.message);   } }

? 进阶示例：访问整个目录并重命名文件

async function manageDirectory() {   try {     const dirHandle = await window.showDirectoryPicker();      // 列出所有文件（不包含子目录）for await (const entry of dirHandle.values()) {if (entry.kind === 'file') {console.log('Found file:', entry.name);          // 示例：将 .txt 文件重命名为 .bak（需先复制再删除）if (entry.name.endsWith('.txt')) {const newHandle = await dirHandle.getDirectoryHandle(             entry.name.replace(/.txt$/, '.bak'),             {create: true}           );           // ⚠️ 注意：API 不直接支持 rename；需 copy + delete           await entry.copyTo(dirHandle, entry.name.replace(/.txt$/, '.bak'));           await entry.remove();}       }     }   } catch (err) {if (err.name === 'NotAllowedError') {alert('User denied access — please try again and grant permission.');     } else {console.error(err);     }   } }

⚠️ 关键注意事项

• 必须部署在 HTTPS 或 localhost：生产环境需有效 SSL 证书；开发时 http://localhost 可用，但 http://127.0.0.1 或自定义 host 需额外配置。
• 用户主动触发：所有 show*Picker() 调用必须由用户手势（如点击按钮）发起，不可在页面加载时自动执行。
• 无静默权限：每次访问新路径均需用户确认；requestPermission() 仅对已打开的句柄生效，且不能绕过 UI 提示。
• 浏览器兼容性有限：目前仅 Chromium 系内核浏览器（Chrome/Edge）完全支持；Firefox 逐步实现中（v125+ 支持核心 API）；Safari 尚未支持。务必使用 if (‘showOpenFilePicker’ in window) 特性检测。
• 安全边界清晰：句柄仅指向用户主动选择的文件 / 目录，无法越权访问其他路径（如 /etc/passwd 或父目录 ../）。

✅ 最佳实践建议

• 始终提供降级方案（如 + 下载 Blob）以兼容不支持该 API 的环境；
• 使用 navigator.permissions.query({name: ‘access-file-system’}) 检查权限状态并友好提示；
• 对敏感操作（如删除、重命名）增加二次确认弹窗；
• 在 beforeunload 中保存句柄至 IndexedDB（配合 persisted 权限），提升用户体验连贯性。

File System Access API 并非替代后端文件服务，而是为离线优先、本地优先的 Web 应用（如代码编辑器、笔记 工具 、音视频处理应用）提供了关键能力。合理运用它，能让 Web 应用真正跨越“浏览器”与“ 操作系统”的边界，走向更强大的原生体验。