Vue 3 中 Axios 封装大文件上传需解决进度不稳定、小文件仅触发一次、100%不等于服务端完成三大问题：透传 onUploadProgress、兜底定时模拟进度、区分 uploadEnd 与进度完成、预留断点续传接口。
Vue 3 中用 Axios 封装大文件上传进度监听，核心不是“加个回调就行”，而是要解决三个实际问题：进度回调触发不稳定、小文件只触发一次、进度显示 100% 但服务端还没处理完。封装时得把逻辑分层，让调用方干净，底层鲁棒。
封装时必须暴露 onUploadProgress 并透传参数
不能在封装层直接写死回调逻辑，否则无法适配不同组件（比如 Element Plus 的 el-progress 或 Ant Design Vue 的 a-progress）。正确做法是把 onUploadProgress 作为配置项接收，并原样透传给 axios 请求选项：
- 对外 API 保留 onUploadProgress: (e: ProgressEvent) => void 参数
- 内部构造请求时，直接将该函数赋值给 axios 配置的 onUploadProgress 字段
- 避免在封装里做 Math.round((e.loaded / e.total) * 100) 计算——交由业务组件自己控制展示逻辑更灵活
兼容小文件“只触发一次”问题
XMLHttpRequest 对极小文件（如几 KB）可能只派发一次 progress 事件（甚至不派发），导致进度条卡在 0% 或直接跳到 100%。封装层可加一层兜底策略：
python-flask-vue-creator
下载
创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。
- 检测 e.lengthComputable === false 时，改用定时器模拟渐进式更新（例如每 200ms +5%，直到收到响应）
- 对 total 为 0 或 undefined 的情况，主动 fallback 到“上传中…”状态文本，不强行驱动进度条归零或满格
- 在请求发起后立即触发一次手动进度通知（如 onUploadProgress({ loaded: 0, total: 1, lengthComputable: true })），确保 UI 至少能初始化
区分“传输完成”和“服务端处理完成”
进度到达 100% 只代表浏览器已把数据发完，不代表后端已保存成功或返回结果。封装层应明确这个边界：
立即学习“前端免费学习笔记（深入）”；
- 不要在 onUploadProgress 里自动把进度设为 100% 后就隐藏进度条或弹成功提示
- 建议增加一个 onUploadEnd 回调（非 axios 原生，自定义），在 axios .then() 响应解析后触发，此时才适合置灰按钮、显示“上传成功”或跳转
- 若后端响应耗时长（如压缩、转码），可在 onUploadEnd 里启动 loading 状态，与上传进度解耦
支持断点续传需额外抽象上传任务单元
纯 axios 封装无法直接支持断点续传，但可为上层分片逻辑留好接口：
- 封装的 upload 方法返回一个可取消的 Promise（用 AbortController），并暴露 cancel() 方法
- 接受 chunkSize?: number 和 fileId?: string 参数，方便外部按块组织请求
- 进度事件中的 e.loaded 是当前 chunk 的已传字节，总进度需由上层聚合计算，封装层不越权汇总
