Vue 3 文件上传通用封装核心是 useUpload 组合式函数,统一管理上传逻辑、进度计算(Math.round((e.loaded/e.total)*100))、分片断点续传、错误重试与取消清理,返回响应式状态和纯净 API,不绑定 UI。

Vue 3 中处理文件上传与进度条的通用封装,核心是把上传逻辑、状态管理、进度计算、错误恢复等能力从组件中抽离,用组合式 API(Composable)统一组织。这样既能复用,又便于测试、升级和跨项目迁移。
用 useUpload 封装基础上传能力
把文件选择、FormData 构建、请求发起、响应解析等收进一个 useUpload 函数里,返回 ref 管理的 fileList、progress、status 和函数如 upload()、cancel():
- 内部用
ref存当前进度值,配合watch或事件回调实时更新 - 支持单文件 / 多文件模式,通过参数控制是否自动清空上次列表
- 默认携带 token、自定义 header,可透传额外字段(如业务 ID、分类)
- 失败时提供重试入口,不强绑定 UI,由调用方决定是否弹窗或展示错误提示
进度条要精准,就得接管原生 upload 过程
别依赖 el-upload 的 on-progress —— 它只在 xhr 层面触发,粒度粗、不准、无法取消。改用 Axios 或 fetch + AbortController 手动控制:
- 创建 FormData 后,用
XMLHttpRequest或fetch发起请求,并监听upload.onprogress - 进度计算公式:
Math.round((e.loaded / e.total) * 100),注意 e.total 可能为 0(流式上传或服务端未设 Content-Length) - 把进度值暴露为响应式 ref,让进度条组件直接绑定,无需额外事件总线
- 上传取消后,主动清理 xhr 实例或 abort fetch,避免内存泄漏
大文件场景必须分片 + 断点续传
单次上传 GB 级文件极易超时或中断,真正健壮的封装要内置分片能力:
- 用
File.prototype.slice()按固定大小(如 2MB)切块,每块带序号、hash、偏移量 - 上传前先算全文件 MD5(用 Web Worker 防止主线程卡顿),发给服务端判断是否秒传
- 若非秒传,先查已上传分片列表,只上传缺失部分;合并成功后再触发最终回调
- 并发控制(如最多同时传 3 片)、失败重试(带退避策略)、断网自动暂停,都应在 hook 内部闭环
与 UI 组件解耦,适配不同技术栈
封装的目标不是做一个“万能上传组件”,而是提供可插拔的逻辑层:
- 不强制依赖 Element Plus 或 Vxe-UI,
useUpload返回的是纯逻辑和状态,UI 自由渲染 - 可轻松对接
el-upload(覆盖其 uploadMethod)、vxe-upload(传入 upload-method)、甚至原生 input - 类型定义写清楚:
UploadOptions、UploadResult、UploadStatus,TS 支持开箱即用 - 对外暴露的 API 干净:只有
upload(file)、cancel()、reset(),无副作用
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











