戰(zhàn)：文件指紋與分片上傳詳解)
1. 項(xiàng)目概述1.1 核心需求解析大文件秒傳這個(gè)詞做過文件上傳的人都繞不過去。最早聽到這類需求通常是產(chǎn)品經(jīng)理或者老板甩過來一句你看某某網(wǎng)盤傳大文件一下子就傳完了咱們也得做到。但實(shí)際上所謂秒傳并不是網(wǎng)絡(luò)快而是壓根沒傳文件本身——只在服務(wù)器上做了一次文件指紋比對(duì)發(fā)現(xiàn)文件已經(jīng)存在就直接把新記錄掛到那個(gè)已有文件上前端跳過了上傳等待看起來就像秒傳。這篇文章要做的就是用 Vue 3 HTML5 的 File API 組合從零寫一個(gè)帶文件指紋計(jì)算、秒傳校驗(yàn)、分片上傳、斷點(diǎn)續(xù)傳的 DEMO后端用 Node.js 簡(jiǎn)化模擬不依賴任何付費(fèi)服務(wù)。整個(gè)項(xiàng)目跑起來之后你把這個(gè)文件傳給 App 端或者別的 Web 項(xiàng)目核心邏輯都是通用的。這個(gè) DEMO 解決的核心問題有三個(gè)用戶上傳 1GB 以上文件時(shí)HTTP 請(qǐng)求直接傳整個(gè)文件容易超時(shí)、容易斷而且瀏覽器內(nèi)存扛不住。上傳中斷后從頭再來浪費(fèi)帶寬和時(shí)間體驗(yàn)極差。公司內(nèi)網(wǎng)里多人傳同一個(gè)安裝包、鏡像文件服務(wù)器上明明已經(jīng)有了還每次都重新傳一遍浪費(fèi)磁盤也浪費(fèi)網(wǎng)絡(luò)。這套東西適合誰來參考后端同學(xué)想給前端提供上傳接口時(shí)先了解前端行為前端同學(xué)想搞明白秒傳原理、分片策略以及對(duì)前端為什么能算出一個(gè)很大的文件哈希值感到好奇的初學(xué)者。我按實(shí)際落地的思路走代碼會(huì)逐步拆清楚。1.2 技術(shù)選型思路選 HTML5 而不是 Flash 或客戶端插件核心原因是 HTML5 把文件操作能力直接下沉到了瀏覽器標(biāo)準(zhǔn)層。你不需要安裝任何東西一個(gè) input[typefile] 就能拿到 File 對(duì)象File 對(duì)象有 size、type 這些屬性有 slice() 方法做文件切片配合 FileReader 可以讀文件內(nèi)容配合 Web Worker 可以做耗時(shí)計(jì)算不卡頁面。Vue 這邊主要是做狀態(tài)管理、UI 渲染和請(qǐng)求編排。用 Vue 3 的 Composition API 處理上傳任務(wù)的生命周期會(huì)比 Vue 2 舒服很多——watch、computed、reactive 這套東西處理多任務(wù)進(jìn)度是天然契合的。模板編譯也快調(diào)試方便。我曾經(jīng)見過一個(gè)項(xiàng)目用原生 JavaScript 手寫上傳隊(duì)列狀態(tài)分散在各個(gè)全局變量里后期加需求改得崩潰。用 Vue 來管理上傳狀態(tài)屬于用對(duì)了工具它不是為上傳而生但響應(yīng)式狀態(tài)管理確實(shí)讓多文件上傳、進(jìn)度更新、任務(wù)取消這類邏輯變得直觀。2. 秒傳設(shè)計(jì)背后的原理拆解2.1 什么才算真正的秒傳現(xiàn)在很多項(xiàng)目號(hào)稱支持秒傳實(shí)現(xiàn)方式五花八門但真正經(jīng)得起推敲的做法是基于文件摘要比對(duì)。流程很簡(jiǎn)單前端選中文件。前端計(jì)算整個(gè)文件的 MD5 或 SHA-1 摘要哈希值。將摘要 文件大小發(fā)送給后端。后端在數(shù)據(jù)庫 / 文件系統(tǒng)索引里查詢是否存在相同摘要 相同大小的文件。如果存在則返回文件已存在前端直接顯示上傳完成跳過后面的上傳過程。如果不存在前端再走分片上傳流程。這里有兩個(gè)必須一起比的維度摘要和大小。只比摘要理論上也夠但哈希碰撞的可能性雖然低疊加上大小比對(duì)可以把誤判概率壓到幾乎為零。同時(shí)這種做法也方便后端做快速篩掉明顯不同的文件減輕摘要檢索壓力。有人會(huì)問MD5 不是已經(jīng)不安全了嗎在秒傳場(chǎng)景里MD5 不是做加密而是做內(nèi)容指紋攻擊者不會(huì)刻意構(gòu)造一個(gè) MD5 碰撞來上傳惡意文件因?yàn)槲募?nèi)容服務(wù)器會(huì)原樣保存不涉及防篡改場(chǎng)景。當(dāng)然如果項(xiàng)目安全意識(shí)極強(qiáng)可以升級(jí)到 SHA-256代價(jià)是性能略低但對(duì)大文件計(jì)算來說差別不大。2.2 秒傳為什么離不開分片只有秒傳還不夠。如果文件確實(shí)不存在你是做不到秒傳的得要老老實(shí)實(shí)上傳。這時(shí)就要考慮怎么把大文件安全高效地傳完。直接一次性 POST 整個(gè)文件在幾百 MB 以內(nèi)勉強(qiáng)能玩但上了 GB 級(jí)別就全是問題瀏覽器內(nèi)存被大 File 對(duì)象撐爆其實(shí) File 對(duì)象有點(diǎn)特殊它是引用磁盤/內(nèi)存中的數(shù)據(jù)不一定會(huì)一次性把整個(gè)文件讀進(jìn) JS 堆但你如果構(gòu)造 FormData 塞一個(gè)超大文件網(wǎng)絡(luò)層就要處理整段數(shù)據(jù)。網(wǎng)絡(luò)閃斷導(dǎo)致請(qǐng)求失敗一切從頭再來。后端接口接收超大 body超時(shí)設(shè)置、內(nèi)存限制都要調(diào)Nginx 默認(rèn)client_max_body_size才 1MB生產(chǎn)環(huán)境忘了改就直接 413。進(jìn)度條只有沒開始和完成兩個(gè)狀態(tài)體驗(yàn)極度糟糕。分片上傳把大文件切成比如 5MB、10MB 的小塊逐塊上傳這樣每塊請(qǐng)求都在一個(gè)合理的網(wǎng)絡(luò)范圍內(nèi)失敗后只需要重傳那一塊。而且多個(gè)分片可以并發(fā)上傳整個(gè)上傳速度往往比單線程傳大文件更快。這是秒傳和分片在我這個(gè) DEMO 中的關(guān)系秒傳負(fù)責(zé)不傳分片負(fù)責(zé)怎么傳先秒傳后分片。2.3 前端計(jì)算大文件指紋的難點(diǎn)計(jì)算整個(gè)文件 MD5 需要把文件內(nèi)容從頭到尾讀取一遍。FileReader 一次讀一個(gè)切片然后通過 SparkMD5 庫的 append 方法逐步累積哈希計(jì)算狀態(tài)最后 end() 得到最終摘要。這里有個(gè)性能問題4GB 的文件如果在前端主線程里切分成幾千個(gè)分片循環(huán)讀取計(jì)算瀏覽器會(huì)卡頓到像死機(jī)一樣用戶會(huì)以為網(wǎng)頁崩了。我之前第一次實(shí)現(xiàn)時(shí)就是這么干的用戶反饋一選文件就白屏。后來改成 Web Worker 之后再大的文件計(jì)算期間 UI 依然能操作進(jìn)度條照常動(dòng)畫體驗(yàn)好了幾個(gè)量級(jí)。流程變成主線程把 File 對(duì)象交給 Worker。Worker 內(nèi)部通過 File 對(duì)象的 slice 讀取分片逐片交給 SparkMD5。Worker 每計(jì)算完一個(gè)分片通過 postMessage 通知主線程更新進(jìn)度。全部完成后 postMessage 返回最終 MD5。注意一點(diǎn)File 對(duì)象是可以直接傳給 Web Worker 的不需要通過結(jié)構(gòu)化的拷貝把整個(gè)文件數(shù)據(jù)拿過來瀏覽器底層用引用傳遞處理這個(gè)所以不用擔(dān)心內(nèi)存翻倍。3. 前端工程落地Vue 3 HTML5 實(shí)現(xiàn)一個(gè)可運(yùn)行 DEMO3.1 環(huán)境準(zhǔn)備與項(xiàng)目初始化這一步?jīng)]什么高深的就按 Vue 官方推薦的 Vite 來。我假設(shè)你已經(jīng)裝了 Node.js 18。npm create vuelatest模板選的時(shí)候只需要勾選JSX和Vue Router就好其他 Test、Lint 看自己習(xí)慣。項(xiàng)目初始化的目的是快速跑起來一個(gè)最小 Vue 3 工程接下來在 App.vue 和新建的 Worker 文件里寫核心代碼。如果不想用腳手架也可以用 CDN 方式在單 HTML 里引 Vue 3但那樣 Worker 文件和模塊組織會(huì)比較別扭DEMO 還是用工程化方式更貼近真實(shí)項(xiàng)目。3.2 核心代碼結(jié)構(gòu)我的 DEMO 文件結(jié)構(gòu)如下├── index.html ├── package.json ├── src │ ├── App.vue │ ├── components │ │ └── UploadPanel.vue │ ├── utils │ │ ├── fileHash.js # 負(fù)責(zé)與 Worker 通信 │ │ ├── fileHash.worker.js # 真正計(jì)算 MD5 的地方 │ │ └── uploader.js # 分片上傳核心邏輯 │ └── api │ └── uploadApi.js # 后端接口封裝每個(gè)文件的職責(zé)要理清楚別把 Worker 邏輯和 Vue 組件混在一起后期改起來會(huì)很頭疼。我見過不少初學(xué)者把 Worker 的代碼寫成字符串用 Blob 動(dòng)態(tài)創(chuàng)建雖然能跑但調(diào)試很痛苦還是物理文件清晰。3.3 前端代碼全解UploadPanel.vue組件要做的事文件選擇顯示文件信息調(diào)起秒傳校驗(yàn)觸發(fā)分片上傳展示進(jìn)度先看組件的核心邏輯部分template div classupload-panel input typefile changeonFileChange / div v-iffile p文件名{{ file.name }}/p p文件大小{{ formatSize(file.size) }}/p div v-ifhashProgress 0 正在計(jì)算文件指紋{{ hashProgress }}% /div div v-else-ifuploadProgress 0 上傳進(jìn)度{{ uploadProgress }}% /div button clickstartUpload :disableduploading開始上傳/button /div /div /template script setup import { ref } from vue; import { getFileHash } from ../utils/fileHash; import { checkExist, uploadChunk, mergeChunks } from ../api/uploadApi; const file ref(null); const hashProgress ref(-1); // -1 表示未開始 const uploadProgress ref(-1); const uploading ref(false); const fileMd5 ref(); const chunkSize 5 * 1024 * 1024; // 每片 5MB function onFileChange(e) { const selected e.target.files[0]; if (!selected) return; file.value selected; hashProgress.value -1; uploadProgress.value -1; } async function startUpload() { if (!file.value) return; uploading.value true; // 第一步計(jì)算文件指紋 fileMd5.value await getFileHash(file.value, (p) { hashProgress.value p; }); hashProgress.value 100; // 第二步秒傳校驗(yàn) const exist await checkExist(fileMd5.value, file.value.size); if (exist) { uploadProgress.value 100; uploading.value false; alert(文件已在服務(wù)器上秒傳成功); return; } // 第三步分片上傳 const chunks Math.ceil(file.value.size / chunkSize); let uploaded 0; for (let i 0; i chunks; i) { const start i * chunkSize; const end Math.min(start chunkSize, file.value.size); const blob file.value.slice(start, end); await uploadChunk({ fileMd5: fileMd5.value, chunkIndex: i, chunk: blob, }); uploaded; uploadProgress.value Math.round((uploaded / chunks) * 100); } // 第四步通知后端合并分片 await mergeChunks({ fileMd5: fileMd5.value, fileName: file.value.name }); uploading.value false; alert(上傳完成); } function formatSize(size) { if (size 1024 * 1024) return (size / 1024).toFixed(2) KB; return (size / (1024 * 1024)).toFixed(2) MB; } /script這段代碼把流程串起來了但說實(shí)話第一次寫別按這個(gè)直接上由于await uploadChunk是串行的效率偏低。我在后面 3.5 小節(jié)會(huì)給出一個(gè)并發(fā)控制版本的思路DEMO 先保證邏輯正確再談性能。fileHash.worker.js的核心代碼import SparkMD5 from spark-md5; self.onmessage function (e) { const { file, chunkSize } e.data; const spark new SparkMD5.ArrayBuffer(); const reader new FileReaderSync(); const chunks Math.ceil(file.size / chunkSize); let currentChunk 0; try { while (currentChunk chunks) { const start currentChunk * chunkSize; const end Math.min(start chunkSize, file.size); const buffer reader.readAsArrayBuffer(file.slice(start, end)); spark.append(buffer); currentChunk; self.postMessage({ type: progress, percent: Math.round((currentChunk / chunks) * 100), }); } self.postMessage({ type: done, md5: spark.end(), }); } catch (err) { self.postMessage({ type: error, message: err.message }); } };注意這里用了FileReaderSync在 Worker 里它是可以同步讀取文件的天然適合這種循環(huán)切片的邏輯代碼比異步回調(diào)清晰得多。瀏覽器兼容性方面現(xiàn)代瀏覽器對(duì) Worker 里的 FileReaderSync 支持沒問題。fileHash.js負(fù)責(zé)創(chuàng)建 Worker 并做 Promise 封裝export function getFileHash(file, onProgress) { return new Promise((resolve, reject) { const worker new Worker(new URL(./fileHash.worker.js, import.meta.url), { type: module, }); worker.postMessage({ file, chunkSize: 5 * 1024 * 1024 }); worker.onmessage (e) { const { type, percent, md5, message } e.data; if (type progress) { onProgress onProgress(percent); } else if (type done) { worker.terminate(); resolve(md5); } else if (type error) { worker.terminate(); reject(new Error(message)); } }; }); }這里用import.meta.url的方式引入 Worker 是 Vite 的標(biāo)準(zhǔn)做法打包時(shí)瀏覽器會(huì)自己處理 Worker 的資源路徑問題。uploadApi.js是后端接口封裝。注意分片上傳的請(qǐng)求頭要加Content-Type: application/octet-stream如果傳 FormData 也可以但二進(jìn)制流更干凈import axios from axios; const BASE_URL http://localhost:3000; export function checkExist(fileMd5, fileSize) { return axios .post(${BASE_URL}/exists, { fileMd5, fileSize }) .then((res) res.data.data.exists); } export function uploadChunk({ fileMd5, chunkIndex, chunk }) { const formData new FormData(); formData.append(chunk, chunk); formData.append(fileMd5, fileMd5); formData.append(chunkIndex, chunkIndex); return axios.post(${BASE_URL}/upload, formData, { headers: { Content-Type: multipart/form-data }, }); } export function mergeChunks({ fileMd5, fileName }) { return axios .post(${BASE_URL}/merge, { fileMd5, fileName }) .then((res) res.data); }3.4 為什么要把 chunkSize 定為 5MBchunkSize 的選擇是有講究的不是隨便拍的。太小的分片比如 256KB分片數(shù)量暴增請(qǐng)求次數(shù)太多HTTP 握手開銷壓過傳輸收益后端也要處理海量元數(shù)據(jù)。太大的分片比如 100MB單請(qǐng)求耗時(shí)太長(zhǎng)失敗重試代價(jià)大而且瀏覽器內(nèi)存占用高。5MB 是業(yè)界比較通用的值7Zip 官方在分卷壓縮時(shí)也常用 5MB 級(jí)別的塊大小。對(duì)于普通的企業(yè)內(nèi)網(wǎng)帶寬5MB 大約 1-3 秒傳完一片用戶感知進(jìn)度會(huì)平滑更新。我實(shí)際測(cè)過 10MB 分片在千兆內(nèi)網(wǎng)沒問題但公網(wǎng)上就反而容易出現(xiàn)單片超時(shí)。200MB 視頻有 40 片每片重試一次也就是多 40 個(gè)請(qǐng)求可接受。3.5 并發(fā)上傳與斷點(diǎn)續(xù)傳升級(jí)DEMO 里的串行上傳在文件特別大時(shí)耗時(shí)較長(zhǎng)但可以簡(jiǎn)單改造為并發(fā)控制。思路是維護(hù)一個(gè)任務(wù)池限定同時(shí)進(jìn)行 3-5 個(gè)上傳請(qǐng)求async function uploadChunksWithConcurrency(file, fileMd5, chunks, limit 3) { const tasks Array.from({ length: chunks }, (_, i) i); const pool new Set(); let uploadedCount 0; for (const index of tasks) { if (pool.size limit) { await Promise.race(pool); } const p uploadSingleChunk(file, fileMd5, index).then(() { pool.delete(p); uploadedCount; uploadProgress.value Math.round((uploadedCount / chunks) * 100); }); pool.add(p); } await Promise.all([...pool]); }斷點(diǎn)續(xù)傳需要后端支持查詢哪些分片已經(jīng)上傳過前端在開始上傳前請(qǐng)求一下已上傳分片列表只傳沒傳過的。這個(gè)邏輯在 DEMO 里我留作擴(kuò)展點(diǎn)后面 4.2 會(huì)展開講實(shí)現(xiàn)方式。4. 后端配合用 Node.js 實(shí)現(xiàn)最小可行服務(wù)前端代碼再花哨后端不支持也是白搭。這個(gè) DEMO 的后端我用 Express 寫了最簡(jiǎn)版本存儲(chǔ)用本地磁盤 一個(gè) JSON 文件做元數(shù)據(jù)記錄。4.1 Express 后端接口實(shí)現(xiàn)const express require(express); const multer require(multer); const fs require(fs); const path require(path); const app express(); app.use(express.json()); const UPLOAD_DIR path.join(__dirname, uploads); const META_FILE path.join(__dirname, meta.json); const storage multer.diskStorage({ destination: (req, file, cb) { const chunkDir path.join(UPLOAD_DIR, req.body.fileMd5); if (!fs.existsSync(chunkDir)) { fs.mkdirSync(chunkDir, { recursive: true }); } cb(null, chunkDir); }, filename: (req, file, cb) { cb(null, ${req.body.chunkIndex}); }, }); const upload multer({ storage }); function readMeta() { if (!fs.existsSync(META_FILE)) return {}; return JSON.parse(fs.readFileSync(META_FILE, utf-8)); } function writeMeta(meta) { fs.writeFileSync(META_FILE, JSON.stringify(meta, null, 2)); } app.post(/exists, (req, res) { const { fileMd5, fileSize } req.body; const meta readMeta(); const record meta[fileMd5]; res.json({ data: { exists: !!(record record.size fileSize), }, }); }); app.post(/upload, upload.single(chunk), (req, res) { res.json({ code: 0, message: chunk received }); }); app.post(/merge, (req, res) { const { fileMd5, fileName } req.body; const chunkDir path.join(UPLOAD_DIR, fileMd5); const chunks fs.readdirSync(chunkDir); chunks.sort((a, b) a - b); const dest path.join(UPLOAD_DIR, fileName); const fd fs.openSync(dest, w); for (const chunk of chunks) { const chunkPath path.join(chunkDir, chunk); const data fs.readFileSync(chunkPath); fs.writeSync(fd, data); } fs.closeSync(fd); const meta readMeta(); meta[fileMd5] { size: fs.statSync(dest).size }; writeMeta(meta); res.json({ code: 0, message: merge done }); }); app.listen(3000, () { console.log(server running at http://localhost:3000); });這個(gè)后端的核心思路/exists做秒傳判斷看 meta.json 里是否有相同文件指紋記錄。/upload把分片保存到以 fileMd5 為名的目錄下文件名就是分片序號(hào)。/merge把所有分片按序號(hào)拼回原文件更新元數(shù)據(jù)。只跑 DEMO 的話完全夠用。真實(shí)項(xiàng)目里需要把 meta 換成 Redis MySQL磁盤存儲(chǔ)換成對(duì)象存儲(chǔ)OSS / MinIO分片合并也可以放到異步隊(duì)列里做不能在請(qǐng)求里同步合成幾百 MB 的文件。4.2 已上傳分片查詢與補(bǔ)傳機(jī)制斷點(diǎn)續(xù)傳的核心是前端要知道哪些分片上傳過了。后端加一個(gè)接口app.get(/chunks/:fileMd5, (req, res) { const chunkDir path.join(UPLOAD_DIR, req.params.fileMd5); if (!fs.existsSync(chunkDir)) { res.json({ data: { uploadedChunks: [] } }); return; } const chunks fs.readdirSync(chunkDir).map(Number); res.json({ data: { uploadedChunks: chunks } }); });前端拿到uploadedChunks后在分片上傳循環(huán)里直接跳過已存在的序號(hào)。進(jìn)度計(jì)算也要基于當(dāng)前累計(jì)已上傳數(shù)來做不能從 0 開始。5. 常見問題與排查技巧實(shí)錄5.1 計(jì)算哈希時(shí)瀏覽器卡死現(xiàn)象選了一個(gè) 2GB 的文件頁面直接白屏鼠標(biāo)都動(dòng)不了。原因FileReader 逐片讀取文件是在主線程執(zhí)行的循環(huán)幾萬次切片操作會(huì)持續(xù)占用渲染進(jìn)程。解決把哈希計(jì)算扔進(jìn) Web Worker。如果已經(jīng)用了 Worker 還卡檢查是不是你把fileHash.js里的 Worker 實(shí)例重復(fù)創(chuàng)建了或者你的 Worker 里又 require 了大模塊。我之前見過一個(gè)同事寫了 Worker但每次分片都 new 一個(gè) SparkMD5 實(shí)例內(nèi)存炸了也是卡。5.2 秒傳校驗(yàn)通過但文件遲遲不出現(xiàn)在目標(biāo)路徑現(xiàn)象前端拿到了秒傳成功提示但服務(wù)器上找不到文件。原因元數(shù)據(jù)記錄在了 meta.json但文件本身可能在第一次上傳之后被清理了或者是 merge 接口只更新了 meta沒有真正把分片拼裝成文件。解決/exists 判斷時(shí)不僅要查 meta 記錄還要校驗(yàn)?zāi)繕?biāo)文件是否真的存在于磁盤const destPath path.join(UPLOAD_DIR, fileName); const fileExists fs.existsSync(destPath); res.json({ data: { exists: !!record record.size fileSize fileExists } });注意 fileName 不要直接用用戶傳來的原始名有路徑穿越風(fēng)險(xiǎn)應(yīng)當(dāng)用哈希重命名存儲(chǔ)。5.3 分片合并后文件內(nèi)容損壞現(xiàn)象上傳完成后打開文件提示格式損壞或者 MD5 校驗(yàn)不通過。原因大概率是分片合并順序有問題。Node 的fs.readdirSync返回順序不一定是文件名的數(shù)字順序比如字符串排序會(huì)把 10 排在 2 前面導(dǎo)致合并錯(cuò)亂。解決合并前必須先按數(shù)字排序const chunks fs.readdirSync(chunkDir).sort((a, b) parseInt(a) - parseInt(b));這是一個(gè)非常經(jīng)典的坑。任何時(shí)候合并分片都要顯式排序別依賴文件系統(tǒng)返回順序。5.4 超大文件上傳時(shí)后端報(bào)錯(cuò) 413 Payload Too Large現(xiàn)象本地開發(fā)跑得好好的放到 Nginx 后面就失敗。原因Nginx 默認(rèn)client_max_body_size是 1MB分片雖然只有 5MB但也會(huì)被攔下來。解決在 Nginx 配置里顯式聲明client_max_body_size 10m;如果你后續(xù)調(diào)大分片這個(gè)值跟著調(diào)大就行。如果服務(wù)器上有網(wǎng)關(guān)層也需要檢查網(wǎng)關(guān)的請(qǐng)求體大小限制。5.5 前后端聯(lián)調(diào)時(shí) CORS 報(bào)錯(cuò)本地用 Vite5173去請(qǐng)求后端3000端口瀏覽器會(huì)攔截跨域響應(yīng)。在后端加上const cors require(cors); app.use(cors());DEMO 階段直接放開所有來源沒毛病生產(chǎn)環(huán)境再按域名白名單收緊。6. 實(shí)操心得與擴(kuò)展建議6.1 從 DEMO 到生產(chǎn)級(jí)上傳組件你還需要補(bǔ)什么這個(gè) DEMO 跑通之后距離生產(chǎn)環(huán)境還有一些距離我列一下優(yōu)先級(jí)比較高的增強(qiáng)點(diǎn)上傳任務(wù)持久化刷新頁面之后已傳分片還能查到續(xù)傳不丟。接入文件流加密敏感場(chǎng)景下分片內(nèi)容要做 AES 加密再上傳服務(wù)端解密落盤。后端摘要二次校驗(yàn)分片合并完成后后端重新計(jì)算 MD5和前端傳過來的 fileMd5 比對(duì)能發(fā)現(xiàn)傳輸過程中被篡改或損壞的問題。進(jìn)度展示優(yōu)化結(jié)合請(qǐng)求耗時(shí)、網(wǎng)絡(luò)吞吐預(yù)估剩余時(shí)間而不是只顯示百分比。拖拽上傳與文件夾上傳HTML5 的 DataTransfer 接口可以輕松實(shí)現(xiàn)視覺體驗(yàn)提升很大。并發(fā)閾值自適應(yīng)根據(jù)網(wǎng)絡(luò)環(huán)境動(dòng)態(tài)調(diào)整并發(fā)數(shù)弱網(wǎng)時(shí)降低并發(fā)避免大量重試。6.2 一個(gè)容易踩的坑文件重復(fù)上傳時(shí)的重復(fù)合并你可能會(huì)遇到這種情況用戶第一次上傳時(shí)中斷了第二次點(diǎn)開始上傳秒傳校驗(yàn)沒通過服務(wù)端沒記錄完整文件走分片上傳但是服務(wù)端已經(jīng)殘留了一部分分片。如果后端合并接口不檢查已有分片是否存在可能重復(fù)執(zhí)行 merge把兩個(gè)不完整的文件拼在一起。我的做法是 merge 之前先檢查目標(biāo)文件是否已經(jīng)存在如果存在且 size 等于記錄值直接返回成功。如果 size 不一致則先刪除殘留分片目錄再?gòu)牧汩_始傳保證分片干凈。6.3 最后分享一個(gè)小技巧很多大文件上傳場(chǎng)景會(huì)碰到用戶等不到計(jì)算哈希完成就關(guān)頁面的問題。我的經(jīng)驗(yàn)是在哈希計(jì)算階段就開始做用戶引導(dǎo)比如顯示正在分析文件請(qǐng)勿關(guān)閉頁面同時(shí)把哈希計(jì)算的粒度調(diào)得細(xì)一些比如 2MB 一片進(jìn)度條能更快動(dòng)起來用戶就不會(huì)以為卡死了。還有一個(gè)細(xì)節(jié)對(duì)體驗(yàn)影響很大秒傳成功后建議給一個(gè)動(dòng)畫反饋比如打勾或者彈一層遮罩玩家心理上會(huì)有這么快就完成了的驚喜感。續(xù)傳、并發(fā)控制的完整代碼其實(shí)在這個(gè) DEMO 基礎(chǔ)上加不了多少但生產(chǎn)工程里每一步都要考慮到異常處理和資源釋放這塊值得你花時(shí)間好好打磨。 Vue 3大文件秒傳實(shí)戰(zhàn)：文件指紋與分片上傳詳解
1. 項(xiàng)目概述1.1 核心需求解析大文件秒傳這個(gè)詞做過文件上傳的人都繞不過去。最早聽到這類需求通常是產(chǎn)品經(jīng)理或者老板甩過來一句你看某某網(wǎng)盤傳大文件一下子就傳完了咱們也得做到。但實(shí)際上所謂秒傳并不是網(wǎng)絡(luò)快而是壓根沒傳文件本身——只在服務(wù)器上做了一次文件指紋比對(duì)發(fā)現(xiàn)文件已經(jīng)存在就直接把新記錄掛到那個(gè)已有文件上前端跳過了上傳等待看起來就像秒傳。這篇文章要做的就是用 Vue 3 HTML5 的 File API 組合從零寫一個(gè)帶文件指紋計(jì)算、秒傳校驗(yàn)、分片上傳、斷點(diǎn)續(xù)傳的 DEMO后端用 Node.js 簡(jiǎn)化模擬不依賴任何付費(fèi)服務(wù)。整個(gè)項(xiàng)目跑起來之后你把這個(gè)文件傳給 App 端或者別的 Web 項(xiàng)目核心邏輯都是通用的。這個(gè) DEMO 解決的核心問題有三個(gè)用戶上傳 1GB 以上文件時(shí)HTTP 請(qǐng)求直接傳整個(gè)文件容易超時(shí)、容易斷而且瀏覽器內(nèi)存扛不住。上傳中斷后從頭再來浪費(fèi)帶寬和時(shí)間體驗(yàn)極差。公司內(nèi)網(wǎng)里多人傳同一個(gè)安裝包、鏡像文件服務(wù)器上明明已經(jīng)有了還每次都重新傳一遍浪費(fèi)磁盤也浪費(fèi)網(wǎng)絡(luò)。這套東西適合誰來參考后端同學(xué)想給前端提供上傳接口時(shí)先了解前端行為前端同學(xué)想搞明白秒傳原理、分片策略以及對(duì)前端為什么能算出一個(gè)很大的文件哈希值感到好奇的初學(xué)者。我按實(shí)際落地的思路走代碼會(huì)逐步拆清楚。1.2 技術(shù)選型思路選 HTML5 而不是 Flash 或客戶端插件核心原因是 HTML5 把文件操作能力直接下沉到了瀏覽器標(biāo)準(zhǔn)層。你不需要安裝任何東西一個(gè) input[typefile] 就能拿到 File 對(duì)象File 對(duì)象有 size、type 這些屬性有 slice() 方法做文件切片配合 FileReader 可以讀文件內(nèi)容配合 Web Worker 可以做耗時(shí)計(jì)算不卡頁面。Vue 這邊主要是做狀態(tài)管理、UI 渲染和請(qǐng)求編排。用 Vue 3 的 Composition API 處理上傳任務(wù)的生命周期會(huì)比 Vue 2 舒服很多——watch、computed、reactive 這套東西處理多任務(wù)進(jìn)度是天然契合的。模板編譯也快調(diào)試方便。我曾經(jīng)見過一個(gè)項(xiàng)目用原生 JavaScript 手寫上傳隊(duì)列狀態(tài)分散在各個(gè)全局變量里后期加需求改得崩潰。用 Vue 來管理上傳狀態(tài)屬于用對(duì)了工具它不是為上傳而生但響應(yīng)式狀態(tài)管理確實(shí)讓多文件上傳、進(jìn)度更新、任務(wù)取消這類邏輯變得直觀。2. 秒傳設(shè)計(jì)背后的原理拆解2.1 什么才算真正的秒傳現(xiàn)在很多項(xiàng)目號(hào)稱支持秒傳實(shí)現(xiàn)方式五花八門但真正經(jīng)得起推敲的做法是基于文件摘要比對(duì)。流程很簡(jiǎn)單前端選中文件。前端計(jì)算整個(gè)文件的 MD5 或 SHA-1 摘要哈希值。將摘要 文件大小發(fā)送給后端。后端在數(shù)據(jù)庫 / 文件系統(tǒng)索引里查詢是否存在相同摘要 相同大小的文件。如果存在則返回文件已存在前端直接顯示上傳完成跳過后面的上傳過程。如果不存在前端再走分片上傳流程。這里有兩個(gè)必須一起比的維度摘要和大小。只比摘要理論上也夠但哈希碰撞的可能性雖然低疊加上大小比對(duì)可以把誤判概率壓到幾乎為零。同時(shí)這種做法也方便后端做快速篩掉明顯不同的文件減輕摘要檢索壓力。有人會(huì)問MD5 不是已經(jīng)不安全了嗎在秒傳場(chǎng)景里MD5 不是做加密而是做內(nèi)容指紋攻擊者不會(huì)刻意構(gòu)造一個(gè) MD5 碰撞來上傳惡意文件因?yàn)槲募?nèi)容服務(wù)器會(huì)原樣保存不涉及防篡改場(chǎng)景。當(dāng)然如果項(xiàng)目安全意識(shí)極強(qiáng)可以升級(jí)到 SHA-256代價(jià)是性能略低但對(duì)大文件計(jì)算來說差別不大。2.2 秒傳為什么離不開分片只有秒傳還不夠。如果文件確實(shí)不存在你是做不到秒傳的得要老老實(shí)實(shí)上傳。這時(shí)就要考慮怎么把大文件安全高效地傳完。直接一次性 POST 整個(gè)文件在幾百 MB 以內(nèi)勉強(qiáng)能玩但上了 GB 級(jí)別就全是問題瀏覽器內(nèi)存被大 File 對(duì)象撐爆其實(shí) File 對(duì)象有點(diǎn)特殊它是引用磁盤/內(nèi)存中的數(shù)據(jù)不一定會(huì)一次性把整個(gè)文件讀進(jìn) JS 堆但你如果構(gòu)造 FormData 塞一個(gè)超大文件網(wǎng)絡(luò)層就要處理整段數(shù)據(jù)。網(wǎng)絡(luò)閃斷導(dǎo)致請(qǐng)求失敗一切從頭再來。后端接口接收超大 body超時(shí)設(shè)置、內(nèi)存限制都要調(diào)Nginx 默認(rèn)client_max_body_size才 1MB生產(chǎn)環(huán)境忘了改就直接 413。進(jìn)度條只有沒開始和完成兩個(gè)狀態(tài)體驗(yàn)極度糟糕。分片上傳把大文件切成比如 5MB、10MB 的小塊逐塊上傳這樣每塊請(qǐng)求都在一個(gè)合理的網(wǎng)絡(luò)范圍內(nèi)失敗后只需要重傳那一塊。而且多個(gè)分片可以并發(fā)上傳整個(gè)上傳速度往往比單線程傳大文件更快。這是秒傳和分片在我這個(gè) DEMO 中的關(guān)系秒傳負(fù)責(zé)不傳分片負(fù)責(zé)怎么傳先秒傳后分片。2.3 前端計(jì)算大文件指紋的難點(diǎn)計(jì)算整個(gè)文件 MD5 需要把文件內(nèi)容從頭到尾讀取一遍。FileReader 一次讀一個(gè)切片然后通過 SparkMD5 庫的 append 方法逐步累積哈希計(jì)算狀態(tài)最后 end() 得到最終摘要。這里有個(gè)性能問題4GB 的文件如果在前端主線程里切分成幾千個(gè)分片循環(huán)讀取計(jì)算瀏覽器會(huì)卡頓到像死機(jī)一樣用戶會(huì)以為網(wǎng)頁崩了。我之前第一次實(shí)現(xiàn)時(shí)就是這么干的用戶反饋一選文件就白屏。后來改成 Web Worker 之后再大的文件計(jì)算期間 UI 依然能操作進(jìn)度條照常動(dòng)畫體驗(yàn)好了幾個(gè)量級(jí)。流程變成主線程把 File 對(duì)象交給 Worker。Worker 內(nèi)部通過 File 對(duì)象的 slice 讀取分片逐片交給 SparkMD5。Worker 每計(jì)算完一個(gè)分片通過 postMessage 通知主線程更新進(jìn)度。全部完成后 postMessage 返回最終 MD5。注意一點(diǎn)File 對(duì)象是可以直接傳給 Web Worker 的不需要通過結(jié)構(gòu)化的拷貝把整個(gè)文件數(shù)據(jù)拿過來瀏覽器底層用引用傳遞處理這個(gè)所以不用擔(dān)心內(nèi)存翻倍。3. 前端工程落地Vue 3 HTML5 實(shí)現(xiàn)一個(gè)可運(yùn)行 DEMO3.1 環(huán)境準(zhǔn)備與項(xiàng)目初始化這一步?jīng)]什么高深的就按 Vue 官方推薦的 Vite 來。我假設(shè)你已經(jīng)裝了 Node.js 18。npm create vuelatest模板選的時(shí)候只需要勾選JSX和Vue Router就好其他 Test、Lint 看自己習(xí)慣。項(xiàng)目初始化的目的是快速跑起來一個(gè)最小 Vue 3 工程接下來在 App.vue 和新建的 Worker 文件里寫核心代碼。如果不想用腳手架也可以用 CDN 方式在單 HTML 里引 Vue 3但那樣 Worker 文件和模塊組織會(huì)比較別扭DEMO 還是用工程化方式更貼近真實(shí)項(xiàng)目。3.2 核心代碼結(jié)構(gòu)我的 DEMO 文件結(jié)構(gòu)如下├── index.html ├── package.json ├── src │ ├── App.vue │ ├── components │ │ └── UploadPanel.vue │ ├── utils │ │ ├── fileHash.js # 負(fù)責(zé)與 Worker 通信 │ │ ├── fileHash.worker.js # 真正計(jì)算 MD5 的地方 │ │ └── uploader.js # 分片上傳核心邏輯 │ └── api │ └── uploadApi.js # 后端接口封裝每個(gè)文件的職責(zé)要理清楚別把 Worker 邏輯和 Vue 組件混在一起后期改起來會(huì)很頭疼。我見過不少初學(xué)者把 Worker 的代碼寫成字符串用 Blob 動(dòng)態(tài)創(chuàng)建雖然能跑但調(diào)試很痛苦還是物理文件清晰。3.3 前端代碼全解UploadPanel.vue組件要做的事文件選擇顯示文件信息調(diào)起秒傳校驗(yàn)觸發(fā)分片上傳展示進(jìn)度先看組件的核心邏輯部分template div classupload-panel input typefile changeonFileChange / div v-iffile p文件名{{ file.name }}/p p文件大小{{ formatSize(file.size) }}/p div v-ifhashProgress 0 正在計(jì)算文件指紋{{ hashProgress }}% /div div v-else-ifuploadProgress 0 上傳進(jìn)度{{ uploadProgress }}% /div button clickstartUpload :disableduploading開始上傳/button /div /div /template script setup import { ref } from vue; import { getFileHash } from ../utils/fileHash; import { checkExist, uploadChunk, mergeChunks } from ../api/uploadApi; const file ref(null); const hashProgress ref(-1); // -1 表示未開始 const uploadProgress ref(-1); const uploading ref(false); const fileMd5 ref(); const chunkSize 5 * 1024 * 1024; // 每片 5MB function onFileChange(e) { const selected e.target.files[0]; if (!selected) return; file.value selected; hashProgress.value -1; uploadProgress.value -1; } async function startUpload() { if (!file.value) return; uploading.value true; // 第一步計(jì)算文件指紋 fileMd5.value await getFileHash(file.value, (p) { hashProgress.value p; }); hashProgress.value 100; // 第二步秒傳校驗(yàn) const exist await checkExist(fileMd5.value, file.value.size); if (exist) { uploadProgress.value 100; uploading.value false; alert(文件已在服務(wù)器上秒傳成功); return; } // 第三步分片上傳 const chunks Math.ceil(file.value.size / chunkSize); let uploaded 0; for (let i 0; i chunks; i) { const start i * chunkSize; const end Math.min(start chunkSize, file.value.size); const blob file.value.slice(start, end); await uploadChunk({ fileMd5: fileMd5.value, chunkIndex: i, chunk: blob, }); uploaded; uploadProgress.value Math.round((uploaded / chunks) * 100); } // 第四步通知后端合并分片 await mergeChunks({ fileMd5: fileMd5.value, fileName: file.value.name }); uploading.value false; alert(上傳完成); } function formatSize(size) { if (size 1024 * 1024) return (size / 1024).toFixed(2) KB; return (size / (1024 * 1024)).toFixed(2) MB; } /script這段代碼把流程串起來了但說實(shí)話第一次寫別按這個(gè)直接上由于await uploadChunk是串行的效率偏低。我在后面 3.5 小節(jié)會(huì)給出一個(gè)并發(fā)控制版本的思路DEMO 先保證邏輯正確再談性能。fileHash.worker.js的核心代碼import SparkMD5 from spark-md5; self.onmessage function (e) { const { file, chunkSize } e.data; const spark new SparkMD5.ArrayBuffer(); const reader new FileReaderSync(); const chunks Math.ceil(file.size / chunkSize); let currentChunk 0; try { while (currentChunk chunks) { const start currentChunk * chunkSize; const end Math.min(start chunkSize, file.size); const buffer reader.readAsArrayBuffer(file.slice(start, end)); spark.append(buffer); currentChunk; self.postMessage({ type: progress, percent: Math.round((currentChunk / chunks) * 100), }); } self.postMessage({ type: done, md5: spark.end(), }); } catch (err) { self.postMessage({ type: error, message: err.message }); } };注意這里用了FileReaderSync在 Worker 里它是可以同步讀取文件的天然適合這種循環(huán)切片的邏輯代碼比異步回調(diào)清晰得多。瀏覽器兼容性方面現(xiàn)代瀏覽器對(duì) Worker 里的 FileReaderSync 支持沒問題。fileHash.js負(fù)責(zé)創(chuàng)建 Worker 并做 Promise 封裝export function getFileHash(file, onProgress) { return new Promise((resolve, reject) { const worker new Worker(new URL(./fileHash.worker.js, import.meta.url), { type: module, }); worker.postMessage({ file, chunkSize: 5 * 1024 * 1024 }); worker.onmessage (e) { const { type, percent, md5, message } e.data; if (type progress) { onProgress onProgress(percent); } else if (type done) { worker.terminate(); resolve(md5); } else if (type error) { worker.terminate(); reject(new Error(message)); } }; }); }這里用import.meta.url的方式引入 Worker 是 Vite 的標(biāo)準(zhǔn)做法打包時(shí)瀏覽器會(huì)自己處理 Worker 的資源路徑問題。uploadApi.js是后端接口封裝。注意分片上傳的請(qǐng)求頭要加Content-Type: application/octet-stream如果傳 FormData 也可以但二進(jìn)制流更干凈import axios from axios; const BASE_URL http://localhost:3000; export function checkExist(fileMd5, fileSize) { return axios .post(${BASE_URL}/exists, { fileMd5, fileSize }) .then((res) res.data.data.exists); } export function uploadChunk({ fileMd5, chunkIndex, chunk }) { const formData new FormData(); formData.append(chunk, chunk); formData.append(fileMd5, fileMd5); formData.append(chunkIndex, chunkIndex); return axios.post(${BASE_URL}/upload, formData, { headers: { Content-Type: multipart/form-data }, }); } export function mergeChunks({ fileMd5, fileName }) { return axios .post(${BASE_URL}/merge, { fileMd5, fileName }) .then((res) res.data); }3.4 為什么要把 chunkSize 定為 5MBchunkSize 的選擇是有講究的不是隨便拍的。太小的分片比如 256KB分片數(shù)量暴增請(qǐng)求次數(shù)太多HTTP 握手開銷壓過傳輸收益后端也要處理海量元數(shù)據(jù)。太大的分片比如 100MB單請(qǐng)求耗時(shí)太長(zhǎng)失敗重試代價(jià)大而且瀏覽器內(nèi)存占用高。5MB 是業(yè)界比較通用的值7Zip 官方在分卷壓縮時(shí)也常用 5MB 級(jí)別的塊大小。對(duì)于普通的企業(yè)內(nèi)網(wǎng)帶寬5MB 大約 1-3 秒傳完一片用戶感知進(jìn)度會(huì)平滑更新。我實(shí)際測(cè)過 10MB 分片在千兆內(nèi)網(wǎng)沒問題但公網(wǎng)上就反而容易出現(xiàn)單片超時(shí)。200MB 視頻有 40 片每片重試一次也就是多 40 個(gè)請(qǐng)求可接受。3.5 并發(fā)上傳與斷點(diǎn)續(xù)傳升級(jí)DEMO 里的串行上傳在文件特別大時(shí)耗時(shí)較長(zhǎng)但可以簡(jiǎn)單改造為并發(fā)控制。思路是維護(hù)一個(gè)任務(wù)池限定同時(shí)進(jìn)行 3-5 個(gè)上傳請(qǐng)求async function uploadChunksWithConcurrency(file, fileMd5, chunks, limit 3) { const tasks Array.from({ length: chunks }, (_, i) i); const pool new Set(); let uploadedCount 0; for (const index of tasks) { if (pool.size limit) { await Promise.race(pool); } const p uploadSingleChunk(file, fileMd5, index).then(() { pool.delete(p); uploadedCount; uploadProgress.value Math.round((uploadedCount / chunks) * 100); }); pool.add(p); } await Promise.all([...pool]); }斷點(diǎn)續(xù)傳需要后端支持查詢哪些分片已經(jīng)上傳過前端在開始上傳前請(qǐng)求一下已上傳分片列表只傳沒傳過的。這個(gè)邏輯在 DEMO 里我留作擴(kuò)展點(diǎn)后面 4.2 會(huì)展開講實(shí)現(xiàn)方式。4. 后端配合用 Node.js 實(shí)現(xiàn)最小可行服務(wù)前端代碼再花哨后端不支持也是白搭。這個(gè) DEMO 的后端我用 Express 寫了最簡(jiǎn)版本存儲(chǔ)用本地磁盤 一個(gè) JSON 文件做元數(shù)據(jù)記錄。4.1 Express 后端接口實(shí)現(xiàn)const express require(express); const multer require(multer); const fs require(fs); const path require(path); const app express(); app.use(express.json()); const UPLOAD_DIR path.join(__dirname, uploads); const META_FILE path.join(__dirname, meta.json); const storage multer.diskStorage({ destination: (req, file, cb) { const chunkDir path.join(UPLOAD_DIR, req.body.fileMd5); if (!fs.existsSync(chunkDir)) { fs.mkdirSync(chunkDir, { recursive: true }); } cb(null, chunkDir); }, filename: (req, file, cb) { cb(null, ${req.body.chunkIndex}); }, }); const upload multer({ storage }); function readMeta() { if (!fs.existsSync(META_FILE)) return {}; return JSON.parse(fs.readFileSync(META_FILE, utf-8)); } function writeMeta(meta) { fs.writeFileSync(META_FILE, JSON.stringify(meta, null, 2)); } app.post(/exists, (req, res) { const { fileMd5, fileSize } req.body; const meta readMeta(); const record meta[fileMd5]; res.json({ data: { exists: !!(record record.size fileSize), }, }); }); app.post(/upload, upload.single(chunk), (req, res) { res.json({ code: 0, message: chunk received }); }); app.post(/merge, (req, res) { const { fileMd5, fileName } req.body; const chunkDir path.join(UPLOAD_DIR, fileMd5); const chunks fs.readdirSync(chunkDir); chunks.sort((a, b) a - b); const dest path.join(UPLOAD_DIR, fileName); const fd fs.openSync(dest, w); for (const chunk of chunks) { const chunkPath path.join(chunkDir, chunk); const data fs.readFileSync(chunkPath); fs.writeSync(fd, data); } fs.closeSync(fd); const meta readMeta(); meta[fileMd5] { size: fs.statSync(dest).size }; writeMeta(meta); res.json({ code: 0, message: merge done }); }); app.listen(3000, () { console.log(server running at http://localhost:3000); });這個(gè)后端的核心思路/exists做秒傳判斷看 meta.json 里是否有相同文件指紋記錄。/upload把分片保存到以 fileMd5 為名的目錄下文件名就是分片序號(hào)。/merge把所有分片按序號(hào)拼回原文件更新元數(shù)據(jù)。只跑 DEMO 的話完全夠用。真實(shí)項(xiàng)目里需要把 meta 換成 Redis MySQL磁盤存儲(chǔ)換成對(duì)象存儲(chǔ)OSS / MinIO分片合并也可以放到異步隊(duì)列里做不能在請(qǐng)求里同步合成幾百 MB 的文件。4.2 已上傳分片查詢與補(bǔ)傳機(jī)制斷點(diǎn)續(xù)傳的核心是前端要知道哪些分片上傳過了。后端加一個(gè)接口app.get(/chunks/:fileMd5, (req, res) { const chunkDir path.join(UPLOAD_DIR, req.params.fileMd5); if (!fs.existsSync(chunkDir)) { res.json({ data: { uploadedChunks: [] } }); return; } const chunks fs.readdirSync(chunkDir).map(Number); res.json({ data: { uploadedChunks: chunks } }); });前端拿到uploadedChunks后在分片上傳循環(huán)里直接跳過已存在的序號(hào)。進(jìn)度計(jì)算也要基于當(dāng)前累計(jì)已上傳數(shù)來做不能從 0 開始。5. 常見問題與排查技巧實(shí)錄5.1 計(jì)算哈希時(shí)瀏覽器卡死現(xiàn)象選了一個(gè) 2GB 的文件頁面直接白屏鼠標(biāo)都動(dòng)不了。原因FileReader 逐片讀取文件是在主線程執(zhí)行的循環(huán)幾萬次切片操作會(huì)持續(xù)占用渲染進(jìn)程。解決把哈希計(jì)算扔進(jìn) Web Worker。如果已經(jīng)用了 Worker 還卡檢查是不是你把fileHash.js里的 Worker 實(shí)例重復(fù)創(chuàng)建了或者你的 Worker 里又 require 了大模塊。我之前見過一個(gè)同事寫了 Worker但每次分片都 new 一個(gè) SparkMD5 實(shí)例內(nèi)存炸了也是卡。5.2 秒傳校驗(yàn)通過但文件遲遲不出現(xiàn)在目標(biāo)路徑現(xiàn)象前端拿到了秒傳成功提示但服務(wù)器上找不到文件。原因元數(shù)據(jù)記錄在了 meta.json但文件本身可能在第一次上傳之后被清理了或者是 merge 接口只更新了 meta沒有真正把分片拼裝成文件。解決/exists 判斷時(shí)不僅要查 meta 記錄還要校驗(yàn)?zāi)繕?biāo)文件是否真的存在于磁盤const destPath path.join(UPLOAD_DIR, fileName); const fileExists fs.existsSync(destPath); res.json({ data: { exists: !!record record.size fileSize fileExists } });注意 fileName 不要直接用用戶傳來的原始名有路徑穿越風(fēng)險(xiǎn)應(yīng)當(dāng)用哈希重命名存儲(chǔ)。5.3 分片合并后文件內(nèi)容損壞現(xiàn)象上傳完成后打開文件提示格式損壞或者 MD5 校驗(yàn)不通過。原因大概率是分片合并順序有問題。Node 的fs.readdirSync返回順序不一定是文件名的數(shù)字順序比如字符串排序會(huì)把 10 排在 2 前面導(dǎo)致合并錯(cuò)亂。解決合并前必須先按數(shù)字排序const chunks fs.readdirSync(chunkDir).sort((a, b) parseInt(a) - parseInt(b));這是一個(gè)非常經(jīng)典的坑。任何時(shí)候合并分片都要顯式排序別依賴文件系統(tǒng)返回順序。5.4 超大文件上傳時(shí)后端報(bào)錯(cuò) 413 Payload Too Large現(xiàn)象本地開發(fā)跑得好好的放到 Nginx 后面就失敗。原因Nginx 默認(rèn)client_max_body_size是 1MB分片雖然只有 5MB但也會(huì)被攔下來。解決在 Nginx 配置里顯式聲明client_max_body_size 10m;如果你后續(xù)調(diào)大分片這個(gè)值跟著調(diào)大就行。如果服務(wù)器上有網(wǎng)關(guān)層也需要檢查網(wǎng)關(guān)的請(qǐng)求體大小限制。5.5 前后端聯(lián)調(diào)時(shí) CORS 報(bào)錯(cuò)本地用 Vite5173去請(qǐng)求后端3000端口瀏覽器會(huì)攔截跨域響應(yīng)。在后端加上const cors require(cors); app.use(cors());DEMO 階段直接放開所有來源沒毛病生產(chǎn)環(huán)境再按域名白名單收緊。6. 實(shí)操心得與擴(kuò)展建議6.1 從 DEMO 到生產(chǎn)級(jí)上傳組件你還需要補(bǔ)什么這個(gè) DEMO 跑通之后距離生產(chǎn)環(huán)境還有一些距離我列一下優(yōu)先級(jí)比較高的增強(qiáng)點(diǎn)上傳任務(wù)持久化刷新頁面之后已傳分片還能查到續(xù)傳不丟。接入文件流加密敏感場(chǎng)景下分片內(nèi)容要做 AES 加密再上傳服務(wù)端解密落盤。后端摘要二次校驗(yàn)分片合并完成后后端重新計(jì)算 MD5和前端傳過來的 fileMd5 比對(duì)能發(fā)現(xiàn)傳輸過程中被篡改或損壞的問題。進(jìn)度展示優(yōu)化結(jié)合請(qǐng)求耗時(shí)、網(wǎng)絡(luò)吞吐預(yù)估剩余時(shí)間而不是只顯示百分比。拖拽上傳與文件夾上傳HTML5 的 DataTransfer 接口可以輕松實(shí)現(xiàn)視覺體驗(yàn)提升很大。并發(fā)閾值自適應(yīng)根據(jù)網(wǎng)絡(luò)環(huán)境動(dòng)態(tài)調(diào)整并發(fā)數(shù)弱網(wǎng)時(shí)降低并發(fā)避免大量重試。6.2 一個(gè)容易踩的坑文件重復(fù)上傳時(shí)的重復(fù)合并你可能會(huì)遇到這種情況用戶第一次上傳時(shí)中斷了第二次點(diǎn)開始上傳秒傳校驗(yàn)沒通過服務(wù)端沒記錄完整文件走分片上傳但是服務(wù)端已經(jīng)殘留了一部分分片。如果后端合并接口不檢查已有分片是否存在可能重復(fù)執(zhí)行 merge把兩個(gè)不完整的文件拼在一起。我的做法是 merge 之前先檢查目標(biāo)文件是否已經(jīng)存在如果存在且 size 等于記錄值直接返回成功。如果 size 不一致則先刪除殘留分片目錄再?gòu)牧汩_始傳保證分片干凈。6.3 最后分享一個(gè)小技巧很多大文件上傳場(chǎng)景會(huì)碰到用戶等不到計(jì)算哈希完成就關(guān)頁面的問題。我的經(jīng)驗(yàn)是在哈希計(jì)算階段就開始做用戶引導(dǎo)比如顯示正在分析文件請(qǐng)勿關(guān)閉頁面同時(shí)把哈希計(jì)算的粒度調(diào)得細(xì)一些比如 2MB 一片進(jìn)度條能更快動(dòng)起來用戶就不會(huì)以為卡死了。還有一個(gè)細(xì)節(jié)對(duì)體驗(yàn)影響很大秒傳成功后建議給一個(gè)動(dòng)畫反饋比如打勾或者彈一層遮罩玩家心理上會(huì)有這么快就完成了的驚喜感。續(xù)傳、并發(fā)控制的完整代碼其實(shí)在這個(gè) DEMO 基礎(chǔ)上加不了多少但生產(chǎn)工程里每一步都要考慮到異常處理和資源釋放這塊值得你花時(shí)間好好打磨。