HTML文件夹上传有两种主流方案：webkitdirectory属性（兼容Chrome/Edge，保留webkitRelativePath路径）和showDirectoryPicker() API（仅HTTPS下Chrome 86+支持，可递归遍历目录树），需注意兼容性、路径安全校验及跨平台分隔符处理。
HTML 本身不支持直接上传带子目录结构的文件夹，但现代浏览器提供了两个可行路径：用 webkitdirectory 属性（Chrome/Edge）或 showDirectoryPicker() API（Chrome 86+，需 HTTPS）。关键不是“能不能传”，而是“怎么保结构、怎么兼容、怎么避免丢文件”。
用 webkitdirectory 读取带路径的文件列表
这是最轻量、兼容性最好的方案，适用于 Chrome 78+、Edge 79+。它不会真正“选中文件夹”，而是把用户选中的整个目录下所有文件（含子目录）一次性塞进 FileList，每个 File 对象带 webkitRelativePath 字段，保留原始层级。
常见错误现象：
- 只拿到文件名，没拿到路径 → 忘了用
file.webkitRelativePath，误用了file.name - 选了文件夹但
files.length === 0→ 没加multiple属性（某些旧版 Chrome 要求） - macOS 隐藏文件（如
__MACOSX/）被上传 → 没做过滤
实操建议：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
立即学习“前端免费学习笔记（深入）”；
- HTML 中必须写：
<input type="file" webkitdirectory directory multiple>（directory是 Firefox 的 fallback，但实际仅 Firefox 支持，且行为不一致；加了无害） - JS 中遍历前先检查：
if (!file.webkitRelativePath) continue; - 过滤掉隐藏路径：
if (file.webkitRelativePath.includes('__MACOSX') || file.webkitRelativePath.startsWith('.')) - 注意：该方式无法递归判断是否为目录项，
FileList只包含文件，不包含空目录
用 showDirectoryPicker() 真正遍历目录树
这个 API 才是“真正意义上”的文件夹访问——它返回一个 FileSystemDirectoryHandle，能递归遍历子目录、区分文件/目录、读取元数据，甚至未来可写入。但它有硬性限制：必须 HTTPS、必须用户主动触发（不能 onload 自动调）、目前仅 Chrome 86+ 和 Edge 115+ 支持。
常见错误现象：
-
showDirectoryPicker is not defined→ 在非安全上下文（HTTP）或低版本 Chrome 中调用 - Promise 永远 pending 或静默失败 → 没在用户手势（如 click）回调里调用
- 遍历卡死或内存暴涨 → 没做深度限制或没用
for await流式处理
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 触发时机必须是用户点击事件内：
button.addEventListener('click', async () => { const dir = await window.showDirectoryPicker(); ... }) - 递归遍历时加深度保护（比如最大 10 层），避免无限嵌套或符号链接爆炸
- 用
for await (const entry of dir.values())遍历，比dir.keys()+getEntry()更简洁可靠 - 空目录不会产生任何
File，如需保留目录结构，得自己构造占位信息（例如上传前生成 JSON 描述树）
后端如何还原原始目录结构
前端传上来的只是扁平化的 File 列表，每个带 webkitRelativePath（如 src/main.js 或 assets/logo.png）。后端不做解析，就只能全堆在一个目录里，彻底丢失结构。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 前端上传每个文件时，必须把
webkitRelativePath作为额外字段传给后端（比如 formdata.append('path', file.webkitRelativePath)） - 后端接收时，不能只依赖
filename，要严格按传入的path字段拼出完整服务端路径，例如：upload_root + '/' + path - 务必对
path做安全校验：禁止../、空字符、控制字符、绝对路径开头，否则可能写到任意目录（路径遍历漏洞） - Node.js 示例中可用
path.posix.join(uploadDir, safePath)+path.relative()双重校验；PHP 中用basename()提取最后一级再拼接更稳妥
Firefox 和 Safari 怎么办
Firefox 支持 directory 属性但不返回 webkitRelativePath，Safari 目前完全不支持任一原生方案。这意味着纯 HTML 方案在非 Chromium 内核下会退化为“无法选择文件夹”。
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 不要试图 polyfill
webkitdirectory—— 它底层依赖操作系统对话框能力，JS 无法模拟 - 降级方案只有两个实用选项：Zip 打包上传（前端用
JSZip，用户手动压缩）或拖放（drop事件 +item.webkitGetAsEntry()，但仅限 Chromium） - 如果业务强依赖多浏览器文件夹上传，必须接受“Firefox/Safari 用户需 zip 后上传”，并在 UI 明确提示：“推荐使用 Chrome 或 Edge 浏览器以直接选择文件夹”
- 切勿在检测到 Firefox 时悄悄 fallback 到单文件
multiple—— 用户会以为功能坏了
最易被忽略的一点：无论用哪种前端方案，webkitRelativePath 都是浏览器生成的字符串，不是文件系统路径；它的分隔符固定为 /，即使在 Windows 上也是如此。后端拼路径时若盲目用 path.join()（Node.js 默认用 \），可能导致路径错乱。统一用 path.posix.join() 或字符串替换才是稳的。
