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