UniApp 进阶：打造高效图片上传组件（支持断点续传与失败重试）

1. 为什么需要断点续传与失败重试在实际开发中我们经常会遇到这样的场景用户上传一张5MB的图片进度到90%时突然断网或者后台服务临时维护导致上传失败。传统的一次性上传方案会让用户不得不重新选择文件、重新上传这种体验简直让人抓狂。我去年负责过一个社区类App的项目用户反馈最多的就是上传照片总失败。测试发现在地铁、电梯等网络不稳定的场景下普通上传功能的失败率高达35%。后来我们引入断点续传机制后失败率直接降到了3%以下。断点续传的核心价值在于网络中断后可以从上次断开的位置继续上传而不是从头开始节省用户时间和流量消耗特别是大文件场景提升弱网环境下的功能可用性失败重试机制则解决了服务端临时不可用时的自动恢复网络抖动导致的偶发失败避免用户手动重复操作2. 断点续传的实现原理2.1 分块上传设计要实现断点续传首先要将文件切碎。就像搬家时把大件家具拆成零件运输一样我们把大文件分成若干个小块chunk上传。通常每个分块1-5MB为宜具体大小需要权衡分块太小增加请求次数影响性能分块太大失去断点续传的意义// 文件分片示例 function createFileChunks(file, chunkSize 5 * 1024 * 1024) { const chunks [] let start 0 while (start file.size) { chunks.push({ file: file.slice(start, start chunkSize), chunkId: Math.random().toString(36).slice(2) }) start chunkSize } return chunks }2.2 任务状态持久化分块上传过程中需要维护几个关键状态已上传成功的分块列表当前正在上传的分块上传失败的记录我推荐使用uni-app的本地存储来保存这些信息// 保存上传状态 function saveUploadState(fileHash, state) { uni.setStorageSync(upload_state_${fileHash}, JSON.stringify(state)) } // 读取上传状态 function getUploadState(fileHash) { const state uni.getStorageSync(upload_state_${fileHash}) return state ? JSON.parse(state) : null }3. 完整实现方案3.1 前端核心代码基于uni.uploadFile封装增强版上传组件// 增强版上传方法 async function enhancedUpload(options) { const { filePath, onProgress, maxRetry 3 } options const file await getFileInfo(filePath) const fileHash await calculateFileHash(file) let state getUploadState(fileHash) || { fileHash, totalSize: file.size, uploadedSize: 0, chunks: [] } const chunks createFileChunks(file) let retryCount 0 while (state.uploadedSize file.size retryCount maxRetry) { try { const nextChunk findNextChunk(chunks, state) if (!nextChunk) break const res await uploadChunk({ ...nextChunk, fileHash, chunkIndex: state.chunks.length }, onProgress) state.chunks.push(res.chunkId) state.uploadedSize nextChunk.file.size saveUploadState(fileHash, state) retryCount 0 // 重置重试计数 } catch (err) { retryCount if (retryCount maxRetry) throw err await delay(1000 * retryCount) // 指数退避 } } if (state.uploadedSize file.size) { await verifyUpload(fileHash) clearUploadState(fileHash) } return { success: true } }3.2 服务端配合要点后端需要实现三个关键接口分块上传接口接收文件分块并临时存储分块验证接口检查分块是否已存在合并接口将所有分块合并为完整文件以Node.js为例// 分块上传处理 router.post(/upload/chunk, async (ctx) { const { chunkId, fileHash, chunkIndex } ctx.request.body const file ctx.request.files.chunk // 检查是否已上传过 if (await checkChunkExists(fileHash, chunkIndex)) { return ctx.body { code: 0, chunkId } } // 存储分块 const savePath path.join(TEMP_DIR, ${fileHash}-${chunkIndex}) await fs.promises.rename(file.path, savePath) ctx.body { code: 0, chunkId } }) // 合并分块 router.post(/upload/merge, async (ctx) { const { fileHash, fileName } ctx.request.body const chunkPaths await findChunks(fileHash) // 按索引排序 chunkPaths.sort((a, b) { const aIndex parseInt(a.split(-).pop()) const bIndex parseInt(b.split(-).pop()) return aIndex - bIndex }) // 合并文件 const targetPath path.join(UPLOAD_DIR, fileName) await mergeFiles(chunkPaths, targetPath) // 清理临时文件 await Promise.all(chunkPaths.map(p fs.promises.unlink(p))) ctx.body { code: 0, url: /uploads/${fileName} } })4. 用户体验优化技巧4.1 进度展示的艺术普通进度条已经不能满足用户期待了我总结了几种更友好的展示方式分阶段进度将上传过程分为准备中、上传中、合并中三个阶段速度预测根据当前网速预估剩余时间断网提示检测到网络中断时显示等待网络恢复...实现代码示例// 增强版进度处理 function handleEnhancedProgress(uploadTask, file) { let lastLoaded 0 let lastTime Date.now() uploadTask.onProgressUpdate((res) { const now Date.now() const duration (now - lastTime) / 1000 // 秒 const loadedDiff res.totalBytesSent - lastLoaded // 计算瞬时速度 (KB/s) const speed duration 0 ? (loadedDiff / duration / 1024).toFixed(2) : 0 // 预估剩余时间 const remainingBytes file.size - res.totalBytesSent const remainingTime speed 0 ? (remainingBytes / 1024 / speed).toFixed(1) : Infinity this.$emit(progress, { percent: res.progress, speed, remainingTime, status: uploading }) lastLoaded res.totalBytesSent lastTime now }) }4.2 失败处理的正确姿势在实现重试逻辑时有几个坑我帮大家踩过了指数退避第一次失败立即重试第二次等待1秒第三次等待4秒...混合错误区分网络错误和服务端错误前者重试后者直接报错用户提示不要简单显示上传失败要说明具体原因和解决方案async function uploadWithRetry(taskCreator, maxRetry 3) { let retryCount 0 let lastError null while (retryCount maxRetry) { try { const task taskCreator() return await new Promise((resolve, reject) { task.then(resolve).catch(reject) }) } catch (err) { lastError err retryCount // 非网络错误直接退出 if (!isNetworkError(err)) break // 指数退避 await delay(1000 * Math.pow(2, retryCount - 1)) } } throw lastError }5. 跨平台兼容性处理5.1 各端特有问题在uni-app中实现断点续传不同平台有不同表现H5端注意事项分块上传需要后端支持CORS进度事件更精确可以使用更现代的API如fetch小程序端限制单次上传文件不能超过10MB微信小程序需要配置uploadFile合法域名后台运行时可能被暂停上传App端优势可以突破H5的安全限制支持后台持续上传能获取更精确的网络状态5.2 条件编译技巧使用uni-app的条件编译处理平台差异// #ifdef H5 const uploadApi /api/upload // #endif // #ifdef MP-WEIXIN const uploadApi https://your-domain.com/upload // #endif // #ifdef APP-PLUS const uploadApi process.env.NODE_ENV development ? http://localhost:3000/upload : https://your-domain.com/upload // #endif6. 性能优化实战6.1 并发控制同时上传太多分块会阻塞网络需要做并发控制。我推荐使用p-limit这样的库import pLimit from p-limit // 限制并发数为3 const limit pLimit(3) async function uploadAllChunks(chunks) { const results await Promise.all( chunks.map(chunk limit(() uploadChunk(chunk)) ) ) return results }6.2 文件哈希优化计算文件哈希可能很耗时特别是大文件。可以采用以下优化抽样哈希只计算文件头尾和中间部分Web Worker将计算放到后台线程增量计算在上传过程中并行计算// 使用Web Worker计算文件哈希 function calculateFileHash(file) { return new Promise((resolve) { const worker new Worker(/hash-worker.js) worker.postMessage({ file }) worker.onmessage (e) { resolve(e.data.hash) worker.terminate() } }) }7. 实际项目中的经验分享在电商项目中我们曾遇到用户上传3分钟视频频繁失败的问题。最终方案结合了断点续传和本地缓存用户选择文件后立即计算哈希并保存到本地上传过程中断后下次打开App自动继续七天内未完成的记录会自动清理这个方案使视频上传成功率从68%提升到97%关键代码片段// 持久化上传任务 function saveUploadJob(job) { const jobs uni.getStorageSync(upload_jobs) || [] const existing jobs.find(j j.fileHash job.fileHash) if (!existing) { jobs.push(job) uni.setStorageSync(upload_jobs, jobs) } } // 恢复未完成任务 function resumeUploadJobs() { const jobs uni.getStorageSync(upload_jobs) || [] jobs.forEach(job { if (job.expireTime Date.now()) { startUploadJob(job) } }) // 清理过期任务 const validJobs jobs.filter(j j.expireTime Date.now()) uni.setStorageSync(upload_jobs, validJobs) }