做后臺管理系統(tǒng)做到第三年我發(fā)現(xiàn)自己最怵的不是表單校驗不是表格分頁而是文件上傳。Element UI的Upload組件看著人畜無害可真要把文件穩(wěn)定傳到騰訊云COS同時還要兼顧進度條、回顯、刪除、權限校驗一整套鏈路攢下來中間能出的幺蛾子比想象中多得多。這篇就圍繞一個很常見的需求展開在Element UI項目里用Upload組件選文件用axios向后端換上傳憑證再借助COS SDK把文件直傳對象存儲。讀完你至少能理清這三者的分工拿到一套可以直接落地改的代碼也知道哪些坑是控制臺看不出來的。1. 為什么我放棄Upload的action直傳改用http-request自定義上傳1.1 Upload自帶的上傳行為到底解決了什么問題很多剛接觸Upload組件的朋友第一反應肯定是它自帶一個action屬性往里填個后端地址選完文件它自己就發(fā)請求了這不就完事了嗎確實如果你們后端有一個非常標準的文件接收接口比如把multipart/form-data接過去存本地磁盤那action模式完全夠用。組件內部會自己創(chuàng)建XMLHttpRequest自己維護進度自己把結果丟給on-success回調你幾乎不用寫什么額外代碼。但這里有個隱含前提后端必須愿意并且有能力收這個文件。一旦涉及云存儲你會發(fā)現(xiàn)這個前提變得很尷尬。文件要落到騰訊云COS通常有兩條路前端把文件POST給后端后端再轉存到COS。開發(fā)簡單但文件流要走你們自己的服務器帶寬、超時、磁盤占用全壓在業(yè)務機器上。傳一個幾百MB的視頻后端接口能卡到懷疑人生。前端拿著臨時憑證直連COS文件壓根不過業(yè)務服務器。這種方式對后端友好也更符合對象存儲的設計初衷但Upload組件默認行為完全不知道COS的存在。你選哪條路直接決定了后面所有代碼的寫法。我見過不少團隊先用方案一走通結果線上傳大文件把服務器帶寬打滿又回頭重寫成方案二。所以我個人的意見是如果項目里已經明確用了COS那就從一開始走直傳后端只負責簽發(fā)臨時密鑰不碰文件本體。1.2 后端轉發(fā)COS的代價遠不止帶寬有人可能會反駁文件不大轉發(fā)就轉發(fā)唄也就幾十兆。這里的問題不只是帶寬。你想想后端接文件的時候需要設置上傳大小限制吧Nginx有client_max_body_sizeJava的Spring有multipart.max-file-sizeNode的Express有body-parser限制。你每加一個限制都是在給極端情況埋雷。今天傳50MB沒問題明天產品說視頻要支持500MB你就得改后端配置、調超時時間、考慮分片整個鏈路所有環(huán)節(jié)都要跟著動。而直傳COS的話后端只需要提供一個無狀態(tài)的簽名接口。文件多大、傳多久業(yè)務服務器根本無感知。前端和COS之間走得越順暢后端越省心。從架構上看上傳鏈路被拆成了兩條憑證鏈路前端到后端輕量和數(shù)據鏈路前端到COS高帶寬。這才是對象存儲該有的用法。1.3 三者的職責邊界Upload負責交互axios負責憑證COS SDK負責搬運把問題拆開事情就清晰了角色職責關鍵點Element UI Upload組件文件選擇、文件列表、上傳觸發(fā)、回調展示不直接發(fā)請求用http-request接管axios請求后端簽名接口換取臨時密鑰不負責傳文件本體cos-js-sdk-v5真正把文件傳到COS桶里依賴臨時密鑰完成鑒權這個分工的好處是每一層都很薄。Upload組件不需要知道COS的細節(jié)它只管把file對象交出來等我們手動調用onSuccess或onError告訴它結果axios不需要關心文件內容它要的只是那幾個憑證字段COS SDK也不需要關心你用的什么UI框架拿到文件就往桶里塞。如果你把這三者的邊界拎不清很容易寫出用Upload的action指向一個后端轉發(fā)接口再用axios攔截上傳結果的雜交代碼——不是說不能用而是排查問題時你分不清到底是哪一環(huán)出了問題。我以前就見過一個項目上傳失敗后前端、后端、運維各查各的最后發(fā)現(xiàn)是COS桶的跨域沒配前端在組件和axios之間找了兩天都沒找到原因。這個坑后面在第五章專門展開。2. axios拿臨時密鑰、COS SDK傳文件簽名鏈路與憑證設計2.1 為什么前端不能直接用永久密鑰講簽名鏈路之前先說說一個很多人栽過的念頭COS的SecretId和SecretKey就那兩串字符我直接把它寫進前端代碼里用COS SDK一初始化想傳哪個桶傳哪個桶多省事。這個念頭會帶來兩個問題。第一是泄露風險前端代碼本質上是公開的打包后的JS里搜一下字符串密鑰直接就暴露了別人拿著它可以對你桶里的文件做任意讀寫賬單也由你來扛。第二是權限粒度永久密鑰是賬號級的你沒法單獨限制它只能上傳某個桶的某個目錄也沒法讓它在兩小時后自動失效這對權限管理來說幾乎是裸奔。所以正規(guī)做法是讓后端去申請臨時密鑰。騰訊云提供了STS服務后端用自己的永久密鑰換一組有時效的臨時憑證返回給前端。前端拿著臨時憑證去初始化COS SDK有效期通常可以設為900秒到幾個小時過期之后自動失效哪怕被截獲了風險也可控。2.2 先用axios封裝一個簽名接口后端怎么接騰訊云的STS這里不展開我們只需要約定一個接口的返回結構。我常用的格式大致是這樣POST /api/upload/cos-temp-key { code: 0, message: success, data: { tmpSecretId: AKIDxxxxx, tmpSecretKey: xxxxxxxxx, sessionToken: xxxxxxxxx, startTime: 1700000000, expiredTime: 1700003600 } }前端這邊直接用項目里現(xiàn)有的axios實例封裝一下就行不需要額外引庫import request from /utils/request let authPromise null export function getCosAuth() { if (authPromise) { return authPromise } authPromise request({ url: /api/upload/cos-temp-key, method: post }).then((res) { if (res.data.code ! 0) { authPromise null return Promise.reject(new Error(res.data.message)) } return res.data.data }).catch((error) { authPromise null return Promise.reject(error) }) return authPromise }這里有一個細節(jié)值得多提一句我把authPromise做成了模塊級緩存。為什么因為用戶一次選擇多個文件時Upload組件的http-request會被調用多次如果每個文件都重新請求一次簽名接口后端瞬間會收到一堆重復請求。用Promise做緩存第一個請求發(fā)出去之后后續(xù)的調用直接復用同一個Promise等第一個響應回來大家都能拿到同一份憑證。這個寫法其實是個很經典的前端異步緩存技巧不只是簽名接口能用任何短時間內多個調用者共享一個請求結果的場景都適用。2.3 getAuthorization的調用時機別在每次上傳時都現(xiàn)拉密鑰COS SDK初始化時支持兩種傳密鑰的方式。一種是直接在構造函數(shù)里把憑證字段填進去const cos new COS({ SecretId: tmpSecretId, SecretKey: tmpSecretKey, SecurityToken: sessionToken })這種寫法適合一次性使用但臨時密鑰會過期一旦過期整個實例就廢了。另一種是傳getAuthorization回調SDK在每次發(fā)請求前都會調用它讓你有機會動態(tài)返回憑證const cos new COS({ getAuthorization(options, callback) { // 返回臨時密鑰 callback({ TmpSecretId: tmpSecretId, TmpSecretKey: tmpSecretKey, SecurityToken: sessionToken, StartTime: startTime, ExpiredTime: expiredTime }) } })這里的StartTime和ExpiredTime不是隨便填的SDK會根據它們判斷當前憑證是否有效。如果還沒到StartTime或者已經過了ExpiredTimeSDK會直接報錯。所以后端返回的startTime和expiredTime要原樣傳進去不要自己瞎改。但這里也有個新問題getAuthorization每次上傳都觸發(fā)如果你的實現(xiàn)是調用后端接口那相當于把簽名請求從每批文件一次退化成了每個文件一次。我的做法是在getAuthorization回調里不要直接發(fā)請求而是復用前面封裝好的getCosAuth函數(shù)配合Promise緩存同一時間段內只產生一次真實請求const cos new COS({ getAuthorization(options, callback) { getCosAuth().then((auth) { callback({ TmpSecretId: auth.tmpSecretId, TmpSecretKey: auth.tmpSecretKey, SecurityToken: auth.sessionToken, StartTime: auth.startTime, ExpiredTime: auth.expiredTime }) }).catch((err) { callback(err) }) } })還要注意一個問題臨時密鑰過期后緩存里的Promise必須失效。所以緩存不能是永久性的我通常會在getCosAuth內部判斷一下當前時間和expiredTime的距離距離小于60秒時就主動重置authPromise為null讓下一次調用重新走后端。3. 核心實現(xiàn)http-request里跑putObject上傳3.1 組件層面的關鍵配置簽名的鏈路理清了現(xiàn)在真正進入Upload組件的核心改造。先看模板部分el-upload refuploadRef v-model:file-listfileList :http-requesthandleHttpRequest :before-uploadhandleBeforeUpload :before-removehandleBeforeRemove :on-removehandleRemove :limit5 accept.jpg,.jpeg,.png,.pdf,.xlsx,.xls,.doc,.docx multiple el-button typeprimary點擊上傳/el-button /el-upload關鍵就在:http-requesthandleHttpRequest。這個屬性的作用是讓組件不再使用默認的ajax上傳行為而是把上傳那張牌交到你手里。你手上有options里面有file、onProgress、onSuccess、onError這幾個方法和屬性你要做的就是把文件傳出去然后調對應的回調。這里的fileList我用了v-model:file-list雙向綁定Element UI 2.15以上版本支持這種寫法比舊的:file-listupdate:file-list順手得多。如果你項目里的Element UI版本比較老記得升級一下組件庫否則fileList的更新會偶爾不同步。3.2 完整的上傳處理函數(shù)下面這段是我在實際項目里用的簡化版去掉業(yè)務噪音后核心邏輯長這樣import COS from cos-js-sdk-v5 import { getCosAuth } from /api/cosAuth let cosInstance null function getCosInstance() { if (cosInstance) { return cosInstance } cosInstance new COS({ getAuthorization(options, callback) { getCosAuth() .then((auth) { callback({ TmpSecretId: auth.tmpSecretId, TmpSecretKey: auth.tmpSecretKey, SecurityToken: auth.sessionToken, StartTime: auth.startTime, ExpiredTime: auth.expiredTime }) }) .catch((err) callback(err)) } }) return cosInstance } async handleHttpRequest(options) { const { file, onProgress, onSuccess, onError } options const cos getCosInstance() const key buildCosKey(file) cos.putObject({ Bucket: your-bucket-1250000000, Region: ap-guangzhou, Key: key, Body: file, ContentType: file.type || application/octet-stream, onProgress: (info) { const percent Math.min(info.percent * 100, 100) onProgress({ percent }) } }, (err, data) { if (err) { onError(err) return } onSuccess({ key, url: https://${data.Location}, name: file.name }) }) }這里要特別提醒的是ContentType這一行。很多同學忽略它結果就是文件確實傳上去了COS控制臺里也有但拿到的URL在瀏覽器里打開時直接變成了下載而不是預覽。原因就是COS保存對象時如果沒有正確的Content-Type元數(shù)據Web服務器就會用默認的application/octet-stream去響應瀏覽器看到這個類型自然就觸發(fā)下載了。所以file.type要原樣傳給putObject如果拿不到type再用二進制流兜底。3.3 文件Key的生成規(guī)則buildCosKey這個函數(shù)說白了是決定文件在桶里存放路徑的。我建議不管業(yè)務多簡單都別直接把用戶原始文件名當Key至少做兩件事加日期目錄加隨機后綴。function buildCosKey(file) { const ext file.name.includes(.) ? file.name.slice(file.name.lastIndexOf(.)) : const date new Date() const y date.getFullYear() const m String(date.getMonth() 1).padStart(2, 0) const d String(date.getDate()).padStart(2, 0) const random Math.random().toString(36).slice(2, 10) return uploads/${y}${m}$cj3uvhbzvbv/${random}${ext} }為什么加隨機串而不是直接用文件名因為同一天內兩個用戶都上傳一個項目資料.pdf的話第二個會把第一個覆蓋掉。用時間戳隨機串基本能保證唯一性。另外把原始文件名丟掉的后果是回顯時需要另存一個字段來保存file.name所以前面onSuccess里我特意把name也帶上了后面列表展示就會用到它。3.4 多文件上傳的另一個隱蔽細節(jié)Upload組件在multiple模式下會并行觸發(fā)多個http-request。如果你在handleHttpRequest里每次都new一個COS實例雖然不至于報錯但等于把初始化成本重復了很多遍。所以我用了getCosInstance這個單例模式整個頁面生命周期內只創(chuàng)建一個實例getAuthorization在內部自動處理簽名刷新這樣效率最高。另外如果你的文件名是中文COS的putObject在有些瀏覽器下會偶爾把Body當成字符串處理導致上傳內容損壞。穩(wěn)妥的做法是對文件名做一次URL編碼或者在生成Key時用前面那種隨機串替代中文名回顯時再把原始名存在數(shù)據庫。我推薦后者因為COS的Key本身也不建議放中文。4. 文件列表回顯、進度換算與刪除策略的實現(xiàn)細節(jié)4.1 進度條為什么老是在99%卡住Upload組件自帶的進度條來自onProgress回調。COS SDK給出的info.percent是一個0到1的小數(shù)比如0.42表示42%。組件內部需要的percent字段是0到100的整數(shù)所以要做一步換算。我前面代碼里寫了Math.min(info.percent * 100, 100)這個min的兜底是必須的因為COS在某些臨界情況下會把percent精確計算到1.000001這種值直接賦值給組件進度條會突然跳到超過100%看起來非常怪。還有一種情況是進度條到了99%就不動了要等好幾秒才跳到100%。這一般不是我們的代碼問題而是COS在上傳完成后有一個服務端確認過程最后的握手階段沒有進度數(shù)據可報所以前端進度條會短暫停留在99%。遇到這種情況別慌最終onSuccess回調一定會觸發(fā)觸發(fā)之后組件會把文件標記為上傳成功。4.2 回顯時的fileList結構上傳成功后Upload組件會根據onSuccess傳進來的response更新fileList里對應項的response字段?；仫@無非兩種場景上傳過程中實時展示以及編輯頁面打開時回填已有文件。實時展示最簡單只要onSuccess返回的數(shù)據能標識出文件即可組件會自動把文件狀態(tài)變成success。但編輯回顯就麻煩一點因為Upload組件的fileList是它內部維護的你直接往數(shù)組里塞普通對象可不一定有效。正確的回顯結構是這樣的// 編輯頁打開彈窗時 this.fileList [ { name: 原始文件名.pdf, url: https://your-bucket-1250000000.cos.ap-guangzhou.myqcloud.com/uploads/20250101/xxxxx.pdf, status: success } ]url字段是給預覽用的status要用success否則組件會以為這個文件還在上傳中。如果后端返回數(shù)據里正好有文件名和完整的COS地址那直接映射一下就好。我見過很多同學把數(shù)據庫里的COS Key當成url回填結果整個列表都是裂圖就是因為缺了域名前綴。更要注意的是如果這個upload放在彈窗里彈窗關閉再打開時fileList必須重新賦值。有些情況下你明明賦了值界面上就是不顯示原因是Upload組件在彈窗銷毀后還保留了上一次的渲染狀態(tài)。這時候給el-upload加一個:keydialogVisible強制重新渲染一次就能解決。4.3 大小與類型校驗到底寫在哪層類型和大小校驗我一般放在before-upload里。注意這個鉤子有兩個作用返回false可以阻止上傳返回Promise則可以異步阻止或放行。如果你只是簡單判斷一下大小同步返回即可handleBeforeUpload(file) { const maxSize 50 * 1024 * 1024 const allowTypes [image/jpeg, image/png, application/pdf] if (file.size maxSize) { this.$message.error(文件不能超過50MB) return false } if (!allowTypes.includes(file.type)) { this.$message.error(僅支持jpg、png、pdf格式) return false } return true }這里有個概念要澄清HTML的accept屬性只是控制文件選擇框的篩選用戶可以手動改成所有文件繞過它所以它不能當作安全邊界。真正的類型校驗還是要看before-upload甚至要看后端。如果你的業(yè)務文件類型比較復雜比如需要在上傳前讀一下文件頭那就得返回一個PromisehandleBeforeUpload(file) { return new Promise((resolve, reject) { // 模擬異步校驗邏輯 if (someCondition) { resolve(true) } else { this.$message.error(校驗不通過) reject(false) } }) }注意reject觸發(fā)的行為Element UI會把Promise被reject理解為上傳失敗從而走到on-error邏輯里。如果不想讓組件重復彈錯誤提示你可以像我上面這樣在reject之前自己彈一次Message然后reject一個不會觸發(fā)額外提示的值。4.4 刪除COS文件的兩種策略Upload組件的before-remove和on-remove是處理刪除的兩個時機。很多人只關心文件列表里刪掉一條記錄卻忘了COS上對應的對象還占著空間。今天就你家這個桶的存儲量來說一次幾MB無所謂但積少成多到月底看賬單就心疼了。刪除策略我推薦分兩種場景如果文件是用戶臨時上傳、還沒提交表單的前端應該在on-remove里直接調COS的deleteObject幫后端省事。如果文件已經隨表單一起提交入庫了前端不要自己刪而是只做列表變更等用戶整體提交時告訴后端哪些舊文件需要清理由后端統(tǒng)一刪。為什么后者不讓前端刪因為已提交的資源可能存在被其他地方引用的情況比如一個頭像被多個業(yè)務引用了你前端直接刪了COS對象后面想追溯都找不到。讓后端在事務里確認沒有引用后再刪才是最穩(wěn)的。handleRemove(file, fileList) { // file.response?.key 是上傳成功后我塞進去的COS Key if (file.response file.response.key) { const cos getCosInstance() cos.deleteObject( { Bucket: your-bucket-1250000000, Region: ap-guangzhou, Key: file.response.key }, (err) { if (err) { console.warn(COS刪除失敗, err) } } ) } }5. 三個讓上傳看似成功實則失敗的坑和排查鏈路5.1 跨域報錯COS控制臺的CORS配置不配就是白折騰你可能會遇到這種情況代碼邏輯完全沒問題但在瀏覽器里一點上傳控制臺就蹦出一行Access to XMLHttpRequest at https://xxx.cos.ap-guangzhou.myqcloud.com/... from origin http://localhost:8080 has been blocked by CORS policy。這個報錯看起來像是代碼問題實際上絕大多數(shù)情況是COS桶的跨域規(guī)則沒配。你去騰訊云控制臺找到對應的存儲桶權限管理跨域訪問CORS設置新增一條規(guī)則把允許的來源加上你的前端域名注意是協(xié)議域名端口全匹配比如http://localhost:8080別只寫*生產環(huán)境最好精確到具體域名。AllowedMethod記得勾上PUT、POST、GET、DELETE因為putObject用的是PUT請求deleteObject用的是DELETE。AllowedHeader建議填*這樣SDK帶自定義Header時不會被瀏覽器攔截。這個配置改完一般一分鐘內生效如果還報錯先確認是不是瀏覽器緩存了舊的OPTIONS預檢結果強刷一下再看。5.2 Content-Type被置空上傳成功后圖片卻變成了下載這個問題我在3.2節(jié)提過一嘴但它的隱蔽性值得拿出來單講。癥狀是這樣的文件上傳成功回顯圖片的URL前戳也拼對了但在新標簽頁打開時瀏覽器沒有顯示圖片而是直接下載了一個無后綴名的文件。排查鏈路我建議這樣走先看COS控制臺里這個對象的Content-Type字段是什么。如果顯示application/octet-stream那就證明上傳時Metadata沒設置對。再回頭看你的putObject參數(shù)ContentType是不是漏了或者從file.type取到的值是空字符串。某些壓縮包、特定格式文件的file.type就是空的所以取不到的時候要兜底成二進制的標準類型但如果是圖片或PDF強烈建議手動指定為image/jpeg、application/pdf這種確切類型。還有一個小技巧如果你不想改前端代碼重新傳一遍可以在COS控制臺里手動修改這個對象的Content-Type能立刻解決眼前的問題但這只適合補救根治還是要把代碼補上。5.3 臨時密鑰過期隔了很久再上傳直接403臨時密鑰默認幾百秒到幾小時有效期如果你頁面一直開著超過了有效期再去上傳COS會返回SignatureDoesNotMatch或Access Denied。但為什么你傳一次就失敗、沒有自動刷新呢回到getAuthorization的實現(xiàn)如果你像我前面那樣用了getCosAuth的Promise緩存而緩存里沒有判斷過期時間那同一份過期憑證會被反復使用當然每次都失敗。所以正確緩存邏輯必須帶時間判斷。我給個清晰版本let authCache null let authExpireTime 0 export function getCosAuth() { const now Math.floor(Date.now() / 1000) if (authCache authExpireTime - now 60) { return Promise.resolve(authCache) } authCache null authExpireTime 0 return request({ url: /api/upload/cos-temp-key, method: post }).then((res) { const data res.data.data authCache data authExpireTime data.expiredTime return data }) }留出60秒的余量是為了避免剛好卡在過期瞬間去請求省得有邊界問題。改完這個即使你的tab掛了兩小時再上傳第一個請求觸發(fā)getAuthorization時會發(fā)現(xiàn)憑證臨近過期自動重新拉取后面的請求就都正常了。5.4 彈窗內Upload初始回顯丟失最后一個坑可能只有頻繁做彈窗表單的人才會碰到。Upload放在el-dialog里第一次打開對話框回顯正常關閉后再打開文件列表空了。你這是不是也在疑惑fileList的data明明已經重新賦值了啊這個現(xiàn)象的本質是彈窗組件沒有銷毀Upload的內部狀態(tài)還停留在上一次關閉時的樣子。你賦fileList的時機在彈窗open之后但組件沒有重新渲染或者說它內部對fileList做了緩存。解決手段簡單粗暴我上面提過給el-upload加一個:keydialogVisibledialogVisible是一個每次打開都變的布爾值或彈窗ID。key一變Vue就會把Upload組件整個銷毀重建內部狀態(tài)全部清空這時候再賦fileList就能穩(wěn)穩(wěn)地渲染出來。如果你不想加key也可以用this.$nextTick配合手動重置fileList但沒有key那種一擊必殺的確定性。最后再說一個這些年攢下來的小經驗凡是涉及COS直傳的項目我都習慣在Upload的on-error回調里把COS返回的原始錯誤對象原樣打印出來。COS SDK的錯誤碼跟HTTP狀態(tài)碼不是一一對應的Access Denied有可能是密鑰過期、也有可能是桶權限不足還有可能是你壓根沒配置SecurityToken轉發(fā)。前端排查這類問題時先把錯誤日志留住再對照COS的服務端錯誤碼文檔逐條排除比瞎猜穩(wěn)得多。上傳這塊慢就是快把每一環(huán)的日志補全了后面能省下大把聯(lián)調時間。