JS使用showDirectoryPicker选择文件夹并递归读取内容

作者:微光

时间:2026-11-22

浏览:468

深入讲解如何在JavaScript中使用showDirectoryPicker选择本地文件夹,并结合异步迭代器递归读取目录下的全部文件与子文件夹结构。包含完整代码示例、流式内存优化、异常处理与兼容性降级方案。

文章目录
在现代浏览器中,通过调用 File System Access API 提供的 window.showDirectoryPicker() 方法,可以让用户主动选择本地的一个文件夹,并向前端脚本授予一个代表该目录的根句柄对象(FileSystemDirectoryHandle)。利用该句柄原生支持的异步迭代器(for await...of handle.values()),配合树形深度优先递归函数,开发者能够以非阻塞的方式自上而下逐层扫描所有子文件夹与文件项,并按需提取文件数据或构建包含相对路径的树状目录结构。
JS使用showDirectoryPicker选择文件夹并递归读取内容
图 0:showDirectoryPicker 目录选择与递归读取工作流全景

一、为什么需要 showDirectoryPicker

在过去,前端如果想要读取用户的本地文件夹,主要依赖 <input type="file" webkitdirectory> 标签。尽管这一传统方式在跨浏览器兼容性上表现良好,但在处理复杂业务场景时存在明显痛点:

  • 全量加载导致内存剧烈膨胀:webkitdirectory 在用户选定目录的瞬间,会一口气在内存中构建包含目录中全部文件的 FileList。当文件夹内存在成千上万个文件时(例如含有 node_modules 的工程项目),主线程会产生严重卡顿,甚至导致标签页崩溃。
  • 缺乏句柄持久性与只读限制:传统文件选择框返回的仅仅是一次性文件快照,无法保存当前目录的系统句柄;一旦用户刷新页面,之前的目录授权便全部失效,更无法对选定目录进行就地读写与内容变更。

window.showDirectoryPicker() 彻底解决了这一问题。它返回的是一个细粒度的、按需加载的目录指针对象(Handle)。在这个对象上,文件内容和子目录的元数据并不会在初始时刻被全量装载进内存,而是当你的代码逐层迭代或主动请求某个文件时,系统才进行即时解析。

二、前置条件与基础调用规范

在正式调用 showDirectoryPicker 之前,必须满足现代浏览器对该 API 的两项硬性安全要求:

  1. 安全上下文(Secure Context):代码必须在安全环境下执行,即部署在 https:// 协议的网站上,或者在本地调试环境 http://localhost、http://127.0.0.1 中运行。在不安全的普通 HTTP 域名下调用该方法会直接抛出未定义异常。
  2. 瞬时用户手势触发(User Activation):为了防止恶意脚本在未经许可的情况下随意刺探用户的文件系统,showDirectoryPicker 只能直接绑定在诸如按钮 click 或触摸等真实手势事件的处理函数中。如果在脚本初始化时自动调用,浏览器将直接抛出 SecurityError。
JS使用showDirectoryPicker选择文件夹并递归读取内容
图 1:showDirectoryPicker 执行生命周期与操作步骤

下面是一个安全调用 showDirectoryPicker 并捕获用户交互异常的基础示例:

/**
 * 触发系统文件夹选择框
 * @returns {Promise<FileSystemDirectoryHandle|null>} 返回根目录句柄,若用户取消则返回 null
 */
async function selectDirectory() {
  try {
    const dirHandle = await window.showDirectoryPicker({
      mode: 'read', // 可选 'read' (只读) 或 'readwrite' (读写)
      startIn: 'documents' // 建议的初始选择路径:'desktop' | 'documents' | 'downloads'
    });
    console.log(`成功获取文件夹句柄: ${dirHandle.name}`, dirHandle);
    return dirHandle;
  } catch (err) {
    // 用户在弹出的系统选择框中点击了“取消”按钮
    if (err.name === 'AbortError') {
      console.warn('用户主动取消了文件夹选择。');
      return null;
    }
    // 其他安全或环境异常
    console.error('选择文件夹失败:', err);
    throw err;
  }
}
注意:当用户点击原生文件选择框右下角的“取消”时,Promise 并不会默默 resolve 一个空值,而是会 reject 一个名称为 AbortError 的 DOMException。因此在实际工程中,必须显式对 err.name === 'AbortError' 进行捕获,避免控制台抛出未处理的 Promise rejection。

三、句柄对象模型与异步迭代机制

掌握目录遍历的核心,在于理解 File System Access API 所定义的两类核心句柄对象以及它们继承的基类 FileSystemHandle:

  • FileSystemHandle:顶层抽象接口,提供公共属性 name(文件或文件夹的名称)和 kind(标识类型,值为 'file' 或 'directory')。
  • FileSystemDirectoryHandle:目录句柄,代表一个文件夹。它最关键的方法是异步迭代器 .values(),该方法按需逐个产生当前目录下的直接子节点句柄。
  • FileSystemFileHandle:文件句柄,代表具体的单项文件。它提供 .getFile() 异步方法,用于将句柄转为标准的只读 File 对象。
JS使用showDirectoryPicker选择文件夹并递归读取内容
图 2:File System Access API 句柄对象模型与数据流向

当获取到 FileSystemDirectoryHandle 时,可以使用现代 JavaScript 提供的 for await...of 语法对其 values() 进行非阻塞消费。在每次迭代循环中,产出的 entry 可能是一个新的 FileSystemDirectoryHandle,也可能是一个 FileSystemFileHandle,我们可以通过检查 entry.kind 决定下一步的分发逻辑。

四、核心实现:递归遍历目录树

在实际业务中,我们通常需要获取整个目录结构的完整树形表达,包括每个节点的相对路径、文件体积以及深层子目录。下面是基于深度优先搜索(DFS)的完整递归遍历函数实现:

JS使用showDirectoryPicker选择文件夹并递归读取内容
图 3:递归遍历目录树逻辑分支与状态转移
/**
 * 递归读取目录内容并构建结构树
 * @param {FileSystemDirectoryHandle} dirHandle 目录句柄
 * @param {string} currentPath 累积的相对路径
 * @param {object} options 配置选项(如排除目录、最大深度等)
 * @returns {Promise<Array<object>>} 当前层级包含的文件与子目录集合
 */
async function readDirectoryRecursive(dirHandle, currentPath = '', options = {}) {
  const {
    maxDepth = 30, // 避免过深或软链接循环
    ignoreDirs = ['.git', 'node_modules', '.vscode', 'dist'], // 忽略的目录
    currentDepth = 0
  } = options;

  if (currentDepth > maxDepth) {
    console.warn(`达到最大递归深度限制 [${maxDepth}],停止下探: ${currentPath}`);
    return [];
  }

  const entries = [];

  // 使用异步迭代器依次产出子项目
  for await (const entry of dirHandle.values()) {
    // 构造当前项的相对路径
    const nodeRelativePath = currentPath ? `${currentPath}/${entry.name}` : entry.name;

    if (entry.kind === 'file') {
      // 处理文件项:获取底层 File 实例以读取基本属性
      const file = await entry.getFile();
      entries.push({
        kind: 'file',
        name: entry.name,
        path: nodeRelativePath,
        size: file.size,
        type: file.type || 'application/octet-stream',
        lastModified: file.lastModified,
        handle: entry // 保留句柄供后续需要时按需读取具体内容
      });
    } else if (entry.kind === 'directory') {
      // 检查是否在过滤目录列表中
      if (ignoreDirs.includes(entry.name)) {
        continue;
      }

      // 处理目录项:进入下一层递归调用
      const children = await readDirectoryRecursive(entry, nodeRelativePath, {
        ...options,
        currentDepth: currentDepth + 1
      });

      entries.push({
        kind: 'directory',
        name: entry.name,
        path: nodeRelativePath,
        children: children,
        handle: entry
      });
    }
  }

  return entries;
}

在上述代码中,有几个关键设计细节需要关注:

  1. 路径拼接机制:通过参数 currentPath 记录从根目录开始的相对层级,这样在最终产出的叶子节点中,每个文件对象都会附带如 src/components/Header.vue 这样易于检索的规范相对路径。
  2. 目录过滤策略:对于前端工程项目,node_modules 或 .git 目录动辄包含数万个小文件。如果不进行判断而盲目深度遍历,不仅会消耗大量的网络与系统资源,还会大幅延长递归时间。
  3. 保留原始句柄而非内容:在扫描树结构时,只提取了 file.size 与 file.lastModified 等元数据,并将 entry 句柄附着在节点属性中,没有在遍历时一次性调用 await file.text()。这使得内存开销控制在毫秒级数量级,极具扩展性。

五、按需读取文件内容与流式处理

当整棵目录树被扫描并展示在前端界面的文件树组件中后,用户往往只会点击查看或编辑其中的特定文件。此时,便可以取出先前保存在节点中的 handle,按需读取其内容:

/**
 * 读取文本文件内容(适合代码、Markdown、JSON 等中小文本)
 * @param {FileSystemFileHandle} fileHandle 目标文件句柄
 * @returns {Promise<string>} 文件文本字符串
 */
async function readTextContent(fileHandle) {
  const file = await fileHandle.getFile();
  return await file.text();
}

/**
 * 流式读取大文件(适合大型二进制文件、音视频等,防止爆内存)
 * @param {FileSystemFileHandle} fileHandle 目标文件句柄
 * @param {function} onChunkReceived 数据块回调函数
 */
async function readStreamContent(fileHandle, onChunkReceived) {
  const file = await fileHandle.getFile();
  const reader = file.stream().getReader();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    // value 是 Uint8Array 类型的二进制数据块
    onChunkReceived(value);
  }
}

六、方案对比与工程兼容性降级

在实际生产部署中,我们必须清醒地认识到 showDirectoryPicker 的平台兼容边界。截至目前,该 API 主要在 Chromium 内核系列浏览器(如 Chrome、Edge、Opera、Brave 86+)中得到全面原生支持,而在 Firefox 和 Safari 中由于安全考量仍未开启或仅处于实验阶段。

JS使用showDirectoryPicker选择文件夹并递归读取内容
图 4:两种文件夹读取方案特性对比与工程降级决策

为了保障系统的健壮性,推荐在业务代码中采用特性检测 + 动态降级的防御性编程模式:

/**
 * 跨浏览器文件夹选择统一适配器
 * 支持 Chromium 原生 API,同时优雅降级兼容 Safari / Firefox
 */
async function pickDirectoryAdaptive() {
  // 1. 特性检测:优先使用现代 showDirectoryPicker
  if ('showDirectoryPicker' in window && window.isSecureContext) {
    try {
      const rootHandle = await window.showDirectoryPicker();
      return await readDirectoryRecursive(rootHandle);
    } catch (err) {
      if (err.name === 'AbortError') return null;
      throw err;
    }
  }

  // 2. 降级方案:动态构建 input[webkitdirectory]
  console.info('当前运行环境不支持 showDirectoryPicker,自动降级为传统文件选择模式。');
  return new Promise((resolve) => {
    const input = document.createElement('input');
    input.type = 'file';
    input.webkitdirectory = true;
    input.style.display = 'none';

    input.addEventListener('change', () => {
      const files = Array.from(input.files || []);
      // 将扁平 FileList 按 webkitRelativePath 映射为树状或列表结构
      const result = files.map(file => ({
        kind: 'file',
        name: file.name,
        path: file.webkitRelativePath,
        size: file.size,
        type: file.type,
        lastModified: file.lastModified,
        rawFile: file
      }));
      document.body.removeChild(input);
      resolve(result);
    });

    input.addEventListener('cancel', () => {
      document.body.removeChild(input);
      resolve(null);
    });

    document.body.appendChild(input);
    input.click();
  });
}

七、总结

window.showDirectoryPicker 标志着 Web 应用从传统的“被动文件接收者”向“具备本地文件系统操作能力的富客户端”的质的飞跃。在实践落地时,牢记以下三项关键原则:

  • 权限与交互绑定:必须由用户手势同步拉起,在 HTTPS 环境下运行,并妥善包裹 AbortError 异常捕获;
  • 按需迭代,句柄先行:借助 dirHandle.values() 异步迭代器递归遍历构建骨架,只在真正需要时再调用 getFile() 解析数据;
  • 兼顾多端,做好降级:以特性检测为守门哨,在不支持的浏览器环境下平滑回退到 <input webkitdirectory>,兼顾前沿体验与基础可用性。

实用工具推荐

电子包浆

绿化、压缩、噪点和虚拟水印,自由调节做旧程度。

使用 ›
图片压缩

选择画质和输出格式,预览压缩前后的大小。

使用 ›
相关文章