必须同时声明 webkitdirectory 和 directory 属性才能触发文件夹选择,且需在 HTML 中静态书写;浏览器仅扁平列出文件并提供 webkitRelativePath 字符串,前端须将其作为独立字段传给后端以重建目录结构。

webkitdirectory 属性必须显式声明才能触发文件夹选择
浏览器不会自动把 当作文件夹上传控件,哪怕加了 multiple 也不行。必须同时写上 webkitdirectory 和 directory 两个属性,否则 Chrome/Edge 会忽略文件夹选项,Firefox 则直接禁用该功能(它已移除 directory 支持)。
常见错误是只写一个属性,或试图用 JS 动态设置:input.setAttribute('webkitdirectory', '') —— 这无效。属性必须在 HTML 中静态存在,且用户需主动点击弹出原生选择框,JS 无法触发。
-
是最低可用写法 - 不要混用
accept属性(某些浏览器会因此禁用文件夹模式) - macOS 用户可能遇到
__MACOSX隐藏目录,需在 JS 中过滤掉
file.webkitRelativePath 是还原目录结构的唯一依据
浏览器根本不“上传文件夹”,它只是递归列出所有文件,并给每个 File 对象挂一个 webkitRelativePath 字符串(如 "docs/spec.pdf" 或 "src/components/Button.js")。后端靠这个字段重建路径,前端若丢弃它,目录结构就彻底丢失。
注意:这个属性只在 webkitdirectory 模式下存在,普通多选文件时为 "";且 Safari 16.4+ 才稳定支持,旧版 Safari 可能返回空字符串。
- 务必在
change事件中遍历e.target.files,逐个读取file.webkitRelativePath - 用
split('/')解析路径层级,避免直接拼接造成路径注入(如"../../etc/passwd") - 对空路径或根目录文件(
file.webkitRelativePath === ""),统一视为顶层文件处理
递归上传逻辑不能靠 File API 自动遍历
HTML5 的 FileList 是扁平结构,没有父子关系或 isDirectory 方法。所谓“递归”,其实是浏览器在选中文件夹时已一次性展开全部子文件并塞进 files,前端无需、也无法用 JS 再去调用 entries() 或 showDirectoryPicker()(后者是独立 API,不兼容当前上传流程)。
真正要“递归”的地方在后端:你得按 webkitRelativePath 中的斜杠层级,在服务器上 mkdir 并写入对应路径。前端只需确保每个文件都带上这个路径字段即可。
- 别写类似
for (const entry of folder.entries())的代码——FileList没有entries()方法 - 不要尝试用
URL.createObjectURL(file)后再 fetch 路径——这只会拿到 blob URL,不带相对路径信息 - 大文件(>100MB)建议分片,但分片逻辑与目录结构无关,仍基于单个
File对象切块
FormData 上传时路径信息必须作为额外字段传给后端
FormData.append('file', file) 只传二进制内容,webkitRelativePath 不会自动附带。如果后端只收文件流,没收到路径,就只能全扔进一个文件夹里,目录结构归零。
标准做法是每个文件单独构造一个 FormData 实例,或在一个实例里 append 两份数据:文件本体 + 路径字符串。后端据此创建子目录。
- 推荐方式:
formData.append('file', file); formData.append('path', file.webkitRelativePath); - 避免用
append('files[]', file)批量提交——后端难对齐路径和文件顺序 - 若用 fetch,记得删掉
Content-Type头(浏览器会自动设为multipart/form-data; boundary=...),手动设会导致 400
实际最易被忽略的点:**webkitRelativePath 在 Windows 系统下可能含反斜杠 ,但现代 Chrome 已统一转为正斜杠 /;不过仍建议后端做一次 .replace(/\/g, '/') 归一化,否则 "ac.txt" 会被误判为非法路径。**
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南











