能保留文件夹原始路径:关键用 file.webkitRelativePath 获取相对路径(如"project/src/index.js"),Chrome/Edge/Firefox及Safari 16.4+支持;为空时降级为file.name并告警;后端须据此重建目录结构,避免平铺存储。

直接用 <input type="file" webkitdirectory directory multiple> 能选中整个文件夹,但默认行为只是把所有文件平铺上传,不带目录结构、不校验、不控制并发、大体积下极易失败——这不是“能用”,而是“埋雷”。
怎么保留文件夹原始路径?关键看 webkitRelativePath
浏览器选中文件夹后,每个 File 对象自带 webkitRelativePath 属性,它返回的是从根文件夹开始的完整相对路径(如 "project/src/index.js")。这个字段是跨浏览器兼容的关键:
- Chrome/Edge 完全支持,值为字符串
- Firefox 也支持
webkitRelativePath(尽管名字带 webkit,实际已成事实标准) - Safari 16.4+ 开始支持,旧版 Safari 会返回空字符串,需降级为平铺处理
- 不要依赖
file.path或file.fullPath,它们在现代浏览器中已被禁用或不可靠
实操建议:遍历 e.target.files 时优先取 file.webkitRelativePath;为空则 fallback 到 file.name,并加 warning 日志提醒用户 Safari 版本过低。
大文件夹上传失败?核心卡点在并发和内存
一个含 500 个文件、总大小 2GB 的文件夹,如果一次性全塞进 FormData 并发上传,大概率触发以下问题:
立即学习“前端免费学习笔记(深入)”;
- 浏览器内存暴涨(尤其 Chrome,单次
slice()大文件会复制 ArrayBuffer) - HTTP 请求队列阻塞,部分请求超时被浏览器静默丢弃
- 服务端收到不完整分片,合并失败
正确做法是分层控制:
- 前端先按文件粒度排队,而非全部加载进内存
- 限制并发数(
MAX_CONCURRENT = 3是安全起点) - 对单个 >10MB 的文件再做分片(用
file.slice(start, end)),小文件直接整传 - 用
AbortController管理每个请求,便于取消和重试
别省略 Content-Type: multipart/form-data 的 boundary 自动设置——手动拼接极易出错,坚持用原生 FormData.append()。
后端怎么接才不丢结构、不崩?
前端传来的每个文件都带 webkitRelativePath,后端必须利用它重建目录。常见错误是只存 name,结果所有文件挤在根目录下。
- Spring Boot 接收时,用
@RequestParam MultipartFile[] files拿到数组,再从 request header 或额外参数里提取对应路径(推荐把路径作为独立字段随每个分片发送) - Node.js(Express + Multer)需配合
multer.fields()或自定义 storage,用file.originalname不可靠,应读取自定义字段如relativePath - 合并前务必校验:同一文件夹下不能有同名文件夹与文件冲突(如
"log"和"log.txt") - 写磁盘前检查目标路径是否存在,mkdirp 类逻辑必须原子化,避免竞态创建失败
最易被忽略的一点:webkitRelativePath 中的路径分隔符是 /,Windows 用户选的文件夹路径本身用 ,但浏览器已统一转义——后端千万别再做一次 replace(/\/g, '/'),否则可能把 "a/c" 错转成 "a/b/c"(实际应保持原样)。



















