做前端时间久了基本上都会遇到“大文件上传”这个需求。小文件用input typefile配合 axios 一把梭就行但一旦文件超过几百 MB甚至到了几个 G问题就全冒出来了内存暴涨、请求超时、断网白传、后端收不到完整数据。我见过太多团队在这种需求上反复踩坑所以干脆把 vue 大文件上传这块的选型和落地细节一次讲透。这篇文章我会从开源代码和商业应用两个方向做对比分析重点讲清楚分片上传、断点续传、秒传这些核心概念的实现原理也会把我在实际项目中用过的方案、调过的参数、踩过的坑全部放出来。不管你是刚接触 vue 前端开发的新手还是正在做技术选型的团队负责人应该都能从里面找到可以直接抄作业的结论。1. 大文件上传到底难在哪先别急着挑框架和库。很多项目失败不是方案不好而是根本没搞清楚大文件上传这个需求真正的难点在哪里。1.1 不是“上传”难是“重传”难普通的 HTTP 上传本质上是把整个文件作为请求体发给服务器。前端这边浏览器会把文件读进内存然后通过网络传输。对于几十 MB 的小文件这完全没问题但文件一大麻烦就来了。首先是内存压力。浏览器读取一个 2GB 的文件到内存再转换成二进制流发出去这个过程对普通电脑来说已经接近极限。其次是网络稳定性。公网环境下任何一次网络抖动、路由器重启、服务器超时都可能导致整个请求失败。如果是整文件上传失败之后只能从头再来。传了 40 分钟的视频最后 1 秒断网前面全部白干这种体验放到产品里就是事故。所以大文件上传的核心不是怎么把文件传上去而是传了一半断了怎么花最小代价续上。这就催生了两个关键技术分片上传和断点续传。分片是把大文件切成若干小块分别上传断点续传是记录哪些分片已经上传成功下次只传缺失的部分。1.2 三个经典崩溃现场在我接触过的项目里有几个崩溃场景非常典型基本每个团队都会遇到。第一个是后端报 413。文件传到一半nginx 直接返回 Request Entity Too Large。很多新手不知道 nginx 默认对请求体大小有限制通常是 1MB不调client_max_body_size整个上传就是废的。第二个是进度条卡在 99%。文件本身的请求其实已经发完了但因为后端还在处理合并逻辑前端拿到的响应还没返回界面就一直转圈。用户等不及直接关掉页面服务端合并到一半的文件就变成了脏数据。第三个是并发上传分片时浏览器直接卡死。这个通常是因为分片切太小、同时发太多请求把浏览器的连接池和内存都打满了。我见过有人把 1GB 文件切成 1MB 分片然后 20 个并发同时传页面直接白屏。这些场景说明大文件上传不是简单换个库就能解决需要从架构上理解它的整体流程。2. 开源方案横评四个主流选项的真实表现如果决定自建整套上传链路vue 生态里其实有不少开源代码可以借鉴或者直接集成。下面这几个是我实际用过或者深入看过的方案。2.1 vue-simple-uploader分片上传的“瑞士军刀”这个库在 vue 圈子里知名度很高底层基于 simple-uploader.js。它把分片上传、断点续传、秒传、并发控制这些能力都封装好了支持 vue2 和 vue3。你只需要引入组件配置一下上传地址和分片参数就能快速跑通一条完整的上传链路。我比较喜欢它的一点是它内置了spark-md5的 hash 计算逻辑。秒传功能的思路是前端算文件的唯一指纹服务器发现这个指纹已经存在就直接返回你已经传过了不用重复上传。这个库在 UI 层面也提供了现成的组件比如文件列表、进度条、拖拽上传区域但它们都偏基础真实项目里大概率要自己二次开发。用它的过程中有两点要注意。第一是它默认会使用web-worker计算 hash但 worker 的加载路径如果配不对在 production 环境会报错。第二是它的后端口不是现成的Java、Go、Node 业务方得按simple-uploader的协议实现接收分片、合并分片的接口前端和联调成本没有省掉。2.2 uppy大而全的现代方案uppy 是 Transloadit 团队维护的现代上传库目前也已经支持 vue 封装。它的特点是非常大而全从本地文件选择、拖拽、剪贴板粘贴到远程 URL 抓取、云盘导入、摄像头拍摄几乎你能想到的上传入口都有插件支持。真正让它适合大文件场景的是它对 tus 协议的支持。tus 是一个开放的上传协议核心优势是可恢复性。它通过标准化的 PATCH 请求实现断点续传前端断网之后重新打开页面可以随时接着上次的进度传不需要自己设计一套续传逻辑。服务端只要实现了 tus 规范就能和前端的 upyun、transloadit 这类客户端直接配合。但 uppy 的问题也很明显它太重了。默认引入整个包的话首屏加载体积大得离谱。你需要配合uppy/core按需引用各种插件对构建配置有一定要求。如果你只想要一个分片上传组件用它完全是杀鸡用牛刀。不过如果你的产品有非常丰富的上传场景比如用户可能从微信、钉钉、网页各个渠道传文件uppy 的生态能帮你省很多自己造轮子的精力。2.3 resumable.js 和 jQuery-File-Upload轻量派的取舍resumable.js 是这个领域的老前辈了很多国产开源分片组件都是基于它改的。它只做分片和断点续传两件事API 也很干净。但在现代 vue 项目里用它需要自己包一层 vue 组件还要自己处理 UI 状态适合那种我就想要一个纯逻辑UI 全自己画的项目。jQuery-File-Upload 则是更远古的方案。虽然它当年在各种后台管理系统里非常流行但现在已经不太建议在新项目里用了它绑定 jQuery 生态对现代打包工具和 vue 的组合式 API 支持都不友好。从选型角度看轻量派适合规模小、业务认知清晰、团队有足够精力做 UI 定制的场景。如果你希望后端同事不要被复杂协议折腾也可以考虑只用它作为前端组件让后端只负责接收分片。2.4 自研分片 Web Worker完全可控的硬核路线如果前面这些库都满足不了你的定制需求可以走自研路线。自研的核心就是自己用File.prototype.slice()把文件切成若干 Blob然后逐个上传。配合 vue 的组合式 API可以很优雅地组织这段逻辑。第一个核心点是计算 hash。文件切完后你需要前端算一个全局唯一标识。纯主线程算大文件 hash 会卡住 UI所以要用 worker。vue 项目里可以用new Worker(new URL(./hash-worker.js, import.meta.url), { type: module })这种方式加载 worker避免把 worker 脚本打得乱七八糟。第二个核心点是并发控制。不能把全部分片一次性发出去要维护一个并发池比如同时最多 3~5 个请求在跑。可以用 p-limit 这类库也可以手写一个计数器加队列。第三个核心点是断点续传的持久化。最简单的方式是每上传完一个分片就把分片序号存到 localStorage。下次选择同一个文件时先算 hash然后从 localStorage 里读取已上传分片列表只上传剩下的部分。自研方案的优势是完全可控从 UI 到协议都能贴合自己的后端团队。但代价是开发周期长细节多尤其是并发、重试、合并这些逻辑处理不好很容易出 bug。3. 商业产品怎么解决大文件上传了解完开源方案再看商业应用。其实现在很多大型系统、toB 产品里大文件上传已经不是靠纯开源代码硬扛了而是直接购买商业服务或者使用云厂商的成熟方案。3.1 对象存储 服务商 SDK最务实的商业路径阿里云 OSS、腾讯云 COS、七牛云 Kodo、又拍云这些对象存储服务基本都有前端 SDK而且全部支持分片上传和断点续传。核心流程是先调用后端接口获取一个临时上传凭证然后前端直接用 SDK 直传文件到对象存储服务端只是鉴权不经过自己的应用服务器。这种方案的好处显而易见。第一服务端不用写文件接收和合并接口省掉了大量 IO 操作。第二断点续传、并发控制、秒传都是 SDK 内置的稳定性和性能已经经过线上大规模验证。第三对象存储本身自带 CDN上传完成后可以直接生成下载链接还要自己搭一套文件服务。我实际接过的几个项目里用的都是类似流程前端发起请求获取 STS token然后使用 SDK 实例化上传器监听分片上传进度。整个过程代码量不大主要精力花在 token 的过期管理和错误处理上。不过商业方案也不是没有门槛。最直接的门槛是预算。存储费、流量费、API 请求次数这些费用在文件量大的时候会非常可观。尤其是视频类产品动辄几十 GB 的单个资源如果 CDN 回源流量没控制好月底账单会吓人一跳。3.2 私有化部署场景下的商业化选择很多企业的数据是不能出内网的或者出于合规要求必须资产评估本地这时没法用公有云对象存储。在私有化场景下比较流行的做法是部署一套 MinIO 或者 SeaweedFS这些系统兼容 S3 协议前端可以直接用 AWS S3 SDK 的 JavaScript 版本做直传。使用 S3 SDK 做分片上传核心是通过 Multipart Upload 接口。前端拿到预签名的 URL 后调用 createMultipartUpload、uploadPart、completeMultipartUpload 三个接口完成整条链路。这种方式的优势是协议标准化换任何一家兼容 S3 的对象存储都能无缝切换。私有化部署的另一条路是直接购买商业软件比如各种企业网盘系统和企业协作平台。它们把大文件上传、预览、版本管理都做成开箱即用的能力前端只需要嵌入它的上传组件或者调用它的开放 API。对业务团队来说前期投入较大但对非技术密集型公司来说稳定性和支持服务是更有保障的。3.3 商业方案和开源方案的成本账很多人一听到商业就觉得贵但这笔账算下来不一定。开源方案看起来不花钱但隐形成本很高。文件存储要自建服务器带宽要买大规格的后端要投入人力维护分片合并逻辑还要处理并发、脏数据、磁盘占满等问题。一旦线上出现上传失败、文件损坏、服务器磁盘告急都需要有人工介入排查。商业方案的费用结构很清晰存储 流量 请求数 必要的增值服务。对于中小团队特别是没有专职后端或者后端资源稀缺的团队每个月花几百块钱买对象存储换来的是极低的上传失败率和极高的开发效率这个性价比其实是划算的。如果公司有运维能力又不想受制于人也可以用开源对象存储做私有化再搭配一些商业 API 网关或者 CDN 能力也就是混合方案。关键还是要结合团队规模和业务量来做综合评估。4. 分片上传核心原理与实测参数不管最后选了哪条路线作为前端理解分片上传的底层原理都特别重要。很多配套参数不是乱调的要根据实际场景来定。4.1 分片大小到底怎么定分片大小并不是固定的。我自己的经验是100MB 以下的小文件不需要分片直接整体上传就行分片反而因为额外请求带来性能损失。1GB 以上的文件分片大小建议设置在 5MB 到 20MB 之间。假设一个 2GB 的文件如果你切 5MB会有 410 个分片。每个分片从上传到服务端确认都需要一次 HTTP 往返。分片太小请求数量太多服务端的接口压力大前端也要维护很长的分片状态列表。分片太大呢每传一片耗时太长中途断网损失就很大而且服务端接收内存缓冲区也要扩大。我常用的一个折中方案是2GB 文件用 10MB 分片也就是 205 片并发数控制在 3~5。这样既不会因为分片太多造成请求过多也不会因为单片太大导致失败重传成本高。关于并发数也要特别说一句。浏览器对同一域名的连接数是有限制的HTTP/1.1 下通常是 6 个左右。如果你开 10 个并发很多请求实际都在排队并不会真的更快反而可能因为 TCP 连接相互争抢带宽让整体上传更慢。所以并发数不是越多越好3~5 是我实测下来比较稳定的区间。4.2 断点续传和数据完整性校验断点续传的核心是记录和恢复。记录什么记录哪些分片已经传成功了。恢复怎么做下次选择同一个文件时先计算整个文件的 hash去服务端查一下这个 hash 对应的上传任务存在不存在存在的话已传分片是哪些然后只上传缺失的。这个 hash 计算很多人直接用 MD5但要注意 MD5 的碰撞风险在超大文件场景下是存在的。如果对完整性要求很高可以用 SHA-1 或者做抽样 hash 整体 hash 的双重校验。不过说实话只做秒传的话MD5 配合文件大小已经能覆盖绝大多数场景。分片上传完之后服务端需要合并。合并的接口一般会接收一个上传任务的 ID然后后端按分片序号把临时文件拼起来最后对合并后的文件做一次 hash 校验和前端提交的 hash 比对一致才算真正上传成功。这一步我强烈建议保留不然很容易出现文件损坏。前端在进度条方面也要注意。整体进度计算的公式是已经上传的分片数 / 总分片数 * 100%而不是直接拿单个请求的 loaded/total因为分片大小可能不统一最后一片往往是多余的。用“分片个数”计算逻辑简单而且准确。5. 双端联调与常见问题排查大文件上传是前后端共同协作的产物联调阶段最容易暴露问题。我在项目里排查过太多上传问题整理一些高频坑出来。5.1 后端接收分片要注意什么后端如果走自研接口最容易被坑的就是临时文件管理。我在后端排查问题时发现很多上传任务失败不是传输环节挂了而是服务器磁盘上塞满了来不及合并的临时分片。建议后端给每个上传任务建独立目录定期清理超时的临时目录。合并时也要注意性能。最差的做法是把所有分片数据 append 到一个文件里这样每片都要打开文件、移动指针、写入对机械磁盘是灾难。好一点的做法是先把分片写到一个临时文件中合并时直接用流式拼接或者干脆在上传每个分片时把数据追加到同一个目标文件流里最后只做完整性校验。另外nginx 的反向代理层也要配置好。虽然分片上传请求的 body 不大但合并接口一次要处理的可能是完整的文件元数据如果自定义 headers 过多也可能突破默认的请求头大小限制。5.2 前端常见问题速查表我把平时被问得最多的几个问题整理成一个速查表希望对排查问题有帮助。现象可能原因解决办法上传后 nginx 返回 413client_max_body_size 未设置或过小在 nginx 配置里调整 client_max_body_size分片请求和合并接口各自设置合理值大文件上传主线程卡死hash 计算在主线程执行改用 Web Worker 计算 hash避免阻塞渲染断点续传失效重新上传从头开始localStorage 被清空或 hash 不一致将上传任务 ID 和已传分片列表保存到服务端前端优先从服务端获取上传进度条跳到 100% 后又变回 80%整体进度计算方式错误分片请求使用已上传分片数/总分片数计算进度合并阶段单独展示浏览器内存暴涨、页面卡顿没有用 Blob.slice 做分片读取而是把整个文件读进内存确认前端是基于 Blob 切片上传而不是 FileReader 全量读取并发上传总是失败并发数太高TCP 连接竞争严重把并发数调小到 3~5并增加请求失败重试机制这个小表格是我在实际项目里常看的很多时候问题不是某个库不行而是使用姿势不对。5.3 使用开源库常见坑选开源库一定不能光看 star 数量要看维护情况和社区活跃度。vue-simple-uploader 早期版本对 vite 的支持有问题需要手动 external 一些依赖uppy 版本更新快但 API 变化也频繁锁版本很重要。如果你用 Web Worker 计算 hash还要注意 worker 脚本的前端公共路径。vue-cli 打包默认把 worker 文件作为独立资源但如果部署后访问路径变了比如放在 CDN 子目录下worker 加载就会失败。建议用相对路径或者动态 import 的方式加载 worker 脚本。还有一点就是现在很多浏览器已经支持navigator.storage.estimate()接口来估算存储空间但断点续传的持久化主要还是靠 localStorage。localStorage 有 5MB 左右的限制如果你记录的分片列表太长或者文件特别多有可能会溢出。解决办法就是只记录必要的上传任务 ID 和最新进度不要把整个文件列表塞进去。6. 选型建议什么时候该用什么方案聊了这么多最后把这几年总结的选型逻辑拎出来说说。先看团队规模和业务属性。如果你是个人开发者或者创业团队没有专职后端直接上商业对象存储 SDK 是效率最高的选择省心又稳定。次选是找成熟的开源组件比如 vue-simple-uploader把后端的接收方案定规范。如果公司要求数据必须完全内网或者法定环境不能上公有云那就得走私有化部署。这时候再分两条线不想折腾直接买商业软件或企业网盘愿意投入就部署 MinIO自己写点服务端代码。如果是大型 toB 项目上传的文件特别大例如几十 GB 的视频素材、设计源文件那就要考虑多节点存储和 CDN 回源加速的问题不是简单一个组件能解决的建议先评估商业传输加速方案再做开源二次开发。从我在实际项目中的体会来看没有哪个方案是银弹。开源代码给你自由度商业应用给你稳定和效率关键是想清楚团队现有的人力、预算和业务的稳定要求。自己从零造轮子之前先问一个特别朴素的问题这个文件真的需要分片上传吗如果只是偶尔传个两三百 MB 的文件直接调大 nginx 限制、设置长超时反而更省事。分片上传解决的是”频繁、大、不稳定环境“下的体验问题不是所有上传场景都必须上它的。最后再分享一个小技巧。不管用哪个方案测试阶段一定要在开发者工具里开启网络节流选一个 3G/慢速网络的配置然后传一个 1GB 以上的文件把暂停、断网、切换网络、关页面重新打开这几条路径全部走一遍。大部分问题会在这一步暴露出来比上线后等用户报错要舒服得多。
Vue大文件上传完全指南：分片、续传与商业方案选型
做前端时间久了基本上都会遇到“大文件上传”这个需求。小文件用input typefile配合 axios 一把梭就行但一旦文件超过几百 MB甚至到了几个 G问题就全冒出来了内存暴涨、请求超时、断网白传、后端收不到完整数据。我见过太多团队在这种需求上反复踩坑所以干脆把 vue 大文件上传这块的选型和落地细节一次讲透。这篇文章我会从开源代码和商业应用两个方向做对比分析重点讲清楚分片上传、断点续传、秒传这些核心概念的实现原理也会把我在实际项目中用过的方案、调过的参数、踩过的坑全部放出来。不管你是刚接触 vue 前端开发的新手还是正在做技术选型的团队负责人应该都能从里面找到可以直接抄作业的结论。1. 大文件上传到底难在哪先别急着挑框架和库。很多项目失败不是方案不好而是根本没搞清楚大文件上传这个需求真正的难点在哪里。1.1 不是“上传”难是“重传”难普通的 HTTP 上传本质上是把整个文件作为请求体发给服务器。前端这边浏览器会把文件读进内存然后通过网络传输。对于几十 MB 的小文件这完全没问题但文件一大麻烦就来了。首先是内存压力。浏览器读取一个 2GB 的文件到内存再转换成二进制流发出去这个过程对普通电脑来说已经接近极限。其次是网络稳定性。公网环境下任何一次网络抖动、路由器重启、服务器超时都可能导致整个请求失败。如果是整文件上传失败之后只能从头再来。传了 40 分钟的视频最后 1 秒断网前面全部白干这种体验放到产品里就是事故。所以大文件上传的核心不是怎么把文件传上去而是传了一半断了怎么花最小代价续上。这就催生了两个关键技术分片上传和断点续传。分片是把大文件切成若干小块分别上传断点续传是记录哪些分片已经上传成功下次只传缺失的部分。1.2 三个经典崩溃现场在我接触过的项目里有几个崩溃场景非常典型基本每个团队都会遇到。第一个是后端报 413。文件传到一半nginx 直接返回 Request Entity Too Large。很多新手不知道 nginx 默认对请求体大小有限制通常是 1MB不调client_max_body_size整个上传就是废的。第二个是进度条卡在 99%。文件本身的请求其实已经发完了但因为后端还在处理合并逻辑前端拿到的响应还没返回界面就一直转圈。用户等不及直接关掉页面服务端合并到一半的文件就变成了脏数据。第三个是并发上传分片时浏览器直接卡死。这个通常是因为分片切太小、同时发太多请求把浏览器的连接池和内存都打满了。我见过有人把 1GB 文件切成 1MB 分片然后 20 个并发同时传页面直接白屏。这些场景说明大文件上传不是简单换个库就能解决需要从架构上理解它的整体流程。2. 开源方案横评四个主流选项的真实表现如果决定自建整套上传链路vue 生态里其实有不少开源代码可以借鉴或者直接集成。下面这几个是我实际用过或者深入看过的方案。2.1 vue-simple-uploader分片上传的“瑞士军刀”这个库在 vue 圈子里知名度很高底层基于 simple-uploader.js。它把分片上传、断点续传、秒传、并发控制这些能力都封装好了支持 vue2 和 vue3。你只需要引入组件配置一下上传地址和分片参数就能快速跑通一条完整的上传链路。我比较喜欢它的一点是它内置了spark-md5的 hash 计算逻辑。秒传功能的思路是前端算文件的唯一指纹服务器发现这个指纹已经存在就直接返回你已经传过了不用重复上传。这个库在 UI 层面也提供了现成的组件比如文件列表、进度条、拖拽上传区域但它们都偏基础真实项目里大概率要自己二次开发。用它的过程中有两点要注意。第一是它默认会使用web-worker计算 hash但 worker 的加载路径如果配不对在 production 环境会报错。第二是它的后端口不是现成的Java、Go、Node 业务方得按simple-uploader的协议实现接收分片、合并分片的接口前端和联调成本没有省掉。2.2 uppy大而全的现代方案uppy 是 Transloadit 团队维护的现代上传库目前也已经支持 vue 封装。它的特点是非常大而全从本地文件选择、拖拽、剪贴板粘贴到远程 URL 抓取、云盘导入、摄像头拍摄几乎你能想到的上传入口都有插件支持。真正让它适合大文件场景的是它对 tus 协议的支持。tus 是一个开放的上传协议核心优势是可恢复性。它通过标准化的 PATCH 请求实现断点续传前端断网之后重新打开页面可以随时接着上次的进度传不需要自己设计一套续传逻辑。服务端只要实现了 tus 规范就能和前端的 upyun、transloadit 这类客户端直接配合。但 uppy 的问题也很明显它太重了。默认引入整个包的话首屏加载体积大得离谱。你需要配合uppy/core按需引用各种插件对构建配置有一定要求。如果你只想要一个分片上传组件用它完全是杀鸡用牛刀。不过如果你的产品有非常丰富的上传场景比如用户可能从微信、钉钉、网页各个渠道传文件uppy 的生态能帮你省很多自己造轮子的精力。2.3 resumable.js 和 jQuery-File-Upload轻量派的取舍resumable.js 是这个领域的老前辈了很多国产开源分片组件都是基于它改的。它只做分片和断点续传两件事API 也很干净。但在现代 vue 项目里用它需要自己包一层 vue 组件还要自己处理 UI 状态适合那种我就想要一个纯逻辑UI 全自己画的项目。jQuery-File-Upload 则是更远古的方案。虽然它当年在各种后台管理系统里非常流行但现在已经不太建议在新项目里用了它绑定 jQuery 生态对现代打包工具和 vue 的组合式 API 支持都不友好。从选型角度看轻量派适合规模小、业务认知清晰、团队有足够精力做 UI 定制的场景。如果你希望后端同事不要被复杂协议折腾也可以考虑只用它作为前端组件让后端只负责接收分片。2.4 自研分片 Web Worker完全可控的硬核路线如果前面这些库都满足不了你的定制需求可以走自研路线。自研的核心就是自己用File.prototype.slice()把文件切成若干 Blob然后逐个上传。配合 vue 的组合式 API可以很优雅地组织这段逻辑。第一个核心点是计算 hash。文件切完后你需要前端算一个全局唯一标识。纯主线程算大文件 hash 会卡住 UI所以要用 worker。vue 项目里可以用new Worker(new URL(./hash-worker.js, import.meta.url), { type: module })这种方式加载 worker避免把 worker 脚本打得乱七八糟。第二个核心点是并发控制。不能把全部分片一次性发出去要维护一个并发池比如同时最多 3~5 个请求在跑。可以用 p-limit 这类库也可以手写一个计数器加队列。第三个核心点是断点续传的持久化。最简单的方式是每上传完一个分片就把分片序号存到 localStorage。下次选择同一个文件时先算 hash然后从 localStorage 里读取已上传分片列表只上传剩下的部分。自研方案的优势是完全可控从 UI 到协议都能贴合自己的后端团队。但代价是开发周期长细节多尤其是并发、重试、合并这些逻辑处理不好很容易出 bug。3. 商业产品怎么解决大文件上传了解完开源方案再看商业应用。其实现在很多大型系统、toB 产品里大文件上传已经不是靠纯开源代码硬扛了而是直接购买商业服务或者使用云厂商的成熟方案。3.1 对象存储 服务商 SDK最务实的商业路径阿里云 OSS、腾讯云 COS、七牛云 Kodo、又拍云这些对象存储服务基本都有前端 SDK而且全部支持分片上传和断点续传。核心流程是先调用后端接口获取一个临时上传凭证然后前端直接用 SDK 直传文件到对象存储服务端只是鉴权不经过自己的应用服务器。这种方案的好处显而易见。第一服务端不用写文件接收和合并接口省掉了大量 IO 操作。第二断点续传、并发控制、秒传都是 SDK 内置的稳定性和性能已经经过线上大规模验证。第三对象存储本身自带 CDN上传完成后可以直接生成下载链接还要自己搭一套文件服务。我实际接过的几个项目里用的都是类似流程前端发起请求获取 STS token然后使用 SDK 实例化上传器监听分片上传进度。整个过程代码量不大主要精力花在 token 的过期管理和错误处理上。不过商业方案也不是没有门槛。最直接的门槛是预算。存储费、流量费、API 请求次数这些费用在文件量大的时候会非常可观。尤其是视频类产品动辄几十 GB 的单个资源如果 CDN 回源流量没控制好月底账单会吓人一跳。3.2 私有化部署场景下的商业化选择很多企业的数据是不能出内网的或者出于合规要求必须资产评估本地这时没法用公有云对象存储。在私有化场景下比较流行的做法是部署一套 MinIO 或者 SeaweedFS这些系统兼容 S3 协议前端可以直接用 AWS S3 SDK 的 JavaScript 版本做直传。使用 S3 SDK 做分片上传核心是通过 Multipart Upload 接口。前端拿到预签名的 URL 后调用 createMultipartUpload、uploadPart、completeMultipartUpload 三个接口完成整条链路。这种方式的优势是协议标准化换任何一家兼容 S3 的对象存储都能无缝切换。私有化部署的另一条路是直接购买商业软件比如各种企业网盘系统和企业协作平台。它们把大文件上传、预览、版本管理都做成开箱即用的能力前端只需要嵌入它的上传组件或者调用它的开放 API。对业务团队来说前期投入较大但对非技术密集型公司来说稳定性和支持服务是更有保障的。3.3 商业方案和开源方案的成本账很多人一听到商业就觉得贵但这笔账算下来不一定。开源方案看起来不花钱但隐形成本很高。文件存储要自建服务器带宽要买大规格的后端要投入人力维护分片合并逻辑还要处理并发、脏数据、磁盘占满等问题。一旦线上出现上传失败、文件损坏、服务器磁盘告急都需要有人工介入排查。商业方案的费用结构很清晰存储 流量 请求数 必要的增值服务。对于中小团队特别是没有专职后端或者后端资源稀缺的团队每个月花几百块钱买对象存储换来的是极低的上传失败率和极高的开发效率这个性价比其实是划算的。如果公司有运维能力又不想受制于人也可以用开源对象存储做私有化再搭配一些商业 API 网关或者 CDN 能力也就是混合方案。关键还是要结合团队规模和业务量来做综合评估。4. 分片上传核心原理与实测参数不管最后选了哪条路线作为前端理解分片上传的底层原理都特别重要。很多配套参数不是乱调的要根据实际场景来定。4.1 分片大小到底怎么定分片大小并不是固定的。我自己的经验是100MB 以下的小文件不需要分片直接整体上传就行分片反而因为额外请求带来性能损失。1GB 以上的文件分片大小建议设置在 5MB 到 20MB 之间。假设一个 2GB 的文件如果你切 5MB会有 410 个分片。每个分片从上传到服务端确认都需要一次 HTTP 往返。分片太小请求数量太多服务端的接口压力大前端也要维护很长的分片状态列表。分片太大呢每传一片耗时太长中途断网损失就很大而且服务端接收内存缓冲区也要扩大。我常用的一个折中方案是2GB 文件用 10MB 分片也就是 205 片并发数控制在 3~5。这样既不会因为分片太多造成请求过多也不会因为单片太大导致失败重传成本高。关于并发数也要特别说一句。浏览器对同一域名的连接数是有限制的HTTP/1.1 下通常是 6 个左右。如果你开 10 个并发很多请求实际都在排队并不会真的更快反而可能因为 TCP 连接相互争抢带宽让整体上传更慢。所以并发数不是越多越好3~5 是我实测下来比较稳定的区间。4.2 断点续传和数据完整性校验断点续传的核心是记录和恢复。记录什么记录哪些分片已经传成功了。恢复怎么做下次选择同一个文件时先计算整个文件的 hash去服务端查一下这个 hash 对应的上传任务存在不存在存在的话已传分片是哪些然后只上传缺失的。这个 hash 计算很多人直接用 MD5但要注意 MD5 的碰撞风险在超大文件场景下是存在的。如果对完整性要求很高可以用 SHA-1 或者做抽样 hash 整体 hash 的双重校验。不过说实话只做秒传的话MD5 配合文件大小已经能覆盖绝大多数场景。分片上传完之后服务端需要合并。合并的接口一般会接收一个上传任务的 ID然后后端按分片序号把临时文件拼起来最后对合并后的文件做一次 hash 校验和前端提交的 hash 比对一致才算真正上传成功。这一步我强烈建议保留不然很容易出现文件损坏。前端在进度条方面也要注意。整体进度计算的公式是已经上传的分片数 / 总分片数 * 100%而不是直接拿单个请求的 loaded/total因为分片大小可能不统一最后一片往往是多余的。用“分片个数”计算逻辑简单而且准确。5. 双端联调与常见问题排查大文件上传是前后端共同协作的产物联调阶段最容易暴露问题。我在项目里排查过太多上传问题整理一些高频坑出来。5.1 后端接收分片要注意什么后端如果走自研接口最容易被坑的就是临时文件管理。我在后端排查问题时发现很多上传任务失败不是传输环节挂了而是服务器磁盘上塞满了来不及合并的临时分片。建议后端给每个上传任务建独立目录定期清理超时的临时目录。合并时也要注意性能。最差的做法是把所有分片数据 append 到一个文件里这样每片都要打开文件、移动指针、写入对机械磁盘是灾难。好一点的做法是先把分片写到一个临时文件中合并时直接用流式拼接或者干脆在上传每个分片时把数据追加到同一个目标文件流里最后只做完整性校验。另外nginx 的反向代理层也要配置好。虽然分片上传请求的 body 不大但合并接口一次要处理的可能是完整的文件元数据如果自定义 headers 过多也可能突破默认的请求头大小限制。5.2 前端常见问题速查表我把平时被问得最多的几个问题整理成一个速查表希望对排查问题有帮助。现象可能原因解决办法上传后 nginx 返回 413client_max_body_size 未设置或过小在 nginx 配置里调整 client_max_body_size分片请求和合并接口各自设置合理值大文件上传主线程卡死hash 计算在主线程执行改用 Web Worker 计算 hash避免阻塞渲染断点续传失效重新上传从头开始localStorage 被清空或 hash 不一致将上传任务 ID 和已传分片列表保存到服务端前端优先从服务端获取上传进度条跳到 100% 后又变回 80%整体进度计算方式错误分片请求使用已上传分片数/总分片数计算进度合并阶段单独展示浏览器内存暴涨、页面卡顿没有用 Blob.slice 做分片读取而是把整个文件读进内存确认前端是基于 Blob 切片上传而不是 FileReader 全量读取并发上传总是失败并发数太高TCP 连接竞争严重把并发数调小到 3~5并增加请求失败重试机制这个小表格是我在实际项目里常看的很多时候问题不是某个库不行而是使用姿势不对。5.3 使用开源库常见坑选开源库一定不能光看 star 数量要看维护情况和社区活跃度。vue-simple-uploader 早期版本对 vite 的支持有问题需要手动 external 一些依赖uppy 版本更新快但 API 变化也频繁锁版本很重要。如果你用 Web Worker 计算 hash还要注意 worker 脚本的前端公共路径。vue-cli 打包默认把 worker 文件作为独立资源但如果部署后访问路径变了比如放在 CDN 子目录下worker 加载就会失败。建议用相对路径或者动态 import 的方式加载 worker 脚本。还有一点就是现在很多浏览器已经支持navigator.storage.estimate()接口来估算存储空间但断点续传的持久化主要还是靠 localStorage。localStorage 有 5MB 左右的限制如果你记录的分片列表太长或者文件特别多有可能会溢出。解决办法就是只记录必要的上传任务 ID 和最新进度不要把整个文件列表塞进去。6. 选型建议什么时候该用什么方案聊了这么多最后把这几年总结的选型逻辑拎出来说说。先看团队规模和业务属性。如果你是个人开发者或者创业团队没有专职后端直接上商业对象存储 SDK 是效率最高的选择省心又稳定。次选是找成熟的开源组件比如 vue-simple-uploader把后端的接收方案定规范。如果公司要求数据必须完全内网或者法定环境不能上公有云那就得走私有化部署。这时候再分两条线不想折腾直接买商业软件或企业网盘愿意投入就部署 MinIO自己写点服务端代码。如果是大型 toB 项目上传的文件特别大例如几十 GB 的视频素材、设计源文件那就要考虑多节点存储和 CDN 回源加速的问题不是简单一个组件能解决的建议先评估商业传输加速方案再做开源二次开发。从我在实际项目中的体会来看没有哪个方案是银弹。开源代码给你自由度商业应用给你稳定和效率关键是想清楚团队现有的人力、预算和业务的稳定要求。自己从零造轮子之前先问一个特别朴素的问题这个文件真的需要分片上传吗如果只是偶尔传个两三百 MB 的文件直接调大 nginx 限制、设置长超时反而更省事。分片上传解决的是”频繁、大、不稳定环境“下的体验问题不是所有上传场景都必须上它的。最后再分享一个小技巧。不管用哪个方案测试阶段一定要在开发者工具里开启网络节流选一个 3G/慢速网络的配置然后传一个 1GB 以上的文件把暂停、断网、切换网络、关页面重新打开这几条路径全部走一遍。大部分问题会在这一步暴露出来比上线后等用户报错要舒服得多。
