前几天我接到一个上传需求单个文件最大能到3GB左右网络环境还说不上好用户要求上传中途断网、刷新页面都不能从头再来。我第一个想到的就是WebUploader。这货虽然发布有些年头了但在vue-cli项目里做大文件分片上传依然是很能打的方案。真正把它跑顺之前我栽了不少跟头静态资源路径不对、MD5算得卡到爆、上传完成后触发合并的时机判断错乱。这篇文章就把我在vue-cli里用WebUploader做分片上传的完整源码、配置参数、服务端配合逻辑以及那些常规文档里不会写的坑一次性整理出来给正在做同样需求的朋友一个可以直接参考的底稿。这套方案核心解决的是三个问题单个超大文件无法稳定传输、上传中断后必须重新开始、服务端瞬间接收大文件容易把内存和进程压垮。适用场景包括视频平台后台、网盘类工具、企业内部文件管理系统。无论你用的是vue-cli 2还是vue-cli 3以上版本核心逻辑都能复用差异只在静态资源的放置方式。1. 为什么大文件上传必须先分片1.1 单请求上传的致命瓶颈很多人第一反应是文件上传嘛把input typefile里的File对象丢给后端不就行了小文件确实可以但文件一旦到了GB级别问题就会成串冒出来。首先是网络稳定性问题。一个3GB的文件普通家庭上行带宽也就30Mbps左右传完要接近二十分钟。这二十分钟里只要断一次网、路由器重启一次、电脑休眠一下HTTP请求就会中断整个文件就要重新传。其次是服务端问题后端如果用类似readFile这种方式把一个完整请求体读进内存内存直接被打满如果做超时限制大文件长时间没有完成写入连接被强制断开前端拿到的可能是一个莫名其妙的错误。再就是体验问题没有任何进度条和分片维度反馈用户只能干等传到哪里完全不可知。分片上传的逻辑本质上就是把一个大任务拆成多个小任务并行处理。我用一个生活化的类比来解释搬家的时候一整面墙的柜子没办法直接搬下楼你会把它拆成柜门、隔板、抽屉分几次搬到了新家再按编号组装。分片上传就是这个思路文件按固定大小切成若干小块每个小块作为一个独立的HTTP请求上传全部传完后由服务端按序号拼接恢复成完整文件。1.2 分片上传的协议设计明确了要分片下一步就是设计一套“切片协议”。前端怎么切、请求带哪些参数、服务端怎么认出这些分片以及最后怎么合并这些都要提前定清楚。我习惯这样做前端用固定大小切割文件比如5MB一片。整个文件先计算一个MD5作为文件的唯一标识。每个分片请求都带上文件的MD5、当前分片的序号、总分片数、文件原始名称。服务端以文件MD5建目录把分片按序号存成临时文件。所有分片上传完成后前端再发一个合并请求服务端按顺序将临时文件流式拼接。整个流程里MD5承担了两个关键能力第一它是文件的“身份证”同一个文件上传过一次服务端可以直接秒传第二它让断点续传变成可能刷新页面之后只要MD5不变已经传过的分片可以直接跳过。做完这套设计前端和后端各干各的活逻辑边界很清楚。注意文件MD5和每个分片的MD5不是一回事。整个文件的MD5用于标识文件身份和最终完整性校验分片请求里的序号用于排序合并请求层面一般不需要单独算每个分片的MD5除非你对服务端落盘校验极度敏感。2. vue-cli项目里集成WebUploader的前置准备2.1 静态资源引入的两种方式WebUploader不是纯JS库它依赖UI组件资源CSS、选择按钮DOM结构以及可选的目标Flash组件。在vue-cli项目里引入它有两类主流方式我实际都用过先说结论老项目且不想折腾webpack的话优先选择放public目录手动引入新项目对模块化要求高选择npm引入但要会处理两种冲突。先看方式一下载WebUploader官方dist包把整个目录拷到项目的public/webuploader下然后在index.html里用script和link直接引入。!-- vue-cli 3 对应 public 目录 -- link relstylesheet href/webuploader/webuploader.css script src/webuploader/webuploader.min.js/scriptvue-cli 2用的是static目录路径类似static/webuploader引用时对应/static/webuploader/...。这样做的最大好处是WebUploader不参与webpack打包老库不会在构建环节出幺蛾子同时它内部依赖的jQuery也能直接使用页面里引入的版本或让全局jQuery指向它。方式二是npm安装至少在模块化统一上更干净npm install webuploader jquery spark-md5然后在组件或公共模块里引入import $ from jquery window.jQuery window.$ $ import WebUploader from webuploader import webuploader/dist/webuploader.css import SparkMD5 from spark-md5这里有一个非常容易卡住的问题WebUploader内部操作DOM依赖jQuery如果项目里没有全局jQuery变量初始化时直接报错。所以必须要做window.jQuery window.$ $这一步顺序也要在import WebUploader之前。两种方式各有适用场景我整理成一张对比表方便你选型维度public目录引入npm引入打包参与度不参与参与webpack处理路径问题手动控制由代码import管理老库兼容风险低高依赖全局jQueryUI资源引用手动写相对路径CSS内部路径可能需处理维护便利性资源独立升级手动替换可走包版本管理2.2 资源依赖清单与配置细节不管哪种方式只要用了WebUploader官方包就要留意它默认依赖的几类资源CSS样式、图片图标、Uploader.swf。如果项目不需要兼容老版本的IE浏览器目标文件选择器默认走HTML5能力Flash完全可以不用但swf参数最好还是配一个路径因为WebUploader内部的老逻辑会检测这个配置项是否有效缺失时虽然现代浏览器一般不影响但控制台可能冒出警告。CSS和图片资源在npm方式下一般由webpack处理问题不大。但如果用的是public目录方式要确认字体图标和背景图相对路径正确。我的经验是直接整个dist目录拷过去不要只拷webuploader.js否则样式里的图片路径会404。引入完成后验证方式很简单在浏览器控制台执行typeof WebUploader能拿到对象就说明基础环境OK了。接下来才是重头戏分片上传的核心配置和源码实现。3. 前端分片上传核心源码解析3.1 初始化配置关键参数逐个拆解WebUploader的最外层入口是WebUploader.create一堆能力都由创建时传入的配置对象控制。下面是拆解后的重点参数每个我都标注了实际作用const uploader WebUploader.create({ swf: /webuploader/Uploader.swf, server: /api/upload/chunk, pick: #uploadPicker, accept: { title: 视频文件, extensions: mp4,mov,avi,wmv,flv, mimeTypes: .mp4,.mov,.avi,.wmv,.flv }, auto: false, chunked: true, chunkSize: 5 * 1024 * 1024, threads: 3, fileVal: file, method: POST, duplicate: true, formData: { type: chunk } })逐个说含义server分片上传请求的地址每个分片都会向这个地址发一次请求。服务端的接收接口要和它对应上。pick选择按钮的DOM选择器。WebUploader会在这个DOM上生成点击选择文件的交互层。auto我习惯设为false先选文件再主动触发上传。如果设为true选完文件立刻上传在需要先算MD5的场景下有冲突。chunked分片开关false就是整文件上传。chunkSize每个分片的大小。5MB对大型视频比较平衡。分片太小会导致请求数量爆炸比如500KB一片3GB的文件会产生6000多次请求分片太大又失去分片的意义单个请求耗时长断点续传粒度粗。threads同时上传的分片请求数。3个是多数场景下的安全值既不会把带宽全占也能降低服务端并发压力。fileVal分片请求中文件字段的字段名服务端解析时要用这个key取文件流。duplicate是否允许选择同一个文件。允许重复选择能让断点续传场景下的重新选择操作更顺畅。formData附加参数会随每个分片请求发送。3.2 全文件MD5计算与上传前拦截分片上传协议里文件MD5是整个流程的核心标识。WebUploader提供了before-send-file事件这个事件在文件进入队列之后、第一个分片发出之前触发。我们在这里用SparkMD5对整个文件做指纹计算算完再继续上传。这里有个效率问题一个3GB的文件如果一次性把整个Blob读进内存浏览器很容易卡死甚至崩溃。所以MD5计算也要分块读每次读2MB左右的ArrayBuffer依次追加进SparkMD5。代码实现如下const calcWholeFileMd5 (file) { const deferred WebUploader.Deferred() const blob file.source.getSource() const fileReader new FileReader() const chunkSize 2 * 1024 * 1024 const total Math.ceil(blob.size / chunkSize) let current 0 const spark new SparkMD5.ArrayBuffer() fileReader.onload (e) { spark.append(e.target.result) current if (current total) { loadNext() } else { file.wholeMd5 spark.end() deferred.resolve() } } fileReader.onerror () { deferred.reject() } const loadNext () { const start current * chunkSize const end Math.min(start chunkSize, blob.size) fileReader.readAsArrayBuffer(blob.slice(start, end)) } loadNext() return deferred.promise() }这里有两个细节值得注意。第一file.source.getSource()是WebUploader内部提供的文件源入口在before-send-file阶段可以拿到原始Blob第二使用SparkMD5.ArrayBuffer()而不是默认的SparkMD5()否则append时类型不匹配。计算完成后把MD5存到file.wholeMd5上供后续所有分片请求使用。关联到WebUploader事件上就是uploader.on(before-send-file, (file) { return calcWholeFileMd5(file) })事件回调返回一个PromiseWebUploader会等这个Promise resolve之后再开始发分片这是一个关键的流程卡点。3.3 分片请求参数与MD5值绑定文件MD5算好后每个分片真正发出之前还会触发before-send事件。这个事件的参数里除了文件对象还带一个chunk对象我们需要在这个回调里把分片序号、总数、文件标识等参数塞进uploader.options.formData这些参数就会随当前分片请求提交给服务端。uploader.on(before-send, (file, chunk) { const totalChunks Math.max(1, Math.ceil(file.size / uploader.options.chunkSize)) uploader.options.formData.identifier file.wholeMd5 uploader.options.formData.chunkIndex chunk.index uploader.options.formData.totalChunks totalChunks uploader.options.formData.fileName encodeURIComponent(file.name) })为什么identifier在before-send里还要再赋值一次因为uploader.options.formData是同一个对象在create时初始化的配置可能被清掉或覆盖而且WebUploader内部某些版本不会自适应地把新参数拷贝进实际请求体最稳妥的方式就是每次分片发送前都确保formData里的值是最新的。紧接着的服务端只需要按照identifier建目录、按照chunkIndex存文件、按照totalChunks和fileName做合并依据协议就完整闭环了。4. 完整前端上传模块实操步骤4.1 组件封装与目录结构实际项目中不建议把逻辑全部堆在页面组件里太乱且无法复用。我做了一个独立的Uploader模块目录结构如下src/ components/ Uploader/ index.vue uploader.jsuploader.js负责创建上传实例、绑定核心事件、维护分片成功计数index.vue负责界面交互和进度显示。这样一个模块既能用在视频上传页也能用在网盘文件上传弹窗里。4.2 uploader.js 完整源码分享下面是封装后的核心源码我在模拟项目X里就是直接拿这套跑通的。这里把分片成功计数也做了出来因为在分片模式下每个分片成功都会触发uploadSuccess事件如果不做计数容易在第一个分片返回后就误判整个文件完成。import $ from jquery window.jQuery window.$ $ import WebUploader from webuploader import webuploader/dist/webuploader.css import SparkMD5 from spark-md5 const calcWholeFileMd5 (file) { const deferred WebUploader.Deferred() const blob file.source.getSource() if (!blob) { deferred.reject() return deferred.promise() } const fileReader new FileReader() const readSize 2 * 1024 * 1024 const total Math.ceil(blob.size / readSize) let current 0 const spark new SparkMD5.ArrayBuffer() fileReader.onload (e) { spark.append(e.target.result) current if (current total) { loadNext() } else { file.wholeMd5 spark.end() deferred.resolve() } } fileReader.onerror () { deferred.reject() } const loadNext () { const start current * readSize const end Math.min(start readSize, blob.size) fileReader.readAsArrayBuffer(blob.slice(start, end)) } loadNext() return deferred.promise() } const createUploader (options) { const chunkSize options.chunkSize || 5 * 1024 * 1024 const uploader WebUploader.create({ swf: /webuploader/Uploader.swf, server: options.server, pick: options.pick, accept: options.accept || {}, auto: false, chunked: true, chunkSize, threads: options.threads || 3, fileVal: file, method: POST, duplicate: true }) uploader.on(before-send-file, (file) calcWholeFileMd5(file)) uploader.on(before-send, (file, chunk) { const totalChunks Math.max(1, Math.ceil(file.size / chunkSize)) uploader.options.formData.identifier file.wholeMd5 uploader.options.formData.chunkIndex chunk.index uploader.options.formData.totalChunks totalChunks uploader.options.formData.fileName encodeURIComponent(file.name) }) return uploader } export default createUploader这段代码我放在uploader.js里对外暴露的只有createUploader页面组件不关心WebUploader内部细节。4.3 index.vue 组件绑定与进度展示组件里要做的事很直白初始化上传实例、监听进度、处理成功与错误、最后调合并接口。为了避免this指向错乱事件回调里我统一用箭头函数或者提前缓存self变量。template div classuploader-wrapper div iduploadPicker classupload-pick选择文件/div div v-ifprogress 0 progress 100 classupload-progress div classprogress-bar span :style{ width: progress % }/span /div span classprogress-text{{ progress }}%/span /div div v-ifstatusText classupload-status{{ statusText }}/div /div /template script import axios from axios import createUploader from ./uploader export default { name: Uploader, data() { return { uploader: null, progress: 0, statusText: , chunkSuccessCount: 0, chunkTotalCount: 0 } }, mounted() { const self this const uploader createUploader({ pick: #uploadPicker, server: /api/upload/chunk, accept: { title: 视频文件, extensions: mp4,mov,avi,wmv,flv, mimeTypes: .mp4,.mov,.avi,.wmv,.flv } }) this.uploader uploader uploader.on(uploadProgress, (file, percentage) { self.progress Number((percentage * 100).toFixed(2)) }) uploader.on(uploadStart, (file) { self.statusText 正在上传... self.chunkSuccessCount 0 self.chunkTotalCount Math.max(1, Math.ceil(file.size / uploader.options.chunkSize)) }) uploader.on(uploadSuccess, (file, response) { if (response response.code 0) { self.chunkSuccessCount self.statusText 已上传 ${self.chunkSuccessCount}/${self.chunkTotalCount} 个分片 } }) uploader.on(uploadError, (file, reason) { self.statusText 上传失败${reason || 未知错误} }) uploader.on(uploadComplete, (file) { if (self.chunkSuccessCount self.chunkTotalCount) { self.mergeFile(file) } }) uploader.on(error, (type) { if (type Q_TYPE_DENIED) { self.statusText 文件类型不允许 } }) }, methods: { async mergeFile(file) { const self this this.statusText 正在合并分片... try { const res await axios.post(/api/upload/merge, { identifier: file.wholeMd5, fileName: decodeURIComponent(file.name), totalChunks: self.chunkTotalCount }) if (res.data.code 0) { self.progress 100 self.statusText 上传完成 this.$emit(success, { url: res.data.data res.data.data.url }) } } catch (e) { this.statusText 合并失败请重试 } } }, beforeDestroy() { if (this.uploader) { this.uploader.destroy() } } } /script组件卸载时执行uploader.destroy()这一步很容易被忽略。如果不销毁WebUploader在DOM上注册的事件和队列状态会残留切换到其它页面再回来上传状态可能错乱。这是我在实际测试里发现的一个隐蔽问题。5. 服务端分片接收与合并接口设计前端发来的分片请求到达服务端后服务端要做两件事先把分片落盘再在全部完成后按顺序合并。这里以Node.js配合Express和Multer为例其它后端语言逻辑可以等价翻译。5.1 分片上传接口逻辑接收分片的接口需要两个核心能力保存上传的分片数据和读取请求里的业务参数。业务参数就是identifier、chunkIndex、totalChunks、fileName这几个它们以普通表单字段的形式随请求体发过来。const express require(express) const multer require(multer) const fs require(fs) const path require(path) const app express() const tmpDir path.join(__dirname, upload_tmp) const fileDir path.join(__dirname, upload_files) const upload multer({ dest: tmpDir }) app.post(/api/upload/chunk, upload.single(file), (req, res) { const { identifier, chunkIndex } req.body if (!identifier || chunkIndex undefined) { res.status(400).json({ code: -1, msg: 参数缺失 }) return } const chunkDir path.join(tmpDir, identifier) if (!fs.existsSync(chunkDir)) { fs.mkdirSync(chunkDir, { recursive: true }) } const chunkPath path.join(chunkDir, String(chunkIndex)) fs.renameSync(req.file.path, chunkPath) res.json({ code: 0, msg: 分片上传成功 }) })fs.renameSync这一步比“再读出来写入目标文件”高效因为Multer已经把临时文件存到磁盘我们只需要把临时文件移动到按identifier建好的目录里。每个分片都以chunkIndex作为文件名方便后面按数字顺序合并。注意分片文件名一定要用纯数字不要用“chunk_0.txt”这种带前缀的格式也不要依赖字符串排序。否则合并时第10个分片会排在第二个分片前面文件直接错乱。5.2 合并接口与完整性校验合并接口收到identifier、fileName、totalChunks后把对应的分片目录里所有分片按0到totalChunks-1的顺序写入最终文件。大文件合并要避免一次性把全部数据读进内存最好用流式追加。const { createReadStream, createWriteStream } require(fs) const mergeChunks async (identifier, fileName, totalChunks) { const chunkDir path.join(tmpDir, identifier) const destPath path.join(fileDir, fileName) const dest createWriteStream(destPath) const writeChunk (index) new Promise((resolve, reject) { const src createReadStream(path.join(chunkDir, String(index))) src.pipe(dest, { end: false }) src.on(error, reject) src.on(end, resolve) }) for (let i 0; i Number(totalChunks); i) { await writeChunk(i) } dest.end() fs.rmSync(chunkDir, { recursive: true, force: true }) } app.post(/api/upload/merge, async (req, res) { const { identifier, fileName, totalChunks } req.body try { await mergeChunks(identifier, fileName, totalChunks) res.json({ code: 0, msg: 合并成功 }) } catch (e) { res.status(500).json({ code: -1, msg: e.message }) } })这里用createWriteStream只创建一次配合src.pipe(dest, { end: false })保证每个分片写完不会意外关闭目标流这是流式合并的核心细节。合并完成后清理分片临时目录避免磁盘空间被大量残留的临时分片占满。如果是Java服务端思路一样每个分片接口把文件流写入磁盘用文件MD5作为目录名合并时用RandomAccessFile或FileOutputStream顺序写入再对总字节数做一次校验。校验逻辑可以对最终文件重新计算MD5与前端identifier比对不过在大文件场景下这个操作耗时较长我一般在合并参数里带上客户端发送的原始文件大小合并完成后比对最终文件字节数是否一致这样代价小很多。6. 常见问题排查与避坑实录6.1 事件回调触发时机不一致分片模式下uploadSuccess并不是整个文件完成后才触发而是每个分片请求成功都会触发。早期我直接把合并逻辑写在uploadSuccess里第一个分片成功就开始调合并接口结果服务端只合并了一个不完整的文件。正确的做法就是我在组件里展示的自己维护chunkSuccessCount和chunkTotalCount等成功数等于总分片数后再发起合并。另一个容易混淆的是uploadComplete。这个事件对整个文件而言确实会触发但它并不等同于“所有分片成功”因为失败重试后的最终状态也会走到uploadComplete。所以合并判断不能只看uploadComplete必须以成功计数为准。6.2 分片成功但statusText提示失败出现这种问题通常不是前端逻辑错了而是服务端响应格式不满足预期。WebUploader会对分片上传的响应做解析如果响应不是合法的JSON结构或者在uploadError里接收到的rason并不是直观的报错界面上就会显示上传失败。我的习惯是服务端无论成功失败都返回固定的{ code: xxx, msg: xxx }格式前端只认这个结构。还有encodeURIComponent(file.name)这个细节。不编码文件名的直接后果就是中文文件名在服务端解析后变成乱码合并出来的文件无法识别。服务端拿到参数后要对应做一次decodeURIComponent。6.3 大文件MD5计算时间过长3GB文件用2MB分块读大概要读取1500多次耗时通常在几秒到十几秒之间和电脑硬盘读取速度有关。这个时间不是白花的毕竟MD5承担了秒传和断点续传两个核心能力。但如果你发现在计算MD5过程中界面有明显的冻结感可以考虑把readAsArrayBuffer的读块大小调到5MB甚至10MB减少读取次数。不过单块读太大一次追加进SparkMD5的内存峰值也会上升需要做取舍。我的实践是2MB到5MB区间最平衡。如果对时间敏感还可以考虑用Web Worker把MD5计算放到后台线程避免阻塞UI。但这样会显著增加代码复杂度普通上传功能不一定值得。6.4 断点续传和秒传方案补充WebUploader本身不内置断点续传逻辑所谓断点续传要靠MD5这个标识和服务端配合实现。刷新页面后重新选择同一个文件before-send-file阶段会重新计算MD5得到的结果不变。接下来有两种做法一种是我在模拟项目X里用的轻量方案在before-send阶段先请求一个分片状态查询接口告诉服务端identifier和chunkIndex服务端返回这个分片是否已存在。如果已存在前端把这个分片的请求跳过。WebUploader在before-send里返回reject的Promise时会跳过当前分片的上传动作让流程进入下一个分片。核心伪代码如下uploader.on(before-send, (file, chunk) { const deferred WebUploader.Deferred() axios.post(/api/upload/chunk/status, { identifier: file.wholeMd5, chunkIndex: chunk.index }).then((res) { if (res.data.code 0 res.data.exists) { deferred.reject() } else { deferred.resolve() } }) return deferred.promise() })这里的skip语义在不同WebUploader版本里行为略有差异建议在本地实测确认。如果reject会导致整个队列卡住就改成resolve并让服务端对已存在的分片直接返回成功效果也差不多。秒传的逻辑更简单MD5算完后直接调一个/api/upload/check接口服务端查一下这个MD5是否已存在对应文件存在就直接返回“秒传成功”前端连分片流程都不需要进入。6.5 常见问题速查表现象可能原因解决办法控制台报jQuery is not definednpm方式引入时全局jQuery未设置在导入WebUploader前执行window.jQuery window.$ $静态资源404public路径配错或目录放错检查浏览器请求的URL和public/static下实际路径上传请求跨域服务端未开放CORS服务端增加跨域配置允许PUT/POST/OPTIONS合并后文件损坏分片合并顺序用了字符串排序用数字序号循环写入分片文件命名保持纯数字分片传完但页面卡在99%合并接口耗时较长或合并失败检查合并接口的流写入逻辑再看响应格式是否异常刷新后重新上传又从头开始没有做分片状态查询或identifier变化前端用完整文件MD5做identifier并对已存在分片做跳过处理浏览器内存飙升并发数过高或MD5单块读太大threads设为2到3MD5读取块控制在2MB到5MB分片成功数超过总分片数重试机制导致重复计数计数前先判断该分片是否已标记成功7. 几个值得再说的实操心得这整套方案我实际跑下来有一个很深的感受分片上传的上限不在浏览器不在WebUploader而在后端合并逻辑的健壮性。前端传得再快分片存了一堆合并接口一崩溃全白费。所以做联调时先把服务端合并接口单独测熟用脚本模拟100个分片调用合并确认文件字节数和MD5都对再回到前端调整个流程。另一个建议是分片大小和并发数不要抄参数要结合单位带宽实测。内网环境带宽高分片可以设置到10MB甚至20MB公网环境上行带宽有限5MB分片加3个并发通常是比较稳的组合。如果并发数拉满导致服务端出现很多超时错误先从日志里确认瓶颈是带宽还是服务端CPU、磁盘IO。最后再提一个不起眼但很影响体验的点上传过程中不要让用户离开页面。WebUploader一旦页面被刷新内存里的队列状态就消失。虽然断点续传可以恢复分片级别但界面进度、合并动作都需要重建。我在项目里的应对方法是弹层提示用户“上传中请勿关闭页面”同时在组件销毁时记录一个未完成状态用户再次进入时主动提醒是否续传。这套代码和思路在模拟项目X里已经稳定运行了一段时间3GB文件、2000多分片的场景也扛得住。如果你正在从零接入WebUploader分片上传照着这套逻辑先跑通小文件再挑战大文件基本不会走太多弯路。
