webkitdirectory仅触发文件夹选择并暴露FileList，不自动上传；需手动遍历files、提取webkitRelativePath，用XMLHttpRequest构造带自定义头的FormData发送请求。
用 webkitdirectory 选文件夹，但别指望它自动发请求
HTML 原生的 <input type="file"> 不会上传任何东西，加了 webkitdirectory 也一样。它只负责让用户选中整个文件夹，并把里面所有文件（含嵌套路径）暴露给 JavaScript。你必须手动遍历 e.target.files，提取每个 file.webkitRelativePath，再逐个或批量构造上传逻辑。
常见错误是以为加了 webkitdirectory 就能像表单 submit 那样直接发出去——不行。浏览器不会替你发起 HTTP 请求，也不会自动带上 Authorization 或自定义头。
-
webkitdirectory是非标准属性，仅 Chrome、Edge、Safari 支持；Firefox 不支持（截至 2026 年仍无计划） - 选中文件夹后，
e.target.files是FileList，不是普通数组，得用Array.from()或循环处理 - 每个
File对象的webkitRelativePath包含完整子路径（如"src/index.js"），这是还原目录结构的关键
用 XMLHttpRequest 发请求并设自定义头，setRequestHeader 必须在 open() 后、send() 前
想传 Authorization、X-Upload-ID 这类头，唯一可靠方式是用 XMLHttpRequest 手动发 POST。注意：不能用 fetch + FormData 并手动设 Content-Type，否则会报 TypeError: Failed to execute 'fetch'。
关键顺序不能错：
立即学习“前端免费学习笔记（深入）”；
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
- 先
xhr.open("POST", url) - 紧接着调用
xhr.setRequestHeader("Authorization", "Bearer ...")等（不能在send()之后） - 再构建
FormData，append文件和元数据 - 最后
xhr.send(formData)—— 此时浏览器会自动设Content-Type: multipart/form-data; boundary=...，但你设的其他头都保留
示例片段：
const xhr = new XMLHttpRequest();
xhr.open("POST", "/api/upload");
xhr.setRequestHeader("Authorization", "Bearer abc123");
xhr.setRequestHeader("X-Folder-Root", "project-v2");
const formData = new FormData();
formData.append("file", file, file.webkitRelativePath); // 第三个参数让后端收到原始路径
formData.append("meta", JSON.stringify({ path: file.webkitRelativePath }));
xhr.send(formData);
上传多个文件时，FormData.append 的 key 名和后端约定要一致
如果你一次上传整个文件夹里的几十个文件，后端通常不希望收一堆同名字段（比如全叫 file）。更合理的做法是：每个文件用唯一 key，或统一用数组形式，但必须和服务端解析逻辑对齐。
- 如果后端用
req.files.file接单个文件，那多次formData.append("file", f)会导致只拿到最后一个 - 改用
formData.append("files", f)，后端需支持接收名为files的多值字段（如 Express 的multer.array("files")） - 若需保留路径信息，建议用
formData.append("file", f, f.webkitRelativePath)，这样后端filename字段就是带路径的字符串，方便还原结构 - 大文件夹上传前，建议前端校验总大小（
Array.from(files).reduce((s, f) => s + f.size, 0)），避免请求发到一半被后端 413 拒绝
路径动态拼接和环境适配，别硬编码 URL
上传接口地址往往要根据用户 ID、租户、分类等动态变化，比如 /api/v1/users/123/uploads 或 /api/v1/tenants/acme/docs。这时候不要写死 URL，而是用模板替换或参数拼接。
- 推荐用
URL构造器或字符串模板：new URL(`/api/v1/uploads`, location.origin).href - 路径参数用
encodeURIComponent处理，避免特殊字符（如空格、中文）导致 400 - 开发/测试/生产环境应从配置读取 base URL，而不是写死
https://localhost:3000或https://api.example.com - 如果后端要求上传路径里带 token 或时间戳，可在 URL 查询参数里加，如
?t=1730742549&token=xyz，比塞进 header 更兼容
真正容易被忽略的是：文件夹上传时，webkitRelativePath 在跨平台（Windows/macOS/Linux）下路径分隔符不统一（\ vs /），后端解析前最好 normalize 一下，前端也可提前替换为 /。
