webkitdirectory 仅支持单文件夹递归读取(含子目录文件),需配合 directory 和 multiple 属性;返回扁平化 FileList,各 File.webkitRelativePath 保留原始路径,是还原结构唯一依据。

怎么用 webkitdirectory 获取整个文件夹结构
浏览器原生支持文件夹上传,但必须用对属性。关键不是靠 JavaScript 遍历本地磁盘(做不到),而是让 <input type="file"> 主动递归读取选中目录下的所有文件。
正确写法只有这一种组合:<input type="file" webkitdirectory directory multiple>。其中 webkitdirectory 是 Chrome/Edge 的标准属性,directory 是 Firefox 的对应属性,multiple 不是可选——没有它,Firefox 会只返回根目录本身,而不是里面所有文件。
- 选中文件夹后,
e.target.files返回的是扁平化的FileList,每个File对象带webkitRelativePath属性(如"project/docs/spec.pdf") - iOS Safari 和旧版 Android WebView 完全不支持该特性,别浪费时间适配
- 用户若手动勾选了 macOS 的
.DS_Store或__MACOSX文件夹,需在 JS 中过滤:file.webkitRelativePath.startsWith('.') || file.webkitRelativePath.includes('__MACOSX')
分片上传前怎么避免内存爆炸
直接对整个文件夹做 file.arrayBuffer() 或循环调用 FileReader.readAsArrayBuffer() 会瞬间吃光内存,尤其当文件夹含几十个 CAD 图纸时。必须跳过“全量加载”这一步。
真正安全的做法是:对每个 File 单独分片,且分片动作延迟到点击上传按钮之后,而非文件选择后立即执行。
立即学习“前端免费学习笔记(深入)”;
- 分片用
file.slice(start, end),不要传第三个contentType参数——Safari 不认,会静默失败 - 每片大小建议设为
5 * 1024 * 1024(5MB),内网可提到10 * 1024 * 1024;超过 20MB 容易触发 Android WebView 内存警告 - 不要复用同一个
FileReader实例,每次分片读取完立刻设reader = null,否则 GC 不及时,页面卡死
怎么让服务端能按原始路径重建文件夹
服务端合并分片时,如果只收二进制流,就彻底丢失了目录结构。必须把路径信息随每个分片一起发过去。
最简方案是把 file.webkitRelativePath 当作普通字段塞进 FormData:
const formData = new FormData();
formData.append('file', chunk);
formData.append('path', file.webkitRelativePath); // 关键!
formData.append('chunkIndex', index);
formData.append('totalChunks', total);
formData.append('uploadId', fileId);服务端收到后,根据 path 字段逐级创建目录(如 mkdir -p project/docs/),再把分片写入对应位置。注意:路径需做白名单校验,禁用 ../ 等跳转序列,否则有任意文件写入风险。
并发上传时怎么防止请求雪崩
一个 500MB 的文件夹可能含 200 个文件,每个再分 10 片就是 2000 个请求。浏览器同域名并发上限通常只有 6,盲目并发只会拖慢整体速度、触发服务端限流。
必须做两级节流:先控文件粒度,再控分片粒度。
- 文件级并发数建议设为
3~5,即最多同时处理 5 个文件的分片上传 - 每个文件内部的分片上传用串行或最多
2并发,避免单个大文件抢占全部连接 - 用
Promise.allSettled()而非Promise.all()处理一批分片,确保某一片失败不影响其他片继续上传 - 上传队列需持久化到
localStorage或IndexedDB,页面刷新后能恢复 —— 否则用户点个 F5 就得重来
最后提醒一句:文件夹上传 + 分片 + 断点续传,三者叠加后状态管理复杂度是指数级上升的。别省事把所有逻辑堆在单个 upload() 函数里,至少拆出路径解析、分片调度、错误恢复三个独立模块。



















