現(xiàn)大文件斷點(diǎn)續(xù)傳與分片上傳實(shí)戰(zhàn))
大文件上傳這活兒看著簡單真做起來全是坑。幾 GB 的安裝包、視頻素材、數(shù)據(jù)集傳到一半斷網(wǎng)后端收到的文件沒法用用戶又得從頭來一次脾氣再好也得崩潰。所以這幾年“斷點(diǎn)續(xù)傳”成了大文件上傳方案的標(biāo)配尤其在前端 Vue 工程里配合 JavaScript 的 Blob 切片和發(fā)送異步請求能把整個(gè)上傳過程拆成可控的小任務(wù)強(qiáng)悍又有韌勁。我這次就把自己摸索出來的一套 Vue 3 Node.js 斷點(diǎn)續(xù)傳 DEMO 拆開揉碎了講一遍。從分片思路、哈希計(jì)算到后端合并全流程走通代碼可以直接抄坑也會提前幫你們踩了。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è)小塊逐一上傳如果中間哪一塊沒傳成功下次重新發(fā)起時(shí)只補(bǔ)傳失敗的那幾塊而不是整個(gè)文件再來一遍。這里頭有兩個(gè)關(guān)鍵動作分片slice前端用 Blob API 把大文件按偏移量切成多個(gè)二進(jìn)制塊。記錄與校驗(yàn)后端記錄哪些分片已收到前端在每次恢復(fù)上傳前向后端要一個(gè)“已上傳分片清單”只補(bǔ)缺的部分。用生活類比的話就好比搬家。整棟樓的家具一趟一輛車?yán)呗飞媳ヒ淮稳甑?。切片上傳就像把家具先裝箱每個(gè)箱子獨(dú)立搬運(yùn)哪個(gè)箱子丟了就補(bǔ)哪個(gè)箱子其他箱子不用返工。1.2 斷點(diǎn)續(xù)傳 Solve 什么問題規(guī)模超過 2GB 的文件用傳統(tǒng)單次上傳會有三個(gè)致命問題網(wǎng)絡(luò)穩(wěn)定性不可控移動網(wǎng)絡(luò)、公司代理斷連、服務(wù)器主動超時(shí)都可能中途斷開。服務(wù)端接收壓力大一次 PUT 或 POST 一個(gè)大 Body后端如果沒做好流式接收內(nèi)存直接被頂爆。重試成本太高失敗后全量重傳浪費(fèi)帶寬和時(shí)間尤其在弱網(wǎng)環(huán)境基本等于放棄。斷點(diǎn)續(xù)傳讓整個(gè)上傳過程變成“多批次小任務(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)邏輯抽出來復(fù)用也容易。另外 Vue 3 搭配 Element Plus 的el-upload和el-progress做上傳界面可以少寫一堆 CSS 和交互邏輯。我這套 DEMO 不依賴太重的組件庫但思路完全兼容 Element Plus。2.2 分片大小怎么定分片大小是斷點(diǎn)續(xù)傳方案里最需要權(quán)衡的一個(gè)參數(shù)。常見建議是 1MB 到 20MB 之間得看實(shí)際場景文件大小分片大小分片數(shù)量并發(fā)數(shù)建議100MB2MB5031GB5MB2003-55GB10MB5005我自己的經(jīng)驗(yàn)是普通 Web 服務(wù)5MB 一片最均衡。太小會導(dǎo)致請求次數(shù)爆炸HTTP 握手開銷占大頭太大會失去“斷點(diǎn)”的意義網(wǎng)絡(luò)波動時(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)容沒變才能判定同一文件。兩個(gè)不同文件如果正好同名同大小直接用文件名做標(biāo)識是危險(xiǎn)的容易出現(xiàn)“文件 A 的斷點(diǎn)續(xù)傳到文件 B”的錯(cuò)亂。比較穩(wěn)妥的做法是用SparkMD5對文件計(jì)算 MD5。計(jì)算過程可以放在Web Worker中執(zhí)行避免計(jì)算大文件時(shí)主線程卡死拖慢頁面滾動和渲染。我見過不少項(xiàng)目圖省事直接在主線程算 2GB 文件的 MD5計(jì)算期間整個(gè)頁面像凍住一樣用戶直接以為死機(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用來計(jì)算文件指紋axios用來發(fā)請求。如果項(xiàng)目本身有自己封裝的請求庫換成自己的就行原理都一樣。3.2 封裝核心上傳模塊我得提醒一下千萬別把上傳邏輯全塞進(jìn)組件里那組件會變成一坨“會動的意大利面”。最好單獨(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)展開組件里只需要引入倉庫管理。4. 分片與文件指紋計(jì)算4.1 用 SparkMD5 計(jì)算文件唯一標(biāo)識這一步的目的是給文件生成一個(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ì)算過程如果用 Worker 做這里直接在整個(gè) Worker 文件里封裝相同邏輯即可。4.2 計(jì)算超時(shí)的處理大文件 Hash 計(jì)算有可能會很久。如果文件有幾 GB即使開 Worker計(jì)算 MD5 也需要數(shù)十秒。應(yīng)對方案一般是先做一個(gè)“快速校驗(yàn)”比如查后端是否存在“秒傳文件”存在就直接返回上傳成功跳過切片不存在再進(jìn)入完整計(jì)算流程?！懊雮鳌钡倪壿嬙诤蠖耸且粋€(gè)很有用的優(yōu)化我在第 6 節(jié)會專門提到。5. 分片上傳與前臺上傳進(jìn)度實(shí)現(xiàn)5.1 分片切片邏輯文件切片很簡單用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會導(dǎo)致最后一個(gè)切片越界。上面代碼用Math.min兜底看起來簡單實(shí)際能省掉不少邊界 bug。5.2 上傳單個(gè)分片每個(gè)分片通過 FormData 發(fā)送。這里我要強(qiáng)調(diào)分片數(shù)據(jù)本身在 FormData 里就是二進(jìn)制后端拿到的也是Stream或Buffer不要嘗試轉(zhuǎn)成 base64那會讓體積膨脹 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ā)生“慢請求”120 秒比較合適。如果請求被服務(wù)器提前斷開axios 會拋錯(cuò)我們在上層捕獲后標(biāo)記該分片為“未完成”狀態(tài)等待重試即可。5.3 并發(fā)控制與進(jìn)度條并發(fā)控制是斷點(diǎn)續(xù)傳的進(jìn)階操作。通過并發(fā)上傳上傳總耗時(shí)比挨個(gè)傳快很多同時(shí)又能避免一次性發(fā)起上百個(gè)請求把瀏覽器和服務(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ā)請求數(shù)”計(jì)算而是拿“后端確認(rèn)寫入成功的分片數(shù)”計(jì)算保證進(jìn)度條反映的是真實(shí)落地狀態(tài)而不是“請求發(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)前未完成的分片請求。這個(gè)操作要跟“取消”區(qū)分開取消是徹底終止該文件上傳任務(wù)暫停只是臨時(shí)中斷之后還能從斷點(diǎn)繼續(xù)。我用一個(gè)AbortController來管理每個(gè)分片請求的中斷const pause () { paused.value true // 中斷所有未完成請求 activeControllers.forEach(controller controller.abort()) } const resume async () { paused.value false // 重新請求后端已上傳分片列表過濾后繼續(xù)上傳 await fetchUploadedChunks() await uploadRemainingChunks() }中斷請求時(shí)要注意axios 的abort會直接讓 Promise reject上層要區(qū)分“主動中斷”和“網(wǎng)絡(luò)錯(cuò)誤”。主動中斷不應(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è)接口各司其職前端流程自然就串起來了。6.2 接收單個(gè)分片后端接收分片時(shí)要記錄兩個(gè)關(guān)鍵信息文件標(biāo)識和分片索引。臨時(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移動臨時(shí)文件比fs.writeFile重新寫入要快而且更安全。如果跨磁盤分區(qū)導(dǎo)致 rename 失敗再回退到copyFile unlink。6.3 查詢已上傳分片斷點(diǎn)續(xù)傳的關(guān)鍵接口。前端發(fā)起恢復(fù)上傳時(shí)先問后端“這個(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ā)場景去重。假如多個(gè)分片并發(fā)上傳服務(wù)端可能收到重復(fù)分片前端并發(fā)隊(duì)列里重復(fù)執(zhí)行后端要冪等處理——同名分片已存在就跳過不重復(fù)保存。上面用rename覆蓋同名文件時(shí)Windows 會報(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 拼起來2GB 文件就能把服務(wù)器內(nèi)存打爆。6.5 秒傳檢測我前面提過“秒傳”后端實(shí)現(xiàn)就是在合并前先檢查數(shù)據(jù)庫或一個(gè) JSON 映射表里是否已有相同 fileHash 的文件記錄。如果有直接返回成功前端跳過整個(gè)上傳流程。實(shí)際項(xiàng)目里秒傳檢測一般放在查詢狀態(tài)接口之前或者放在上傳流程最開頭const checkExists async (req, res) { const { fileHash } req.query // fileMap 文件標(biāo)識與實(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)部的資料分享場景同一個(gè)文件被上傳幾十次每次都省了帶寬和存儲的重復(fù)寫入。7. 前端交互組件設(shè)計(jì)與 Demo 頁面7.1 上傳面板組件頁面結(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è)簡單的進(jìn)度條樣式自己控制效果也不差。7.2 分片上傳流程串聯(lián)整個(gè)上傳流程是這樣的用戶選擇文件。計(jì)算文件 HashWorker 后臺執(zhí)行或主線程異步執(zhí)行。請求/api/upload/status獲取已上傳分片索引。把未上傳的分片放入并發(fā)隊(duì)列逐個(gè)上傳。所有分片上傳完成后請求/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ò)的地方我見過很多項(xiàng)目在“查詢已上傳分片”之后沒有過濾直接把全部分片重新上傳一遍浪費(fèi)帶寬。上面代碼先查狀態(tài)再過濾才是真正意義上的“續(xù)傳”。7.3 使用 Web Worker 避免卡頓計(jì)算 Hash 如果文件超過 1GB主線程會明顯卡頓。我建議把 Hash 計(jì)算放進(jìn) Worker。Vite 對 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ì)算但處理起來麻煩得多而且主線程依然會被切片讀文件占據(jù)大量時(shí)間所以還是 Worker 最省心。8. 常見問題與排查技巧實(shí)錄8.1 分片上傳了但服務(wù)器上文件不可用這個(gè)情況十有八九是合并順序錯(cuò)了。我排查的順序是檢查臨時(shí)目錄里分片文件的大小是否每個(gè)都等于設(shè)置的 chunkSize最后一片除外。檢查命名是否包含前導(dǎo)零比如1.part、2.part、10.part被字符串排序后10 會在 2 前面。檢查合并流的管道關(guān)閉時(shí)機(jī)管道沒 close 就結(jié)束寫入文件會截?cái)?。字符串排序問題是最容易踩的坑。如果分片文件名不帶前導(dǎo)零一定要用數(shù)字排序不能默認(rèn)字符串排序。// 錯(cuò)誤示例字符串排序會導(dǎo)致 10 排在 2 前面 files.sort() // 正確示例 files.sort((a, b) parseInt(a, 10) - parseInt(b, 10))8.2 進(jìn)度條回跳或卡住不動進(jìn)度條卡住通常有兩個(gè)原因并發(fā)隊(duì)列里有某個(gè)分片請求長期掛起或者后端寫入速度遠(yuǎn)低于上傳速度導(dǎo)致服務(wù)端 socket 阻塞。處理辦法給每個(gè)分片請求設(shè)置超時(shí)超時(shí)后主動重試 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è)問題的根因通常出在fileHash沒保存。用戶暫停后頁面刷新或組件銷毀hash 狀態(tài)丟了重新選擇文件時(shí) hash 又變了尤其如果文件修改時(shí)間變了。解決辦法是持久化把fileHash存到localStorage文件 MD5 計(jì)算完成后立即保存?；謴?fù)上傳時(shí)從 localStorage 讀取優(yōu)先和后端狀態(tài)接口比對。const saveHash (hash) { localStorage.setItem(upload_hash_${file.value.name}, hash) } const loadHash (name) { return localStorage.getItem(upload_hash_${name}) }注意file.lastModified變化會導(dǎo)致同樣的文件內(nèi)容算出不同的 hash所以持久化時(shí)最好連同lastModified一起保存作為文件變更的校驗(yàn)依據(jù)。8.4 服務(wù)器返回 413 Request Entity Too Large這個(gè)錯(cuò)誤是服務(wù)器限制了單個(gè)請求體大小。很多人只看前端忽略了后端配置。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 就沒問題要始終留一倍余量防止 FormData 額外字段導(dǎo)致的體積偏移。8.5 并發(fā)數(shù)過高導(dǎo)致瀏覽器內(nèi)存飆升并發(fā)數(shù)不是越大越好。我實(shí)測過5MB 分片、并發(fā) 3 個(gè)100MB 文件上傳流暢度最好并發(fā) 10 個(gè)雖然速度快一點(diǎn)但瀏覽器內(nèi)存占用高了差不多 300MB低端設(shè)備會直接卡死。我把不同環(huán)境的建議寫成一個(gè)參考移動端 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)整沒有銀彈。8.6 合并時(shí)提示“分片數(shù)量不匹配”這個(gè)錯(cuò)誤通常由兩種情況引起并發(fā)上傳過程中某些分片請求失敗但沒重試成功前端以為成功、后端沒寫入。前端計(jì)算總片數(shù)時(shí)用了Math.ceil(size / chunkSize)但某個(gè)分片確實(shí)沒發(fā)出去。排查方式在mergeChunks接口打日志把files.length和totalChunks對比輸出。再在前端上傳完成循環(huán)里加一個(gè)“分片上傳結(jié)果集合”的斷言確保每一片都有成功響應(yīng)。8.7 計(jì)算 Hash 時(shí)間長、用戶以為頁面掛了解決方案我在前面提過 Worker。這里再給一個(gè)補(bǔ)充技巧計(jì)算 Hash 前用一個(gè)Loading狀態(tài)提示用戶文案寫清楚“正在分析文件請勿關(guān)閉”配合 Worker 后臺運(yùn)行用戶感知會好很多。如果文件大到連 MD5 計(jì)算都不現(xiàn)實(shí)比如 50GB 級別的數(shù)據(jù)集可以退一步只計(jì)算首尾分片的校驗(yàn)哈?；蛘吒纱嘤梦募笮? 首片哈希 末片哈希組合成標(biāo)識。安全性和準(zhǔn)確性都有折扣但實(shí)用性拉滿。9. 優(yōu)化方向與擴(kuò)展建議9.1 上傳進(jìn)度與服務(wù)端寫入分離大文件場景下前端進(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è)簡單檢查分片文件存在就跳過寫盤直接返回成功。這個(gè)冪等處理極大提升了系統(tǒng)的容錯(cuò)率尤其在高并發(fā)場景。9.3 用 IndexedDB 保存上傳任務(wù)如果項(xiàng)目要支持“關(guān)閉瀏覽器后仍能恢復(fù)任務(wù)”前端本地狀態(tài)就得用 IndexedDB 持久化localStorage 存字符串存大任務(wù)列表太吃力。IndexedDB 可以保存 Blob 切片引用、狀態(tài)機(jī)數(shù)據(jù)源下次打開頁面直接恢復(fù)。這套改造聽著復(fù)雜其實(shí)核心就是多維護(hù)一張“任務(wù)表”。10. 寫在最后的經(jīng)驗(yàn)斷點(diǎn)續(xù)傳這個(gè) DEMO本質(zhì)是一個(gè)“狀態(tài)管理 異步并發(fā) 文件 IO”的組合拳。前端玩的是切片、并發(fā)、異步恢復(fù)后端玩的是文件流、冪等、合并。我做過的幾次線上問題排查得出的經(jīng)驗(yàn)是前端問題看著像后端后端問題往往要從前端驗(yàn)證。比如用戶說“文件壞了”結(jié)果根因是前端并發(fā)重試時(shí)偶然重復(fù)上傳同一個(gè)分片用戶說“上傳卡住了”根因是后端磁盤滿了沒返回響應(yīng)。所以做這類系統(tǒng)日志一定要打“分片索引、文件 Hash、請求耗時(shí)”三段關(guān)鍵信息否則排查起來像大海撈針。如果你第一次寫這個(gè) DEMO建議先跟著這篇文章把鏈路跑通然后嘗試回答這幾個(gè)問題你的并發(fā)控制能應(yīng)對服務(wù)器返回 500 嗎你的斷點(diǎn)恢復(fù)能應(yīng)對用戶手動刷新頁面嗎你的合并邏輯能處理分片文件被中途清空嗎把這三個(gè)場景想明白你的斷點(diǎn)續(xù)傳就算真正落地了。 Vue 3 + Node.js 實(shí)現(xiàn)大文件斷點(diǎn)續(xù)傳與分片上傳實(shí)戰(zhàn)
大文件上傳這活兒看著簡單真做起來全是坑。幾 GB 的安裝包、視頻素材、數(shù)據(jù)集傳到一半斷網(wǎng)后端收到的文件沒法用用戶又得從頭來一次脾氣再好也得崩潰。所以這幾年“斷點(diǎn)續(xù)傳”成了大文件上傳方案的標(biāo)配尤其在前端 Vue 工程里配合 JavaScript 的 Blob 切片和發(fā)送異步請求能把整個(gè)上傳過程拆成可控的小任務(wù)強(qiáng)悍又有韌勁。我這次就把自己摸索出來的一套 Vue 3 Node.js 斷點(diǎn)續(xù)傳 DEMO 拆開揉碎了講一遍。從分片思路、哈希計(jì)算到后端合并全流程走通代碼可以直接抄坑也會提前幫你們踩了。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è)小塊逐一上傳如果中間哪一塊沒傳成功下次重新發(fā)起時(shí)只補(bǔ)傳失敗的那幾塊而不是整個(gè)文件再來一遍。這里頭有兩個(gè)關(guān)鍵動作分片slice前端用 Blob API 把大文件按偏移量切成多個(gè)二進(jìn)制塊。記錄與校驗(yàn)后端記錄哪些分片已收到前端在每次恢復(fù)上傳前向后端要一個(gè)“已上傳分片清單”只補(bǔ)缺的部分。用生活類比的話就好比搬家。整棟樓的家具一趟一輛車?yán)呗飞媳ヒ淮稳甑?。切片上傳就像把家具先裝箱每個(gè)箱子獨(dú)立搬運(yùn)哪個(gè)箱子丟了就補(bǔ)哪個(gè)箱子其他箱子不用返工。1.2 斷點(diǎn)續(xù)傳 Solve 什么問題規(guī)模超過 2GB 的文件用傳統(tǒng)單次上傳會有三個(gè)致命問題網(wǎng)絡(luò)穩(wěn)定性不可控移動網(wǎng)絡(luò)、公司代理斷連、服務(wù)器主動超時(shí)都可能中途斷開。服務(wù)端接收壓力大一次 PUT 或 POST 一個(gè)大 Body后端如果沒做好流式接收內(nèi)存直接被頂爆。重試成本太高失敗后全量重傳浪費(fèi)帶寬和時(shí)間尤其在弱網(wǎng)環(huán)境基本等于放棄。斷點(diǎn)續(xù)傳讓整個(gè)上傳過程變成“多批次小任務(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)邏輯抽出來復(fù)用也容易。另外 Vue 3 搭配 Element Plus 的el-upload和el-progress做上傳界面可以少寫一堆 CSS 和交互邏輯。我這套 DEMO 不依賴太重的組件庫但思路完全兼容 Element Plus。2.2 分片大小怎么定分片大小是斷點(diǎn)續(xù)傳方案里最需要權(quán)衡的一個(gè)參數(shù)。常見建議是 1MB 到 20MB 之間得看實(shí)際場景文件大小分片大小分片數(shù)量并發(fā)數(shù)建議100MB2MB5031GB5MB2003-55GB10MB5005我自己的經(jīng)驗(yàn)是普通 Web 服務(wù)5MB 一片最均衡。太小會導(dǎo)致請求次數(shù)爆炸HTTP 握手開銷占大頭太大會失去“斷點(diǎn)”的意義網(wǎng)絡(luò)波動時(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)容沒變才能判定同一文件。兩個(gè)不同文件如果正好同名同大小直接用文件名做標(biāo)識是危險(xiǎn)的容易出現(xiàn)“文件 A 的斷點(diǎn)續(xù)傳到文件 B”的錯(cuò)亂。比較穩(wěn)妥的做法是用SparkMD5對文件計(jì)算 MD5。計(jì)算過程可以放在Web Worker中執(zhí)行避免計(jì)算大文件時(shí)主線程卡死拖慢頁面滾動和渲染。我見過不少項(xiàng)目圖省事直接在主線程算 2GB 文件的 MD5計(jì)算期間整個(gè)頁面像凍住一樣用戶直接以為死機(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用來計(jì)算文件指紋axios用來發(fā)請求。如果項(xiàng)目本身有自己封裝的請求庫換成自己的就行原理都一樣。3.2 封裝核心上傳模塊我得提醒一下千萬別把上傳邏輯全塞進(jìn)組件里那組件會變成一坨“會動的意大利面”。最好單獨(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)展開組件里只需要引入倉庫管理。4. 分片與文件指紋計(jì)算4.1 用 SparkMD5 計(jì)算文件唯一標(biāo)識這一步的目的是給文件生成一個(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ì)算過程如果用 Worker 做這里直接在整個(gè) Worker 文件里封裝相同邏輯即可。4.2 計(jì)算超時(shí)的處理大文件 Hash 計(jì)算有可能會很久。如果文件有幾 GB即使開 Worker計(jì)算 MD5 也需要數(shù)十秒。應(yīng)對方案一般是先做一個(gè)“快速校驗(yàn)”比如查后端是否存在“秒傳文件”存在就直接返回上傳成功跳過切片不存在再進(jìn)入完整計(jì)算流程?！懊雮鳌钡倪壿嬙诤蠖耸且粋€(gè)很有用的優(yōu)化我在第 6 節(jié)會專門提到。5. 分片上傳與前臺上傳進(jìn)度實(shí)現(xiàn)5.1 分片切片邏輯文件切片很簡單用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會導(dǎo)致最后一個(gè)切片越界。上面代碼用Math.min兜底看起來簡單實(shí)際能省掉不少邊界 bug。5.2 上傳單個(gè)分片每個(gè)分片通過 FormData 發(fā)送。這里我要強(qiáng)調(diào)分片數(shù)據(jù)本身在 FormData 里就是二進(jìn)制后端拿到的也是Stream或Buffer不要嘗試轉(zhuǎn)成 base64那會讓體積膨脹 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ā)生“慢請求”120 秒比較合適。如果請求被服務(wù)器提前斷開axios 會拋錯(cuò)我們在上層捕獲后標(biāo)記該分片為“未完成”狀態(tài)等待重試即可。5.3 并發(fā)控制與進(jìn)度條并發(fā)控制是斷點(diǎn)續(xù)傳的進(jìn)階操作。通過并發(fā)上傳上傳總耗時(shí)比挨個(gè)傳快很多同時(shí)又能避免一次性發(fā)起上百個(gè)請求把瀏覽器和服務(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ā)請求數(shù)”計(jì)算而是拿“后端確認(rèn)寫入成功的分片數(shù)”計(jì)算保證進(jìn)度條反映的是真實(shí)落地狀態(tài)而不是“請求發(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)前未完成的分片請求。這個(gè)操作要跟“取消”區(qū)分開取消是徹底終止該文件上傳任務(wù)暫停只是臨時(shí)中斷之后還能從斷點(diǎn)繼續(xù)。我用一個(gè)AbortController來管理每個(gè)分片請求的中斷const pause () { paused.value true // 中斷所有未完成請求 activeControllers.forEach(controller controller.abort()) } const resume async () { paused.value false // 重新請求后端已上傳分片列表過濾后繼續(xù)上傳 await fetchUploadedChunks() await uploadRemainingChunks() }中斷請求時(shí)要注意axios 的abort會直接讓 Promise reject上層要區(qū)分“主動中斷”和“網(wǎng)絡(luò)錯(cuò)誤”。主動中斷不應(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è)接口各司其職前端流程自然就串起來了。6.2 接收單個(gè)分片后端接收分片時(shí)要記錄兩個(gè)關(guān)鍵信息文件標(biāo)識和分片索引。臨時(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移動臨時(shí)文件比fs.writeFile重新寫入要快而且更安全。如果跨磁盤分區(qū)導(dǎo)致 rename 失敗再回退到copyFile unlink。6.3 查詢已上傳分片斷點(diǎn)續(xù)傳的關(guān)鍵接口。前端發(fā)起恢復(fù)上傳時(shí)先問后端“這個(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ā)場景去重。假如多個(gè)分片并發(fā)上傳服務(wù)端可能收到重復(fù)分片前端并發(fā)隊(duì)列里重復(fù)執(zhí)行后端要冪等處理——同名分片已存在就跳過不重復(fù)保存。上面用rename覆蓋同名文件時(shí)Windows 會報(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 拼起來2GB 文件就能把服務(wù)器內(nèi)存打爆。6.5 秒傳檢測我前面提過“秒傳”后端實(shí)現(xiàn)就是在合并前先檢查數(shù)據(jù)庫或一個(gè) JSON 映射表里是否已有相同 fileHash 的文件記錄。如果有直接返回成功前端跳過整個(gè)上傳流程。實(shí)際項(xiàng)目里秒傳檢測一般放在查詢狀態(tài)接口之前或者放在上傳流程最開頭const checkExists async (req, res) { const { fileHash } req.query // fileMap 文件標(biāo)識與實(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)部的資料分享場景同一個(gè)文件被上傳幾十次每次都省了帶寬和存儲的重復(fù)寫入。7. 前端交互組件設(shè)計(jì)與 Demo 頁面7.1 上傳面板組件頁面結(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è)簡單的進(jìn)度條樣式自己控制效果也不差。7.2 分片上傳流程串聯(lián)整個(gè)上傳流程是這樣的用戶選擇文件。計(jì)算文件 HashWorker 后臺執(zhí)行或主線程異步執(zhí)行。請求/api/upload/status獲取已上傳分片索引。把未上傳的分片放入并發(fā)隊(duì)列逐個(gè)上傳。所有分片上傳完成后請求/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ò)的地方我見過很多項(xiàng)目在“查詢已上傳分片”之后沒有過濾直接把全部分片重新上傳一遍浪費(fèi)帶寬。上面代碼先查狀態(tài)再過濾才是真正意義上的“續(xù)傳”。7.3 使用 Web Worker 避免卡頓計(jì)算 Hash 如果文件超過 1GB主線程會明顯卡頓。我建議把 Hash 計(jì)算放進(jìn) Worker。Vite 對 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ì)算但處理起來麻煩得多而且主線程依然會被切片讀文件占據(jù)大量時(shí)間所以還是 Worker 最省心。8. 常見問題與排查技巧實(shí)錄8.1 分片上傳了但服務(wù)器上文件不可用這個(gè)情況十有八九是合并順序錯(cuò)了。我排查的順序是檢查臨時(shí)目錄里分片文件的大小是否每個(gè)都等于設(shè)置的 chunkSize最后一片除外。檢查命名是否包含前導(dǎo)零比如1.part、2.part、10.part被字符串排序后10 會在 2 前面。檢查合并流的管道關(guān)閉時(shí)機(jī)管道沒 close 就結(jié)束寫入文件會截?cái)?。字符串排序問題是最容易踩的坑。如果分片文件名不帶前導(dǎo)零一定要用數(shù)字排序不能默認(rèn)字符串排序。// 錯(cuò)誤示例字符串排序會導(dǎo)致 10 排在 2 前面 files.sort() // 正確示例 files.sort((a, b) parseInt(a, 10) - parseInt(b, 10))8.2 進(jìn)度條回跳或卡住不動進(jìn)度條卡住通常有兩個(gè)原因并發(fā)隊(duì)列里有某個(gè)分片請求長期掛起或者后端寫入速度遠(yuǎn)低于上傳速度導(dǎo)致服務(wù)端 socket 阻塞。處理辦法給每個(gè)分片請求設(shè)置超時(shí)超時(shí)后主動重試 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è)問題的根因通常出在fileHash沒保存。用戶暫停后頁面刷新或組件銷毀hash 狀態(tài)丟了重新選擇文件時(shí) hash 又變了尤其如果文件修改時(shí)間變了。解決辦法是持久化把fileHash存到localStorage文件 MD5 計(jì)算完成后立即保存?；謴?fù)上傳時(shí)從 localStorage 讀取優(yōu)先和后端狀態(tài)接口比對。const saveHash (hash) { localStorage.setItem(upload_hash_${file.value.name}, hash) } const loadHash (name) { return localStorage.getItem(upload_hash_${name}) }注意file.lastModified變化會導(dǎo)致同樣的文件內(nèi)容算出不同的 hash所以持久化時(shí)最好連同lastModified一起保存作為文件變更的校驗(yàn)依據(jù)。8.4 服務(wù)器返回 413 Request Entity Too Large這個(gè)錯(cuò)誤是服務(wù)器限制了單個(gè)請求體大小。很多人只看前端忽略了后端配置。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 就沒問題要始終留一倍余量防止 FormData 額外字段導(dǎo)致的體積偏移。8.5 并發(fā)數(shù)過高導(dǎo)致瀏覽器內(nèi)存飆升并發(fā)數(shù)不是越大越好。我實(shí)測過5MB 分片、并發(fā) 3 個(gè)100MB 文件上傳流暢度最好并發(fā) 10 個(gè)雖然速度快一點(diǎn)但瀏覽器內(nèi)存占用高了差不多 300MB低端設(shè)備會直接卡死。我把不同環(huán)境的建議寫成一個(gè)參考移動端 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)整沒有銀彈。8.6 合并時(shí)提示“分片數(shù)量不匹配”這個(gè)錯(cuò)誤通常由兩種情況引起并發(fā)上傳過程中某些分片請求失敗但沒重試成功前端以為成功、后端沒寫入。前端計(jì)算總片數(shù)時(shí)用了Math.ceil(size / chunkSize)但某個(gè)分片確實(shí)沒發(fā)出去。排查方式在mergeChunks接口打日志把files.length和totalChunks對比輸出。再在前端上傳完成循環(huán)里加一個(gè)“分片上傳結(jié)果集合”的斷言確保每一片都有成功響應(yīng)。8.7 計(jì)算 Hash 時(shí)間長、用戶以為頁面掛了解決方案我在前面提過 Worker。這里再給一個(gè)補(bǔ)充技巧計(jì)算 Hash 前用一個(gè)Loading狀態(tài)提示用戶文案寫清楚“正在分析文件請勿關(guān)閉”配合 Worker 后臺運(yùn)行用戶感知會好很多。如果文件大到連 MD5 計(jì)算都不現(xiàn)實(shí)比如 50GB 級別的數(shù)據(jù)集可以退一步只計(jì)算首尾分片的校驗(yàn)哈?；蛘吒纱嘤梦募笮? 首片哈希 末片哈希組合成標(biāo)識。安全性和準(zhǔn)確性都有折扣但實(shí)用性拉滿。9. 優(yōu)化方向與擴(kuò)展建議9.1 上傳進(jìn)度與服務(wù)端寫入分離大文件場景下前端進(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è)簡單檢查分片文件存在就跳過寫盤直接返回成功。這個(gè)冪等處理極大提升了系統(tǒng)的容錯(cuò)率尤其在高并發(fā)場景。9.3 用 IndexedDB 保存上傳任務(wù)如果項(xiàng)目要支持“關(guān)閉瀏覽器后仍能恢復(fù)任務(wù)”前端本地狀態(tài)就得用 IndexedDB 持久化localStorage 存字符串存大任務(wù)列表太吃力。IndexedDB 可以保存 Blob 切片引用、狀態(tài)機(jī)數(shù)據(jù)源下次打開頁面直接恢復(fù)。這套改造聽著復(fù)雜其實(shí)核心就是多維護(hù)一張“任務(wù)表”。10. 寫在最后的經(jīng)驗(yàn)斷點(diǎn)續(xù)傳這個(gè) DEMO本質(zhì)是一個(gè)“狀態(tài)管理 異步并發(fā) 文件 IO”的組合拳。前端玩的是切片、并發(fā)、異步恢復(fù)后端玩的是文件流、冪等、合并。我做過的幾次線上問題排查得出的經(jīng)驗(yàn)是前端問題看著像后端后端問題往往要從前端驗(yàn)證。比如用戶說“文件壞了”結(jié)果根因是前端并發(fā)重試時(shí)偶然重復(fù)上傳同一個(gè)分片用戶說“上傳卡住了”根因是后端磁盤滿了沒返回響應(yīng)。所以做這類系統(tǒng)日志一定要打“分片索引、文件 Hash、請求耗時(shí)”三段關(guān)鍵信息否則排查起來像大海撈針。如果你第一次寫這個(gè) DEMO建議先跟著這篇文章把鏈路跑通然后嘗試回答這幾個(gè)問題你的并發(fā)控制能應(yīng)對服務(wù)器返回 500 嗎你的斷點(diǎn)恢復(fù)能應(yīng)對用戶手動刷新頁面嗎你的合并邏輯能處理分片文件被中途清空嗎把這三個(gè)場景想明白你的斷點(diǎn)續(xù)傳就算真正落地了。