1. 从“文件选择器”到“文件系统访问器”的跨越如果你做过前端文件上传肯定对input typefile这个元素又爱又恨。爱的是它简单几行代码就能让用户选文件恨的是它简陋你只能拿到一个File对象用户选了什么路径、文件结构什么样你一概不知。用户想保存一个修改后的文件对不起只能让他“另存为”重新选一遍路径。这种体验就像你请朋友来家里做客但只允许他站在门口把东西递给你连客厅长什么样都不能看一眼。File System Access API 的出现就是为了打破这扇“门”。它允许 Web 应用在获得用户明确授权后直接与用户设备上的文件系统进行交互——读取文件内容、写入修改、甚至获取目录结构。这意味着基于 Web 的代码编辑器可以直接打开一个本地文件夹像 VS Code 一样管理项目文件在线图像处理工具可以让你直接编辑并保存回原文件无需下载再上传文档协作应用能实现真正的本地文件自动同步。这个 API 的核心价值在于它将 Web 应用从“沙箱”中适度解放出来赋予了其接近原生桌面应用的文件操作能力同时严格遵循用户许可和隐私安全模型。它不是要取代传统的文件上传而是在需要更深度、更持久文件交互的场景下提供了一个强大的标准化方案。接下来我将带你深入这个 API 的每一个细节从基础使用到高级技巧再到实际开发中那些容易踩的坑。2. 核心概念与权限模型安全第一的交互设计在开始写代码之前必须彻底理解 File System Access API 的权限模型这是它区别于“危险”的本地 API 的关键也是所有设计决策的基石。2.1 “句柄”Handle是唯一的钥匙整个 API 围绕“句柄”这个概念构建。你可以把句柄理解为一个安全、有权限的“引用”或“指针”。用户通过文件选择器选中一个文件或目录后浏览器并不会直接把文件的原始路径或内容给你而是给你一个对应类型的句柄对象。主要有两种句柄FileSystemFileHandle: 代表一个文件。通过它你可以获取文件内容getFile()或创建可写入的流createWritable()。FileSystemDirectoryHandle: 代表一个目录。通过它你可以遍历目录内容、获取子文件/目录的句柄或在其中创建新文件。重要的一点是句柄与权限绑定。你通过一个句柄进行的任何操作都隐含了用户当初授予该句柄的权限。你不能用一个文件的句柄去操作另一个文件也不能凭空猜出一个路径去获取句柄。所有访问都必须始于用户的一次主动交互如点击。2.2 “显式授权”与“静默访问”权限的获取分为两个阶段显式授权通过window.showOpenFilePicker()或window.showDirectoryPicker()调用文件选择器。这是唯一需要用户直接交互点击选择的步骤。在此过程中浏览器会明确告知用户网站正在请求文件/目录访问权限。静默访问一旦用户授予了权限并且你保存了返回的句柄例如存储到IndexedDB中那么在同一源origin下下次页面加载时你就可以直接使用这个保存的句柄来请求权限而无需再次弹出文件选择器。浏览器会基于已保存的句柄进行“静默”的权限验证。这个设计非常巧妙它既保证了初始授权的明确性又避免了用户每次打开应用都要重复选择文件的繁琐实现了体验与安全的平衡。2.3 权限状态的查询与管理你可以通过navigator.permissions.query()API 来查询对某个特定句柄的权限状态。这对于构建友好的 UI 非常有用比如在页面加载时检查是否还有权限从而决定是显示“打开文件”按钮还是“您已授权访问XXX文件”的提示。// 假设我们有一个之前保存的 fileHandle async function checkPermission(fileHandle) { const permissionStatus await navigator.permissions.query({ name: file-system, // 注意这里传递的是句柄本身而不是路径 fileHandle: fileHandle, mode: readwrite // 或 read }); if (permissionStatus.state granted) { console.log(拥有读写权限可以直接操作); return true; } else if (permissionStatus.state prompt) { console.log(需要再次向用户请求权限例如通过 getFile() 触发); return false; } else { // denied console.log(权限被明确拒绝需要用户重新通过选择器授权); return false; } }注意权限是“源origin 句柄”级别的。即使你拥有对/documents/note.txt的读写权限也不代表你能访问/documents/目录下的其他文件更不代表能访问/downloads/目录。权限的粒度非常精细。3. 基础操作实战打开、读取、写入与保存理解了权限模型我们进入实战环节。我们从最常见的场景开始让用户选择一个文件读取内容修改后保存回去。3.1 打开文件并读取内容传统的文件上传只能拿到File对象而这里我们首先获取的是FileSystemFileHandle。// 3.1.1 打开单个文件读取模式 async function openFile() { try { // 显示文件选择器 options 可配置 const [fileHandle] await window.showOpenFilePicker({ types: [{ description: 文本文件, accept: {text/plain: [.txt, .md]}, }], multiple: false, // 是否允许多选 excludeAcceptAllOption: false, // 是否显示“所有文件”选项 }); // 获取文件句柄后可以通过它拿到真正的 File 对象 const file await fileHandle.getFile(); const contents await file.text(); // 或 arrayBuffer(), stream() console.log(文件 ${file.name} 的内容, contents); // 保存句柄以备后用例如存到 IndexedDB saveHandle(fileHandle); return { fileHandle, contents }; } catch (err) { // 用户取消选择会抛出 DOMException name 为 AbortError if (err.name AbortError) { console.log(用户取消了选择); } else { console.error(打开文件失败, err); } } }showOpenFilePicker方法返回一个 Promise解析为一个FileSystemFileHandle对象的数组。即使multiple: false它返回的也是数组因此我们用解构[fileHandle]来获取第一个。getFile()方法每次调用都会返回一个新的File对象它包含了文件的最新内容。这意味着如果在你的应用之外比如用记事本修改了文件再次调用getFile()就能拿到最新的内容。3.2 写入内容并保存到原文件这是体现 API 威力的地方直接写回原文件无需“另存为”对话框。// 3.2.1 写入内容到已打开的文件句柄 async function saveToFile(fileHandle, newContents) { // 首先检查是否仍有写入权限。尝试创建可写流会触发权限请求。 let writable; try { // 创建一个 FileSystemWritableFileStream writable await fileHandle.createWritable(); // 将新内容写入流 await writable.write(newContents); // 关闭流完成写入操作。这一步至关重要 await writable.close(); console.log(内容已成功保存至 ${fileHandle.name}); } catch (err) { console.error(写入文件失败, err); // 可能是权限丢失或磁盘空间不足或文件被其他程序锁定 if (writable) { // 确保在出错时也尝试关闭流避免资源泄漏 await writable.abort(); } throw err; // 将错误向上传递 } } // 3.2.2 组合使用打开、修改、保存 async function editAndSaveFile() { const { fileHandle, contents } await openFile(); if (!fileHandle) return; // 模拟修改内容 const modifiedContents contents.toUpperCase() \n-- 已编辑; // 保存回原文件 await saveToFile(fileHandle, modifiedContents); }关键点解析createWritable(): 这是执行写入的入口。调用此方法时如果权限状态是prompt浏览器会向用户显示权限请求对话框。如果用户拒绝此方法会抛出错误。write(): 方法接受String、BufferSource如ArrayBuffer或Blob作为参数。它执行的是“覆盖写入”即从文件开头开始写。如果你想实现“追加”或“部分修改”需要更精细地操作流的位置seek。close():必须调用。只有调用close()写入操作才会真正提交到磁盘。如果忘记关闭文件可能处于损坏或锁定状态。错误处理写入操作可能因各种原因失败权限、磁盘满、文件被锁。务必用try...catch包裹并在出错时尝试abort()流以进行清理。3.3 “另存为”与新文件创建有时我们不想覆盖原文件或者需要创建一个全新的文件。这时需要使用window.showSaveFilePicker()。// 3.3.1 显示“另存为”对话框并创建新文件 async function saveFileAs(initialContents ) { try { const fileHandle await window.showSaveFilePicker({ suggestedName: 未命名文档.txt, // 建议的文件名 types: [{ description: 文本文件, accept: {text/plain: [.txt, .md]}, }], excludeAcceptAllOption: false, }); // 获取句柄后写入内容 const writable await fileHandle.createWritable(); await writable.write(initialContents); await writable.close(); console.log(文件已另存为${fileHandle.name}); return fileHandle; // 返回新文件的句柄 } catch (err) { if (err.name AbortError) { console.log(用户取消了保存); } else { console.error(另存为失败, err); } } } // 3.3.2 使用示例将当前内容另存为新文件 async function duplicateCurrentDocument(currentContent) { const newFileHandle await saveFileAs(currentContent); if (newFileHandle) { // 现在你可以选择继续编辑新文件或保留原文件句柄 saveHandle(newFileHandle); } }showSaveFilePicker的行为因操作系统和浏览器而异。在某些情况下如果用户选择了一个已存在的文件浏览器可能会提示是否覆盖。这个 API 给了 Web 应用一个标准的“保存”入口点。4. 目录操作进阶遍历、创建与管理项目当你的应用需要管理一组文件如一个项目文件夹时目录句柄就派上用场了。4.1 打开目录并遍历内容// 4.1.1 选择并遍历目录 async function openDirectory() { try { const directoryHandle await window.showDirectoryPicker({ // mode: read 或 readwrite 默认是 read mode: readwrite, // 如果需要创建文件需要读写权限 }); const fileHandles []; const dirHandles []; // 遍历目录条目 (entries) // for await...of 语法用于异步迭代器 for await (const entry of directoryHandle.values()) { if (entry.kind file) { fileHandles.push(entry); console.log([文件] ${entry.name}); } else if (entry.kind directory) { dirHandles.push(entry); console.log([目录] ${entry.name}); } } console.log(共发现 ${fileHandles.length} 个文件 ${dirHandles.length} 个子目录); return { directoryHandle, fileHandles, dirHandles }; } catch (err) { if (err.name AbortError) { console.log(用户取消了目录选择); } else { console.error(打开目录失败, err); } } }directoryHandle.values()返回一个异步迭代器每次迭代得到一个FileSystemFileHandle或FileSystemDirectoryHandle。注意这个遍历是浅层的不会递归进入子目录。4.2 在目录中获取、创建和删除文件目录句柄提供了类似传统文件系统的 API。// 4.2.1 获取目录内的特定文件句柄 async function getFileInDirectory(dirHandle, fileName) { try { // getFileHandle 用于获取文件 const fileHandle await dirHandle.getFileHandle(fileName); return fileHandle; } catch (err) { if (err.name NotFoundError) { console.log(文件 ${fileName} 不存在); return null; } throw err; } } // 4.2.2 在目录中创建新文件 async function createFileInDirectory(dirHandle, fileName, content ) { try { // create: true 表示如果文件不存在则创建 const fileHandle await dirHandle.getFileHandle(fileName, { create: true }); const writable await fileHandle.createWritable(); await writable.write(content); await writable.close(); console.log(文件 ${fileName} 创建成功); return fileHandle; } catch (err) { // 如果文件已存在且未指定 { create: true } 或 create: true 但无写入权限会报错 console.error(创建文件 ${fileName} 失败, err); throw err; } } // 4.2.3 删除目录内的文件 async function removeFileFromDirectory(dirHandle, fileName) { try { await dirHandle.removeEntry(fileName); console.log(文件 ${fileName} 删除成功); } catch (err) { if (err.name NotFoundError) { console.log(要删除的文件 ${fileName} 不存在); } else { console.error(删除文件 ${fileName} 失败, err); throw err; } } } // 4.2.4 创建和删除子目录 async function manageSubdirectory(dirHandle) { // 创建子目录 const subDirHandle await dirHandle.getDirectoryHandle(mySubfolder, { create: true }); console.log(子目录创建/获取成功); // 在子目录中创建一个文件 await createFileInDirectory(subDirHandle, note.txt, 子目录中的内容); // 删除子目录 (需要目录为空否则会抛出 InvalidModificationError) // await dirHandle.removeEntry(mySubfolder, { recursive: true }); // 递归删除 }重要注意事项getFileHandle和getDirectoryHandle的第二个参数{ create: true }是关键。如果不传且目标不存在会抛出NotFoundError。如果传了且目标不存在则会创建它如果目标已存在则直接返回其句柄。removeEntry用于删除文件或空目录。如果要删除非空目录必须传递{ recursive: true }选项否则会失败。所有操作都基于你拥有的目录句柄的权限。你只能操作该目录下的直接子项。4.3 递归遍历与路径解析API 本身不提供直接的“路径”字符串概念也不提供单次递归遍历整个目录树的方法。你需要自己实现递归。// 4.3.1 递归收集目录树下所有文件句柄 async function collectAllFiles(dirHandle, fileList [], relativePath ) { for await (const entry of dirHandle.values()) { const currentPath relativePath ? ${relativePath}/${entry.name} : entry.name; if (entry.kind file) { // 存储文件句柄及其相对路径 fileList.push({ handle: entry, path: currentPath }); } else if (entry.kind directory) { // 递归进入子目录 await collectAllFiles(entry, fileList, currentPath); } } return fileList; } // 使用示例 async function listProjectFiles() { const dirHandle await window.showDirectoryPicker(); const allFiles await collectAllFiles(dirHandle); console.log(项目文件结构); allFiles.forEach(file console.log( ${file.path})); return allFiles; }这个递归函数会深度遍历整个目录树收集所有文件的句柄和相对于根目录的路径。这在构建文件树浏览器或需要批量处理项目文件时非常有用。5. 持久化权限与句柄存储提升用户体验的关键用户不希望每次刷新页面或关闭浏览器后都要重新选择文件。File System Access API 允许你将获得的句柄持久化存储通常使用 IndexedDB以便后续会话中直接使用。5.1 使用 IndexedDB 存储句柄句柄对象本身可以被结构化克隆算法序列化因此可以直接存入 IndexedDB。// 5.1.1 初始化数据库 const DB_NAME FileAccessDB; const DB_VERSION 1; const STORE_NAME fileHandles; function openDatabase() { return new Promise((resolve, reject) { const request indexedDB.open(DB_NAME, DB_VERSION); request.onerror () reject(request.error); request.onsuccess () resolve(request.result); request.onupgradeneeded (event) { const db event.target.result; if (!db.objectStoreNames.contains(STORE_NAME)) { db.createObjectStore(STORE_NAME, { keyPath: id }); } }; }); } // 5.1.2 保存句柄 async function saveFileHandle(id, fileHandle) { const db await openDatabase(); const transaction db.transaction([STORE_NAME], readwrite); const store transaction.objectStore(STORE_NAME); await store.put({ id, handle: fileHandle }); console.log(句柄已保存ID: ${id}); } // 5.1.3 读取句柄 async function loadFileHandle(id) { const db await openDatabase(); const transaction db.transaction([STORE_NAME], readonly); const store transaction.objectStore(STORE_NAME); return new Promise((resolve, reject) { const request store.get(id); request.onsuccess () resolve(request.result ? request.result.handle : null); request.onerror () reject(request.error); }); } // 5.1.4 使用示例保存最近打开的文件 async function openAndRememberFile() { const [fileHandle] await window.showOpenFilePicker(); if (fileHandle) { // 使用文件名或自定义ID作为键 await saveFileHandle(lastEditedFile, fileHandle); return fileHandle; } } // 页面加载时恢复句柄 window.addEventListener(load, async () { const savedHandle await loadFileHandle(lastEditedFile); if (savedHandle) { // 检查权限状态 const permissionStatus await navigator.permissions.query({ name: file-system, fileHandle: savedHandle, mode: readwrite }); if (permissionStatus.state granted) { console.log(检测到已保存的文件句柄且权限仍在。); // 可以直接使用 savedHandle 操作文件无需再次选择 // 例如更新UI显示文件名 document.getElementById(currentFile).textContent 当前文件: ${savedHandle.name}; } else { console.log(权限已丢失需要用户重新授权。); // 清空保存的句柄 await removeFileHandle(lastEditedFile); } } });5.2 权限的持久化与“静默”恢复当你从 IndexedDB 中取出一个句柄并尝试使用它如调用getFile()或createWritable()时浏览器会检查权限。如果权限状态是granted操作会直接成功如果是prompt浏览器会向用户显示一个权限请求对话框通常比文件选择器更简洁如果是denied操作会失败。最佳实践在页面加载时尝试恢复保存的句柄并立即检查权限。根据权限状态更新 UIgranted: 显示文件已打开提供编辑/保存功能。prompt: 可以显示一个按钮点击后触发一个无害操作如getFile()来请求权限。denied: 提示用户需要重新通过文件选择器授权。这种模式使得 Web 应用能提供接近原生应用的“记住打开的文件”体验。6. 高级特性与边界情况处理掌握了基础我们来看看一些更深入的特性和那些容易出问题的地方。6.1 处理大文件与流式操作对于非常大的文件如视频、大型日志一次性读取到内存file.text()或file.arrayBuffer()可能导致标签页崩溃。应该使用流StreamAPI。// 6.1.1 使用流读取大文件 async function readLargeFileStream(fileHandle) { const file await fileHandle.getFile(); const stream file.stream(); // 获取 ReadableStream const reader stream.getReader(); const decoder new TextDecoder(utf-8); let content ; try { while (true) { const { done, value } await reader.read(); if (done) break; // value 是一个 Uint8Array chunk content decoder.decode(value, { stream: true }); // 可以在这里处理每一块数据例如逐行分析或进度更新 console.log(已读取 ${content.length} 字符); } decoder.decode(); // 处理流末尾 console.log(文件读取完成); return content; } finally { reader.releaseLock(); } } // 6.1.2 使用流写入大文件追加或修改部分内容 async function writeToFileStream(fileHandle, newData, position 0) { const writable await fileHandle.createWritable(); // 将写入位置移动到指定字节 await writable.seek(position); // 写入数据 await writable.write(newData); await writable.close(); }seek()方法允许你在文件的特定位置开始写入结合write()可以实现在文件中间插入或替换内容而不是总是覆盖整个文件。6.2 文件与目录的移动与重命名API 目前没有直接的move或rename方法。这些操作需要通过“读取-创建-删除”的组合来实现。// 6.2.1 重命名文件在同一目录内 async function renameFile(fileHandle, newName) { // 获取文件内容 const file await fileHandle.getFile(); const contents await file.arrayBuffer(); // 获取父目录句柄假设我们知道它在同一个目录下操作 // 注意fileHandle 没有直接获取父目录的方法。 // 通常你需要从上级目录句柄开始操作。 // 以下是一个假设我们拥有父目录句柄 parentDirHandle 的场景 // const parentDirHandle ...; // 从上下文获取 // 1. 在父目录用新名字创建新文件 const newFileHandle await parentDirHandle.getFileHandle(newName, { create: true }); const writable await newFileHandle.createWritable(); await writable.write(contents); await writable.close(); // 2. 删除旧文件 await parentDirHandle.removeEntry(fileHandle.name); console.log(文件已从 ${fileHandle.name} 重命名为 ${newName}); return newFileHandle; // 返回新文件的句柄 } // 6.2.2 移动文件到另一个目录 async function moveFile(fileHandle, destDirHandle, newName fileHandle.name) { const file await fileHandle.getFile(); const contents await file.arrayBuffer(); // 在目标目录创建文件 const newFileHandle await destDirHandle.getFileHandle(newName, { create: true }); const writable await newFileHandle.createWritable(); await writable.write(contents); await writable.close(); // 从源目录删除原文件需要源目录句柄 // const srcDirHandle ...; // await srcDirHandle.removeEntry(fileHandle.name); console.log(文件已移动到 ${destDirHandle.name}/${newName}); return newFileHandle; }重要提醒移动和重命名操作不是原子的。如果在“创建新文件”和“删除旧文件”之间发生错误如崩溃可能会导致数据重复或丢失。在生产环境中需要更严谨的错误处理和回滚逻辑或者考虑使用更高级的存储方案如 Origin Private File System。6.3 错误处理与用户取消用户取消操作点击取消或按 ESC会抛出AbortError。这是预期行为不应视为错误。async function robustFileOpen() { try { const [handle] await window.showOpenFilePicker(); // ... 处理文件 } catch (err) { switch (err.name) { case AbortError: // 用户取消安静处理无需提示 break; case SecurityError: console.error(安全错误可能在不安全的上下文中如非 HTTPS调用了 API。); alert(此功能需要在安全连接HTTPS下使用。); break; case NotAllowedError: console.error(权限被拒绝或请求被阻止。); alert(文件访问权限被拒绝。); break; default: console.error(未知错误, err); alert(打开文件时出错${err.message}); } } }其他常见错误包括NotFoundError文件/目录不存在、TypeMismatchError期望文件却得到目录或反之等。为不同的错误类型提供清晰的用户反馈至关重要。7. 实际应用场景与架构思考理解了 API 的细节我们来看看它能用在哪些地方以及在架构上需要注意什么。7.1 典型应用场景Web IDE 或代码编辑器如 VS Code for Web、StackBlitz。可以打开本地项目文件夹实现完整的文件树浏览、编辑、保存。这是最直接的应用。多媒体创作工具在线图片编辑器如 Photopea、音频/视频编辑器。用户可以直接打开本地媒体文件编辑后保存回原路径工作流无缝衔接。文档处理与办公套件在线 Word、Excel 替代品。支持直接打开.docx、.xlsx文件自动保存避免“下载-编辑-上传”的循环。数据导入/导出工具数据分析平台。允许用户直接选择本地 CSV、JSON 大数据文件进行导入处理后的结果也可以直接保存到用户指定的位置。游戏或应用资源管理器基于 Web 的游戏引擎编辑器可以直接管理本地资产文件夹。7.2 兼容性处理与渐进增强File System Access API 的浏览器支持仍在推进中主要在现代 Chrome、Edge 中支持。必须做好兼容性处理。// 7.2.1 特性检测 if (showOpenFilePicker in window showDirectoryPicker in window) { // 支持 File System Access API initAdvancedFileSystem(); } else { // 降级方案使用传统的 input typefile initLegacyFileUpload(); console.warn(当前浏览器不支持 File System Access API已降级使用传统文件上传。); } // 7.2.2 渐进增强的 UI 设计 function renderOpenButton() { const container document.getElementById(file-open-container); if (showOpenFilePicker in window) { // 显示增强的“打开文件/文件夹”按钮 container.innerHTML button onclickopenWithFSA()打开文件增强模式/button button onclickopenDirWithFSA()打开文件夹/button ; } else { // 显示传统的文件上传 input container.innerHTML input typefile idlegacyFileInput /; } }核心思路是优先使用新 API 提供最佳体验同时为不支持的浏览器提供可靠的回退方案通常是传统的input typefile和多文件上传。7.3 安全与隐私考量HTTPS 强制此 API 仅在安全上下文HTTPS 或localhost中可用。用户手势要求showOpenFilePicker、showSaveFilePicker、showDirectoryPicker必须由用户手势如点击触发不能通过setTimeout或Promise间接调用。这是为了防止恶意网站偷偷弹出文件选择器。权限是临时的虽然可以持久化句柄但用户随时可以在浏览器设置中撤销对某个网站的文件访问权限。你的应用必须能优雅地处理权限丢失的情况。无递归删除警告当使用{ recursive: true }删除目录时浏览器不会像操作系统那样弹出确认对话框。这意味着如果你的代码有 bug可能会意外删除大量用户文件。务必在 UI 上提供明确的、二次确认的删除操作。清理存储的句柄如果用户在你的应用中“关闭”了文件最好也从 IndexedDB 中删除对应的句柄除非你明确想提供“最近文件”功能。长期存储未使用的句柄可能会让用户感到困惑。File System Access API 为 Web 应用打开了一扇新的大门让它真正具备了与本地文件系统协作的能力。从简单的文本编辑器到复杂的 IDE其应用场景非常广泛。然而能力越大责任越大开发者必须深刻理解其以用户许可为核心的安全模型并妥善处理兼容性与错误。在实际项目中我建议从“增强型文件保存”这种对用户价值明显、风险可控的功能点开始尝试逐步积累经验再扩展到更复杂的目录管理场景。记住每一次文件访问都必须始于用户的一个明确选择这是构建用户信任的基石。