“上传文件夹”需依赖 webkitdirectory 属性触发,仅 WebKit/Blink 内核浏览器支持;file.webkitRelativePath 是还原目录结构的唯一可信依据,必须传入 FormData 的 filename 参数;后端须严格校验并安全重建路径,防范路径遍历等风险。

不能直接上传文件夹。HTML 标准 本身不支持文件夹选择,所谓“上传文件夹”实际是浏览器在特定条件下递归读取其内部所有文件,并由前端拼装路径、后端重建结构——这整个流程高度依赖私有属性和主动兼容处理。
webkitdirectory 属性是唯一可行入口
只有 Chrome、Edge、Safari(WebKit/Blink 内核)支持 webkitdirectory,且必须搭配 directory 属性才可能触发文件夹选择对话框:
<input type="file" id="folderInput" webkitdirectory directory multiple>
Firefox 已移除 directory 支持,webkitRelativePath 在其上恒为空字符串;IE/旧版 Edge 完全不识别。这不是可选优化项,而是功能存在的前提。
- 不加
webkitdirectory:浏览器当普通多选文件处理,忽略文件夹 - 只加
directory:现代 Firefox 会静默降级为单文件选择 - 与
multiple混用:部分 Chrome 版本会失效,建议保留但不依赖其行为 - 无法通过 JS 调用
.click()触发:这是安全限制,必须用户真实点击
file.webkitRelativePath 是还原结构的唯一依据
选中文件夹后,e.target.files 返回的是扁平化的 FileList,每个 File 对象的 webkitRelativePath 字段记录了它在原始文件夹中的相对路径(如 "docs/report.pdf" 或 "src/utils/index.js")。这个字段不可伪造、不可写入,是后端重建目录树的唯一可信来源。
- 不要用
file.name拼接:它只是文件名,不含任何层级信息 - 不要尝试读取
file.path:该属性不存在于标准 File API,Node.js 才有 - 上传时需显式传路径:用
formData.append('path', file.webkitRelativePath),不能只传文件 - 空路径(
"")表示根目录下文件,需特殊处理避免写入根路径
FormData 构造必须带 filename 参数
直接 formData.append('files', file) 会导致后端收到的文件名丢失原始路径,变成随机名或 blob。正确做法是把 webkitRelativePath 当作上传时的逻辑文件名传进去:
for (const file of files) {
const path = file.webkitRelativePath || file.name;
formData.append('files', file, path);
}
这样后端接收到的 multipart 请求中,每个 part 的 Content-Disposition 会包含 filename="docs/config.json",而不是 filename="blob"。
- 若
webkitRelativePath为空(如用户手动拖入单个文件),fallback 到file.name - 路径中含非法字符(如
../)需前端清洗,否则可能引发路径遍历漏洞 - 大文件夹(1000+ 文件)别一次性全塞进 FormData:内存暴涨,建议分批上传或流式构造
后端必须按路径创建目录并校验安全性
前端传来的 path 字段不是装饰,是操作指令。后端收到后要:
- 解析
path中的目录层级,逐级mkdir(如 Python 的os.makedirs(os.path.dirname(full_path), exist_ok=True)) - 严格过滤路径:拒绝含
../、/etc/passwd、空字节等的path,防止路径注入 - 限制总路径长度和层级深度(如最多 8 层,总长 ≤ 512 字符)
- 白名单校验文件类型:不能只看前端传的
Content-Type,要读文件头
真正麻烦的从来不是怎么“选中文件夹”,而是如何让一串字符串路径在服务器上安全落地——稍有疏忽,path="../../../.env" 就能覆盖关键配置。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











