webkitRelativePath是还原文件夹层级的唯一可靠依据，仅在使用webkitdirectory/directory属性选择文件夹时有效；Safari不支持该API，需降级方案；后端须校验并标准化rel_path防止路径遍历。
HTML 上传文件夹时，层级结构不是自动保留的，必须依赖 file.webkitRelativePath 解析，且仅在用户通过原生 <input type="file" webkitdirectory directory multiple> 选择文件夹时才有效。
为什么 webkitRelativePath 是唯一可靠依据
浏览器不会把“文件夹”作为一个实体上传，而是把其中所有文件扁平化为 FileList。唯一能还原路径的信息，就是每个 File 对象自带的 webkitRelativePath（Chrome/Edge）或 relativePath（Firefox 117+）。这个字段值形如 "models/gear/assembly.step"，是相对于用户所选根文件夹的路径。
常见错误现象：
- 直接用
file.name拼接 —— 所有文件名都变成平级，丢失子目录 - 忽略空字符串或根层文件 ——
file.webkitRelativePath对根目录下文件可能为空，需 fallback 到file.name - 没过滤 macOS 隐藏文件 ——
__MACOSX/或.DS_Store会污染路径树
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 对每个
file，先取file.webkitRelativePath || file.name - 用
split('/')切分后，逐段构建嵌套对象或路径前缀 - 遇到
pathSegments.some(seg => seg.startsWith('.'))就跳过该文件
webkitdirectory 和 directory 属性的兼容性现实
这两个属性不是“可选增强”，而是功能开关：没有它们，webkitRelativePath 一定为空。但它们的浏览器支持非常有限：
-
webkitdirectory：Chrome、Edge、Opera 支持；Firefox 忽略（但新版支持directory） -
directory：Firefox ≥117 原生支持；旧版 Firefox 完全不支持文件夹选择 - Safari：至今（2026）仍不支持任何文件夹选择 API，无法获取层级
这意味着：如果你的用户包含 Safari 用户（尤其 macOS/iOS 端），必须提供降级方案，比如提示“请使用 Chrome 或 Edge 浏览器上传文件夹”，或改用 ZIP 手动打包 + 后端解压（此时路径由 ZIP 内部结构决定）。
后端如何利用前端传来的路径信息
前端不能也不该拼接完整服务端路径。正确做法是：每个文件上传请求中，额外带一个字段，例如 rel_path，值为 file.webkitRelativePath 的原始字符串。
后端收到后，要做三件事：
- 校验路径合法性：禁止
../、空段、控制字符等（防路径遍历） - 标准化分隔符：统一转为
/，避免 Windows 的\混入 - 组合存储路径：如
uploads/<user_id>/<rel_path></rel_path></user_id>，而非硬编码到固定目录
示例（Node.js Express）：
const path = require('path');
const safeRelPath = rel_path.replace(/\.\.\//g, '').replace(/[^a-zA-Z0-9._/-]/g, '');
const fullPath = path.join('uploads', userId, safeRelPath);
注意：path.join() 在处理含 .. 的字符串时有风险，务必先清洗。
大文件夹上传时路径解析的性能陷阱
当用户一次选中含 1000+ 文件的文件夹时，循环解析每个 webkitRelativePath 并构建树状结构，容易阻塞主线程，导致 UI 卡死。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 避免递归生成 DOM 树（如实时渲染整个文件夹结构），只提取关键路径用于上传逻辑
- 用
for循环代替Array.map()+reduce()，减少中间对象创建 - 对超大列表（>500 个文件），考虑用
requestIdleCallback分片处理
最易被忽略的一点：路径解析本身不耗资源，但后续的分片上传调度、MD5 计算、进度状态维护，会因路径结构复杂而放大并发压力——别只盯着“怎么读路径”，要同步设计好上传队列与路径前缀分组策略。
