FileSystemDirectoryHandle.resolve 怎么确认导出目录里的相对路径

在浏览器文件导出功能里，拿到一个文件句柄并不等于已经知道它在用户选定目录中的位置。FileSystemDirectoryHandle.resolve() 解决的是“这个目标句柄是不是当前目录的后代，以及它由哪些名称组成相对路径”这个问题。

官方地址：https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle/resolve

最小结论：调用 await directoryHandle.resolve(targetHandle)，目录内会得到名称数组，目录外得到 null。它不返回操作系统绝对路径，也不是权限检查的替代品。

resolve 返回的不是绝对路径，而是句柄之间的相对关系

方法的输入是另一个 FileSystemHandle，返回值是一个 Promise。目标是当前目录或其子目录中的文件、目录时，结果是从当前目录往下的名称数组；如果目标不在当前目录树内，结果为 null。因此，数组中的每一项都应被当作名称片段，而不是带斜杠的完整路径。

图1：FileSystemDirectoryHandle.resolve 的句柄关系与返回边界。

用数组片段读取文件或子目录的相对位置

下面的辅助函数只负责把句柄关系转换成适合导出清单展示的相对路径。真正写文件时仍然使用句柄 API，不要把拼出的字符串当作本地绝对路径交给服务器或操作系统。

// 把目标句柄转换为相对路径；目录外目标返回 null
async function getRelativeEntryPath(directoryHandle, targetHandle) {
  // resolve 返回名称数组，可能是空数组，也可能是 null
  const parts = await directoryHandle.resolve(targetHandle);

  if (parts === null) {
    // 目标不属于当前目录树，调用方应拒绝加入导出清单
    return null;
  }

  // 只用于展示或清单字段，避免手写绝对文件系统路径
  return parts.join("/");
}

例如目标是当前目录下的 report.csv，结果通常是 ["report.csv"]；目标位于 exports/2026 下时，结果可能是 ["exports", "2026", "report.csv"]。空数组表示目标就是当前目录本身，不能把它误判为失败。

把目录内、目录本身和目录外分成三个分支

导出任务常见的错误是只判断“有没有字符串”。更稳妥的判断顺序是先区分 null，再处理空数组，最后拼接非空片段：

// 生成一个可序列化的导出条目，并保留原始片段
async function buildExportEntry(rootHandle, entryHandle) {
  // 目标不在 rootHandle 下时，不能加入本次导出清单
  const parts = await rootHandle.resolve(entryHandle);
  if (parts === null) {
    return { accepted: false, reason: "目录外句柄" };
  }

  // 空数组代表 rootHandle 自身，使用明确标记避免空字符串歧义
  const relativePath = parts.length === 0 ? "." : parts.join("/");
  return { accepted: true, relativePath, parts };
}

这里保留 parts 很有价值：清单可以用它做层级显示，后续再次取得子句柄时也不必重新解析一个用户可编辑的字符串。若只需要显示路径，才把片段用斜杠连接。

图2：导出任务中用 resolve 判断目录归属的结构说明图。

安全上下文、权限与兼容边界

resolve() 运行在 File System Access API 的句柄模型中，页面通常需要 HTTPS 等安全上下文；它能回答目录关系，却不会替你取得用户授权，也不会突破用户对文件的访问限制。句柄来自不同目录选择器时，即使名称相同，也不应仅靠文件名判断它们属于同一位置。

兼容处理可以把能力检测放在入口处，并在不支持时退回“由用户重新选择目录”或只处理当前已知句柄的方案：

// 在启用相对路径判断前做能力检测，避免直接调用导致入口报错
function canResolveDirectoryHandle() {
  return typeof FileSystemDirectoryHandle !== "undefined" &&
    typeof FileSystemDirectoryHandle.prototype.resolve === "function";
}

还要注意，resolve() 的返回结果不是服务器可直接使用的路径，不能据此推断用户电脑上的真实目录名。文章只讨论句柄之间的相对关系；如果需求是递归读取目录内容，应另行使用目录句柄的迭代能力并做好授权和失败处理。

常见问题

为什么返回 null 而不是抛出异常？

null 表示目标句柄不是当前目录的后代，是正常的关系判断结果；权限、句柄失效等其他问题仍应按具体 API 调用处理。

能不能把返回数组直接当成本地路径？

不能。它只是从父句柄到目标句柄的名称片段，用于界面展示或导出清单更合适，实际文件操作继续使用句柄。

总结

FileSystemDirectoryHandle.resolve() 的核心是“相对关系判断”：数组表示目录内的名称层级，null 表示目录外，空数组表示目录本身。把这三种状态保留下来，再把能力检测、授权和实际读写分开，导出目录的路径判断就不会混入绝对路径假设。