HTML无法直接上传文件夹到分布式文件系统，因浏览器仅提供只读File对象且无真实路径；需JS提取webkitRelativePath保留层级结构，并由后端中转写入。
HTML 本身不能直接上传文件夹到分布式文件系统（如 HDFS、MinIO、Ceph、S3 等）——它只负责触发浏览器端的文件选择和数据读取，后续必须由 JavaScript 组织数据 + 后端服务中转并写入分布式存储。
为什么 webkitdirectory 选中了文件夹却传不上去？
浏览器通过 <input type="file" webkitdirectory directory multiple> 能拿到所有文件的 File 对象，但这些对象只是只读引用，没有真实路径（出于安全限制），且无法直接发给 MinIO/S3 这类服务——它们不接受浏览器直传的原始 File 流，也不认前端构造的“文件夹路径”字符串。
- 常见错误现象：
event.target.files看起来有几十个文件，但发请求时只传了第一个，或后端收到的全是扁平文件名（如report.pdf），丢失了docs/2024/report.pdf这样的层级 - 根本原因：HTML 表单提交或
FormData.append()默认丢弃文件在文件系统中的相对路径，只保留name属性值 - 关键动作：你必须在 JS 中遍历
event.target.files，手动提取每个File.webkitRelativePath（Chrome/Edge 支持），或用递归模拟路径（Firefox 需 fallback）
如何用 JS 提取并保留文件夹结构？
核心是靠 File.webkitRelativePath。这个属性在 Chrome、Edge、新版 Safari 中返回类似 project/src/index.js 的路径字符串；Firefox 不支持，需配合 input 的 directory 属性 + 人工构造逻辑（比如把用户选中的文件夹名作为根前缀）。
- 必须用
for...of或Array.from()遍历event.target.files，不能用forEach（FileList不是 Array） - 示例提取逻辑：
const files = event.target.files; for (let i = 0; i < files.length; i++) { const file = files[i]; const path = file.webkitRelativePath || `fallback-root/${file.name}`; console.log(path, file.size); // → "src/main.py", 1240 } - 注意：如果用户多选多个顶层文件夹（非单文件夹），
webkitRelativePath可能为空，此时需按文件名去重 + 加时间戳防冲突
后端怎么把文件存进 MinIO / S3 / Ceph？
浏览器不能直连分布式存储的写接口（跨域、鉴权、签名等限制），必须走你自己的后端服务做代理。后端接收分片或完整文件 + 路径信息后，调用对应 SDK 写入。
立即学习“前端免费学习笔记（深入）”；
- 关键参数：目标
objectKey必须拼上File.webkitRelativePath，例如bucket-name/user-123/project/src/main.py - 推荐做法：前端上传时，每个文件单独发一个请求（带
path字段），后端用minioClient.putObject()或s3.upload()写入，避免大文件阻塞 - 性能影响：不要一次性读完整个
File再传——用fetch+ReadableStream流式上传，否则 2GB 文件会吃光浏览器内存 - 兼容性坑：IE 完全不支持
webkitdirectory，若需支持，得降级为 ZIP 压缩上传 + 后端解压（用libzip.js或服务端 unzip）
分布式系统里“文件夹”其实是伪概念
MinIO、S3、Ceph 等对象存储没有真正的目录结构，所谓“文件夹”只是 object key 里的 / 分隔符。这意味着：
- 你不需要、也不能在后端“创建文件夹”，只要上传一个 key 为
data/logs/2026-11/error.log的对象，控制台就会显示为data/ → logs/ → 2026-11/的层级 - 删除“空文件夹”无意义——它只是前缀，删光该前缀下所有 object 即可
- 前端展示树形结构，必须自己解析所有 object keys 的前缀，再聚合生成
folders数组，不能依赖存储系统返回“目录列表”
真正容易被忽略的是：路径拼接时没做 URL 编码。比如文件名含空格或中文，encodeURIComponent(path) 必须用在构建 object key 之前，否则上传失败或 key 错乱——这个细节在本地测试常被绕过，一上生产就 400。
