直接通过file协议打开HTML时FileEntry.file()方法报错求助

问题背景 #

实现拖拽上传功能时，通过drop事件的e.dataTransfer.items获取文件/文件夹句柄，调用items[n].webkitGetAsEntry()得到FileEntry对象，再通过FileEntry.file()回调获取文件对象。核心代码如下：

function traverseFileTree(item, path = "") {
  // The item here is the return value of webkitGetAsEntry().
  const isRecursive = document.getElementById("recursiveOption").checked;
  if (item.isFile) {
    item.file(
      (file) => {
        console.log("file", file);
        if (file.name.toLowerCase().endsWith(".md")) {
          file.fullPath = path + file.name;
          files.push(file);
          updateFileList();
        }
      },
      (error) => {
        console.error(error);
        showPopup(`Failed to read file ${item.name}: ${error.message}`);
      }
    );
  } else if (item.isDirectory) {
    if (isRecursive || path === "") {
      let dirReader = item.createReader();
      dirReader.readEntries(
        (entries) => {
          for (let i = 0; i < entries.length; i++) {
            traverseFileTree(entries[i], path + item.name + "/");
          }
        },
        (error) => {
          console.error("Failed to read directory:", error);
          showPopup(`Failed to read directory ${item.name}: ${error.message}`);
        }
      );
    }
  }
}

遇到异常：直接通过file://协议打开HTML文件时，file()方法抛出错误：

EncodingError: A URI supplied to the API was malformed, or the resulting Data URL has exceeded the URL length limitations for Data URLs.

但通过本地HTTP服务器（如Live Server）部署时，file()方法可正常获取文件对象。

1. 问题具体原因 #

• file://协议的安全与实现限制：浏览器对file://协议施加了严格的同源策略和权限控制，FileEntry.file()在该协议下会尝试将文件内容转换为Data URL返回。当文件路径包含非ASCII字符（如中文、空格），或文件体积过大时，会触发编码失败或Data URL长度超限的错误。
• HTTP环境的API逻辑差异：在HTTP服务器环境下，浏览器通过网络请求读取文件，FileEntry.file()的实现逻辑是直接通过文件流获取文件对象，无需转换为Data URL，因此不会触发此类错误。

2. 自主解决方法 #

• 优先使用本地HTTP服务器开发：使用Live Server、http-server等工具启动本地服务，完全规避file://协议的限制，这是最直接有效的解决方案。
• 排查文件路径与名称：测试路径/名称仅含ASCII字符的文件，确认是否是特殊字符编码导致的问题；若确实是特殊字符问题，可在读取前对路径进行编码处理。
• 深挖浏览器报错细节：打开浏览器DevTools的Console面板，查看错误的完整堆栈信息，定位是路径编码错误还是Data URL长度超限；必要时可调试API的调用流程，观察参数变化。
• 查阅官方兼容性文档：参考MDN等官方文档中FileEntry、webkitGetAsEntry()的协议兼容性说明，明确不同环境下的API行为差异。
• 尝试替代API：若必须在file://环境运行，可尝试：
  • 若无需遍历文件夹，直接从e.dataTransfer.files获取文件对象；
  • 使用现代浏览器支持的FileSystemAccess API替代旧的webkit系列API，该API对file://协议的支持更完善，权限控制更清晰。

内容的提问来源于stack exchange，提问作者Thon Hei