HTML5文件夹上传需前端用webkitdirectory属性获取带webkitRelativePath的文件列表,通过FormData附路径元数据发送;后端解析路径重建目录结构、安全清洗并存入数据库,配合并发控制与进度反馈。

HTML 本身不能上传文件夹,也不能直接更新数据库;必须靠 JavaScript 拦截文件列表 + 后端接口接收并写库,前端只负责组织数据、发请求。
为什么 webkitdirectory 是关键起点
浏览器原生支持文件夹选择,只靠一个属性:input 标签加 webkitdirectory(Chrome/Edge/Safari 支持,Firefox 用 directory,但实际行为一致)。它不是“上传”,只是让 event.target.files 返回带完整路径的 File 对象列表,其中每个 file.webkitRelativePath 就是原始目录结构,比如 "project/src/index.js"。
常见错误现象:
- 忘记加 multiple 属性 → 只能选中文件夹根目录下的文件,不递归
- 用 input.value 读路径 → 始终为空,必须用 e.target.files
- 在 IE 或旧版 Firefox 直接使用 → 报错或静默失败,需先检测支持性
实操建议:
- 检测是否可用:const supportsFolder = 'webkitdirectory' in document.createElement('input');
- 若不支持,降级提示用户“请手动压缩后上传”或启用 ZIP 解析逻辑(需额外 JS 库)
- 不要依赖 file.path(非标准),只信 file.webkitRelativePath 或 file.name
怎么把文件夹结构塞进 FormData 并带上元数据
后端需要知道每个文件属于哪个子路径,否则无法重建目录。不能只传 file 本体,必须显式附带路径信息。
Drizzle ORM 是一个轻量级的 TypeScript ORM,提供类型安全的 SQL 模式声明、关系型和类 SQL 查询构建器,以及自动生成迁移。其压缩后仅 7.4kb,且无依赖项,支持 PostgreSQL、MySQL 和 SQLite,包括 Neon、Turso 和 Cloudflare D1 等无服务器数据库。
常见错误现象:
- 直接 formData.append('file', file) 循环 → 所有文件都丢进同一个字段,后端收不到路径
- 用 file.name 当路径 → 多个同名文件(如不同子目录下的 readme.md)会冲突
实操建议:
- 每个文件单独 append,路径作为额外字段:formData.append('files', file); formData.append('paths', file.webkitRelativePath);
- 或打包成 JSON 字符串传一个字段:formData.append('payload', JSON.stringify({path: file.webkitRelativePath, size: file.size, type: file.type}));
- 如果文件超 10MB,必须分片;此时 webkitRelativePath 要随每一片带上,否则后端拼不回原文件
后端怎么同步写数据库(以 Node.js + Express 为例)
前端传来的只是扁平文件流 + 路径字符串,数据库不会自动“理解”目录结构。你得自己解析路径、生成唯一标识、建父子关系或存全路径字段。
立即学习“前端免费学习笔记(深入)”;
常见错误现象:
- 把 webkitRelativePath 当本地磁盘路径直接 fs.writeFile → 路径注入风险(如 ../../../etc/passwd)
- 数据库只存文件名,不存路径 → 列表页展示时所有文件挤在根目录下
- 没做事务或幂等处理 → 网络重试导致同一文件插入多条记录
实操建议:
- 路径清洗:const safePath = path.posix.normalize(relativePath).replace(/^(\.\.\/)+/, '');
- 数据库字段至少含:file_id(UUID)、original_path(如 "docs/report.pdf")、stored_name(服务端生成的唯一名)、parent_id(可选,用于树形查询)
- 插入前查 WHERE original_path = ? AND upload_session_id = ? 防重
- 大文件上传完成后再批量 INSERT,别每片都写一次库
进度与状态怎么反馈给用户(尤其多文件场景)
单个文件有 xhr.upload.onprogress,但整个文件夹是多个并发请求。用户需要知道“共 127 个文件,已上传 43 个,当前文件:src/utils/date.js(87%)”,而不是笼统的“上传中”。
容易被忽略的点:
- 没做并发控制 → 同时开 100 个 fetch 请求,触发浏览器连接数限制或后端限流
- 进度计算用 loaded / total 单文件比例,却显示在总进度条上 → 总进度跳变剧烈、不可读
- 上传失败后没保留已成功文件的状态,重试时重复上传已成功项
实操建议:
- 用 Promise.allSettled 控制并发(例如每次最多 5 个)
- 总进度 = (已完成文件数 × 平均大小 + 当前文件已传字节数) / 总大小,需提前遍历 files 算出总和
- 每个文件上传后,把结果(id、path、status)存进前端 Map,失败时可点击重试单个


















