現(xiàn)大文件斷點(diǎn)續(xù)傳與分片上傳實(shí)戰(zhàn))
大文件上傳這活兒看著簡(jiǎn)單真做起來(lái)全是坑。幾 GB 的安裝包、視頻素材、數(shù)據(jù)集傳到一半斷網(wǎng)后端收到的文件沒(méi)法用用戶又得從頭來(lái)一次脾氣再好也得崩潰。所以這幾年“斷點(diǎn)續(xù)傳”成了大文件上傳方案的標(biāo)配尤其在前端 Vue 工程里配合 JavaScript 的 Blob 切片和發(fā)送異步請(qǐng)求能把整個(gè)上傳過(guò)程拆成可控的小任務(wù)強(qiáng)悍又有韌勁。我這次就把自己摸索出來(lái)的一套 Vue 3 Node.js 斷點(diǎn)續(xù)傳 DEMO 拆開揉碎了講一遍。從分片思路、哈希計(jì)算到后端合并全流程走通代碼可以直接抄坑也會(huì)提前幫你們踩了。1. 斷點(diǎn)續(xù)傳的核心邏輯分片、記錄、重傳1.1 先把“斷點(diǎn)續(xù)傳”這個(gè)詞拆開看很多人一聽到“斷點(diǎn)續(xù)傳”腦袋里浮現(xiàn)的是迅雷下載那個(gè)進(jìn)度條。本質(zhì)上它確實(shí)就是那個(gè)意思文件不是被當(dāng)作一個(gè)整體傳輸而是切成 N 個(gè)小塊逐一上傳如果中間哪一塊沒(méi)傳成功下次重新發(fā)起時(shí)只補(bǔ)傳失敗的那幾塊而不是整個(gè)文件再來(lái)一遍。這里頭有兩個(gè)關(guān)鍵動(dòng)作分片slice前端用 Blob API 把大文件按偏移量切成多個(gè)二進(jìn)制塊。記錄與校驗(yàn)后端記錄哪些分片已收到前端在每次恢復(fù)上傳前向后端要一個(gè)“已上傳分片清單”只補(bǔ)缺的部分。用生活類比的話就好比搬家。整棟樓的家具一趟一輛車?yán)呗飞媳ヒ淮稳甑啊Ｇ衅蟼骶拖癜鸭揖呦妊b箱每個(gè)箱子獨(dú)立搬運(yùn)哪個(gè)箱子丟了就補(bǔ)哪個(gè)箱子其他箱子不用返工。1.2 斷點(diǎn)續(xù)傳 Solve 什么問(wèn)題規(guī)模超過(guò) 2GB 的文件用傳統(tǒng)單次上傳會(huì)有三個(gè)致命問(wèn)題網(wǎng)絡(luò)穩(wěn)定性不可控移動(dòng)網(wǎng)絡(luò)、公司代理斷連、服務(wù)器主動(dòng)超時(shí)都可能中途斷開。服務(wù)端接收壓力大一次 PUT 或 POST 一個(gè)大 Body后端如果沒(méi)做好流式接收內(nèi)存直接被頂爆。重試成本太高失敗后全量重傳浪費(fèi)帶寬和時(shí)間尤其在弱網(wǎng)環(huán)境基本等于放棄。斷點(diǎn)續(xù)傳讓整個(gè)上傳過(guò)程變成“多批次小任務(wù)”失敗可重試并發(fā)可控制進(jìn)度可恢復(fù)。這套思路同時(shí)兼顧了弱網(wǎng)友好和服務(wù)器資源開銷的平衡。2. 技術(shù)選型與整體設(shè)計(jì)思路2.1 前端為什么用 Vue 3 Composition API其實(shí)斷點(diǎn)續(xù)傳核心是 JavaScript 的能力和框架本身關(guān)系不大。用 Vue 3 主要圖它生態(tài)成熟、組件化開發(fā)方便還有一個(gè)很重要的原因Composition API 的ref、reactive在處理上傳進(jìn)度這種高頻狀態(tài)變更時(shí)比 Options API 更順手狀態(tài)邏輯抽出來(lái)復(fù)用也容易。另外 Vue 3 搭配 Element Plus 的el-upload和el-progress做上傳界面可以少寫一堆 CSS 和交互邏輯。我這套 DEMO 不依賴太重的組件庫(kù)但思路完全兼容 Element Plus。2.2 分片大小怎么定分片大小是斷點(diǎn)續(xù)傳方案里最需要權(quán)衡的一個(gè)參數(shù)。常見(jiàn)建議是 1MB 到 20MB 之間得看實(shí)際場(chǎng)景文件大小分片大小分片數(shù)量并發(fā)數(shù)建議100MB2MB5031GB5MB2003-55GB10MB5005我自己的經(jīng)驗(yàn)是普通 Web 服務(wù)5MB 一片最均衡。太小會(huì)導(dǎo)致請(qǐng)求次數(shù)爆炸HTTP 握手開銷占大頭太大會(huì)失去“斷點(diǎn)”的意義網(wǎng)絡(luò)波動(dòng)時(shí)單塊失敗重傳成本高。要注意分片大小要結(jié)合服務(wù)端的接收超時(shí)時(shí)間和帶寬情況調(diào)整。內(nèi)網(wǎng)環(huán)境帶寬充足可以放大到 20MB/片公網(wǎng)弱網(wǎng)環(huán)境建議 2MB/片更穩(wěn)妥。2.3 哈希計(jì)算是個(gè)繞不開的環(huán)節(jié)斷點(diǎn)續(xù)傳里經(jīng)常要做文件指紋Hash計(jì)算原因在于文件內(nèi)容沒(méi)變才能判定同一文件。兩個(gè)不同文件如果正好同名同大小直接用文件名做標(biāo)識(shí)是危險(xiǎn)的容易出現(xiàn)“文件 A 的斷點(diǎn)續(xù)傳到文件 B”的錯(cuò)亂。比較穩(wěn)妥的做法是用SparkMD5對(duì)文件計(jì)算 MD5。計(jì)算過(guò)程可以放在Web Worker中執(zhí)行避免計(jì)算大文件時(shí)主線程卡死拖慢頁(yè)面滾動(dòng)和渲染。我見(jiàn)過(guò)不少項(xiàng)目圖省事直接在主線程算 2GB 文件的 MD5計(jì)算期間整個(gè)頁(yè)面像凍住一樣用戶直接以為死機(jī)了。3. 前端環(huán)境安裝與項(xiàng)目初始化3.1 創(chuàng)建 Vue 3 項(xiàng)目并安裝依賴先建項(xiàng)目建議直接用 Vite開發(fā)時(shí)熱更新快構(gòu)建產(chǎn)物也干凈。npm init vite-app chunk-upload-demo cd chunk-upload-demo npm install npm install spark-md5 axiosspark-md5用來(lái)計(jì)算文件指紋axios用來(lái)發(fā)請(qǐng)求。如果項(xiàng)目本身有自己封裝的請(qǐng)求庫(kù)換成自己的就行原理都一樣。3.2 封裝核心上傳模塊我得提醒一下千萬(wàn)別把上傳邏輯全塞進(jìn)組件里那組件會(huì)變成一坨“會(huì)動(dòng)的意大利面”。最好單獨(dú)抽一個(gè)useUploader.js模塊把所有狀態(tài)和邏輯封裝進(jìn)去組件里只做界面渲染和事件綁定。import { ref, reactive } from vue export function useUploader() { const file ref(null) const fileHash ref() const chunkSize 5 * 1024 * 1024 // 5MB const uploadedChunks reactive(new Set()) const progress ref(0) const uploading ref(false) const paused ref(false) const selectFile (rawFile) { file.value rawFile uploadedChunks.clear() progress.value 0 fileHash.value } return { file, fileHash, chunkSize, uploadedChunks, progress, uploading, paused, selectFile } }這個(gè)模塊專門管理“上傳狀態(tài)”。后續(xù)所有方法都圍繞這個(gè)狀態(tài)展開組件里只需要引入倉(cāng)庫(kù)管理。4. 分片與文件指紋計(jì)算4.1 用 SparkMD5 計(jì)算文件唯一標(biāo)識(shí)這一步的目的是給文件生成一個(gè)唯一的 chunk 任務(wù) ID。我在實(shí)際項(xiàng)目里用的格式是${fileHash}-${lastModified}-${file.size}SparkMD5的增量計(jì)算寫法如下import SparkMD5 from spark-md5 const calculateHash (file, chunkSize) { return new Promise((resolve, reject) { const blobSlice File.prototype.slice const chunks Math.ceil(file.size / chunkSize) const spark new SparkMD5.ArrayBuffer() const fileReader new FileReader() let currentChunk 0 fileReader.onerror reject fileReader.onload (e) { spark.append(e.target.result) currentChunk if (currentChunk chunks) { loadNext() } else { resolve(spark.end()) } } const loadNext () { const start currentChunk * chunkSize const end start chunkSize file.size ? file.size : start chunkSize fileReader.readAsArrayBuffer(blobSlice.call(file, start, end)) } loadNext() }) }注意我在計(jì)算 Hash 的時(shí)候用了FileReader.readAsArrayBuffer比readAsBinaryString靠譜后者在內(nèi)存占用和兼容性上都有隱患。計(jì)算過(guò)程如果用 Worker 做這里直接在整個(gè) Worker 文件里封裝相同邏輯即可。4.2 計(jì)算超時(shí)的處理大文件 Hash 計(jì)算有可能會(huì)很久。如果文件有幾 GB即使開 Worker計(jì)算 MD5 也需要數(shù)十秒。應(yīng)對(duì)方案一般是先做一個(gè)“快速校驗(yàn)”比如查后端是否存在“秒傳文件”存在就直接返回上傳成功跳過(guò)切片不存在再進(jìn)入完整計(jì)算流程?！懊雮鳌钡倪壿嬙诤蠖耸且粋€(gè)很有用的優(yōu)化我在第 6 節(jié)會(huì)專門提到。5. 分片上傳與前臺(tái)上傳進(jìn)度實(shí)現(xiàn)5.1 分片切片邏輯文件切片很簡(jiǎn)單用file.slice(start, end)就能獲取一段二進(jìn)制塊。切片數(shù)據(jù)要加上額外的元信息讓后端知道這是哪個(gè)文件的第幾片。const createChunk (file, index, chunkSize) { const start index * chunkSize const end Math.min(file.size, start chunkSize) return file.slice(start, end) }這里有個(gè)細(xì)節(jié)切片時(shí)不要用end file.size作為邊界判斷直接start chunkSize會(huì)導(dǎo)致最后一個(gè)切片越界。上面代碼用Math.min兜底看起來(lái)簡(jiǎn)單實(shí)際能省掉不少邊界 bug。5.2 上傳單個(gè)分片每個(gè)分片通過(guò) FormData 發(fā)送。這里我要強(qiáng)調(diào)分片數(shù)據(jù)本身在 FormData 里就是二進(jìn)制后端拿到的也是Stream或Buffer不要嘗試轉(zhuǎn)成 base64那會(huì)讓體積膨脹 33%純屬浪費(fèi)。import axios from axios const uploadChunk (formData) { return axios.post(/api/upload/chunk, formData, { headers: { Content-Type: multipart/form-data }, timeout: 120000 }) }超時(shí)時(shí)間要給足分片上傳經(jīng)常在弱網(wǎng)環(huán)境下發(fā)生“慢請(qǐng)求”120 秒比較合適。如果請(qǐng)求被服務(wù)器提前斷開axios 會(huì)拋錯(cuò)我們?cè)谏蠈硬东@后標(biāo)記該分片為“未完成”狀態(tài)等待重試即可。5.3 并發(fā)控制與進(jìn)度條并發(fā)控制是斷點(diǎn)續(xù)傳的進(jìn)階操作。通過(guò)并發(fā)上傳上傳總耗時(shí)比挨個(gè)傳快很多同時(shí)又能避免一次性發(fā)起上百個(gè)請(qǐng)求把瀏覽器和服務(wù)端都打垮。const concurrentUpload async (tasks, limit 3) { const queue [...tasks] const workers new Array(limit).fill(null).map(async () { while (queue.length) { const task queue.shift() await task() } }) await Promise.all(workers) }進(jìn)度條邏輯是根據(jù)“已成功分片數(shù) / 總分片數(shù)”計(jì)算的。注意這里的進(jìn)度不是拿“已發(fā)請(qǐng)求數(shù)”計(jì)算而是拿“后端確認(rèn)寫入成功的分片數(shù)”計(jì)算保證進(jìn)度條反映的是真實(shí)落地狀態(tài)而不是“請(qǐng)求發(fā)出去但可能失敗”的假進(jìn)度。const updateProgress () { const totalChunks Math.ceil(file.value.size / chunkSize) progress.value Math.round((uploadedChunks.size / totalChunks) * 100) }5.4 暫停、恢復(fù)與取消暫停的本質(zhì)是終止當(dāng)前未完成的分片請(qǐng)求。這個(gè)操作要跟“取消”區(qū)分開取消是徹底終止該文件上傳任務(wù)暫停只是臨時(shí)中斷之后還能從斷點(diǎn)繼續(xù)。我用一個(gè)AbortController來(lái)管理每個(gè)分片請(qǐng)求的中斷const pause () { paused.value true // 中斷所有未完成請(qǐng)求 activeControllers.forEach(controller controller.abort()) } const resume async () { paused.value false // 重新請(qǐng)求后端已上傳分片列表過(guò)濾后繼續(xù)上傳 await fetchUploadedChunks() await uploadRemainingChunks() }中斷請(qǐng)求時(shí)要注意axios 的abort會(huì)直接讓 Promise reject上層要區(qū)分“主動(dòng)中斷”和“網(wǎng)絡(luò)錯(cuò)誤”。主動(dòng)中斷不應(yīng)觸發(fā)錯(cuò)誤提示應(yīng)靜默處理。6. 后端實(shí)現(xiàn)分片接收與合并6.1 Node.js 后端選型與接口設(shè)計(jì)后端我用的 Express。接口就三個(gè)接口作用POST /api/upload/chunk接收單個(gè)分片GET /api/upload/status查詢文件已上傳的分片列表POST /api/upload/merge合并全部分片三個(gè)接口各司其職前端流程自然就串起來(lái)了。6.2 接收單個(gè)分片后端接收分片時(shí)要記錄兩個(gè)關(guān)鍵信息文件標(biāo)識(shí)和分片索引。臨時(shí)文件存到./upload_temp/{fileHash}/{index}.part。const uploadChunk async (req, res) { const { fileHash, chunkIndex } req.body const chunkFile req.files.chunk const chunkDir path.resolve(./upload_temp/${fileHash}) if (!fs.existsSync(chunkDir)) { fs.mkdirSync(chunkDir, { recursive: true }) } const chunkPath path.join(chunkDir, ${chunkIndex}.part) await fs.promises.rename(chunkFile.path, chunkPath) res.json({ code: 0, message: chunk uploaded }) }用rename移動(dòng)臨時(shí)文件比f(wàn)s.writeFile重新寫入要快而且更安全。如果跨磁盤分區(qū)導(dǎo)致 rename 失敗再回退到copyFile unlink。6.3 查詢已上傳分片斷點(diǎn)續(xù)傳的關(guān)鍵接口。前端發(fā)起恢復(fù)上傳時(shí)先問(wèn)后端“這個(gè)文件的哪些分片已經(jīng)存在”然后只傳缺失的部分。const getUploadStatus async (req, res) { const { fileHash } req.query const chunkDir path.resolve(./upload_temp/${fileHash}) if (!fs.existsSync(chunkDir)) { return res.json({ code: 0, data: { uploadedChunks: [] } }) } const files await fs.promises.readdir(chunkDir) const uploadedChunks files .filter(f f.endsWith(.part)) .map(f parseInt(f.split(.)[0], 10)) res.json({ code: 0, data: { uploadedChunks } }) }這個(gè)接口還有一個(gè)作用并發(fā)場(chǎng)景去重。假如多個(gè)分片并發(fā)上傳服務(wù)端可能收到重復(fù)分片前端并發(fā)隊(duì)列里重復(fù)執(zhí)行后端要冪等處理——同名分片已存在就跳過(guò)不重復(fù)保存。上面用rename覆蓋同名文件時(shí)Windows 會(huì)報(bào) EEXIST 錯(cuò)誤所以可以先檢查存在性。6.4 分片合并所有分片都齊了后端執(zhí)行合并。合并方式是流式把每個(gè).part文件按索引順序?qū)懭胱罱K文件。const mergeChunks async (req, res) { const { fileHash, fileName, totalChunks } req.body const chunkDir path.resolve(./upload_temp/${fileHash}) const outputPath path.resolve(./upload_output/${fileName}) await fs.promises.mkdir(path.dirname(outputPath), { recursive: true }) // 校驗(yàn)分片數(shù)量是否匹配 const files await fs.promises.readdir(chunkDir) if (files.length ! Number(totalChunks)) { return res.status(400).json({ code: 1, message: chunk count mismatch }) } // 按索引排序后流式合并 const sortedFiles files .filter(f f.endsWith(.part)) .sort((a, b) { return parseInt(a.split(.)[0], 10) - parseInt(b.split(.)[0], 10) }) const outputStream fs.createWriteStream(outputPath) for (const file of sortedFiles) { const chunkStream fs.createReadStream(path.join(chunkDir, file)) await new Promise((resolve, reject) { chunkStream.pipe(outputStream, { end: false }) chunkStream.on(end, resolve) chunkStream.on(error, reject) }) } outputStream.end() // 清理臨時(shí)目錄 await fs.promises.rm(chunkDir, { recursive: true, force: true }) res.json({ code: 0, message: merge done }) }合并時(shí)用流式管道不把整個(gè)文件加載進(jìn)內(nèi)存這一點(diǎn)很重要。要是直接把所有分片讀進(jìn) Buffer 拼起來(lái)2GB 文件就能把服務(wù)器內(nèi)存打爆。6.5 秒傳檢測(cè)我前面提過(guò)“秒傳”后端實(shí)現(xiàn)就是在合并前先檢查數(shù)據(jù)庫(kù)或一個(gè) JSON 映射表里是否已有相同 fileHash 的文件記錄。如果有直接返回成功前端跳過(guò)整個(gè)上傳流程。實(shí)際項(xiàng)目里秒傳檢測(cè)一般放在查詢狀態(tài)接口之前或者放在上傳流程最開頭const checkExists async (req, res) { const { fileHash } req.query // fileMap 文件標(biāo)識(shí)與實(shí)際文件路徑的映射表 const record fileMap[fileHash] if (record) { return res.json({ code: 0, data: { exists: true, path: record.path } }) } res.json({ code: 0, data: { exists: false } }) }這個(gè)功能特別適合企業(yè)內(nèi)部的資料分享場(chǎng)景同一個(gè)文件被上傳幾十次每次都省了帶寬和存儲(chǔ)的重復(fù)寫入。7. 前端交互組件設(shè)計(jì)與 Demo 頁(yè)面7.1 上傳面板組件頁(yè)面結(jié)構(gòu)不復(fù)雜一個(gè)文件選擇按鈕、一個(gè)進(jìn)度條、一組控制按鈕。重點(diǎn)是組件里把useUploader暴露的方法綁定到界面事件上。template div classupload-panel input typefile changehandleFileChange / el-progress :percentageprogress v-iffile / div classactions button clickstartUpload :disableduploading開始上傳/button button clickpause :disabled!uploading暫停/button button clickresume :disabled!paused繼續(xù)/button /div /div /template script setup import { useUploader } from ../composables/useUploader const { file, progress, uploading, paused, selectFile, startUpload, pause, resume } useUploader() const handleFileChange (e) { selectFile(e.target.files[0]) } /script注意el-progress如果不引入 Element Plus可以用原生 div 寫個(gè)簡(jiǎn)單的進(jìn)度條樣式自己控制效果也不差。7.2 分片上傳流程串聯(lián)整個(gè)上傳流程是這樣的用戶選擇文件。計(jì)算文件 HashWorker 后臺(tái)執(zhí)行或主線程異步執(zhí)行。請(qǐng)求/api/upload/status獲取已上傳分片索引。把未上傳的分片放入并發(fā)隊(duì)列逐個(gè)上傳。所有分片上傳完成后請(qǐng)求/api/upload/merge合并。顯示最終下載鏈接。偽代碼const startUpload async () { uploading.value true fileHash.value await calculateHash(file.value, chunkSize) // 查已上傳分片 const { uploadedChunks } await fetchStatus(fileHash.value) const chunks [] const total Math.ceil(file.value.size / chunkSize) for (let i 0; i total; i) { if (uploadedChunks.includes(i)) { uploadedChunksSet.add(i) } else { chunks.push(i) } } await concurrentUpload(chunks.map(index () uploadOneChunk(index)), 3) await merge() uploading.value false }這一步是最容易出錯(cuò)的地方我見(jiàn)過(guò)很多項(xiàng)目在“查詢已上傳分片”之后沒(méi)有過(guò)濾直接把全部分片重新上傳一遍浪費(fèi)帶寬。上面代碼先查狀態(tài)再過(guò)濾才是真正意義上的“續(xù)傳”。7.3 使用 Web Worker 避免卡頓計(jì)算 Hash 如果文件超過(guò) 1GB主線程會(huì)明顯卡頓。我建議把 Hash 計(jì)算放進(jìn) Worker。Vite 對(duì) Worker 的支持很友好直接用new Worker(new URL(./hashWorker.js, import.meta.url), { type: module })就行。Worker 文件內(nèi)容就是把calculateHash邏輯搬進(jìn)去完成后postMessage返回結(jié)果// hashWorker.js import SparkMD5 from spark-md5 self.onmessage (e) { const { file, chunkSize } e.data const hash calculateHash(file, chunkSize) self.postMessage({ hash }) }如果不想引入 Worker也可以用requestIdleCallback分片計(jì)算但處理起來(lái)麻煩得多而且主線程依然會(huì)被切片讀文件占據(jù)大量時(shí)間所以還是 Worker 最省心。8. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄8.1 分片上傳了但服務(wù)器上文件不可用這個(gè)情況十有八九是合并順序錯(cuò)了。我排查的順序是檢查臨時(shí)目錄里分片文件的大小是否每個(gè)都等于設(shè)置的 chunkSize最后一片除外。檢查命名是否包含前導(dǎo)零比如1.part、2.part、10.part被字符串排序后10 會(huì)在 2 前面。檢查合并流的管道關(guān)閉時(shí)機(jī)管道沒(méi) close 就結(jié)束寫入文件會(huì)截?cái)?。字符串排序?wèn)題是最容易踩的坑。如果分片文件名不帶前導(dǎo)零一定要用數(shù)字排序不能默認(rèn)字符串排序。// 錯(cuò)誤示例字符串排序會(huì)導(dǎo)致 10 排在 2 前面 files.sort() // 正確示例 files.sort((a, b) parseInt(a, 10) - parseInt(b, 10))8.2 進(jìn)度條回跳或卡住不動(dòng)進(jìn)度條卡住通常有兩個(gè)原因并發(fā)隊(duì)列里有某個(gè)分片請(qǐng)求長(zhǎng)期掛起或者后端寫入速度遠(yuǎn)低于上傳速度導(dǎo)致服務(wù)端 socket 阻塞。處理辦法給每個(gè)分片請(qǐng)求設(shè)置超時(shí)超時(shí)后主動(dòng)重試 3 次。后端在接收分片時(shí)如果磁盤 IO 太慢前端并發(fā)數(shù)要調(diào)低比如從 5 降到 3。進(jìn)度條以“成功后端確認(rèn)”為準(zhǔn)不用axios.onUploadProgress的上傳字節(jié)數(shù)。因?yàn)閛nUploadProgress只代表字節(jié)進(jìn)入發(fā)送緩沖區(qū)不代表服務(wù)器讀完。8.3 暫停后恢復(fù)卻從頭開始這個(gè)問(wèn)題的根因通常出在fileHash沒(méi)保存。用戶暫停后頁(yè)面刷新或組件銷毀hash 狀態(tài)丟了重新選擇文件時(shí) hash 又變了尤其如果文件修改時(shí)間變了。解決辦法是持久化把fileHash存到localStorage文件 MD5 計(jì)算完成后立即保存。恢復(fù)上傳時(shí)從 localStorage 讀取優(yōu)先和后端狀態(tài)接口比對(duì)。const saveHash (hash) { localStorage.setItem(upload_hash_${file.value.name}, hash) } const loadHash (name) { return localStorage.getItem(upload_hash_${name}) }注意file.lastModified變化會(huì)導(dǎo)致同樣的文件內(nèi)容算出不同的 hash所以持久化時(shí)最好連同lastModified一起保存作為文件變更的校驗(yàn)依據(jù)。8.4 服務(wù)器返回 413 Request Entity Too Large這個(gè)錯(cuò)誤是服務(wù)器限制了單個(gè)請(qǐng)求體大小。很多人只看前端忽略了后端配置。Express 用multer接收分片時(shí)大小限制設(shè)置const upload multer({ storage: multer.diskStorage({ destination: ./upload_temp, filename: (req, file, cb) { cb(null, ${Date.now()}-${file.originalname}) } }), limits: { fileSize: 20 * 1024 * 1024 } // 單個(gè)分片限制 20MB })如果分片設(shè)置為 10MB這個(gè)限制設(shè)置為 20MB 就沒(méi)問(wèn)題要始終留一倍余量防止 FormData 額外字段導(dǎo)致的體積偏移。8.5 并發(fā)數(shù)過(guò)高導(dǎo)致瀏覽器內(nèi)存飆升并發(fā)數(shù)不是越大越好。我實(shí)測(cè)過(guò)5MB 分片、并發(fā) 3 個(gè)100MB 文件上傳流暢度最好并發(fā) 10 個(gè)雖然速度快一點(diǎn)但瀏覽器內(nèi)存占用高了差不多 300MB低端設(shè)備會(huì)直接卡死。我把不同環(huán)境的建議寫成一個(gè)參考移動(dòng)端 4G 網(wǎng)絡(luò)并發(fā) 2分片 2MBPC 有線網(wǎng)絡(luò)并發(fā) 3-4分片 5MB本地內(nèi)網(wǎng)服務(wù)并發(fā) 5-6分片 10MB這個(gè)組合要靈活調(diào)整沒(méi)有銀彈。8.6 合并時(shí)提示“分片數(shù)量不匹配”這個(gè)錯(cuò)誤通常由兩種情況引起并發(fā)上傳過(guò)程中某些分片請(qǐng)求失敗但沒(méi)重試成功前端以為成功、后端沒(méi)寫入。前端計(jì)算總片數(shù)時(shí)用了Math.ceil(size / chunkSize)但某個(gè)分片確實(shí)沒(méi)發(fā)出去。排查方式在mergeChunks接口打日志把files.length和totalChunks對(duì)比輸出。再在前端上傳完成循環(huán)里加一個(gè)“分片上傳結(jié)果集合”的斷言確保每一片都有成功響應(yīng)。8.7 計(jì)算 Hash 時(shí)間長(zhǎng)、用戶以為頁(yè)面掛了解決方案我在前面提過(guò) Worker。這里再給一個(gè)補(bǔ)充技巧計(jì)算 Hash 前用一個(gè)Loading狀態(tài)提示用戶文案寫清楚“正在分析文件請(qǐng)勿關(guān)閉”配合 Worker 后臺(tái)運(yùn)行用戶感知會(huì)好很多。如果文件大到連 MD5 計(jì)算都不現(xiàn)實(shí)比如 50GB 級(jí)別的數(shù)據(jù)集可以退一步只計(jì)算首尾分片的校驗(yàn)哈?；蛘吒纱嘤梦募笮? 首片哈希 末片哈希組合成標(biāo)識(shí)。安全性和準(zhǔn)確性都有折扣但實(shí)用性拉滿。9. 優(yōu)化方向與擴(kuò)展建議9.1 上傳進(jìn)度與服務(wù)端寫入分離大文件場(chǎng)景下前端進(jìn)度條到 100% 不代表文件立刻可用。后端還有合并時(shí)間。所以實(shí)際做項(xiàng)目時(shí)我一般把狀態(tài)機(jī)做成四態(tài)狀態(tài)含義uploading分片上傳中merging分片合并中success上傳完成failed上傳失敗前端在上傳完最后一片后可以輪詢/api/upload/status或/api/upload/merge-status接口直到返回 success 再展示成功圖標(biāo)。別小看這一步用戶端體驗(yàn)差異巨大。9.2 斷點(diǎn)續(xù)傳 并發(fā)去重前端并發(fā)可能導(dǎo)致兩個(gè)相同的分片同時(shí)上傳。我在后端加了一個(gè)簡(jiǎn)單檢查分片文件存在就跳過(guò)寫盤直接返回成功。這個(gè)冪等處理極大提升了系統(tǒng)的容錯(cuò)率尤其在高并發(fā)場(chǎng)景。9.3 用 IndexedDB 保存上傳任務(wù)如果項(xiàng)目要支持“關(guān)閉瀏覽器后仍能恢復(fù)任務(wù)”前端本地狀態(tài)就得用 IndexedDB 持久化localStorage 存字符串存大任務(wù)列表太吃力。IndexedDB 可以保存 Blob 切片引用、狀態(tài)機(jī)數(shù)據(jù)源下次打開頁(yè)面直接恢復(fù)。這套改造聽著復(fù)雜其實(shí)核心就是多維護(hù)一張“任務(wù)表”。10. 寫在最后的經(jīng)驗(yàn)斷點(diǎn)續(xù)傳這個(gè) DEMO本質(zhì)是一個(gè)“狀態(tài)管理 異步并發(fā) 文件 IO”的組合拳。前端玩的是切片、并發(fā)、異步恢復(fù)后端玩的是文件流、冪等、合并。我做過(guò)的幾次線上問(wèn)題排查得出的經(jīng)驗(yàn)是前端問(wèn)題看著像后端后端問(wèn)題往往要從前端驗(yàn)證。比如用戶說(shuō)“文件壞了”結(jié)果根因是前端并發(fā)重試時(shí)偶然重復(fù)上傳同一個(gè)分片用戶說(shuō)“上傳卡住了”根因是后端磁盤滿了沒(méi)返回響應(yīng)。所以做這類系統(tǒng)日志一定要打“分片索引、文件 Hash、請(qǐng)求耗時(shí)”三段關(guān)鍵信息否則排查起來(lái)像大海撈針。如果你第一次寫這個(gè) DEMO建議先跟著這篇文章把鏈路跑通然后嘗試回答這幾個(gè)問(wèn)題你的并發(fā)控制能應(yīng)對(duì)服務(wù)器返回 500 嗎你的斷點(diǎn)恢復(fù)能應(yīng)對(duì)用戶手動(dòng)刷新頁(yè)面嗎你的合并邏輯能處理分片文件被中途清空嗎把這三個(gè)場(chǎng)景想明白你的斷點(diǎn)續(xù)傳就算真正落地了。 Vue 3 + Node.js 實(shí)現(xiàn)大文件斷點(diǎn)續(xù)傳與分片上傳實(shí)戰(zhàn)
大文件上傳這活兒看著簡(jiǎn)單真做起來(lái)全是坑。幾 GB 的安裝包、視頻素材、數(shù)據(jù)集傳到一半斷網(wǎng)后端收到的文件沒(méi)法用用戶又得從頭來(lái)一次脾氣再好也得崩潰。所以這幾年“斷點(diǎn)續(xù)傳”成了大文件上傳方案的標(biāo)配尤其在前端 Vue 工程里配合 JavaScript 的 Blob 切片和發(fā)送異步請(qǐng)求能把整個(gè)上傳過(guò)程拆成可控的小任務(wù)強(qiáng)悍又有韌勁。我這次就把自己摸索出來(lái)的一套 Vue 3 Node.js 斷點(diǎn)續(xù)傳 DEMO 拆開揉碎了講一遍。從分片思路、哈希計(jì)算到后端合并全流程走通代碼可以直接抄坑也會(huì)提前幫你們踩了。1. 斷點(diǎn)續(xù)傳的核心邏輯分片、記錄、重傳1.1 先把“斷點(diǎn)續(xù)傳”這個(gè)詞拆開看很多人一聽到“斷點(diǎn)續(xù)傳”腦袋里浮現(xiàn)的是迅雷下載那個(gè)進(jìn)度條。本質(zhì)上它確實(shí)就是那個(gè)意思文件不是被當(dāng)作一個(gè)整體傳輸而是切成 N 個(gè)小塊逐一上傳如果中間哪一塊沒(méi)傳成功下次重新發(fā)起時(shí)只補(bǔ)傳失敗的那幾塊而不是整個(gè)文件再來(lái)一遍。這里頭有兩個(gè)關(guān)鍵動(dòng)作分片slice前端用 Blob API 把大文件按偏移量切成多個(gè)二進(jìn)制塊。記錄與校驗(yàn)后端記錄哪些分片已收到前端在每次恢復(fù)上傳前向后端要一個(gè)“已上傳分片清單”只補(bǔ)缺的部分。用生活類比的話就好比搬家。整棟樓的家具一趟一輛車?yán)呗飞媳ヒ淮稳甑啊Ｇ衅蟼骶拖癜鸭揖呦妊b箱每個(gè)箱子獨(dú)立搬運(yùn)哪個(gè)箱子丟了就補(bǔ)哪個(gè)箱子其他箱子不用返工。1.2 斷點(diǎn)續(xù)傳 Solve 什么問(wèn)題規(guī)模超過(guò) 2GB 的文件用傳統(tǒng)單次上傳會(huì)有三個(gè)致命問(wèn)題網(wǎng)絡(luò)穩(wěn)定性不可控移動(dòng)網(wǎng)絡(luò)、公司代理斷連、服務(wù)器主動(dòng)超時(shí)都可能中途斷開。服務(wù)端接收壓力大一次 PUT 或 POST 一個(gè)大 Body后端如果沒(méi)做好流式接收內(nèi)存直接被頂爆。重試成本太高失敗后全量重傳浪費(fèi)帶寬和時(shí)間尤其在弱網(wǎng)環(huán)境基本等于放棄。斷點(diǎn)續(xù)傳讓整個(gè)上傳過(guò)程變成“多批次小任務(wù)”失敗可重試并發(fā)可控制進(jìn)度可恢復(fù)。這套思路同時(shí)兼顧了弱網(wǎng)友好和服務(wù)器資源開銷的平衡。2. 技術(shù)選型與整體設(shè)計(jì)思路2.1 前端為什么用 Vue 3 Composition API其實(shí)斷點(diǎn)續(xù)傳核心是 JavaScript 的能力和框架本身關(guān)系不大。用 Vue 3 主要圖它生態(tài)成熟、組件化開發(fā)方便還有一個(gè)很重要的原因Composition API 的ref、reactive在處理上傳進(jìn)度這種高頻狀態(tài)變更時(shí)比 Options API 更順手狀態(tài)邏輯抽出來(lái)復(fù)用也容易。另外 Vue 3 搭配 Element Plus 的el-upload和el-progress做上傳界面可以少寫一堆 CSS 和交互邏輯。我這套 DEMO 不依賴太重的組件庫(kù)但思路完全兼容 Element Plus。2.2 分片大小怎么定分片大小是斷點(diǎn)續(xù)傳方案里最需要權(quán)衡的一個(gè)參數(shù)。常見(jiàn)建議是 1MB 到 20MB 之間得看實(shí)際場(chǎng)景文件大小分片大小分片數(shù)量并發(fā)數(shù)建議100MB2MB5031GB5MB2003-55GB10MB5005我自己的經(jīng)驗(yàn)是普通 Web 服務(wù)5MB 一片最均衡。太小會(huì)導(dǎo)致請(qǐng)求次數(shù)爆炸HTTP 握手開銷占大頭太大會(huì)失去“斷點(diǎn)”的意義網(wǎng)絡(luò)波動(dòng)時(shí)單塊失敗重傳成本高。要注意分片大小要結(jié)合服務(wù)端的接收超時(shí)時(shí)間和帶寬情況調(diào)整。內(nèi)網(wǎng)環(huán)境帶寬充足可以放大到 20MB/片公網(wǎng)弱網(wǎng)環(huán)境建議 2MB/片更穩(wěn)妥。2.3 哈希計(jì)算是個(gè)繞不開的環(huán)節(jié)斷點(diǎn)續(xù)傳里經(jīng)常要做文件指紋Hash計(jì)算原因在于文件內(nèi)容沒(méi)變才能判定同一文件。兩個(gè)不同文件如果正好同名同大小直接用文件名做標(biāo)識(shí)是危險(xiǎn)的容易出現(xiàn)“文件 A 的斷點(diǎn)續(xù)傳到文件 B”的錯(cuò)亂。比較穩(wěn)妥的做法是用SparkMD5對(duì)文件計(jì)算 MD5。計(jì)算過(guò)程可以放在Web Worker中執(zhí)行避免計(jì)算大文件時(shí)主線程卡死拖慢頁(yè)面滾動(dòng)和渲染。我見(jiàn)過(guò)不少項(xiàng)目圖省事直接在主線程算 2GB 文件的 MD5計(jì)算期間整個(gè)頁(yè)面像凍住一樣用戶直接以為死機(jī)了。3. 前端環(huán)境安裝與項(xiàng)目初始化3.1 創(chuàng)建 Vue 3 項(xiàng)目并安裝依賴先建項(xiàng)目建議直接用 Vite開發(fā)時(shí)熱更新快構(gòu)建產(chǎn)物也干凈。npm init vite-app chunk-upload-demo cd chunk-upload-demo npm install npm install spark-md5 axiosspark-md5用來(lái)計(jì)算文件指紋axios用來(lái)發(fā)請(qǐng)求。如果項(xiàng)目本身有自己封裝的請(qǐng)求庫(kù)換成自己的就行原理都一樣。3.2 封裝核心上傳模塊我得提醒一下千萬(wàn)別把上傳邏輯全塞進(jìn)組件里那組件會(huì)變成一坨“會(huì)動(dòng)的意大利面”。最好單獨(dú)抽一個(gè)useUploader.js模塊把所有狀態(tài)和邏輯封裝進(jìn)去組件里只做界面渲染和事件綁定。import { ref, reactive } from vue export function useUploader() { const file ref(null) const fileHash ref() const chunkSize 5 * 1024 * 1024 // 5MB const uploadedChunks reactive(new Set()) const progress ref(0) const uploading ref(false) const paused ref(false) const selectFile (rawFile) { file.value rawFile uploadedChunks.clear() progress.value 0 fileHash.value } return { file, fileHash, chunkSize, uploadedChunks, progress, uploading, paused, selectFile } }這個(gè)模塊專門管理“上傳狀態(tài)”。后續(xù)所有方法都圍繞這個(gè)狀態(tài)展開組件里只需要引入倉(cāng)庫(kù)管理。4. 分片與文件指紋計(jì)算4.1 用 SparkMD5 計(jì)算文件唯一標(biāo)識(shí)這一步的目的是給文件生成一個(gè)唯一的 chunk 任務(wù) ID。我在實(shí)際項(xiàng)目里用的格式是${fileHash}-${lastModified}-${file.size}SparkMD5的增量計(jì)算寫法如下import SparkMD5 from spark-md5 const calculateHash (file, chunkSize) { return new Promise((resolve, reject) { const blobSlice File.prototype.slice const chunks Math.ceil(file.size / chunkSize) const spark new SparkMD5.ArrayBuffer() const fileReader new FileReader() let currentChunk 0 fileReader.onerror reject fileReader.onload (e) { spark.append(e.target.result) currentChunk if (currentChunk chunks) { loadNext() } else { resolve(spark.end()) } } const loadNext () { const start currentChunk * chunkSize const end start chunkSize file.size ? file.size : start chunkSize fileReader.readAsArrayBuffer(blobSlice.call(file, start, end)) } loadNext() }) }注意我在計(jì)算 Hash 的時(shí)候用了FileReader.readAsArrayBuffer比readAsBinaryString靠譜后者在內(nèi)存占用和兼容性上都有隱患。計(jì)算過(guò)程如果用 Worker 做這里直接在整個(gè) Worker 文件里封裝相同邏輯即可。4.2 計(jì)算超時(shí)的處理大文件 Hash 計(jì)算有可能會(huì)很久。如果文件有幾 GB即使開 Worker計(jì)算 MD5 也需要數(shù)十秒。應(yīng)對(duì)方案一般是先做一個(gè)“快速校驗(yàn)”比如查后端是否存在“秒傳文件”存在就直接返回上傳成功跳過(guò)切片不存在再進(jìn)入完整計(jì)算流程?！懊雮鳌钡倪壿嬙诤蠖耸且粋€(gè)很有用的優(yōu)化我在第 6 節(jié)會(huì)專門提到。5. 分片上傳與前臺(tái)上傳進(jìn)度實(shí)現(xiàn)5.1 分片切片邏輯文件切片很簡(jiǎn)單用file.slice(start, end)就能獲取一段二進(jìn)制塊。切片數(shù)據(jù)要加上額外的元信息讓后端知道這是哪個(gè)文件的第幾片。const createChunk (file, index, chunkSize) { const start index * chunkSize const end Math.min(file.size, start chunkSize) return file.slice(start, end) }這里有個(gè)細(xì)節(jié)切片時(shí)不要用end file.size作為邊界判斷直接start chunkSize會(huì)導(dǎo)致最后一個(gè)切片越界。上面代碼用Math.min兜底看起來(lái)簡(jiǎn)單實(shí)際能省掉不少邊界 bug。5.2 上傳單個(gè)分片每個(gè)分片通過(guò) FormData 發(fā)送。這里我要強(qiáng)調(diào)分片數(shù)據(jù)本身在 FormData 里就是二進(jìn)制后端拿到的也是Stream或Buffer不要嘗試轉(zhuǎn)成 base64那會(huì)讓體積膨脹 33%純屬浪費(fèi)。import axios from axios const uploadChunk (formData) { return axios.post(/api/upload/chunk, formData, { headers: { Content-Type: multipart/form-data }, timeout: 120000 }) }超時(shí)時(shí)間要給足分片上傳經(jīng)常在弱網(wǎng)環(huán)境下發(fā)生“慢請(qǐng)求”120 秒比較合適。如果請(qǐng)求被服務(wù)器提前斷開axios 會(huì)拋錯(cuò)我們?cè)谏蠈硬东@后標(biāo)記該分片為“未完成”狀態(tài)等待重試即可。5.3 并發(fā)控制與進(jìn)度條并發(fā)控制是斷點(diǎn)續(xù)傳的進(jìn)階操作。通過(guò)并發(fā)上傳上傳總耗時(shí)比挨個(gè)傳快很多同時(shí)又能避免一次性發(fā)起上百個(gè)請(qǐng)求把瀏覽器和服務(wù)端都打垮。const concurrentUpload async (tasks, limit 3) { const queue [...tasks] const workers new Array(limit).fill(null).map(async () { while (queue.length) { const task queue.shift() await task() } }) await Promise.all(workers) }進(jìn)度條邏輯是根據(jù)“已成功分片數(shù) / 總分片數(shù)”計(jì)算的。注意這里的進(jìn)度不是拿“已發(fā)請(qǐng)求數(shù)”計(jì)算而是拿“后端確認(rèn)寫入成功的分片數(shù)”計(jì)算保證進(jìn)度條反映的是真實(shí)落地狀態(tài)而不是“請(qǐng)求發(fā)出去但可能失敗”的假進(jìn)度。const updateProgress () { const totalChunks Math.ceil(file.value.size / chunkSize) progress.value Math.round((uploadedChunks.size / totalChunks) * 100) }5.4 暫停、恢復(fù)與取消暫停的本質(zhì)是終止當(dāng)前未完成的分片請(qǐng)求。這個(gè)操作要跟“取消”區(qū)分開取消是徹底終止該文件上傳任務(wù)暫停只是臨時(shí)中斷之后還能從斷點(diǎn)繼續(xù)。我用一個(gè)AbortController來(lái)管理每個(gè)分片請(qǐng)求的中斷const pause () { paused.value true // 中斷所有未完成請(qǐng)求 activeControllers.forEach(controller controller.abort()) } const resume async () { paused.value false // 重新請(qǐng)求后端已上傳分片列表過(guò)濾后繼續(xù)上傳 await fetchUploadedChunks() await uploadRemainingChunks() }中斷請(qǐng)求時(shí)要注意axios 的abort會(huì)直接讓 Promise reject上層要區(qū)分“主動(dòng)中斷”和“網(wǎng)絡(luò)錯(cuò)誤”。主動(dòng)中斷不應(yīng)觸發(fā)錯(cuò)誤提示應(yīng)靜默處理。6. 后端實(shí)現(xiàn)分片接收與合并6.1 Node.js 后端選型與接口設(shè)計(jì)后端我用的 Express。接口就三個(gè)接口作用POST /api/upload/chunk接收單個(gè)分片GET /api/upload/status查詢文件已上傳的分片列表POST /api/upload/merge合并全部分片三個(gè)接口各司其職前端流程自然就串起來(lái)了。6.2 接收單個(gè)分片后端接收分片時(shí)要記錄兩個(gè)關(guān)鍵信息文件標(biāo)識(shí)和分片索引。臨時(shí)文件存到./upload_temp/{fileHash}/{index}.part。const uploadChunk async (req, res) { const { fileHash, chunkIndex } req.body const chunkFile req.files.chunk const chunkDir path.resolve(./upload_temp/${fileHash}) if (!fs.existsSync(chunkDir)) { fs.mkdirSync(chunkDir, { recursive: true }) } const chunkPath path.join(chunkDir, ${chunkIndex}.part) await fs.promises.rename(chunkFile.path, chunkPath) res.json({ code: 0, message: chunk uploaded }) }用rename移動(dòng)臨時(shí)文件比f(wàn)s.writeFile重新寫入要快而且更安全。如果跨磁盤分區(qū)導(dǎo)致 rename 失敗再回退到copyFile unlink。6.3 查詢已上傳分片斷點(diǎn)續(xù)傳的關(guān)鍵接口。前端發(fā)起恢復(fù)上傳時(shí)先問(wèn)后端“這個(gè)文件的哪些分片已經(jīng)存在”然后只傳缺失的部分。const getUploadStatus async (req, res) { const { fileHash } req.query const chunkDir path.resolve(./upload_temp/${fileHash}) if (!fs.existsSync(chunkDir)) { return res.json({ code: 0, data: { uploadedChunks: [] } }) } const files await fs.promises.readdir(chunkDir) const uploadedChunks files .filter(f f.endsWith(.part)) .map(f parseInt(f.split(.)[0], 10)) res.json({ code: 0, data: { uploadedChunks } }) }這個(gè)接口還有一個(gè)作用并發(fā)場(chǎng)景去重。假如多個(gè)分片并發(fā)上傳服務(wù)端可能收到重復(fù)分片前端并發(fā)隊(duì)列里重復(fù)執(zhí)行后端要冪等處理——同名分片已存在就跳過(guò)不重復(fù)保存。上面用rename覆蓋同名文件時(shí)Windows 會(huì)報(bào) EEXIST 錯(cuò)誤所以可以先檢查存在性。6.4 分片合并所有分片都齊了后端執(zhí)行合并。合并方式是流式把每個(gè).part文件按索引順序?qū)懭胱罱K文件。const mergeChunks async (req, res) { const { fileHash, fileName, totalChunks } req.body const chunkDir path.resolve(./upload_temp/${fileHash}) const outputPath path.resolve(./upload_output/${fileName}) await fs.promises.mkdir(path.dirname(outputPath), { recursive: true }) // 校驗(yàn)分片數(shù)量是否匹配 const files await fs.promises.readdir(chunkDir) if (files.length ! Number(totalChunks)) { return res.status(400).json({ code: 1, message: chunk count mismatch }) } // 按索引排序后流式合并 const sortedFiles files .filter(f f.endsWith(.part)) .sort((a, b) { return parseInt(a.split(.)[0], 10) - parseInt(b.split(.)[0], 10) }) const outputStream fs.createWriteStream(outputPath) for (const file of sortedFiles) { const chunkStream fs.createReadStream(path.join(chunkDir, file)) await new Promise((resolve, reject) { chunkStream.pipe(outputStream, { end: false }) chunkStream.on(end, resolve) chunkStream.on(error, reject) }) } outputStream.end() // 清理臨時(shí)目錄 await fs.promises.rm(chunkDir, { recursive: true, force: true }) res.json({ code: 0, message: merge done }) }合并時(shí)用流式管道不把整個(gè)文件加載進(jìn)內(nèi)存這一點(diǎn)很重要。要是直接把所有分片讀進(jìn) Buffer 拼起來(lái)2GB 文件就能把服務(wù)器內(nèi)存打爆。6.5 秒傳檢測(cè)我前面提過(guò)“秒傳”后端實(shí)現(xiàn)就是在合并前先檢查數(shù)據(jù)庫(kù)或一個(gè) JSON 映射表里是否已有相同 fileHash 的文件記錄。如果有直接返回成功前端跳過(guò)整個(gè)上傳流程。實(shí)際項(xiàng)目里秒傳檢測(cè)一般放在查詢狀態(tài)接口之前或者放在上傳流程最開頭const checkExists async (req, res) { const { fileHash } req.query // fileMap 文件標(biāo)識(shí)與實(shí)際文件路徑的映射表 const record fileMap[fileHash] if (record) { return res.json({ code: 0, data: { exists: true, path: record.path } }) } res.json({ code: 0, data: { exists: false } }) }這個(gè)功能特別適合企業(yè)內(nèi)部的資料分享場(chǎng)景同一個(gè)文件被上傳幾十次每次都省了帶寬和存儲(chǔ)的重復(fù)寫入。7. 前端交互組件設(shè)計(jì)與 Demo 頁(yè)面7.1 上傳面板組件頁(yè)面結(jié)構(gòu)不復(fù)雜一個(gè)文件選擇按鈕、一個(gè)進(jìn)度條、一組控制按鈕。重點(diǎn)是組件里把useUploader暴露的方法綁定到界面事件上。template div classupload-panel input typefile changehandleFileChange / el-progress :percentageprogress v-iffile / div classactions button clickstartUpload :disableduploading開始上傳/button button clickpause :disabled!uploading暫停/button button clickresume :disabled!paused繼續(xù)/button /div /div /template script setup import { useUploader } from ../composables/useUploader const { file, progress, uploading, paused, selectFile, startUpload, pause, resume } useUploader() const handleFileChange (e) { selectFile(e.target.files[0]) } /script注意el-progress如果不引入 Element Plus可以用原生 div 寫個(gè)簡(jiǎn)單的進(jìn)度條樣式自己控制效果也不差。7.2 分片上傳流程串聯(lián)整個(gè)上傳流程是這樣的用戶選擇文件。計(jì)算文件 HashWorker 后臺(tái)執(zhí)行或主線程異步執(zhí)行。請(qǐng)求/api/upload/status獲取已上傳分片索引。把未上傳的分片放入并發(fā)隊(duì)列逐個(gè)上傳。所有分片上傳完成后請(qǐng)求/api/upload/merge合并。顯示最終下載鏈接。偽代碼const startUpload async () { uploading.value true fileHash.value await calculateHash(file.value, chunkSize) // 查已上傳分片 const { uploadedChunks } await fetchStatus(fileHash.value) const chunks [] const total Math.ceil(file.value.size / chunkSize) for (let i 0; i total; i) { if (uploadedChunks.includes(i)) { uploadedChunksSet.add(i) } else { chunks.push(i) } } await concurrentUpload(chunks.map(index () uploadOneChunk(index)), 3) await merge() uploading.value false }這一步是最容易出錯(cuò)的地方我見(jiàn)過(guò)很多項(xiàng)目在“查詢已上傳分片”之后沒(méi)有過(guò)濾直接把全部分片重新上傳一遍浪費(fèi)帶寬。上面代碼先查狀態(tài)再過(guò)濾才是真正意義上的“續(xù)傳”。7.3 使用 Web Worker 避免卡頓計(jì)算 Hash 如果文件超過(guò) 1GB主線程會(huì)明顯卡頓。我建議把 Hash 計(jì)算放進(jìn) Worker。Vite 對(duì) Worker 的支持很友好直接用new Worker(new URL(./hashWorker.js, import.meta.url), { type: module })就行。Worker 文件內(nèi)容就是把calculateHash邏輯搬進(jìn)去完成后postMessage返回結(jié)果// hashWorker.js import SparkMD5 from spark-md5 self.onmessage (e) { const { file, chunkSize } e.data const hash calculateHash(file, chunkSize) self.postMessage({ hash }) }如果不想引入 Worker也可以用requestIdleCallback分片計(jì)算但處理起來(lái)麻煩得多而且主線程依然會(huì)被切片讀文件占據(jù)大量時(shí)間所以還是 Worker 最省心。8. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄8.1 分片上傳了但服務(wù)器上文件不可用這個(gè)情況十有八九是合并順序錯(cuò)了。我排查的順序是檢查臨時(shí)目錄里分片文件的大小是否每個(gè)都等于設(shè)置的 chunkSize最后一片除外。檢查命名是否包含前導(dǎo)零比如1.part、2.part、10.part被字符串排序后10 會(huì)在 2 前面。檢查合并流的管道關(guān)閉時(shí)機(jī)管道沒(méi) close 就結(jié)束寫入文件會(huì)截?cái)?。字符串排序?wèn)題是最容易踩的坑。如果分片文件名不帶前導(dǎo)零一定要用數(shù)字排序不能默認(rèn)字符串排序。// 錯(cuò)誤示例字符串排序會(huì)導(dǎo)致 10 排在 2 前面 files.sort() // 正確示例 files.sort((a, b) parseInt(a, 10) - parseInt(b, 10))8.2 進(jìn)度條回跳或卡住不動(dòng)進(jìn)度條卡住通常有兩個(gè)原因并發(fā)隊(duì)列里有某個(gè)分片請(qǐng)求長(zhǎng)期掛起或者后端寫入速度遠(yuǎn)低于上傳速度導(dǎo)致服務(wù)端 socket 阻塞。處理辦法給每個(gè)分片請(qǐng)求設(shè)置超時(shí)超時(shí)后主動(dòng)重試 3 次。后端在接收分片時(shí)如果磁盤 IO 太慢前端并發(fā)數(shù)要調(diào)低比如從 5 降到 3。進(jìn)度條以“成功后端確認(rèn)”為準(zhǔn)不用axios.onUploadProgress的上傳字節(jié)數(shù)。因?yàn)閛nUploadProgress只代表字節(jié)進(jìn)入發(fā)送緩沖區(qū)不代表服務(wù)器讀完。8.3 暫停后恢復(fù)卻從頭開始這個(gè)問(wèn)題的根因通常出在fileHash沒(méi)保存。用戶暫停后頁(yè)面刷新或組件銷毀hash 狀態(tài)丟了重新選擇文件時(shí) hash 又變了尤其如果文件修改時(shí)間變了。解決辦法是持久化把fileHash存到localStorage文件 MD5 計(jì)算完成后立即保存。恢復(fù)上傳時(shí)從 localStorage 讀取優(yōu)先和后端狀態(tài)接口比對(duì)。const saveHash (hash) { localStorage.setItem(upload_hash_${file.value.name}, hash) } const loadHash (name) { return localStorage.getItem(upload_hash_${name}) }注意file.lastModified變化會(huì)導(dǎo)致同樣的文件內(nèi)容算出不同的 hash所以持久化時(shí)最好連同lastModified一起保存作為文件變更的校驗(yàn)依據(jù)。8.4 服務(wù)器返回 413 Request Entity Too Large這個(gè)錯(cuò)誤是服務(wù)器限制了單個(gè)請(qǐng)求體大小。很多人只看前端忽略了后端配置。Express 用multer接收分片時(shí)大小限制設(shè)置const upload multer({ storage: multer.diskStorage({ destination: ./upload_temp, filename: (req, file, cb) { cb(null, ${Date.now()}-${file.originalname}) } }), limits: { fileSize: 20 * 1024 * 1024 } // 單個(gè)分片限制 20MB })如果分片設(shè)置為 10MB這個(gè)限制設(shè)置為 20MB 就沒(méi)問(wèn)題要始終留一倍余量防止 FormData 額外字段導(dǎo)致的體積偏移。8.5 并發(fā)數(shù)過(guò)高導(dǎo)致瀏覽器內(nèi)存飆升并發(fā)數(shù)不是越大越好。我實(shí)測(cè)過(guò)5MB 分片、并發(fā) 3 個(gè)100MB 文件上傳流暢度最好并發(fā) 10 個(gè)雖然速度快一點(diǎn)但瀏覽器內(nèi)存占用高了差不多 300MB低端設(shè)備會(huì)直接卡死。我把不同環(huán)境的建議寫成一個(gè)參考移動(dòng)端 4G 網(wǎng)絡(luò)并發(fā) 2分片 2MBPC 有線網(wǎng)絡(luò)并發(fā) 3-4分片 5MB本地內(nèi)網(wǎng)服務(wù)并發(fā) 5-6分片 10MB這個(gè)組合要靈活調(diào)整沒(méi)有銀彈。8.6 合并時(shí)提示“分片數(shù)量不匹配”這個(gè)錯(cuò)誤通常由兩種情況引起并發(fā)上傳過(guò)程中某些分片請(qǐng)求失敗但沒(méi)重試成功前端以為成功、后端沒(méi)寫入。前端計(jì)算總片數(shù)時(shí)用了Math.ceil(size / chunkSize)但某個(gè)分片確實(shí)沒(méi)發(fā)出去。排查方式在mergeChunks接口打日志把files.length和totalChunks對(duì)比輸出。再在前端上傳完成循環(huán)里加一個(gè)“分片上傳結(jié)果集合”的斷言確保每一片都有成功響應(yīng)。8.7 計(jì)算 Hash 時(shí)間長(zhǎng)、用戶以為頁(yè)面掛了解決方案我在前面提過(guò) Worker。這里再給一個(gè)補(bǔ)充技巧計(jì)算 Hash 前用一個(gè)Loading狀態(tài)提示用戶文案寫清楚“正在分析文件請(qǐng)勿關(guān)閉”配合 Worker 后臺(tái)運(yùn)行用戶感知會(huì)好很多。如果文件大到連 MD5 計(jì)算都不現(xiàn)實(shí)比如 50GB 級(jí)別的數(shù)據(jù)集可以退一步只計(jì)算首尾分片的校驗(yàn)哈?；蛘吒纱嘤梦募笮? 首片哈希 末片哈希組合成標(biāo)識(shí)。安全性和準(zhǔn)確性都有折扣但實(shí)用性拉滿。9. 優(yōu)化方向與擴(kuò)展建議9.1 上傳進(jìn)度與服務(wù)端寫入分離大文件場(chǎng)景下前端進(jìn)度條到 100% 不代表文件立刻可用。后端還有合并時(shí)間。所以實(shí)際做項(xiàng)目時(shí)我一般把狀態(tài)機(jī)做成四態(tài)狀態(tài)含義uploading分片上傳中merging分片合并中success上傳完成failed上傳失敗前端在上傳完最后一片后可以輪詢/api/upload/status或/api/upload/merge-status接口直到返回 success 再展示成功圖標(biāo)。別小看這一步用戶端體驗(yàn)差異巨大。9.2 斷點(diǎn)續(xù)傳 并發(fā)去重前端并發(fā)可能導(dǎo)致兩個(gè)相同的分片同時(shí)上傳。我在后端加了一個(gè)簡(jiǎn)單檢查分片文件存在就跳過(guò)寫盤直接返回成功。這個(gè)冪等處理極大提升了系統(tǒng)的容錯(cuò)率尤其在高并發(fā)場(chǎng)景。9.3 用 IndexedDB 保存上傳任務(wù)如果項(xiàng)目要支持“關(guān)閉瀏覽器后仍能恢復(fù)任務(wù)”前端本地狀態(tài)就得用 IndexedDB 持久化localStorage 存字符串存大任務(wù)列表太吃力。IndexedDB 可以保存 Blob 切片引用、狀態(tài)機(jī)數(shù)據(jù)源下次打開頁(yè)面直接恢復(fù)。這套改造聽著復(fù)雜其實(shí)核心就是多維護(hù)一張“任務(wù)表”。10. 寫在最后的經(jīng)驗(yàn)斷點(diǎn)續(xù)傳這個(gè) DEMO本質(zhì)是一個(gè)“狀態(tài)管理 異步并發(fā) 文件 IO”的組合拳。前端玩的是切片、并發(fā)、異步恢復(fù)后端玩的是文件流、冪等、合并。我做過(guò)的幾次線上問(wèn)題排查得出的經(jīng)驗(yàn)是前端問(wèn)題看著像后端后端問(wèn)題往往要從前端驗(yàn)證。比如用戶說(shuō)“文件壞了”結(jié)果根因是前端并發(fā)重試時(shí)偶然重復(fù)上傳同一個(gè)分片用戶說(shuō)“上傳卡住了”根因是后端磁盤滿了沒(méi)返回響應(yīng)。所以做這類系統(tǒng)日志一定要打“分片索引、文件 Hash、請(qǐng)求耗時(shí)”三段關(guān)鍵信息否則排查起來(lái)像大海撈針。如果你第一次寫這個(gè) DEMO建議先跟著這篇文章把鏈路跑通然后嘗試回答這幾個(gè)問(wèn)題你的并發(fā)控制能應(yīng)對(duì)服務(wù)器返回 500 嗎你的斷點(diǎn)恢復(fù)能應(yīng)對(duì)用戶手動(dòng)刷新頁(yè)面嗎你的合并邏輯能處理分片文件被中途清空嗎把這三個(gè)場(chǎng)景想明白你的斷點(diǎn)續(xù)傳就算真正落地了。