前陣子接了個(gè)老項(xiàng)目升級(jí)的活后臺(tái)管理系統(tǒng)還是五六年前的jQuery寫法為了長(zhǎng)期發(fā)展老板要求整體往vue3遷。但業(yè)務(wù)不能停老頁(yè)面不能一下子推翻重寫最頭疼的是一個(gè)素材上傳模塊——用戶經(jīng)常要傳幾個(gè)G的視頻、壓縮包和設(shè)計(jì)稿以前用傳統(tǒng)form上傳動(dòng)不動(dòng)就超時(shí)傳到一半斷網(wǎng)就只能從頭再來(lái)。需求寫得很明確新功能必須用vue3實(shí)現(xiàn)老頁(yè)面繼續(xù)用jQuery跑同時(shí)必須支持大文件秒傳。就這么一個(gè)“新老結(jié)合”的技術(shù)場(chǎng)景前后磨了一周多。今天把jQuery與vue3混合開(kāi)發(fā)大文件秒傳功能的整套實(shí)現(xiàn)思路、核心代碼和踩過(guò)的坑都整理出來(lái)給同樣在改造老項(xiàng)目的朋友一個(gè)參考。這套方案的適用面其實(shí)很寬只要你的項(xiàng)目正處在jQuery向vue3過(guò)渡的階段或者你負(fù)責(zé)維護(hù)一個(gè)老系統(tǒng)但需要接入現(xiàn)代化上傳體驗(yàn)都應(yīng)該能從中找到能直接用的東西。1. 內(nèi)容整體設(shè)計(jì)與思路拆解1.1 混合開(kāi)發(fā)場(chǎng)景解析為什么不是重寫而是共存很多團(tuán)隊(duì)遇到老項(xiàng)目升級(jí)第一反應(yīng)是“找時(shí)間重寫”。但真實(shí)業(yè)務(wù)場(chǎng)景里老系統(tǒng)背后往往有幾十張表、幾百個(gè)接口、一堆沒(méi)人敢動(dòng)的報(bào)表邏輯全量重寫周期至少按年算業(yè)務(wù)不可能停下來(lái)等你。漸進(jìn)式改造就成了唯一理性選擇老頁(yè)面繼續(xù)穩(wěn)定運(yùn)行新功能以vue3模塊的方式嵌入到老頁(yè)面里去。這條路聽(tīng)起來(lái)簡(jiǎn)單實(shí)際做起來(lái)有一堆細(xì)節(jié)要處理。vue3是組件化、響應(yīng)式的思維jQuery是命令式、直接操作DOM的思維兩者混在一起如果不加隔離很快就亂成一鍋粥。我的做法是把上傳這類新功能整體放到一個(gè)由vue3控制的獨(dú)立容器里jQuery只負(fù)責(zé)老頁(yè)面的交互兩者通過(guò)約定的接口通信不互相碰對(duì)方的DOM結(jié)構(gòu)。另外要認(rèn)清一點(diǎn)混合開(kāi)發(fā)不是長(zhǎng)期目標(biāo)它只是過(guò)渡期的手段。所以新增代碼盡量寫框架無(wú)關(guān)的邏輯比如文件切片、hash計(jì)算、上傳隊(duì)列這些純JS能力抽出來(lái)誰(shuí)都能調(diào)將來(lái)vue3全面接管了這部分代碼可以直接復(fù)用。1.2 秒傳功能的原理與它解決的痛點(diǎn)很多人以為秒傳是“網(wǎng)絡(luò)快”其實(shí)秒傳根本不是傳輸而是“跳過(guò)傳輸”。文件在服務(wù)端本質(zhì)上就是一堆字節(jié)。如果兩個(gè)文件的內(nèi)容完全一致那它們的字節(jié)也完全一致。前端拿到用戶選擇的文件后先對(duì)文件內(nèi)容做一次hash計(jì)算md5或sha1得到一個(gè)指紋字符串。把這個(gè)指紋提交給服務(wù)端服務(wù)端在自己的存儲(chǔ)里查一下——如果之前已經(jīng)有人上傳過(guò)內(nèi)容完全相同的文件就直接返回一個(gè)“已存在”的標(biāo)識(shí)前端立即提示上傳完成。整個(gè)過(guò)程中實(shí)際傳輸?shù)闹挥袔譑B的請(qǐng)求數(shù)據(jù)大幾G的文件瞬間完成這就是“秒傳”的真相。秒傳解決的核心痛點(diǎn)是“重復(fù)上傳”。在素材管理、視頻處理、文檔協(xié)作這類場(chǎng)景里團(tuán)隊(duì)內(nèi)反復(fù)傳同一個(gè)大文件的情況非常常見(jiàn)。如果沒(méi)有秒傳每個(gè)用戶都要完整傳一遍既浪費(fèi)帶寬又浪費(fèi)時(shí)間。有了秒傳相同內(nèi)容只真正上傳一次后續(xù)所有人都是秒開(kāi)。但秒傳也不是萬(wàn)能的它只能處理“服務(wù)端已經(jīng)存在相同內(nèi)容”的場(chǎng)景。如果服務(wù)端沒(méi)有這個(gè)文件那還是得走分片上傳。所以完整的方案是秒傳優(yōu)先分片兜底兩者結(jié)合。1.3 上傳方案選型對(duì)比為什么最終選擇分片加秒傳在確定方案之前我把幾種主流上傳方式放在一起做了對(duì)比方案核心原理優(yōu)點(diǎn)缺點(diǎn)適用場(chǎng)景普通form上傳瀏覽器直接POST整個(gè)文件實(shí)現(xiàn)最簡(jiǎn)單無(wú)法監(jiān)聽(tīng)進(jìn)度、超時(shí)容易失敗、無(wú)斷點(diǎn)續(xù)傳小文件、內(nèi)部工具分片上傳文件切成多塊順序上傳支持?jǐn)帱c(diǎn)續(xù)傳、失敗重傳成本低需要前后端配合分片與合并大文件、弱網(wǎng)環(huán)境斷點(diǎn)續(xù)傳記錄已上傳分片續(xù)傳時(shí)代跳過(guò)對(duì)網(wǎng)絡(luò)波動(dòng)容忍度高需要服務(wù)端記錄分片狀態(tài)大文件、移動(dòng)端弱網(wǎng)秒傳hash判重跳過(guò)實(shí)際傳輸體驗(yàn)極致零等待依賴服務(wù)端已有數(shù)據(jù)重復(fù)內(nèi)容多的平臺(tái)最終方案定為“分片上傳 斷點(diǎn)續(xù)傳 hash秒傳”的組合。前兩步保證大文件在常規(guī)網(wǎng)絡(luò)環(huán)境下能傳得動(dòng)第三步提升重復(fù)場(chǎng)景下的體驗(yàn)。三者在前端流程里是串在一起的先算hash查重查到了直接秒傳沒(méi)查到就切分片上傳過(guò)程中記錄已上傳分片中斷后可以從斷點(diǎn)繼續(xù)。2. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)2.1 分片大小、并發(fā)數(shù)與內(nèi)存的關(guān)系分片大小沒(méi)有絕對(duì)標(biāo)準(zhǔn)但選錯(cuò)了體驗(yàn)差別很大。我常用的分片大小是5MB同時(shí)控制并發(fā)數(shù)為3到5。這個(gè)組合在多數(shù)辦公網(wǎng)環(huán)境下表現(xiàn)穩(wěn)定。分片太小會(huì)有問(wèn)題。比如1GB文件如果按1MB切就是1024個(gè)分片每個(gè)分片都要發(fā)起一次HTTP請(qǐng)求光請(qǐng)求開(kāi)銷就把帶寬優(yōu)勢(shì)抵消了。再加上服務(wù)端合并分片時(shí)文件數(shù)量多意味著排序、I/O操作更頻繁合并耗時(shí)也明顯變長(zhǎng)。分片太大也有問(wèn)題一個(gè)分片傳半天中途失敗重傳的成本高進(jìn)度反饋也不夠細(xì)。并發(fā)數(shù)同樣需要控制。并發(fā)太高瀏覽器會(huì)創(chuàng)建大量連接突破服務(wù)器連接上限后反而互相爭(zhēng)搶帶寬單個(gè)分片傳輸速度直線下降。我做過(guò)一個(gè)簡(jiǎn)單測(cè)試在10MB帶寬下并發(fā)3到5基本能跑滿帶寬并發(fā)上到10之后總吞吐量反而掉了。原因是分片傳輸也要經(jīng)過(guò)TCP握手、TLS協(xié)商等過(guò)程連接過(guò)多會(huì)引入大量排隊(duì)和重傳。內(nèi)存方面前端要盡量避免一次性把整個(gè)文件讀入內(nèi)存。切分片用的是File.slice方法它返回的是原始文件的引用視圖并不是真正把數(shù)據(jù)拷貝出來(lái)所以內(nèi)存壓力基本可控。真正吃內(nèi)存的是計(jì)算hash時(shí)的FileReader讀取過(guò)程這個(gè)需要分塊讀取、逐塊追加不能一次性讀整個(gè)大文件。2.2 文件指紋hash的計(jì)算策略文件hash是整個(gè)秒傳功能的地基地基歪了什么都白搭。目前工程里用得最多的是spark-md5這個(gè)庫(kù)它支持增量追加可以配合FileReader把大文件一片一片讀進(jìn)內(nèi)存計(jì)算這樣內(nèi)存占用始終保持在較低水平。這里有兩個(gè)策略選擇全量計(jì)算和抽樣計(jì)算。全量計(jì)算就是讀文件的每一個(gè)字節(jié)參與hash計(jì)算準(zhǔn)確率最高但大文件耗時(shí)長(zhǎng)。一個(gè)500MB的文件在全量計(jì)算下可能需要5到10秒期間如果放在UI線程會(huì)直接卡死頁(yè)面。解決辦法是把計(jì)算放到Web Worker里異步執(zhí)行或者用requestIdleCallback在瀏覽器空閑時(shí)段分片處理。抽樣計(jì)算則只取文件頭部、中間、尾部的一部分字節(jié)參與hash速度很快但準(zhǔn)確率差一些不同文件可能算出相同hash容易造成誤判。我的建議是追求體驗(yàn)可以先用抽樣hash做快速判斷命中后進(jìn)入分片上傳流程由服務(wù)端按完整hash做最終確認(rèn)。如果項(xiàng)目規(guī)模不大、使用人數(shù)少直接全量計(jì)算更省心。還有一點(diǎn)必須注意hash計(jì)算必須基于文件內(nèi)容不能基于文件名。同一個(gè)文件重命名后內(nèi)容不變hash應(yīng)該一致反過(guò)來(lái)兩個(gè)文件內(nèi)容完全一樣但名字不同也應(yīng)該判重為同一個(gè)文件。有的實(shí)現(xiàn)圖省事直接用文件路徑加文件名算hash這種方案遇到同名不同內(nèi)容的文件就會(huì)出嚴(yán)重問(wèn)題。2.3 秒傳判重、分片上傳、合并確認(rèn)的三段式接口設(shè)計(jì)接口設(shè)計(jì)好不好直接決定前后端對(duì)接效率。我按照“判重、上傳、合并確認(rèn)”三個(gè)階段設(shè)計(jì)了三個(gè)核心接口。第一個(gè)是hash判重接口前端計(jì)算完文件hash后調(diào)用。請(qǐng)求參數(shù)帶上fileHash、fileName、fileSize服務(wù)端返回文件是否存在。為了防止hash碰撞服務(wù)端可以順帶比對(duì)fileSize大小不一致就直接判不存在不用再讀文件內(nèi)容。第二個(gè)是分片上傳接口用于真實(shí)傳輸文件分片。請(qǐng)求參數(shù)要帶fileHash、index、total、fileName文件本體放在FormData的file字段里。服務(wù)端接收到分片后存到臨時(shí)目錄文件名建議用“fileHash_index.part”這種格式方便后續(xù)合并定位。第三個(gè)是合并確認(rèn)接口當(dāng)前端所有分片上傳完成后觸發(fā)。服務(wù)端根據(jù)fileHash在臨時(shí)目錄找到全部分片按index排序后流式合并成最終文件合并完成返回文件訪問(wèn)路徑。這一步盡量不要做成“邊傳邊合”因?yàn)榉制竭_(dá)順序是亂序的邊傳邊合容易寫壞文件。2.4 并發(fā)控制與進(jìn)度上報(bào)機(jī)制并發(fā)控制如果寫在每個(gè)分片請(qǐng)求的for循環(huán)里那等于沒(méi)有控制。我在實(shí)現(xiàn)里是手動(dòng)維護(hù)一個(gè)任務(wù)隊(duì)列隊(duì)列里有待上傳的分片任務(wù)通過(guò)一個(gè)控制函數(shù)限制同時(shí)執(zhí)行的任務(wù)數(shù)每完成一個(gè)就從隊(duì)列取下一個(gè)補(bǔ)上。這種寫法雖然比并行丟棄全部請(qǐng)求要復(fù)雜一些但對(duì)網(wǎng)絡(luò)和服務(wù)端壓力都很友好斷網(wǎng)重試也能自然銜接。進(jìn)度上報(bào)要區(qū)分兩個(gè)維度上傳進(jìn)度和整體進(jìn)度。上傳進(jìn)度指的是當(dāng)前分片請(qǐng)求的字節(jié)進(jìn)度可以用axios的onUploadProgress或XHR的upload.onprogress拿到把它換算成總進(jìn)度里的一個(gè)比例。整體進(jìn)度則是“已成功上傳分片數(shù)/總分片數(shù)”在主線程根據(jù)任務(wù)完成數(shù)計(jì)算直接驅(qū)動(dòng)vue3的進(jìn)度條。兩個(gè)進(jìn)度相互配合用戶看到的進(jìn)度條才會(huì)既有顆粒感又有穩(wěn)定性。3. 實(shí)操過(guò)程jQuery與vue3混合開(kāi)發(fā)的核心環(huán)節(jié)實(shí)現(xiàn)3.1 vue3在老頁(yè)面里安全掛載互不干擾在jQuery頁(yè)面里引入vue3最大的忌諱是直接拿vue3接管整個(gè)頁(yè)面的body。老頁(yè)面有一堆綁定在body上的事件、彈窗、定時(shí)器vue3掛載時(shí)會(huì)重建DOM這些老邏輯會(huì)瞬間失效。我的做法是單獨(dú)劃出一個(gè)上傳區(qū)域只要老頁(yè)面上留一個(gè)空的div容器在jQuery代碼里調(diào)用vue3的createApp把這個(gè)容器作為掛載點(diǎn)。這樣vue3只管自己的這塊DOM老頁(yè)面的其他部分繼續(xù)由jQuery掌控。// 老頁(yè)面的jQuery邏輯里在DOM ready之后掛載vue3 $(document).ready(function () { // 老業(yè)務(wù)代碼繼續(xù)跑 initOldList(); // 新上傳功能由vue3接管 import(./vue/UploadModule.js).then(({ mountUploadModule }) { mountUploadModule(#upload-module); }); });UploadModule.js內(nèi)部就是標(biāo)準(zhǔn)的vue3啟動(dòng)邏輯創(chuàng)建應(yīng)用實(shí)例、掛載router或狀態(tài)、mount到指定容器。這種方式的好處是vue3模塊加載是異步的不阻礙老頁(yè)面首屏渲染掛載位置可控不會(huì)誤傷老邏輯。3.2 上傳核心邏輯抽成框架無(wú)關(guān)的純JS模塊混合開(kāi)發(fā)最怕寫出來(lái)的代碼和框架綁死。我在這個(gè)項(xiàng)目里把上傳核心邏輯完全抽離成純JS模塊uploader.js內(nèi)部不依賴vue、不依賴jQuery只暴露幾個(gè)方法計(jì)算hash、判重、分片上傳、斷點(diǎn)續(xù)傳、取消任務(wù)。UI層無(wú)論是vue3還是jQuery都只是調(diào)用它然后展示狀態(tài)。這樣設(shè)計(jì)的好處很明顯第一vue3組件和jQuery頁(yè)面可以共用同一套上傳能力第二將來(lái)把整個(gè)頁(yè)面都遷到vue3時(shí)上傳邏輯不用重寫第三出問(wèn)題時(shí)很好調(diào)試純JS模塊可以脫離UI單獨(dú)測(cè)試。// uploader.js 模塊導(dǎo)出結(jié)構(gòu) export const Uploader { calcFileHash(file, onProgress) {}, checkExist(fileHash) {}, uploadChunks(file, fileHash, options) {}, cancel() {}, getProgress() {} };// jquery老頁(yè)面直接引用不需要vue3 const uploader new Uploader(); uploader.calcFileHash(file, (p) { $(#hash-progress).text(Math.round(p * 100) %); });而在vue3組件里同樣調(diào)用Uploader只是把回調(diào)綁定到響應(yīng)式變量上UI由模板驅(qū)動(dòng)。這樣一份邏輯服務(wù)兩端真正體現(xiàn)混合開(kāi)發(fā)的優(yōu)雅之處。3.3 jQuery與vue3之間的通信機(jī)制兩套框架共存通信是繞不開(kāi)的問(wèn)題。我總結(jié)出三個(gè)層級(jí)的通信方式按場(chǎng)景選用。第一個(gè)是全局方法掛載。在vue3模塊啟動(dòng)時(shí)把一些能力掛到window上比如window.$uploader { addFile, getStatus }。老頁(yè)面jQuery里可以直接調(diào)用這個(gè)方法把選中的文件交給vue3上傳組件處理。這個(gè)方式最簡(jiǎn)單但要注意命名空間避免污染全局。第二個(gè)是自定義事件。vue3側(cè)通過(guò)dispatchEvent發(fā)自定義事件比如window.dispatchEvent(new CustomEvent(upload-finished, { detail: { fileHash, url } }))jQuery側(cè)用$(window).on(upload-finished, handler)監(jiān)聽(tīng)。反過(guò)來(lái)jQuery觸發(fā)vue3也一樣用事件。這種方式的優(yōu)點(diǎn)是解耦雙方各自監(jiān)聽(tīng)自己關(guān)心的事件不需要互相引用實(shí)例。第三個(gè)是共享狀態(tài)對(duì)象。定義一個(gè)小小的狀態(tài)store用vue3的reactive包裹但把store實(shí)例暴露出去。jQuery和vue3都能讀寫store里的字段vue3由于是響應(yīng)式的store變化會(huì)自動(dòng)更新UI。這個(gè)適合需要頻繁同步狀態(tài)的場(chǎng)景比如上傳隊(duì)列、任務(wù)進(jìn)度、錯(cuò)誤信息等。實(shí)際項(xiàng)目中我大多數(shù)場(chǎng)景用第一種和第二種結(jié)合狀態(tài)同步用第三種。訓(xùn)練下來(lái)的體會(huì)是通信越簡(jiǎn)單越好不要讓jQuery代碼直接操作vue3內(nèi)部的ref變量封裝成方法或事件是更安全的邊界。3.4 樣式與依賴沖突的規(guī)避方案jQuery項(xiàng)目多數(shù)用的是老式全局CSSvue3這邊如果用element-plus這類組件庫(kù)兩邊的樣式很容易互相打架。最典型的是reset樣式和全局padding、font-family不一致vue組件在jQuery頁(yè)面里渲染出來(lái)按鈕大小、間距都和預(yù)期不一樣。我的處理方式是三條線并行。第一vue組件內(nèi)部樣式全部加scoped避免組件樣式泄漏到老頁(yè)面第二引入U(xiǎn)I庫(kù)時(shí)不要全量引入按需加載組件和樣式減少全局污染面第三在vue3掛載容器下單獨(dú)恢復(fù)一套基礎(chǔ)樣式變量和老頁(yè)面的樣式設(shè)定做隔離。依賴沖突方面最怕的是兩套框架各自引入不同版本的公共庫(kù)。老jQuery項(xiàng)目可能全局掛在window.$vue3項(xiàng)目里如果也直接依賴jQuery就亂套了。我的原則是vue3組件里絕不直接使用全局的jQuery對(duì)象所有DOM操作和事件都走vue的方式老jQuery頁(yè)面里也不直接操作vue3內(nèi)部的DOM結(jié)構(gòu)。兩條線徹底分開(kāi)不要交叉引用。4. 完整實(shí)現(xiàn)流程與關(guān)鍵代碼4.1 文件hash計(jì)算的完整實(shí)現(xiàn)hash計(jì)算我用的是spark-md5讀取分塊追加計(jì)算。下面的實(shí)現(xiàn)可以直接放到uploader.js里import SparkMD5 from spark-md5; export function calcFileHash(file, onProgress) { return new Promise((resolve, reject) { const chunkSize 2 * 1024 * 1024; // 每塊2MB const chunkCount Math.ceil(file.size / chunkSize); const spark new SparkMD5.ArrayBuffer(); const fileReader new FileReader(); let currentChunk 0; fileReader.onerror (e) { reject(new Error(文件讀取失敗)); }; fileReader.onload (e) { spark.append(e.target.result); currentChunk; if (onProgress) { onProgress(currentChunk / chunkCount); } if (currentChunk chunkCount) { loadNext(); } else { const fileHash spark.end(); resolve(fileHash); } }; function loadNext() { const start currentChunk * chunkSize; const end Math.min(start chunkSize, file.size); fileReader.readAsArrayBuffer(file.slice(start, end)); } loadNext(); }); }實(shí)際運(yùn)行中500MB文件在普通PC上大約需要5到8秒完成hash計(jì)算。如果覺(jué)得這個(gè)時(shí)間太長(zhǎng)優(yōu)先考慮把它搬進(jìn)Web Worker而不是降低hash計(jì)算的準(zhǔn)確性。Web Worker里不能直接訪問(wèn)File對(duì)象需要先把文件傳到worker里但spark-md5在worker里運(yùn)行完全沒(méi)問(wèn)題UI線程不會(huì)卡。4.2 分片并發(fā)上傳與秒傳判定流程整個(gè)上傳流程走的是狀態(tài)機(jī)模式。每次用戶選中文件先計(jì)算hash然后做秒傳判定。判定命中就直接完成未命中就進(jìn)入分片上傳中間隨時(shí)可以取消、暫停、續(xù)傳。export async function uploadFile(file, options) { const { checkUrl, uploadUrl, mergeUrl, chunkSize 5 * 1024 * 1024 } options; // 第一步計(jì)算文件hash const fileHash await calcFileHash(file, (p) { options.onHashProgress options.onHashProgress(p); }); // 第二步秒傳判定 const checkRes await axios.post(checkUrl, { fileHash, fileName: file.name, fileSize: file.size }); if (checkRes.data.data checkRes.data.data.exist) { options.onSuccess options.onSuccess({ quick: true, url: checkRes.data.data.url, fileHash }); return; } // 第三步分片上傳與斷點(diǎn)續(xù)傳 const totalChunks Math.ceil(file.size / chunkSize); let uploadedChunks await getUploadedChunks(fileHash); // 查詢已上傳分片 const needUploadChunks []; for (let i 0; i totalChunks; i) { if (!uploadedChunks.includes(i)) { needUploadChunks.push(i); } } await runWithConcurrency(needUploadChunks, 3, async (index) { const start index * chunkSize; const end Math.min(start chunkSize, file.size); const formData new FormData(); formData.append(file, file.slice(start, end)); formData.append(fileHash, fileHash); formData.append(index, index); formData.append(total, totalChunks); formData.append(fileName, file.name); await axios.post(uploadUrl, formData, { headers: { Content-Type: multipart/form-data } }); }); // 第四步觸發(fā)服務(wù)端合并 await axios.post(mergeUrl, { fileHash, fileName: file.name, totalChunks }); options.onSuccess options.onSuccess({ quick: false, fileHash }); }并發(fā)控制函數(shù)我用一個(gè)手寫的runWithConcurrency簡(jiǎn)潔直觀async function runWithConcurrency(tasks, limit, worker) { const queue tasks.slice(); let running 0; return new Promise((resolve, reject) { function next() { if (queue.length 0) { if (running 0) resolve(); return; } while (running limit queue.length 0) { const task queue.shift(); running; worker(task) .then(() { running--; next(); }) .catch((err) { reject(err); }); } } next(); }); }這個(gè)寫法的好處是控制明確出錯(cuò)時(shí)可以整體退出也可以按需求改成單個(gè)分片重試幾次。4.3 vue3 UI層的組件實(shí)現(xiàn)與jQuery側(cè)調(diào)用方式vue3這邊的UI我封裝成一個(gè)UploadPanel組件負(fù)責(zé)展示文件列表、進(jìn)度條和狀態(tài)信息。它只通過(guò)props接收配置通過(guò)事件向外發(fā)通知完全不關(guān)心外層是jQuery還是vue3。template div classupload-panel div v-fortask in taskList :keytask.fileHash classtask-item div classtask-name{{ task.fileName }}/div div classtask-progress div classprogress-bar :style{ width: task.progress % }/div /div div classtask-status{{ task.statusText }}/div /div /div /template script setup import { ref, onMounted } from vue; import { Uploader } from ../utils/uploader.js; const taskList ref([]); function addFile(file) { const task { fileName: file.name, fileHash: , progress: 0, statusText: 等待開(kāi)始 }; taskList.value.push(task); Uploader.calcFileHash(file, (p) { task.fileHash uploadState.fileHash; task.progress Math.round(p * 100); task.statusText 計(jì)算文件指紋中; }); uploadFile(file, { checkUrl: /api/file/hash/check, uploadUrl: /api/file/upload, mergeUrl: /api/file/merge }).then((res) { task.statusText res.quick ? 秒傳成功 : 上傳成功; task.progress 100; }); } defineExpose({ addFile }); /script注意組件里沒(méi)有iframe相關(guān)的代碼這里截圖的是簡(jiǎn)化版。實(shí)際使用中如果jQuery頁(yè)面是普通script引入方式需要通過(guò)window.$uploader把a(bǔ)ddFile方法暴露出去// 啟動(dòng)vue3模塊時(shí)掛載方法到window import { createApp } from vue; import UploadPanel from ./UploadPanel.vue; export function mountUploadModule(selector) { const app createApp(UploadPanel); const instance app.mount(selector); window.$uploader { addFile: (file) instance.addFile(file), getTaskList: () instance.taskList }; return instance; }jQuery側(cè)在原來(lái)的文件選擇事件里調(diào)用$(#btn-select-file).on(change, function (e) { const file e.target.files[0]; if (window.$uploader) { window.$uploader.addFile(file); } else { // 降級(jí)到老上傳邏輯或提示模塊尚未加載完成 } });這樣老頁(yè)面只是新增了一行調(diào)用原來(lái)綁定在按鈕上的其他jQuery事件完全不受影響。4.4 后端接口約定的建議寫法與偽代碼前端做完后端如果不知道按什么規(guī)范接整個(gè)方案也跑不起來(lái)。這里給出一個(gè)后端接口的偽代碼約定用Node.js風(fēng)格示意邏輯同樣適用于Java、Go等其他語(yǔ)言。// POST /api/file/hash/check // request body: { fileHash, fileName, fileSize } // response: { code: 0, data: { exist: true, url: /files/xxx.zip } } async function checkHash(req, res) { const { fileHash, fileSize } req.body; const record await db.findFileByHash(fileHash); if (record record.size fileSize) { res.json({ code: 0, data: { exist: true, url: record.url } }); } else { res.json({ code: 0, data: { exist: false } }); } }// POST /api/file/upload // multipart/form-data 里帶 file 文件本體和其他字段 async function uploadChunk(req, res) { const { fileHash, index, total, fileName } req.body; const file req.file; const tmpPath path.join(tmpDir, ${fileHash}_${index}.part); await fs.promises.writeFile(tmpPath, file.buffer); // 記錄分片索引到redis或db方便斷點(diǎn)續(xù)傳查詢 await redis.sadd(upload:${fileHash}:chunks, index); res.json({ code: 0 }); }// POST /api/file/merge async function mergeChunks(req, res) { const { fileHash, fileName, totalChunks } req.body; const chunkList []; for (let i 0; i totalChunks; i) { chunkList.push(path.join(tmpDir, ${fileHash}_${i}.part)); } // 必須按index順序合并 const writeStream fs.createWriteStream(finalPath); for (const chunkPath of chunkList) { const data await fs.promises.readFile(chunkPath); writeStream.write(data); await fs.promises.unlink(chunkPath); // 合并后刪除分片 } writeStream.end(); await db.createFileRecord({ fileHash, url: finalUrl, size: stat.size }); res.json({ code: 0, data: { url: finalUrl } }); }后端一個(gè)關(guān)鍵點(diǎn)是分片臨時(shí)文件的清理策略防止用戶上傳到一半放棄臨時(shí)文件成了垃圾。我一般會(huì)在記錄里加上創(chuàng)建時(shí)間定時(shí)任務(wù)清理超過(guò)24小時(shí)且未合并的分片。5. 踩坑實(shí)錄與排查技巧5.1 秒傳判定成功但下載下來(lái)的文件是空的這個(gè)坑讓我排查了一個(gè)下午?，F(xiàn)象是hash判重接口返回exist:true前端提示秒傳成功但用戶打開(kāi)文件發(fā)現(xiàn)是0字節(jié)。最后查下來(lái)是服務(wù)端判重邏輯的問(wèn)題分片合并完成后服務(wù)端只是寫了一條文件記錄但物理文件因?yàn)榇鎯?chǔ)路徑配置錯(cuò)誤沒(méi)有真正落盤。判重接口卻只看數(shù)據(jù)庫(kù)記錄于是返回了錯(cuò)誤的存在標(biāo)記。解決方法是判重接口必須同時(shí)比對(duì)文件在存儲(chǔ)系統(tǒng)中的真實(shí)狀態(tài)和文件大小不能只查記錄。前端側(cè)也要加一層體驗(yàn)保障——秒傳成功后如果用戶立即訪問(wèn)接口返回的文件地址必須能正常打開(kāi)等價(jià)于增加一次可用性探測(cè)。5.2 jQuery的contentType坑FormData被轉(zhuǎn)成字符串這個(gè)坑專門針對(duì)混合開(kāi)發(fā)場(chǎng)景。老項(xiàng)目里有很多用$.ajax發(fā)請(qǐng)求的代碼如果你在jQuery里寫上傳分片很容易想當(dāng)然$.ajax({ url: /api/file/upload, method: POST, data: formData, success: function () {} });這個(gè)寫法看起來(lái)沒(méi)問(wèn)題實(shí)際上jQuery默認(rèn)的contentType是application/x-www-form-urlencoded; charsetUTF-8把FormData強(qiáng)行轉(zhuǎn)成了表單字符串后端拿不到文件。正確的寫法必須顯式設(shè)置兩個(gè)選項(xiàng)$.ajax({ url: /api/file/upload, method: POST, data: formData, processData: false, // 不要處理data contentType: false, // 讓瀏覽器自動(dòng)設(shè)置multipart boundary success: function () {} });如果你在vue3側(cè)用axios默認(rèn)沒(méi)這個(gè)問(wèn)題但混合開(kāi)發(fā)里很容易出現(xiàn)“vue3里能傳切到j(luò)Query頁(yè)就傳不上去”90%都是這個(gè)原因。我后來(lái)為了統(tǒng)一把上傳請(qǐng)求全部走uploader.js里的XHR封裝不再讓jQuery經(jīng)手上傳邏輯。5.3 hash計(jì)算期間瀏覽器假死大文件全量計(jì)算hash確實(shí)吃CPU如果直接在主線程跑文件一大頁(yè)面就完全卡住用戶點(diǎn)哪都沒(méi)反應(yīng)。我的解決方案是把hash計(jì)算丟到Web Worker里。Web Worker里接收整個(gè)File對(duì)象不行但可以接收ArrayBuffer分片。主線程負(fù)責(zé)按塊讀取文件然后用postMessage傳給workerworker里調(diào)用SparkMD5追加算完再把結(jié)果傳回主線程。這樣UI線程幾乎無(wú)感期間還可以正常滾動(dòng)頁(yè)面、點(diǎn)擊按鈕。如果項(xiàng)目里不方便起Worker也可以用requestIdleCallback把計(jì)算片段拆散到瀏覽器空閑時(shí)段執(zhí)行但效果比Worker差一截高峰期還是會(huì)卡。建議有條件直接上Worker。5.4 并發(fā)上傳后合并出來(lái)的文件偶爾損壞文件合并損壞的檢查方法很簡(jiǎn)單合并完成后用hash工具重新算一遍最終文件的hash和前端算出來(lái)的fileHash比對(duì)不一致就是合并有問(wèn)題。常見(jiàn)的合并問(wèn)題有兩個(gè)。第一個(gè)是分片順序錯(cuò)亂服務(wù)端沒(méi)有按index排序就拼接內(nèi)容第二個(gè)是合并過(guò)程中還在接收新的上傳分片文件被并發(fā)寫入行為弄臟。我的處理方式是在merge接口里做兩層保護(hù)第一層合并前檢查臨時(shí)目錄下的分片數(shù)量是否等于totalChunks數(shù)量不對(duì)直接拒絕合并第二層合并期間對(duì)同一個(gè)fileHash加鎖防止重復(fù)合并或邊傳邊合。這樣處理后文件損壞的問(wèn)題就再?zèng)]出現(xiàn)過(guò)了。5.5 vue3掛載區(qū)域?qū)е吕蟡Query事件失效老頁(yè)面里如果某個(gè)按鈕點(diǎn)擊后動(dòng)態(tài)往上傳區(qū)域塞DOM或者用了html()方法替換節(jié)點(diǎn)很容易把vue3掛載出來(lái)的DOM給換掉導(dǎo)致元素雖然看著還在但事件綁定全沒(méi)了。這是因?yàn)関ue3的虛擬DOM會(huì)維護(hù)自己的一套節(jié)點(diǎn)引用jQuery直接改DOM結(jié)構(gòu)vue3完全感知不到兩邊就產(chǎn)生了不一致。我的處理方法是立一條規(guī)矩凡是被vue3接管的DOM區(qū)域老代碼一律不許直接操作需要改數(shù)據(jù)就用暴露出來(lái)的方法更新。vue3區(qū)域的DOM增刪、屬性修改都交給vue3響應(yīng)式系統(tǒng)。同時(shí)老頁(yè)面如果要銷毀上傳區(qū)域比如切換菜單不要用remove()直接刪節(jié)點(diǎn)而是調(diào)vue3實(shí)例的unmount方法這樣才能保證資源正確釋放。5.6 斷點(diǎn)續(xù)傳查詢接口要謹(jǐn)慎處理斷點(diǎn)續(xù)傳需要前端在重新上傳時(shí)查詢哪些分片已經(jīng)傳過(guò)。這個(gè)接口的數(shù)據(jù)準(zhǔn)確性和性能非常重要如果查詢結(jié)果返回了已上傳但實(shí)際不存在的分片就會(huì)導(dǎo)致最終合并時(shí)缺塊。服務(wù)端在返回已上傳分片列表時(shí)最好同時(shí)校驗(yàn)分片文件是否還物理存在。也就是說(shuō)Redis或數(shù)據(jù)庫(kù)里記錄的分片索引只能作為參考真正的判定標(biāo)準(zhǔn)是臨時(shí)目錄里能不能找到對(duì)應(yīng)的.part文件。我在排查階段加過(guò)一個(gè)檢測(cè)邏輯凡是記錄存在但文件不存在的分片統(tǒng)一標(biāo)記為未上傳重新傳一遍。這樣雖然多傳了幾個(gè)分片但至少最終文件完整不會(huì)因?yàn)榕K數(shù)據(jù)導(dǎo)致合并失敗。寫在最后這套jQuery與vue3混合開(kāi)發(fā)的大文件秒傳方案目前已經(jīng)在我們幾個(gè)老后臺(tái)頁(yè)面穩(wěn)定跑了兩個(gè)月累計(jì)上傳文件總量超過(guò)1TB秒傳命中率大概在30%左右——團(tuán)隊(duì)內(nèi)部經(jīng)常傳同一批源文件這個(gè)比例帶來(lái)的帶寬節(jié)省已經(jīng)非?？捎^。技術(shù)上踩過(guò)的坑不少但回過(guò)頭看核心就是兩條一是上傳邏輯絕不和UI框架綁死純JS模塊是混合開(kāi)發(fā)最穩(wěn)妥的底座二是兩套框架共存時(shí)邊界要?jiǎng)澢宄髯怨芎酶髯缘腄OM和事件不要越界操作。最后分享一個(gè)我個(gè)人的小偏好一切追求“秒傳”的功能都要做好異常降級(jí)不要因?yàn)槊雮魇【妥钄嗾麄€(gè)上傳流程。我在代碼里給秒傳判定加了一個(gè)容錯(cuò)開(kāi)關(guān)判重接口超時(shí)或報(bào)錯(cuò)時(shí)自動(dòng)降級(jí)為分片上傳雖然慢一點(diǎn)但用戶的文件絕不會(huì)因?yàn)橐粋€(gè)優(yōu)化功能而傳不上去。