基于WebUploader的跨平台目录上传方案：大文件分片与目录重建实战

做过多终端大文件上传需求的朋友应该都有体会同一套业务用户在 Windows 的 Chrome 里拖一个 10GB 的视频和他在 macOS 的 Safari 里选一个几十个文件的文件夹背后要处理的东西完全不是一个量级。跨平台、多终端、大文件、目录结构保留这几个词凑在一起基本就是把“文件上传”从 CRUD 复杂度直接拉到了分布式系统边缘。我最近在一个企业内部素材管理项目里就接了这么个活技术约束很明确前端只能用 JS选型可以自己定。最后我用 WebUploader 插件为基础配合 HTML5 的目录选择能力把“选择文件夹 - 保留相对路径 - 分片上传 - 服务端重建目录”整条链路跑通了。这篇文章就是把这套方案的踩坑记录和核心实现拆出来给同样被卡在这类需求上的朋友一个可以抄作业的参考。适用范围先交代清楚如果只是传几个文件用传统 input 就够了如果你的需求是“用户选一个目录传到服务器后目录层级还在并且单个文件可能几 GB 甚至更大”那这篇文章正好是为你准备的。后面涉及前端 JS 代码也会给 Node.js 后端示例虽然不算保姆级教程但跟着走基本能跑通。1. 为什么选 WebUploader以及它在目录上传上的真实边界1.1 WebUploader 的看家本领WebUploader 是百度 FEX 团队早年开源的文件上传组件虽然这几年更新不算活跃但它的分片上传、并发控制、断点续传、MD5 秒传、队列管理这些能力放到今天的浏览器环境里依然是可用的。尤其适合企业内部系统因为这类系统通常要求上传大文件时不能一把梭不能因为网络抖动就让整个文件从头再来。WebUploader 把每个文件切成小块并行上传失败的分片可以单独重传这种设计思路对 500MB 到 100GB 级别的大文件非常友好。我在选型时也对比过其他方案比如直接用 axios 写一个分片上传器或者用 plupload、vue-simple-uploader 等。最后选 WebUploader核心原因是它在不捆绑前端框架的前提下就能提供完整的队列体验文件加入队列后可以排序、删除、重试UI 事件齐全API 文档虽然老派但该有的钩子都有。在“目录结构上传”这个需求里WebUploader 负责它最擅长的传输和调度部分至于目录结构则需要另想办法。1.2 原生能力并不支持“目录结构”真正的突破口是 HTML5 File API这里要先说一个容易踩的认知坑WebUploader 默认并不支持“选择文件夹并保留目录结构”。它的 pick 和 dnd 都是围绕 File 对象设计的用户选择一个或多个文件后插件拿到的是一个扁平的 FileList没有目录层级的概念。所谓“目录结构上传”实际上是你在 WebUploader 之上叠加了一层 HTML5 的能力。具体来说HTML5 的input[typefile]有一个非标准属性webkitdirectory只要给文件域加上这个属性用户弹出来的就是目录选择器。选择后input.files里包含的是该目录下所有文件的 File 对象并且每个 File 对象上会带一个webkitRelativePath字段类似images/2024/0127/photo.jpg。这就是目录重建的核心数据源。所以整个方案的真实技术底座是四层input[typefile].webkitdirectory负责“选目录”File.webkitRelativePath负责“记路径”WebUploader 负责“传文件、控并发、管进度、做分片”服务端负责“按路径落盘、合并分片”这四层缺一不可。如果你只是给 WebUploader 的 pick 加个 directory 属性后面不把相对路径传到服务端那么服务器上收到的仍然是散落的一堆文件目录层级完全丢掉了。1.3 跨平台兼容性盘点我一直强调“跨平台”在这个场景里主要指操作系统、桌面浏览器和移动端浏览器的组合。基于 Chromium 内核的浏览器比如 Chrome、Edge、360 极速、Electron 内嵌 webview对webkitdirectory的支持几乎无差别目录选择、webkitRelativePath、大文件分片都稳定。Firefox 也支持但目录选择弹窗的文案和层级样式略有差异不影响功能。macOS 上的 Safari 支持程度要差一些目录选择能力在部分版本上不可用需要做降级。移动端基本都是浏览器厂商说了算Chrome for Android 支持iOS Safari 的支持不一致这直接决定了“移动端选目录”这个需求能不能成立。我在项目里定的兼容策略很简单先检测动态创建的 input 是否有webkitdirectory属性如果有就启用完整目录上传没有就回退到多文件选择文件路径退化为仅文件名。这样产品体验能保留但不会因为某个浏览器不支持就完全不能用。2. 目录结构上传的整体设计从文件平铺到目录重建2.1 端上链路设计端上的完整链路是这样的用户点击自定义按钮触发一个设置了webkitdirectory的 input。input change 后拿到 FileList遍历每个 File从webkitRelativePath解析相对路径。用uploader.addFiles(files)把这些 File 对象交给 WebUploader 队列。对每个文件用一个 Map 保存file.id到relativePath的映射。每个分片请求发送前把relativePath塞进 formData。所有分片传完后前端触发合并接口告诉服务端“这个文件所有分片齐了可以合并”。这里最容易搞错的是第 3 步。很多人会直接修改 WebUploader 内部生成的 input 并设置webkitdirectory然后依赖插件自身的 change 监听。这条路能跑但和插件内部逻辑耦合太深不同版本行为不一致一旦插件升级就可能崩。我更推荐的做法是不配置 pick自己创建一个临时 input 完成目录选择再把 File 列表交给uploader.addFiles()。addFiles()是插件公开 API它接收 File 或 File 数组并且会走和普通选择一样的校验逻辑不会绕过分片和队列。为什么说这个设计更稳因为 WebUploader 内部的 pick 流程会自己接管 input 的 change 事件你很难在外面安全地追加webkitdirectory属性。自己创建 input 的话整个选择流程都在你手里后面加空目录校验、文件类型过滤、路径预处理都更方便。这个取舍在复杂项目里很重要。2.2 服务端链路设计服务端要做的不是简单的“存文件”而是“拼文件 创建目录”。一个分片请求过来服务端需要知道三件事这个分片属于哪个文件、这个文件一共有几个分片、合并后要放在哪个相对路径下。所以前端在uploadBeforeSend里不仅要传relativePath最好再传一个uploadId我用的是 WebUploader 的文件 id客户端保证唯一即可。服务端收到分片后先在临时目录里建一个以uploadId命名的文件夹把分片按 chunk 序号写进去。等到前端调用合并接口服务端读取该文件夹下所有分片按序号排序后顺序写入目标文件。目标文件路径由relativePath拼接而来比如相对路径是assets/images/a.pngbaseDir 是uploads最终写到uploads/assets/images/a.png同时用fs.mkdirSync把父目录创建好。这里还有一个容易被忽略的点文件本身的名字不需要依赖原始文件名因为最终路径完全由relativePath决定。这种设计天然规避了中文文件名乱码、特殊字符导致服务端存储异常的问题我在第 4 节会专门讲。2.3 空文件夹与符号链接的真实局限这块属于需求阶段就要讲清楚的硬伤。HTML5 的 File 体系里文件选择器只能给出“文件”空的子目录在 FileList 里是不存在的。也就是说用户选了一个包含空目录的文件夹服务端重建后不会有空目录。如果业务上必须保留空目录需要改用FileSystemDirectoryEntry遍历方式浏览器会回调目录条目循环目录时能发现空目录但它已经不是 WebUploader 的 File 队列模型能直接处理的了得自己递归拉出文件树再决定如何上传目录标记文件。我在这个项目里直接和产品确认“空目录不保留”因为这个场景价值太低复杂度却极高。symlink 也类似File API 拿不到链接本身的信息浏览器会把软链接视为普通文件展开服务端重建出来只能是普通文件不会被恢复成链接。对绝大多数业务来说没影响但如果是做备份类工具要提前在需求评审里说明不然上线后业务方会来找你。3. 前端核心实现WebUploader 目录选择与分片上传3.1 初始化配置不配置 pick直接用 addFiles 接管队列WebUploader 的初始化参数很多我直接把项目里实际用到的配置贴出来再逐个讲为什么这么设。const uploader WebUploader.create({ auto: false, server: /api/upload, accept: { title: All Files, extensions: , mimeTypes: */* }, chunked: true, chunkSize: 2 * 1024 * 1024, threads: 3, fileNumLimit: 5000, fileSizeLimit: 100 * 1024 * 1024 * 1024, fileSingleSizeLimit: 50 * 1024 * 1024 * 1024, duplicate: true });注意这里没有配置pick和dnd因为目录选择器我们要自己写。auto设为 false用户点击“开始上传”之后再触发uploader.upload()。chunked开启分片chunkSize是每个分片的大小默认 2MB对大多数业务够用。threads是并发上传的分片数量设 3 是保守值避免把服务器打满。fileSizeLimit是整个队列的总大小限制fileSingleSizeLimit是单个文件的大小限制这里给了个 100GB 和 50GB 的上限实际项目里你要按业务调整。duplicate允许重复文件加入队列因为目录下可能有同名文件在不同子目录里如果不开会出现文件莫名其妙被替换掉的情况。3.2 自定义目录选择器让 input 真正弹出“选择文件夹”核心代码是这样的document.getElementById(btnSelectDir).addEventListener(click, function () { const input document.createElement(input); input.type file; input.multiple true; if (webkitdirectory in input) { input.webkitdirectory true; input.directory true; } input.onchange function () { const files Array.from(input.files || []); if (!files.length) return; uploader.addFiles(files); }; input.click(); });这里有两个细节值得注意。第一webkitdirectory in input用来判断浏览器是否支持目录选择比简单判断 UA 靠谱得多因为同一浏览器的不同版本能力差异很大。第二设置input.directory true是为了让部分新版本浏览器也走目录选择逻辑双保险。当用户选择完目录后input.files里已经是目录下所有文件了不需要递归读取浏览器已经帮你展平了。有人可能会问为什么不用 WebUploader 自带的 pick 再改 input因为 WebUploader 会在内部监听 pick input 的 change我们再在外面挂一个 change事件触发顺序和文件对象包装时机都不好控制。自定义 input 是干净方案。实测下来Chrome、Edge、Firefox 都能正常弹出目录选择器Safari 则根据系统版本降级为普通文件选择但不会报错。3.3 记录相对路径并注入到每个分片请求文件加入队列后WebUploader 会把原生 File 对象包装成自己的 File 对象原对象的引用依然可以通过file.source访问。所以我在fileQueued事件里读取file.source.webkitRelativePath把它转成业务上需要的相对路径再存到一个 map 里。后续上传过程中所有的分片请求都会携带这个路径。const relativePathMap {}; uploader.on(fileQueued, function (file) { const rawFile file.source; let relativePath rawFile rawFile.webkitRelativePath ? rawFile.webkitRelativePath : file.name; // 去掉根目录一段否则会多一层用户选择的文件夹名 if (relativePath.includes(/)) { relativePath relativePath.replace(/^[^/]\//, ); } // 双保险有些环境下路径分隔符可能是反斜杠 relativePath relativePath.replace(/\\/g, /); relativePathMap[file.id] relativePath; const li document.createElement(li); li.textContent relativePath; document.getElementById(fileList).appendChild(li); }); uploader.on(uploadBeforeSend, function (file, data) { const relativePath relativePathMap[file.id]; if (relativePath) { data.relativePath relativePath; } data.uploadId file.id; });这里最关键的是uploadBeforeSend。WebUploader 在每个分片真正发出去之前都会触发这个回调data对象最后会作为 formData 的一部分随请求发送。所以每个分片请求都会带上relativePath服务端就知道这个分片属于哪个文件、最终该放哪里。关于去掉根目录一段决策依据是业务需求。如果产品希望保留用户选择的根目录名就不要执行那行replace。Chrome 里webkitRelativePath第一段一定是你选中的那个文件夹名比如你选了myFolder返回的路径是myFolder/images/a.png通常业务上不需要这层我一般都会去掉。3.4 大文件参数怎么调分片大小、并发数、秒传开关参数调优这件事很多文档不会讲得太细但我实际跑下来差别很大。chunkSize太小比如默认 2MB在千兆局域网传大文件时会产生大量请求每个请求都有 HTTP 头、服务端 memore 操作效率反而低。我在内网场景会调到 5MB 或 10MB外网弱网环境维持在 2MB 到 5MB 之间这样单个分片失败重传的代价也可控。threads并发数并不是越大越好。浏览器 HTTP/1.1 对同一域名的并发连接数通常有限制一般 6 个左右。WebUploader 的 threads 是分片并发如果设成 10很多请求还是会在浏览器队列里排队虚高没有意义。我通常设 3 到 6再配合服务端的分片落盘速度来决定。MD5 秒传这件事我建议慎重开启。如果要计算整个文件的 MD5WebUploader 会把文件从头到尾读一遍几百 MB 的单个文件还好如果是几千个小文件组成的目录那就像是开着浏览器在疯狂跑 CPU页面直接卡成幻灯片。我在这个项目里直接关闭了秒传只保留分片断点续传能力。如果业务上必须秒传至少要加一个文件大小阈值小于 50MB 的文件不计算 hash或者只在用户点上传后再按队列逐个算别让所有文件同时开始 hash。4. 服务端接收与目录重建完整实现4.1 使用 Node.js Multer 接收分片前端的分片请求是标准 multipart/form-data后端我用 Express Multer 接收。这里给出一个能直接跑通的实现const express require(express); const multer require(multer); const path require(path); const fs require(fs); const app express(); const BASE_DIR path.join(__dirname, uploads); const TMP_DIR path.join(__dirname, tmp); const upload multer({ dest: TMP_DIR }); app.post(/api/upload, upload.single(file), (req, res) { const { chunk, uploadId } req.body; if (!uploadId || chunk undefined || !req.file) { return res.status(400).json({ code: 1, msg: 参数不完整 }); } const fileDir path.join(TMP_DIR, String(uploadId)); fs.mkdirSync(fileDir, { recursive: true }); const chunkPath path.join(fileDir, String(chunk)); fs.renameSync(req.file.path, chunkPath); res.json({ code: 0, msg: ok }); });注意upload.single(file)里的file字段名来自 WebUploader 默认的fileVal配置如果改过这里要对应改。Multer 收到的分片文件会先落到临时目录然后我用renameSync移到以uploadId命名的子目录里实际生产环境建议用fs.promises.rename或者加 try/catch避免极端情况下目录不存在或权限异常。这种设计的好处是每个分片是独立的、无状态的。服务端不需要维护复杂的内存状态只需要按uploadId和chunk序号落盘。即使某个分片上传失败前端重试时重新提交同一个 chunk 序号也只会覆盖旧文件不会产生脏数据。4.2 合并分片并重建目录结构合并接口的职责是把临时目录里的分片按顺序拼接成完整文件然后根据relativePath创建目标目录。我的实现如下app.use(express.json()); app.post(/api/merge, (req, res) { const { uploadId, relativePath, totalChunks } req.body; if (!uploadId || !relativePath || !totalChunks) { return res.status(400).json({ code: 1, msg: 参数不完整 }); } const chunkDir path.join(TMP_DIR, String(uploadId)); if (!fs.existsSync(chunkDir)) { return res.status(400).json({ code: 1, msg: 分片目录不存在 }); } const chunkNames fs.readdirSync(chunkDir); if (chunkNames.length ! Number(totalChunks)) { return res.status(400).json({ code: 1, msg: 分片不完整: ${chunkNames.length}/${totalChunks} }); } chunkNames.sort((a, b) Number(a) - Number(b)); const target getSafePath(relativePath); fs.mkdirSync(path.dirname(target), { recursive: true }); const ws fs.createWriteStream(target); let index 0; function next() { if (index chunkNames.length) { ws.end(() { fs.rmSync(chunkDir, { recursive: true, force: true }); res.json({ code: 0, msg: ok, path: target }); }); return; } const rs fs.createReadStream(path.join(chunkDir, chunkNames[index])); rs.pipe(ws, { end: false }); rs.on(end, next); rs.on(error, (e) { res.status(500).json({ code: 1, msg: e.message }); }); } next(); });这里没有用fs.writeFileSync把整个文件读进内存再写因为大文件可能几个 GB一次读进内存会爆。我用流式管道按顺序把每个分片写入目标文件读一个分片就写一个分片。{ end: false }是关键不然第一个分片写完后ws会自动关闭后面的分片就写不进去了。全部写完后在ws.end回调里删除临时目录并返回最终存储路径。排序那行chunkNames.sort((a, b) Number(a) - Number(b))也必须注意。如果直接用字符串排序chunkNames可能是[0,1,10,11,2]合并出来的文件就是损坏的。数字排序才能保证分片顺序正确。4.3 路径穿越防护与文件名乱码处理relativePath来自前端前端是可以被篡改的所以服务端绝不能直接拼路径。比如用户传一个../../etc/crontab如果直接拼到 baseDir 后面就能把文件写到服务器任意目录这是非常严重的漏洞。我写了一个getSafePath来做保护和规范化。function getSafePath(relativePath) { const base path.resolve(BASE_DIR); const normPath path.normalize(relativePath).replace(/^([./\\])/, ); const target path.resolve(base, normPath); if (!target.startsWith(base)) { throw new Error(非法路径); } return target; }思路是先算出目标绝对路径再判断它是否真的在BASE_DIR范围内。startsWith在这里没有绝对安全但配合path.resolve和path.normalize能挡住常见的目录穿越。更严格的做法是再判断target base || target.startsWith(base path.sep)可以避免/uploads和/uploads_bak这类前缀误判。关于中文乱码我前面提过分片临时文件名只用数字序号最终文件名完全来自relativePath而relativePath是前端 JS 通过 FormData 提交的 UTF-8 字符串Multer 处理req.body时会正确解码。如果反过来使用req.file.originalname拼路径就很容易遇到 Multer 默认把非 ASCII 文件名转成 latin1 导致乱码的问题。所以这个设计是有意为之的不是偷懒。5. 跨平台实测踩坑记录与问题排查5.1 Chrome、Edge、Firefox 的表现差异我在实际测试中覆盖了 Windows 10 的 Chrome 122、Edge 122、Firefox 123macOS 的 Chrome 和 Safari以及 Android Chrome 和企业微信内置 WebView。Chromium 系浏览器全程无压力目录选择正常、webkitRelativePath返回值稳定、2GB 以上文件分片上传不掉链子。Firefox 有一个小坑它支持webkitdirectory已经有很长时间但选择目录后input.files里的webkitRelativePath在某些 Linux 发行版上可能使用/作为分隔符macOS 上也是/但 Windows 上如果系统区域设置特殊个别文件可能返回反斜杠。所以我前端代码里统一做了一次replace(/\\/g, /)这个替换成本极低但能避免服务端在 Windows 上创建出带反斜杠的“伪目录”。还有一个容易忽略的点是磁盘路径大小写。macOS 默认文件系统不区分大小写Linux 区分。如果目录里同时有Image/a.png和image/a.png在 Linux 上没问题但同步到 macOS 或 Windows 上可能冲突。这种跨平台边界问题很难在前端解决只能靠产品规则规避。5.2 移动端浏览器不支持 webkitdirectory 怎么办移动端是这个方案最大的变数。Android Chrome 支持目录选择但弹出的文件管理器和桌面端不同用户得在手机上定位目录体验谈不上好。iOS Safari 在部分版本里即使你动态设置了input.webkitdirectory点击后仍然只弹普通文件选择器不能选文件夹而且不同 iOS 版本行为还不一致非常坑。我的降级方案是在创建 input 之前先探测能力如果没有webkitdirectory属性就把 input 的multiple打开用户只能多选文件上传后的相对路径退化成文件名服务端也照常落盘只是没有目录层级。同时前端在 UI 上给出提示“当前浏览器不支持目录上传请使用 Chrome/Edge 桌面版获得完整体验”。从产品角度看这不是最优解但至少保证了“多终端能用”。如果你的业务强制要求在移动端保留目录结构那只能走原生 App 或 App 内嵌的 WebView 上传纯浏览器方案确实无能为力。5.3 分片合并失败或乱序合并失败是我在联调时遇到最多的问题而且大部分不是前端逻辑问题而是服务端状态没处理好。第一个坑是分片不完整就触发合并。WebUploader 的uploadFinished事件代表队列中所有文件都至少发起过一次上传但并不能保证有的文件在中途失败后没重试成功。如果某个文件的一部分分片没传完合并接口就会卡在“分片不完整”的校验上。我在项目里做了两层保护第一前端在uploadFinished后遍历所有文件逐个调用合并接口第二如果合并接口返回分片不完整就把失败信息记录到日志同时前端自动重试上传缺失分片。实际线上丢分片的概率很低但一旦出现没有重试机制就会让用户卡死。第二个坑是分片序号排序。前面代码里用了数字排序但如果你是用某个语言的原生sort()不加参数排序字符串数组就会出现1, 10, 11, 2的顺序错误合并出来的文件要么损坏要么直接无法打开。这个坑我栽过一次所以在这里特别强调。第三个坑是磁盘空间不足。大文件合并时临时目录和目标目录同时在写服务器至少需要两倍文件大小的可用空间。如果一个 50GB 的文件正在合并磁盘只剩 40GB合并就会在写到一半时失败而且已经写进去的部分文件还留在磁盘上。好的实践是合并前先检查磁盘剩余空间失败后清理临时分片目录。5.4 大量小文件导致 MD5 秒传卡死这个问题的本质是MD5 计算是整个文件级别的而 WebUploader 把一个文件加入队列后如果需要计算 hash会把这个文件从头到尾读一遍。单独一个大文件可能还好但目录上传场景下可能有几千个文件每个文件都要做全量读取浏览器主线程和文件读取线程全都被占满页面会卡住几分钟甚至更久。我建议的方案很简单不使用 WebUploader 的全局 hash 配置而是自己在业务层做开关。如果你确实需要秒传可以按文件大小分成两档超过 100MB 的文件计算 MD5小于 100MB 的普通文件直接上传。大文件秒传价值高小文件秒传带来的体验提升远小于计算成本。另外一个相关优化是fileQueued事件里不要做太多 DOM 操作。几千个文件同时加入队列时每来一个文件就往页面上追加一个 li浏览器会不断回流重绘。如果目录里文件数量特别多建议用文档片段批量渲染或者只显示上传进度平板列表延迟到上传完成后再渲染不然树形目录还没选完页面就已经卡死了。5.5 一个值得加的前端优化并发批量合并我最初的设计是在uploadFinished后用Promise.all一次性触发所有文件的合并接口。实测发现几千个小文件时这会瞬间产生大量并发请求服务端同时打开几十个写文件流磁盘 IO 直接打满。后来我加了一个简单的并发限制最多同时跑 5 个合并请求每个文件合并完成后再启动下一个。改动很小但稳定性提升非常明显。另外合并接口最好设计成幂等的。也就是说同一个uploadId如果收到多次合并请求第一次合并成功后第二次再来应该直接返回成功而不是报错。因为前端网络超时后往往会自动重试服务端如果不做幂等处理会出现同一个文件被重复合并或者第二次合并时报“分片目录不存在”。我在实现里是这样的如果目标文件已存在且临时分片目录不存在直接返回成功把重试当成好消息处理。最后说点项目里的小体会这套方案改造成本其实不高核心就是把webkitRelativePath摘出来喂给 WebUploader剩下的都是规矩活。但规矩活里最容易出问题的往往是那些看起来不起眼的字段传递比如chunk排序、路径穿越、并发上限。我现在的习惯是前端日志里把uploadId、relativePath、chunk三个字段打成结构化日志排查问题时一眼就能看出是哪个文件、哪个分片出了问题不用靠猜。如果你后续也想扩展这套方案可以考虑把断点续传做得更完整前端保存已上传分片列表页面刷新后重新加文件时先询问服务端哪些分片已存在缺失的分片才重新上传。WebUploader 底层支持这种扩展只是需要多写两个接口。目录结构上传本身是个很垂直的需求但它的通用思路——把文件系统里的路径信息带上、传输、再重建——在其他很多场景里都能复用。