第一次在管理后台里需要做视频上传功能时我图省事直接用了组件库里自带的Upload组件。当时想得很简单视频也就是文件上传不都一样吗结果第一个版本上线没多久问题就集中爆发了——某内容管理平台需要支持运营上传短视频素材单个视频动辄三五百MB有些甚至超过1GB。用Upload组件传大文件几乎必失败快传满了进度条卡在99%不动用户直接投诉到产品那里。后来我花了两天时间把这个功能重构成一个独立的Vue上传视频组件分片、断点续传、秒传、并发控制、失败重试全都安排上用在了三个后台项目里稳定跑了大半年。今天把这些设计思路和踩坑经历整理出来给遇到同样问题的开发者一个参考。这个组件解决的核心问题很简单让大视频文件上传变得可失败、可恢复、可感知。它适合用过Vue但没做过深度上传功能的人也适合在后台项目里被大文件上传折腾过的朋友。下面从思路到实现完整过一遍。1. 为什么视频上传不能直接用现成Upload组件1.1 大文件上传真正的问题是什么视频文件的体积和图片完全不是一个量级。一张压缩过的图片可能几十KB到几MB网络再差也忍忍就过去了。但一段高清培训视频、课程回放、宣传片素材随便就是几百MB起步压完码率也不低。这类大文件用普通的单请求上传会遇到三个绕不开的问题第一服务端和网关的限制。大多数Nginx配置里默认的client_max_body_size只有1MB或者几MB。就算后端专门调大这个值网关层、负载均衡器、云厂商的对象存储预签名URL每一层都有自己的大小限制。你不可能为了一个上传功能把所有中间件的限制都放大这既不安全也不现实。第二网络中断的成本太高。单请求上传意味着整个文件都在一个HTTP连接里传输。公司内网偶尔抖动、会议室切换Wi-Fi、电脑休眠唤醒都可能让连接断开。一旦断开整个视频从头再传用户可以当场崩溃。第三用户看不到细节。单请求上传的进度是“全有或全无”没有一个清晰的中间状态。卡在99%和传到一半毫无区别用户不知道该等还是该重试。所以视频上传不能当普通文件上传处理本质上它需要一套针对大文件的传输策略。业界通用的做法就是分片——把一个大文件切成若干小块逐块上传失败只重传失败的那几块和碎片化下载的道理一样。这也是整个组件的核心设计起点。1.2 现成Upload组件缺少的东西有些朋友可能会说element-plus、antd这些组件库的Upload明明也能传文件还能自定义请求方法看起来挺灵活。这话对了一半。组件库的Upload组件设计定位是“文件的选择与提交”它默认处理的流程是用户选文件、拿到File对象、发一个POST请求、等待响应。你确实可以在beforeUpload里手动切分文件再自己发起分片请求但这样做你会和组件库内部的受控逻辑反复打架状态是组件的进度是组件给的异常分支也是组件定义的。想实现分片批量请求、断点续传、并发控制基本等于绕过组件本身重新写一套那为什么还要用从能力对比上看差距很直接能力项通用Upload组件视频上传组件需要大文件单请求提交支持不合适必须分片分片上传不内置必须内置断点续传刷新后继续不内置建议内置并发控制不提供需要可配置单分片失败重试不提供需要可配置秒传服务端已有文件不提供强烈建议真实传输进度依赖底层XHR必须精确汇总取消与暂停部分支持必须可控表格里列的全是视频上传场景的“刚需”。组件库解决的是80%常规场景而视频上传属于那20%的深水区用通用组件硬顶到了线上就是隐患。另外一个容易被忽略的点视频上传不是一个“发一次请求”的动作而是一个多阶段流程。选文件后要先校验然后算哈希然后询问服务端可不可以秒传服务端说不行就再挨个传分片全部传完了还要触发合并。这个流程需要明确的“状态机”——待处理、哈希计算中、检查中、上传中、暂停中、已完成、已失败。通用Upload组件给不了这种细粒度的状态管理。所以我的结论是视频上传组件值得自己写一次。写成一个独立可复用的组件后续任何项目需要“传大文件”的能力直接拿过去用比反复和组件库API作斗争划算得多。2. 组件的整体设计与参数选择2.1 先把组件里要做的事拆开写这种不算小的功能组件最忌讳的就是把所有逻辑堆在一个.vue文件里。两千行代码挤在一起自己维护都费劲更别说复用了。我在设计时把整个功能拆成了三个层级VideoUploader.vue纯UI层负责文件列表渲染、拖拽区域、进度条、操作按钮不关心任何上传逻辑。useUploader.ts组合式函数层管理上传状态、分片队列、进度汇总、事件对外抛出这是组件和上传核心之间的胶水层。upload-core.ts纯逻辑层负责文件切割、哈希计算、并发调度、XHR请求、重试策略。这一层不依赖Vue理论上任何框架都能用。这样拆的好处很明显如果你不想用我的组件UI也不想用Vue你直接把upload-core拿走去接自己的逻辑也可以如果后端接口有变化只改upload-core组件层完全不用动。分层的同时我还把“组件交互”和“上传调度”从设计上解耦了。比如上传中用户点了取消UI层只是调了一个cancel方法真正的中止逻辑在上传调度器里。组件不会因为用户主动取消、网络断开、分片失败这些情况不知所措因为所有分支都有明确的状态路径。2.2 分片大小和并发数怎么定这两个参数是整个组件里最值得花心思的地方。我见过有人把分片设成1MB好家伙一个500MB的视频要发500个请求后端接收分片的临时目录全是碎文件合并时也慢。也有人一把梭把整个文件切成几个大块每个块200MB断了重传的成本依然很高。我自己用的默认值是分片大小5MB并发数3。分片大小选5MB的逻辑是这样的第一要远小于Nginx和网关的常见大小限制避免触发中间层拦截第二要足够大避免分片数量过多导致请求开销占比过高第三5MB的分片上传时间通常控制在两三秒内失败重试的成本低用户感知不明显。并发数选3理由更简单。浏览器对同一域名的HTTP/1.1连接数限制一般是6个你如果并发拉满6个页面里的其他接口请求就得排队。视频上传这种后台场景页面往往还有列表加载、详情查询、表单提交不能把所有连接都占满。并发3是一个相对平衡的点——上传不算慢页面也不至于卡死。实际代码里这两个参数不是写死的而是作为上传核心的配置项暴露interface UploadOptions { url: string file: File chunkSize?: number // 默认 5 * 1024 * 1024 concurrency?: number // 默认 3 retryCount?: number // 分片失败重试次数默认 3 }如果你的视频本身比较小比如小于50MB走不分片的单请求上传也完全没问题效率还更高。组件里可以加判断文件小于某个阈值时直接整体上传大于阈值时自动切分。这个优化对体验提升其实是感知不强的但能少走后端的分片合并逻辑后端同事会感激你。2.3 为什么必须算文件哈希视频上传组件和普通文件上传最大的区别就在于“重复上传”这个场景。一个几百MB的培训视频可能多个运营都拿到了源文件重复传到后台的情况非常常见。如果每次都完整走一遍分片上传流程服务器白白浪费带宽和存储。所以组件里必须给文件算一个内容指纹——哈希。有了哈希上传流程多了一步“秒传检查”组件把文件的哈希值先发给后端后端查一下库里有没有相同哈希的文件记录如果有直接返回已存在的URL前端显示“秒传成功”一秒都不到。另一个用途是断点续传。断点续传要求前后端对“同一个文件的哪些分片已经上传成功”有一致的判断文件名不可靠因为同名文件内容可能完全不同。唯一可靠的标识就是内容哈希。前端在断点续传时用localStorage把上传过的文件哈希和分片索引记录下来重新打开页面后比对哈希就知道哪些分片不用重新传。技术选型上我用的是spark-md5这个库。它的特点是支持增量哈希计算——不用一次性把整个文件读进内存而是分片读、分片累加最后统一输出完整文件的MD5。这一步对大文件很关键如果直接readAsArrayBuffer读一个1GB的文件浏览器内存分分钟爆掉。哈希计算的代码大致是这样import SparkMD5 from spark-md5 function calculateFileHash(file) { return new Promise((resolve, reject) { const spark new SparkMD5.ArrayBuffer() const reader new FileReader() const chunkSize 2 * 1024 * 1024 let offset 0 const loadNext () { const chunk file.slice(offset, offset chunkSize) reader.readAsArrayBuffer(chunk) } reader.onload (event) { spark.append(event.target.result) offset chunkSize if (offset file.size) { loadNext() } else { resolve(spark.end()) } } reader.onerror () reject(new Error(文件读取失败)) loadNext() }) }这里读取小块用2MB而不是上传分片的5MB是为了让哈希计算的单位更细避免读入内存的数据量过大。整个计算过程是异步的文件大时耗时明显UI上需要显示“计算中”的状态不能让人以为页面卡死了。3. 分片上传与断点续传的代码实现3.1 文件校验与预处理用户选完视频文件之后组件做的第一件事不是急着上传而是做三道校验。第一道是类型校验。组件上设置acceptvideo/*这个只是让文件选择器默认过滤视频格式挡不住用户改成“所有文件”然后选一个非视频文件。所以代码里还需要再确认一遍file.type是否以video开头。需要注意的是file.type在部分浏览器里可能为空字符串比如某些Linux浏览器对特定视频格式识别不了所以还要配合后缀名兜底判断确保.ts、.mp4、.mov、.mkv这些常见格式不会被误拦。第二道是大小校验。每个项目对视频大小的要求不一样组件要暴露一个maxSize属性给业务方配置。超过了就触发error事件在UI上红字提示不进入上传流程。第三道是空文件校验。file.size为0的文件看起来是个视频格式实际上没有任何内容这类文件在最开始就应该被拦掉上传了也是后端合并时出错。预处理阶段还有一个容易被忽略的点URL.createObjectURL生成预览地址。即使视频没有上传用户也需要知道“我选的到底是哪个视频”。通过createObjectURL创建一个指向该File对象的临时URL赋给video标签的src用户就能立即看到视频缩略预览。这个URL要记住在组件卸载或状态重置时通过URL.revokeObjectURL释放否则会有内存泄漏。3.2 分片切割与并发调度校验通过之后就是真正的核心流程。先按配置的分片大小把文件切成一个个独立的数据块function createChunks(file, chunkSize) { const chunks [] let cur 0 while (cur file.size) { chunks.push(file.slice(cur, cur chunkSize)) cur chunkSize } return chunks }File对象的slice方法返回的是一个Blob它不会把文件内容复制到内存里只是记录了一个“文件引用偏移量长度”所以切几百个分片对内存几乎没压力不用惧怕分片数量多。切分完成之后进入并发调度环节。我这里没有引入第三方并发库直接手写了一个简单的并发池。原理很朴素把任务放进队列先启动N个任务每完成一个就从队列里补一个直到全部结束。async function runWithConcurrency(tasks, limit, worker) { const results [] const queue tasks.map((task, index) ({ task, index })).reverse() let activeCount 0 return new Promise((resolve, reject) { const startNext () { if (queue.length 0 activeCount 0) { resolve(results) return } while (activeCount limit queue.length 0) { const { task, index } queue.pop() activeCount worker(task, index) .then((result) { results[index] result activeCount-- startNext() }) .catch((err) { activeCount-- reject(err) }) } } startNext() }) }这个并发池不复杂但胜在可控。每个分片的上传请求包装成一个返回Promise的任务失败时可以重试重试仍然失败就把错误抛出去中止整个上传。分片上传请求本身用的是XMLHttpRequest不是fetch。原因很简单fetch直到现在也没有原生的上传进度事件要拿上传进度只能自己用流去模拟成本不值。XHR的upload.onprogress事件用起来干净利落。3.3 分片请求与整体进度计算每个分片的请求函数如下function uploadChunk({ url, fileHash, index, chunk, fileName, totalChunks, onProgress }) { return new Promise((resolve, reject) { const formData new FormData() formData.append(file, chunk, ${fileHash}_${index}) formData.append(hash, fileHash) formData.append(index, index) formData.append(totalChunks, totalChunks) formData.append(fileName, fileName) const xhr new XMLHttpRequest() xhr.open(POST, url) xhr.upload.onprogress (e) { if (e.lengthComputable) { onProgress(e.loaded / e.total) } } xhr.onload () { if (xhr.status 200 xhr.status 300) { resolve(xhr.responseText) } else { reject(new Error(分片${index}上传失败状态码${xhr.status})) } } xhr.onerror () reject(new Error(网络异常)) xhr.send(formData) }) }formData里带上fileHash、index、totalChunks这些字段是为了让后端能够按哈希建目录、记录分片序号、合并时按顺序拼接。这里有一个后端协作的前提后端接口必须支持分片参数并且在合并前把所有分片严格按index排序。分片并发上传时到达顺序是乱的后端合并前不排序生成的视频就会出现花屏、跳帧、文件头损坏这类诡异问题。整体进度的计算比单个分片麻烦。很多组件的进度条都会出现“前90%很快、最后10%卡半天”的怪象就是因为只算了当前分片的进度没有算总体。我采用的公式是总体进度 (已成功分片总数 当前正在上传分片的已传输占比之和) / 总分片数实现上每次某个分片触发onprogress就重新汇总一次所有分片的状态把结果刷到进度上。这个计算频率可能很频繁所以我把它包了一层节流保证一秒钟最多刷新十次UI避免过度渲染。3.4 秒传与断点续传的落地秒传和断点续传的实现是一对孪生兄弟都依赖文件哈希作为索引。上传前组件先向后端的check接口发一个请求参数就是文件的哈希const checkResponse await fetch(/api/video/check, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ hash: fileHash }) }) const checkData await checkResponse.json()后端返回的可能是三种情况文件已存在返回带url的对象前端直接进入“已存在”状态不发起任何分片请求。文件不存在但已有部分分片返回已上传分片的index数组前端跳过这些分片只上传缺失的。文件不存在、没有任何分片返回空数组前端从第0个分片开始。第二种情况的妙处在于它不仅支持“前端主动断点续传”还支持“前端不知道之前传过但后端知道”。哪怕用户换了一台电脑、换了浏览器、清空了localStorage只要后端临时目录里还留着一部分分片就能从断点继续。前端的本地记录也要做。我维护了一个Map结构key是文件哈希value是已成功分片的index数组同时把这份映射持久化到localStoragefunction saveUploadRecord(fileHash, chunkIndex) { const key video-upload:${fileHash} const record JSON.parse(localStorage.getItem(key) || []) if (!record.includes(chunkIndex)) { record.push(chunkIndex) localStorage.setItem(key, JSON.stringify(record)) } }每次分片上传成功就更新一下localStorage。用户刷新页面后组件发现本地有记录就可以把已存在的分片直接标记为完成。需要注意localStorage的容量有限record数组如果太长要压缩控制阈值为每5个分片记一条连续范围而不是每个index都单独存。500个分片全存数组虽然通常也够但没必要。所有分片传完之后组件再发一个merge请求const mergeResponse await fetch(/api/video/merge, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ hash: fileHash, fileName: file.name }) })后端收到merge请求后找到该哈希对应的临时分片目录按index顺序将所有分片拼接成一个完整视频文件写入正式存储路径。合并完成后返回视频的访问URL组件拿到这个URL更新自己的最终状态。4. 封装成Vue组件后的接入体验4.1 props和事件怎么设计组件最终要给别人用API设计得好不好会直接决定它有没有复用价值。我在设计props时尽量遵循“少而明确”的原则——组件不应该知道业务细节但业务方应该能控制所有关键行为。属性类型默认值说明urlstring必填上传接口地址chunkSizenumber5242880分片大小单位字节concurrencynumber3同时上传的分片数maxSizenumber2GB允许上传的最大文件大小acceptstringvideo/*可接受的文件类型autoUploadbooleantrue选完文件后是否立即开始上传disabledbooleanfalse是否禁用上传交互事件方面我定义了一组语义明确的事件名change文件列表发生变化时触发参数是当前所有File对象。start上传正式开始参数是文件的初始信息和目标URL。progress上传进度更新参数是0到1的进度值。success单个文件上传成功参数是最终的视频URL和文件信息。error单个文件上传失败参数是Error对象。cancel用户点击取消上传时触发。这里我坚持不用v-model去绑定一个文件对象。原因在于文件上传的流程太长状态变量太多一个v-model根本表达不了“上传中”“失败”“已暂停”“秒传成功”这些状态。用事件辐射出去业务方自己在父组件里按照需求接逻辑反而更灵活。4.2 模板结构和交互细节组件模板里分了几块区域拖拽选择区、文件列表区、操作区。拖拽区的逻辑比较固定监听dragover和drop事件dragover时把isDragging置为true给容器加一个高亮边框drop时用event.dataTransfer.files取出文件列表。需要注意拖拽时的事件对象里拿到的是DataTransfer对象不是File对象数组要转一下。文件列表区使用v-for渲染当前所有待上传和上传中的文件每个文件项展示的信息包括文件名、文件大小、当前状态、进度条、操作按钮。上传中显示进度条和取消按钮失败状态显示重试按钮和错误原因成功状态显示视频链接和“重新选择”按钮。一个值得提到的细节进度条组件我用的是原生div自己画的没有引UI库。原因很简单视频上传组件在某些项目里可能搭配不同的UI框架如果组件内部硬编码绑定某个UI库的进度条组件换项目就要换依赖。自己画一个二十行的进度条非常容易换来的是组件完全中立这一点在我看来很值。4.3 与业务表单配合的细节视频上传组件很少是一个孤立页面更多时候是嵌在内容发布表单里的一个字段——发布课程需要传课程视频发布动态需要传封面视频。表单里最常见的问题是用户还没传完视频就点了提交按钮。所以useUploader里要暴露一个isUploading的响应式状态业务方把它接进表单校验逻辑const { files, isUploading, uploadProgress, startUpload, cancelUpload } useUploader()在业务页面的提交方法里校验isUploading是否为false不为false就提示“视频上传中请稍候”。如果视频上传失败还要阻止表单提交否则发布出去的内容会是一个坏链。还有一类场景业务方需要把上传结果塞到提交给后端的表单数据里。做法是在success事件里捕获返回的URL存入表单state。视频还没传完时URL字段为空提交前校验一下即可。这样设计后上传组件和表单的关系就清晰了——组件只负责把视频安全地传到服务器拿到URL交给你剩下业务逻辑由业务方自己编排。5. 常见问题排查与避坑实录5.1 问题速查表把我在实际项目里遇到的典型问题列成一张表方便排查现象可能原因处理方式进度条卡在某个百分比不动分片请求失败但没重试网络断了哈希计算阻塞UI检查重试逻辑是否生效查看Network面板确认是否有请求挂起视频传完后无法播放后端合并分片时没按index排序分片文件类型丢失确认合并逻辑里index必须升序排列formData里的file字段保持原有Blob接口跨域报错后端未配置CORS自定义请求头未加入允许列表OPTIONS预检请求必须有正常响应Access-Control-Allow-Headers要包含自定义头秒传一直不生效哈希计算错误本地记录和服务器记录不一致文件内容确实不同用同一文件分别计算两次哈希对比检查check接口的参数名是否对齐刷新页面后断点续传失败后端临时分片目录被清理localStorage里记录的index和服务器不一致确认后端临时目录过期时间check接口返回的已传分片列表优先于本地记录上传大视频时页面卡死一次性读取整个文件计算哈希分片请求过多导致渲染线程压力大使用增量哈希计算进度更新节流必要时把哈希计算挪到Web Worker组件上传成功但业务拿不到URLsuccess事件的参数结构没对应上后端回包URL字段名不对和后端对齐回包格式在success事件里打印原始响应体排查5.2 后端协作的几个关键约定前端把分片上传做出来了但整个流程能不能跑通一半取决于前端实现另一半取决于后端约定。跨域是整个过程中最常见也最烦人的问题。前端如果要用自定义请求头比如加Authorization、X-Client-Type后端就必须在Access-Control-Allow-Headers里显式列出这些头否则浏览器会拦截响应前端看到的是请求发出去了但没有返回。另一个约定是错误返回格式。分片上传时错误会出现在两个层面HTTP层错误比如413、500和业务层错误比如“分片大小超过限制”“文件数超过限制”。我要求后端在业务错误时也返回HTTP 4XX并且body里带一个统一的错误结构{ code: CHUNK_LIMIT_EXCEEDED, message: 分片数量超过限制 }这样前端catch到错误后能直接拿到message展示给用户而不是面对一串摸不着头脑的网络状态码。还有上传BaseURL的问题。组件接收url参数但这个url经常是相对路径比如/upload/video。在部署到子目录的项目里前端的baseURL可能带了项目前缀直接把相对路径交给XHR会404。我处理的方式是组件内部把url做一次统一处理如果是相对路径先拼接上全局配置的baseURL再发起请求。这样一个细节能避免很多“本地好好的部署上去就失效”的莫名其妙的问题。5.3 断点续传的边界情况断点续传虽好但有几个边界情况需要处理否则会上线后暴露问题。切换网络的情况用户用4G上传了几个分片切到Wi-Fi后继续。这个情况下已上传的分片还在后端临时目录里XHR的重试逻辑会自动把失败的分片补传整体流程不用变。特殊情况是IP变了之后某些后端安全策略可能要求校验上传者身份导致临时分片目录的归属判断出错——前端解决不了只能和后端约定用文件哈希做分片目录的主人ID而不是用会话ID。系统重启的情况如果用户上传到一半电脑休眠了浏览器里的JS状态全部丢失。用户重新打开页面组件优先读取localStorage里的上传记录再调check接口比对后端已存分片二者取并集就能找到真正需要补传的分片。要注意并集不是交集因为可能存在前端记录里有但后端临时目录被清理了的情况这时要以后端为准重传缺失块。秒传的误判情况不同文件内容完全相同会被判定为同一文件这是哈希的本质特性。MD5冲突的概率极低但如果你对完整性要求很高可以考虑让后端再对比文件大小哈希一致且大小一致才判秒传成功。多一层判断多一分安全。5.4 大文件场景的性能优化最后单独说一些独占大文件性能相关的点。视频上传最怕的不是慢是“把浏览器搞崩”。我第一次在低配测试机上跑1GB视频上传时页面直接白屏打开DevTools看是内存飙升到1.5GB。问题出在哈希计算环节我一开始用了读取整个文件再算哈希的方式1GB全部读进内存当然爆炸。后来改成增量读取2MB小块内存占用降到几十MB问题消失。还有一个容易忽略的性能点上传进度更新太频繁也会造成性能问题。分片并发3个每个分片每秒可能触发几十次progress事件如果每一次都把Vue响应式数据更新一遍页面渲染的压力非常大。解决办法很简单——节流。让进度更新最多每100毫秒一次肉眼完全察觉不到差异页面流畅性会有明显提升。如果视频文件经常超过1GB还可以把哈希计算丢到Web Worker里跑避免阻塞主线程的渲染和交互。我在自己负责的项目里没有做这一步因为主线程算哈希虽然占资源但用户这时候通常在看文件列表不太感知得到。如果你的产品对上传过程的交互体验要求很高建议上Worker实现成本也不算高。我个人在实际操作中的体会是视频上传组件这类东西写一次之后能在很多项目里反复复用但稳定性的核心从来不是UI好看与否而是上传调度层是否做得扎实。把分片、并发、断点续传当成一个严肃的工程问题来处理组件自然不会脆弱。最后再分享一个小技巧组件里可以加一个全局的“上传中离开页面”的确认弹窗通过beforeunload或Vue路由守卫去提示用户能避免很多人辛辛苦苦传到90%误关页面的悲剧。这个逻辑侵入性很低但体验提升非常明显建议保留。 
长河君 · 2026/10/14 20:35:37 · 阅读 1.2k Vue视频上传组件：分片、断点续传与秒传的工程实践
第一次在管理后台里需要做视频上传功能时我图省事直接用了组件库里自带的Upload组件。当时想得很简单视频也就是文件上传不都一样吗结果第一个版本上线没多久问题就集中爆发了——某内容管理平台需要支持运营上传短视频素材单个视频动辄三五百MB有些甚至超过1GB。用Upload组件传大文件几乎必失败快传满了进度条卡在99%不动用户直接投诉到产品那里。后来我花了两天时间把这个功能重构成一个独立的Vue上传视频组件分片、断点续传、秒传、并发控制、失败重试全都安排上用在了三个后台项目里稳定跑了大半年。今天把这些设计思路和踩坑经历整理出来给遇到同样问题的开发者一个参考。这个组件解决的核心问题很简单让大视频文件上传变得可失败、可恢复、可感知。它适合用过Vue但没做过深度上传功能的人也适合在后台项目里被大文件上传折腾过的朋友。下面从思路到实现完整过一遍。1. 为什么视频上传不能直接用现成Upload组件1.1 大文件上传真正的问题是什么视频文件的体积和图片完全不是一个量级。一张压缩过的图片可能几十KB到几MB网络再差也忍忍就过去了。但一段高清培训视频、课程回放、宣传片素材随便就是几百MB起步压完码率也不低。这类大文件用普通的单请求上传会遇到三个绕不开的问题第一服务端和网关的限制。大多数Nginx配置里默认的client_max_body_size只有1MB或者几MB。就算后端专门调大这个值网关层、负载均衡器、云厂商的对象存储预签名URL每一层都有自己的大小限制。你不可能为了一个上传功能把所有中间件的限制都放大这既不安全也不现实。第二网络中断的成本太高。单请求上传意味着整个文件都在一个HTTP连接里传输。公司内网偶尔抖动、会议室切换Wi-Fi、电脑休眠唤醒都可能让连接断开。一旦断开整个视频从头再传用户可以当场崩溃。第三用户看不到细节。单请求上传的进度是“全有或全无”没有一个清晰的中间状态。卡在99%和传到一半毫无区别用户不知道该等还是该重试。所以视频上传不能当普通文件上传处理本质上它需要一套针对大文件的传输策略。业界通用的做法就是分片——把一个大文件切成若干小块逐块上传失败只重传失败的那几块和碎片化下载的道理一样。这也是整个组件的核心设计起点。1.2 现成Upload组件缺少的东西有些朋友可能会说element-plus、antd这些组件库的Upload明明也能传文件还能自定义请求方法看起来挺灵活。这话对了一半。组件库的Upload组件设计定位是“文件的选择与提交”它默认处理的流程是用户选文件、拿到File对象、发一个POST请求、等待响应。你确实可以在beforeUpload里手动切分文件再自己发起分片请求但这样做你会和组件库内部的受控逻辑反复打架状态是组件的进度是组件给的异常分支也是组件定义的。想实现分片批量请求、断点续传、并发控制基本等于绕过组件本身重新写一套那为什么还要用从能力对比上看差距很直接能力项通用Upload组件视频上传组件需要大文件单请求提交支持不合适必须分片分片上传不内置必须内置断点续传刷新后继续不内置建议内置并发控制不提供需要可配置单分片失败重试不提供需要可配置秒传服务端已有文件不提供强烈建议真实传输进度依赖底层XHR必须精确汇总取消与暂停部分支持必须可控表格里列的全是视频上传场景的“刚需”。组件库解决的是80%常规场景而视频上传属于那20%的深水区用通用组件硬顶到了线上就是隐患。另外一个容易被忽略的点视频上传不是一个“发一次请求”的动作而是一个多阶段流程。选文件后要先校验然后算哈希然后询问服务端可不可以秒传服务端说不行就再挨个传分片全部传完了还要触发合并。这个流程需要明确的“状态机”——待处理、哈希计算中、检查中、上传中、暂停中、已完成、已失败。通用Upload组件给不了这种细粒度的状态管理。所以我的结论是视频上传组件值得自己写一次。写成一个独立可复用的组件后续任何项目需要“传大文件”的能力直接拿过去用比反复和组件库API作斗争划算得多。2. 组件的整体设计与参数选择2.1 先把组件里要做的事拆开写这种不算小的功能组件最忌讳的就是把所有逻辑堆在一个.vue文件里。两千行代码挤在一起自己维护都费劲更别说复用了。我在设计时把整个功能拆成了三个层级VideoUploader.vue纯UI层负责文件列表渲染、拖拽区域、进度条、操作按钮不关心任何上传逻辑。useUploader.ts组合式函数层管理上传状态、分片队列、进度汇总、事件对外抛出这是组件和上传核心之间的胶水层。upload-core.ts纯逻辑层负责文件切割、哈希计算、并发调度、XHR请求、重试策略。这一层不依赖Vue理论上任何框架都能用。这样拆的好处很明显如果你不想用我的组件UI也不想用Vue你直接把upload-core拿走去接自己的逻辑也可以如果后端接口有变化只改upload-core组件层完全不用动。分层的同时我还把“组件交互”和“上传调度”从设计上解耦了。比如上传中用户点了取消UI层只是调了一个cancel方法真正的中止逻辑在上传调度器里。组件不会因为用户主动取消、网络断开、分片失败这些情况不知所措因为所有分支都有明确的状态路径。2.2 分片大小和并发数怎么定这两个参数是整个组件里最值得花心思的地方。我见过有人把分片设成1MB好家伙一个500MB的视频要发500个请求后端接收分片的临时目录全是碎文件合并时也慢。也有人一把梭把整个文件切成几个大块每个块200MB断了重传的成本依然很高。我自己用的默认值是分片大小5MB并发数3。分片大小选5MB的逻辑是这样的第一要远小于Nginx和网关的常见大小限制避免触发中间层拦截第二要足够大避免分片数量过多导致请求开销占比过高第三5MB的分片上传时间通常控制在两三秒内失败重试的成本低用户感知不明显。并发数选3理由更简单。浏览器对同一域名的HTTP/1.1连接数限制一般是6个你如果并发拉满6个页面里的其他接口请求就得排队。视频上传这种后台场景页面往往还有列表加载、详情查询、表单提交不能把所有连接都占满。并发3是一个相对平衡的点——上传不算慢页面也不至于卡死。实际代码里这两个参数不是写死的而是作为上传核心的配置项暴露interface UploadOptions { url: string file: File chunkSize?: number // 默认 5 * 1024 * 1024 concurrency?: number // 默认 3 retryCount?: number // 分片失败重试次数默认 3 }如果你的视频本身比较小比如小于50MB走不分片的单请求上传也完全没问题效率还更高。组件里可以加判断文件小于某个阈值时直接整体上传大于阈值时自动切分。这个优化对体验提升其实是感知不强的但能少走后端的分片合并逻辑后端同事会感激你。2.3 为什么必须算文件哈希视频上传组件和普通文件上传最大的区别就在于“重复上传”这个场景。一个几百MB的培训视频可能多个运营都拿到了源文件重复传到后台的情况非常常见。如果每次都完整走一遍分片上传流程服务器白白浪费带宽和存储。所以组件里必须给文件算一个内容指纹——哈希。有了哈希上传流程多了一步“秒传检查”组件把文件的哈希值先发给后端后端查一下库里有没有相同哈希的文件记录如果有直接返回已存在的URL前端显示“秒传成功”一秒都不到。另一个用途是断点续传。断点续传要求前后端对“同一个文件的哪些分片已经上传成功”有一致的判断文件名不可靠因为同名文件内容可能完全不同。唯一可靠的标识就是内容哈希。前端在断点续传时用localStorage把上传过的文件哈希和分片索引记录下来重新打开页面后比对哈希就知道哪些分片不用重新传。技术选型上我用的是spark-md5这个库。它的特点是支持增量哈希计算——不用一次性把整个文件读进内存而是分片读、分片累加最后统一输出完整文件的MD5。这一步对大文件很关键如果直接readAsArrayBuffer读一个1GB的文件浏览器内存分分钟爆掉。哈希计算的代码大致是这样import SparkMD5 from spark-md5 function calculateFileHash(file) { return new Promise((resolve, reject) { const spark new SparkMD5.ArrayBuffer() const reader new FileReader() const chunkSize 2 * 1024 * 1024 let offset 0 const loadNext () { const chunk file.slice(offset, offset chunkSize) reader.readAsArrayBuffer(chunk) } reader.onload (event) { spark.append(event.target.result) offset chunkSize if (offset file.size) { loadNext() } else { resolve(spark.end()) } } reader.onerror () reject(new Error(文件读取失败)) loadNext() }) }这里读取小块用2MB而不是上传分片的5MB是为了让哈希计算的单位更细避免读入内存的数据量过大。整个计算过程是异步的文件大时耗时明显UI上需要显示“计算中”的状态不能让人以为页面卡死了。3. 分片上传与断点续传的代码实现3.1 文件校验与预处理用户选完视频文件之后组件做的第一件事不是急着上传而是做三道校验。第一道是类型校验。组件上设置acceptvideo/*这个只是让文件选择器默认过滤视频格式挡不住用户改成“所有文件”然后选一个非视频文件。所以代码里还需要再确认一遍file.type是否以video开头。需要注意的是file.type在部分浏览器里可能为空字符串比如某些Linux浏览器对特定视频格式识别不了所以还要配合后缀名兜底判断确保.ts、.mp4、.mov、.mkv这些常见格式不会被误拦。第二道是大小校验。每个项目对视频大小的要求不一样组件要暴露一个maxSize属性给业务方配置。超过了就触发error事件在UI上红字提示不进入上传流程。第三道是空文件校验。file.size为0的文件看起来是个视频格式实际上没有任何内容这类文件在最开始就应该被拦掉上传了也是后端合并时出错。预处理阶段还有一个容易被忽略的点URL.createObjectURL生成预览地址。即使视频没有上传用户也需要知道“我选的到底是哪个视频”。通过createObjectURL创建一个指向该File对象的临时URL赋给video标签的src用户就能立即看到视频缩略预览。这个URL要记住在组件卸载或状态重置时通过URL.revokeObjectURL释放否则会有内存泄漏。3.2 分片切割与并发调度校验通过之后就是真正的核心流程。先按配置的分片大小把文件切成一个个独立的数据块function createChunks(file, chunkSize) { const chunks [] let cur 0 while (cur file.size) { chunks.push(file.slice(cur, cur chunkSize)) cur chunkSize } return chunks }File对象的slice方法返回的是一个Blob它不会把文件内容复制到内存里只是记录了一个“文件引用偏移量长度”所以切几百个分片对内存几乎没压力不用惧怕分片数量多。切分完成之后进入并发调度环节。我这里没有引入第三方并发库直接手写了一个简单的并发池。原理很朴素把任务放进队列先启动N个任务每完成一个就从队列里补一个直到全部结束。async function runWithConcurrency(tasks, limit, worker) { const results [] const queue tasks.map((task, index) ({ task, index })).reverse() let activeCount 0 return new Promise((resolve, reject) { const startNext () { if (queue.length 0 activeCount 0) { resolve(results) return } while (activeCount limit queue.length 0) { const { task, index } queue.pop() activeCount worker(task, index) .then((result) { results[index] result activeCount-- startNext() }) .catch((err) { activeCount-- reject(err) }) } } startNext() }) }这个并发池不复杂但胜在可控。每个分片的上传请求包装成一个返回Promise的任务失败时可以重试重试仍然失败就把错误抛出去中止整个上传。分片上传请求本身用的是XMLHttpRequest不是fetch。原因很简单fetch直到现在也没有原生的上传进度事件要拿上传进度只能自己用流去模拟成本不值。XHR的upload.onprogress事件用起来干净利落。3.3 分片请求与整体进度计算每个分片的请求函数如下function uploadChunk({ url, fileHash, index, chunk, fileName, totalChunks, onProgress }) { return new Promise((resolve, reject) { const formData new FormData() formData.append(file, chunk, ${fileHash}_${index}) formData.append(hash, fileHash) formData.append(index, index) formData.append(totalChunks, totalChunks) formData.append(fileName, fileName) const xhr new XMLHttpRequest() xhr.open(POST, url) xhr.upload.onprogress (e) { if (e.lengthComputable) { onProgress(e.loaded / e.total) } } xhr.onload () { if (xhr.status 200 xhr.status 300) { resolve(xhr.responseText) } else { reject(new Error(分片${index}上传失败状态码${xhr.status})) } } xhr.onerror () reject(new Error(网络异常)) xhr.send(formData) }) }formData里带上fileHash、index、totalChunks这些字段是为了让后端能够按哈希建目录、记录分片序号、合并时按顺序拼接。这里有一个后端协作的前提后端接口必须支持分片参数并且在合并前把所有分片严格按index排序。分片并发上传时到达顺序是乱的后端合并前不排序生成的视频就会出现花屏、跳帧、文件头损坏这类诡异问题。整体进度的计算比单个分片麻烦。很多组件的进度条都会出现“前90%很快、最后10%卡半天”的怪象就是因为只算了当前分片的进度没有算总体。我采用的公式是总体进度 (已成功分片总数 当前正在上传分片的已传输占比之和) / 总分片数实现上每次某个分片触发onprogress就重新汇总一次所有分片的状态把结果刷到进度上。这个计算频率可能很频繁所以我把它包了一层节流保证一秒钟最多刷新十次UI避免过度渲染。3.4 秒传与断点续传的落地秒传和断点续传的实现是一对孪生兄弟都依赖文件哈希作为索引。上传前组件先向后端的check接口发一个请求参数就是文件的哈希const checkResponse await fetch(/api/video/check, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ hash: fileHash }) }) const checkData await checkResponse.json()后端返回的可能是三种情况文件已存在返回带url的对象前端直接进入“已存在”状态不发起任何分片请求。文件不存在但已有部分分片返回已上传分片的index数组前端跳过这些分片只上传缺失的。文件不存在、没有任何分片返回空数组前端从第0个分片开始。第二种情况的妙处在于它不仅支持“前端主动断点续传”还支持“前端不知道之前传过但后端知道”。哪怕用户换了一台电脑、换了浏览器、清空了localStorage只要后端临时目录里还留着一部分分片就能从断点继续。前端的本地记录也要做。我维护了一个Map结构key是文件哈希value是已成功分片的index数组同时把这份映射持久化到localStoragefunction saveUploadRecord(fileHash, chunkIndex) { const key video-upload:${fileHash} const record JSON.parse(localStorage.getItem(key) || []) if (!record.includes(chunkIndex)) { record.push(chunkIndex) localStorage.setItem(key, JSON.stringify(record)) } }每次分片上传成功就更新一下localStorage。用户刷新页面后组件发现本地有记录就可以把已存在的分片直接标记为完成。需要注意localStorage的容量有限record数组如果太长要压缩控制阈值为每5个分片记一条连续范围而不是每个index都单独存。500个分片全存数组虽然通常也够但没必要。所有分片传完之后组件再发一个merge请求const mergeResponse await fetch(/api/video/merge, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ hash: fileHash, fileName: file.name }) })后端收到merge请求后找到该哈希对应的临时分片目录按index顺序将所有分片拼接成一个完整视频文件写入正式存储路径。合并完成后返回视频的访问URL组件拿到这个URL更新自己的最终状态。4. 封装成Vue组件后的接入体验4.1 props和事件怎么设计组件最终要给别人用API设计得好不好会直接决定它有没有复用价值。我在设计props时尽量遵循“少而明确”的原则——组件不应该知道业务细节但业务方应该能控制所有关键行为。属性类型默认值说明urlstring必填上传接口地址chunkSizenumber5242880分片大小单位字节concurrencynumber3同时上传的分片数maxSizenumber2GB允许上传的最大文件大小acceptstringvideo/*可接受的文件类型autoUploadbooleantrue选完文件后是否立即开始上传disabledbooleanfalse是否禁用上传交互事件方面我定义了一组语义明确的事件名change文件列表发生变化时触发参数是当前所有File对象。start上传正式开始参数是文件的初始信息和目标URL。progress上传进度更新参数是0到1的进度值。success单个文件上传成功参数是最终的视频URL和文件信息。error单个文件上传失败参数是Error对象。cancel用户点击取消上传时触发。这里我坚持不用v-model去绑定一个文件对象。原因在于文件上传的流程太长状态变量太多一个v-model根本表达不了“上传中”“失败”“已暂停”“秒传成功”这些状态。用事件辐射出去业务方自己在父组件里按照需求接逻辑反而更灵活。4.2 模板结构和交互细节组件模板里分了几块区域拖拽选择区、文件列表区、操作区。拖拽区的逻辑比较固定监听dragover和drop事件dragover时把isDragging置为true给容器加一个高亮边框drop时用event.dataTransfer.files取出文件列表。需要注意拖拽时的事件对象里拿到的是DataTransfer对象不是File对象数组要转一下。文件列表区使用v-for渲染当前所有待上传和上传中的文件每个文件项展示的信息包括文件名、文件大小、当前状态、进度条、操作按钮。上传中显示进度条和取消按钮失败状态显示重试按钮和错误原因成功状态显示视频链接和“重新选择”按钮。一个值得提到的细节进度条组件我用的是原生div自己画的没有引UI库。原因很简单视频上传组件在某些项目里可能搭配不同的UI框架如果组件内部硬编码绑定某个UI库的进度条组件换项目就要换依赖。自己画一个二十行的进度条非常容易换来的是组件完全中立这一点在我看来很值。4.3 与业务表单配合的细节视频上传组件很少是一个孤立页面更多时候是嵌在内容发布表单里的一个字段——发布课程需要传课程视频发布动态需要传封面视频。表单里最常见的问题是用户还没传完视频就点了提交按钮。所以useUploader里要暴露一个isUploading的响应式状态业务方把它接进表单校验逻辑const { files, isUploading, uploadProgress, startUpload, cancelUpload } useUploader()在业务页面的提交方法里校验isUploading是否为false不为false就提示“视频上传中请稍候”。如果视频上传失败还要阻止表单提交否则发布出去的内容会是一个坏链。还有一类场景业务方需要把上传结果塞到提交给后端的表单数据里。做法是在success事件里捕获返回的URL存入表单state。视频还没传完时URL字段为空提交前校验一下即可。这样设计后上传组件和表单的关系就清晰了——组件只负责把视频安全地传到服务器拿到URL交给你剩下业务逻辑由业务方自己编排。5. 常见问题排查与避坑实录5.1 问题速查表把我在实际项目里遇到的典型问题列成一张表方便排查现象可能原因处理方式进度条卡在某个百分比不动分片请求失败但没重试网络断了哈希计算阻塞UI检查重试逻辑是否生效查看Network面板确认是否有请求挂起视频传完后无法播放后端合并分片时没按index排序分片文件类型丢失确认合并逻辑里index必须升序排列formData里的file字段保持原有Blob接口跨域报错后端未配置CORS自定义请求头未加入允许列表OPTIONS预检请求必须有正常响应Access-Control-Allow-Headers要包含自定义头秒传一直不生效哈希计算错误本地记录和服务器记录不一致文件内容确实不同用同一文件分别计算两次哈希对比检查check接口的参数名是否对齐刷新页面后断点续传失败后端临时分片目录被清理localStorage里记录的index和服务器不一致确认后端临时目录过期时间check接口返回的已传分片列表优先于本地记录上传大视频时页面卡死一次性读取整个文件计算哈希分片请求过多导致渲染线程压力大使用增量哈希计算进度更新节流必要时把哈希计算挪到Web Worker组件上传成功但业务拿不到URLsuccess事件的参数结构没对应上后端回包URL字段名不对和后端对齐回包格式在success事件里打印原始响应体排查5.2 后端协作的几个关键约定前端把分片上传做出来了但整个流程能不能跑通一半取决于前端实现另一半取决于后端约定。跨域是整个过程中最常见也最烦人的问题。前端如果要用自定义请求头比如加Authorization、X-Client-Type后端就必须在Access-Control-Allow-Headers里显式列出这些头否则浏览器会拦截响应前端看到的是请求发出去了但没有返回。另一个约定是错误返回格式。分片上传时错误会出现在两个层面HTTP层错误比如413、500和业务层错误比如“分片大小超过限制”“文件数超过限制”。我要求后端在业务错误时也返回HTTP 4XX并且body里带一个统一的错误结构{ code: CHUNK_LIMIT_EXCEEDED, message: 分片数量超过限制 }这样前端catch到错误后能直接拿到message展示给用户而不是面对一串摸不着头脑的网络状态码。还有上传BaseURL的问题。组件接收url参数但这个url经常是相对路径比如/upload/video。在部署到子目录的项目里前端的baseURL可能带了项目前缀直接把相对路径交给XHR会404。我处理的方式是组件内部把url做一次统一处理如果是相对路径先拼接上全局配置的baseURL再发起请求。这样一个细节能避免很多“本地好好的部署上去就失效”的莫名其妙的问题。5.3 断点续传的边界情况断点续传虽好但有几个边界情况需要处理否则会上线后暴露问题。切换网络的情况用户用4G上传了几个分片切到Wi-Fi后继续。这个情况下已上传的分片还在后端临时目录里XHR的重试逻辑会自动把失败的分片补传整体流程不用变。特殊情况是IP变了之后某些后端安全策略可能要求校验上传者身份导致临时分片目录的归属判断出错——前端解决不了只能和后端约定用文件哈希做分片目录的主人ID而不是用会话ID。系统重启的情况如果用户上传到一半电脑休眠了浏览器里的JS状态全部丢失。用户重新打开页面组件优先读取localStorage里的上传记录再调check接口比对后端已存分片二者取并集就能找到真正需要补传的分片。要注意并集不是交集因为可能存在前端记录里有但后端临时目录被清理了的情况这时要以后端为准重传缺失块。秒传的误判情况不同文件内容完全相同会被判定为同一文件这是哈希的本质特性。MD5冲突的概率极低但如果你对完整性要求很高可以考虑让后端再对比文件大小哈希一致且大小一致才判秒传成功。多一层判断多一分安全。5.4 大文件场景的性能优化最后单独说一些独占大文件性能相关的点。视频上传最怕的不是慢是“把浏览器搞崩”。我第一次在低配测试机上跑1GB视频上传时页面直接白屏打开DevTools看是内存飙升到1.5GB。问题出在哈希计算环节我一开始用了读取整个文件再算哈希的方式1GB全部读进内存当然爆炸。后来改成增量读取2MB小块内存占用降到几十MB问题消失。还有一个容易忽略的性能点上传进度更新太频繁也会造成性能问题。分片并发3个每个分片每秒可能触发几十次progress事件如果每一次都把Vue响应式数据更新一遍页面渲染的压力非常大。解决办法很简单——节流。让进度更新最多每100毫秒一次肉眼完全察觉不到差异页面流畅性会有明显提升。如果视频文件经常超过1GB还可以把哈希计算丢到Web Worker里跑避免阻塞主线程的渲染和交互。我在自己负责的项目里没有做这一步因为主线程算哈希虽然占资源但用户这时候通常在看文件列表不太感知得到。如果你的产品对上传过程的交互体验要求很高建议上Worker实现成本也不算高。我个人在实际操作中的体会是视频上传组件这类东西写一次之后能在很多项目里反复复用但稳定性的核心从来不是UI好看与否而是上传调度层是否做得扎实。把分片、并发、断点续传当成一个严肃的工程问题来处理组件自然不会脆弱。最后再分享一个小技巧组件里可以加一个全局的“上传中离开页面”的确认弹窗通过beforeunload或Vue路由守卫去提示用户能避免很多人辛辛苦苦传到90%误关页面的悲剧。这个逻辑侵入性很低但体验提升非常明显建议保留。