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