一格式方案)
寫這篇東西的起因是前陣子有個(gè)朋友在群里吐槽項(xiàng)目用的CKEditor用戶從截圖軟件、微信、word里復(fù)制圖片往編輯器里一貼結(jié)果瀏覽器之間表現(xiàn)完全不一樣。Chrome里粘貼變成base64大長串Firefox里有些圖片能傳有些傳不上去Safari干脆沒反應(yīng)。而且圖片格式五花八門有png有jpg有webp上傳到PHP服務(wù)器后要么擴(kuò)展名和實(shí)際格式對不上要么透明背景變成黑塊。他問我跨瀏覽器用CKEditor粘貼圖片到PHP服務(wù)器到底怎么統(tǒng)一格式這個(gè)問題其實(shí)很多做后臺管理系統(tǒng)、富文本編輯器、CMS、甚至B端工作臺的人都遇到過。編輯器的粘貼圖片上傳本質(zhì)上是三條線的交匯瀏覽器剪貼板API的兼容性處理、CKEditor事件機(jī)制的攔截、PHP服務(wù)端的文件接收與格式重編碼。任何一條線沒處理好就會出各種怪問題。這篇文章把我自己項(xiàng)目里沉淀下來的完整方案拆開講清楚包括前端怎么攔截粘貼事件、怎么跨瀏覽器拿到圖片文件、怎么在前端把格式統(tǒng)一以及服務(wù)端PHP怎么用GD庫做二次兜底轉(zhuǎn)換和安全校驗(yàn)。如果你正在做或者準(zhǔn)備做類似的編輯器和上傳功能這篇文章可以直接當(dāng)作參考方案來用。1. 整體方案設(shè)計(jì)與思路拆解1.1 核心痛點(diǎn)粘貼圖片對編輯器來說究竟意味著什么用戶從外部復(fù)制一張圖片然后粘貼到編輯框里這對CKEditor來說本質(zhì)上是一個(gè)內(nèi)容插入事件。它不像input typefile那樣直接把圖片文件丟給你而是把剪貼板里的數(shù)據(jù)當(dāng)作一段HTML或者文本內(nèi)容塞進(jìn)編輯器。問題就出在這里剪貼板里的圖片在不同瀏覽器里呈現(xiàn)的形式完全不同。Chrome和Edge在粘貼圖片時(shí)默認(rèn)會把圖片轉(zhuǎn)成base64編碼的data URL然后以img srcdata:image/png;base64,...的形式插入編輯器。這種做法的后果是編輯器的內(nèi)容區(qū)會塞進(jìn)一大段幾十KB甚至幾MB的字符串保存到數(shù)據(jù)庫時(shí)會直接把列表頁拖垮。Firefox在這方面相對老實(shí)一點(diǎn)它更多時(shí)候會提供文件對象但不同版本之間表現(xiàn)也不穩(wěn)定。Safari在macOS上從訪達(dá)復(fù)制圖片文件時(shí)可以拿到文件但從網(wǎng)頁內(nèi)復(fù)制圖片時(shí)卻經(jīng)常只有HTML沒有文件對象。早期版本的IE更不用提根本不支持DataTransfer相關(guān)API。除此之外還有一個(gè)隱含的痛點(diǎn)圖片格式五花八門。用戶粘貼的可能是PNG截圖、JPEG照片、webp網(wǎng)頁圖片、甚至從微信復(fù)制過來的不明格式。如果不加干預(yù)保存到服務(wù)器上的就是一堆擴(kuò)展名和實(shí)際格式混亂的文件后續(xù)做圖片處理、兼容性展示、二次壓縮都很麻煩。所以統(tǒng)一格式并不是一個(gè)單純的技術(shù)潔癖問題而是直接關(guān)系到后臺圖片存儲規(guī)范和頁面穩(wěn)定性的實(shí)際需求。1.2 方案選型為什么不讓編輯器自動(dòng)處理而是自己攔截CKEditor 4本身是支持配置圖片上傳的官方文檔里有filebrowserImageUploadUrl這類的配置項(xiàng)配合文件管理器或者自研上傳接口來做圖片上傳。但如果你實(shí)際試過就會知道這個(gè)內(nèi)置流程對粘貼上傳的支持并不理想尤其是跨瀏覽器場景。它更多是為點(diǎn)擊按鈕選擇文件上傳設(shè)計(jì)的粘貼時(shí)它傾向于直接插入base64而不是把圖片當(dāng)作上傳任務(wù)處理。所以更穩(wěn)妥的做法是自己監(jiān)聽編輯器的paste事件在編輯器默認(rèn)邏輯執(zhí)行之前把圖片攔截下來提取成文件對象走自己的上傳接口。這樣有幾個(gè)好處一是可以針對不同瀏覽器分別處理兼容性可控二是可以決定哪些圖片粘貼后上傳、哪些不做處理三是可以在上傳前做格式統(tǒng)一和壓縮而不是把圖片原封不動(dòng)地塞進(jìn)編輯器。從后端視角看服務(wù)端也必須做二次兜底。前端統(tǒng)一格式雖然在大多數(shù)場景下可靠但你不能依賴前端傳過來的文件和參數(shù)完全可信任。而且從Word等富文本工具里粘貼過來的圖片經(jīng)常是嵌入在HTML里的base64或者特殊格式的二進(jìn)制流這些路徑下前端不一定來得及攔截服務(wù)端必須能夠在接收后判斷真實(shí)格式并做轉(zhuǎn)換。前端統(tǒng)一格式解決體驗(yàn)問題后端統(tǒng)一格式解決可靠性和安全問題兩條路同時(shí)走才能保證最終落到服務(wù)器上的文件一定是統(tǒng)一的、規(guī)范的。1.3 整體數(shù)據(jù)流設(shè)計(jì)整套流程走下來可以把數(shù)據(jù)流拆成四個(gè)關(guān)鍵節(jié)點(diǎn)粘貼事件觸發(fā)、前端提取與轉(zhuǎn)換、異步上傳、服務(wù)端接收與再加工。每一步都有它的職責(zé)和容易踩坑的地方我列個(gè)簡表說明節(jié)點(diǎn)關(guān)鍵職責(zé)主要風(fēng)險(xiǎn)點(diǎn)粘貼事件觸發(fā)捕獲剪貼板中的圖片數(shù)據(jù)部分瀏覽器事件獲取時(shí)機(jī)不同前端提取與轉(zhuǎn)換獲取File對象Canvas重編碼為統(tǒng)一格式跨域圖片污染Canvas異步上傳FormData提交到PHP接口跨域CORS配置、超時(shí)服務(wù)端接收與再加工校驗(yàn)真實(shí)格式GD庫重編碼保存擴(kuò)展名偽造、透明通道黑色塊這個(gè)流程里最核心的設(shè)計(jì)原則是前端做體驗(yàn)層優(yōu)化服務(wù)端做兜底和規(guī)范。前端優(yōu)先把圖片轉(zhuǎn)成統(tǒng)一的格式和合理的尺寸減輕服務(wù)端壓力服務(wù)端則無論如何都按真實(shí)內(nèi)容來保存而不是按聲稱的格式來保存。兩層各自獨(dú)立又互相配合。2. 前端攔截粘貼圖片的完整實(shí)現(xiàn)2.1 監(jiān)聽paste事件并讀取剪貼板數(shù)據(jù)CKEditor 4的實(shí)例在instanceReady事件觸發(fā)后我們就可以通過editor.on(paste, handler)來監(jiān)聽粘貼事件。請注意這里的paste事件是CKEditor封裝過的事件對象內(nèi)部會提供evt.data.dataTransfer這個(gè)對象和瀏覽器原生clipboardData基本等價(jià)但在不同瀏覽器里字段的表現(xiàn)形式有細(xì)微差異所以不能只寫一種寫法就指望所有瀏覽器通用。CKEDITOR.on(instanceReady, function(e) { var editor e.editor; editor.on(paste, function(evt) { var dataTransfer evt.data.dataTransfer; if (!dataTransfer) { return; } console.log(剪貼板類型, dataTransfer.types); }); });很多人在這一步就會遇到第一個(gè)坑綁定的時(shí)間不對。如果你在instanceReady之前就去editor.on(paste)那么大部分事件根本不會觸發(fā)因?yàn)榫庉嬈鲀?nèi)部的實(shí)例還沒初始化完成事件機(jī)制還沒掛載。還有一個(gè)非常隱蔽的問題有些瀏覽器在paste事件里dataTransfer雖然有值但items是空的反而files里有數(shù)據(jù)。這個(gè)在下面的跨瀏覽器處理里具體展開。2.2 從不同瀏覽器中可靠地拿到圖片文件拿到dataTransfer之后任務(wù)就從事件監(jiān)聽階段切換到找圖片階段。標(biāo)準(zhǔn)做法是先遍歷dataTransfer.items找type以image/開頭的項(xiàng)然后調(diào)用getAsFile()獲取文件對象。但真實(shí)世界沒有這么理想我整理了三種常見來源對應(yīng)不同的處理方式。第一種也是最常見的dataTransfer.items里存在圖片項(xiàng)getAsFile()能正常返回File對象。這種情況出現(xiàn)在Chrome、Edge、Firefox的新版本里用戶從本地復(fù)制圖片文件或者從截圖工具粘貼時(shí)基本都是這個(gè)路徑。第二種items里沒有圖片項(xiàng)但dataTransfer.files里有文件。這種情況在Safari和部分Firefox版本中經(jīng)常出現(xiàn)。所以判斷順序不能只盯著items看files也要檢查。第三種剪貼板里沒有文件對象但text/html數(shù)據(jù)里嵌著一串base64圖片通常是從網(wǎng)頁上直接復(fù)制圖片時(shí)出現(xiàn)這種情況。這時(shí)候需要從text/html中提取img srcdata:image/...里的data URL再把它轉(zhuǎn)成Blob對象。function extractImageFile(dataTransfer) { // 方式一從 items 中取 var items dataTransfer.items || []; for (var i 0; i items.length; i) { if (items[i].type items[i].type.indexOf(image) ! -1) { var file items[i].getAsFile items[i].getAsFile(); if (file) { return file; } } } // 方式二從 files 中取 if (dataTransfer.files dataTransfer.files.length 0) { return dataTransfer.files[0]; } // 方式三從 text/html 中解析 data URL var html dataTransfer.getData(text/html); if (html html.indexOf(data:image) ! -1) { var match html.match(/src(data:image\/[^])/); if (match) { return dataURLToBlob(match[1]); } } return null; } function dataURLToBlob(dataURL) { var arr dataURL.split(,); var mime arr[0].match(/:(.*?);/)[1]; var bstr atob(arr[1]); var n bstr.length; var u8arr new Uint8Array(n); while (n--) { u8arr[n] bstr.charCodeAt(n); } return new Blob([u8arr], { type: mime }); }這段代碼我建議直接作為工具函數(shù)常駐前端公共庫里不只編輯器用其他地方需要讀取剪貼板圖片也可以用。走通這段邏輯Chrome、Firefox、Edge、Safari這四個(gè)主流瀏覽器基本都能拿到圖片文件了。2.3 攔截默認(rèn)的base64插入行為這是整個(gè)流程里最容易被忽略、但影響最大的一步。如果我們只提取圖片文件而不做攔截那么CKEditor默認(rèn)的粘貼處理器會同時(shí)把base64圖片插入編輯器導(dǎo)致上傳之后編輯器里出現(xiàn)兩個(gè)圖片一個(gè)是你上傳后插入的URL版本一個(gè)是默認(rèn)處理的base64版本。所以拿到圖片文件之后第一時(shí)間要調(diào)用evt.data.preventDefault()阻止默認(rèn)行為。editor.on(paste, function(evt) { var imageFile extractImageFile(evt.data.dataTransfer); if (!imageFile) { return; } evt.data.preventDefault(); handlePastedImage(imageFile); });這里有一個(gè)經(jīng)驗(yàn)點(diǎn)preventDefault()的位置很重要必須在判斷出確實(shí)有圖片文件之后才調(diào)用。如果判斷沒有圖片就放行讓編輯器正常處理文字粘貼或者其他內(nèi)容。一旦誤攔截用戶復(fù)制普通文本也會沒反應(yīng)體驗(yàn)非常糟糕。另外如果你的編輯器開啟了forcePasteAsPlainText這類配置要特別注意它和preventDefault的相互作用處理不好容易導(dǎo)致攔截后插入的內(nèi)容丟失。2.4 前端統(tǒng)一格式用Canvas把圖片轉(zhuǎn)換成目標(biāo)格式拿到File對象之后就要面對統(tǒng)一的第一個(gè)層面格式統(tǒng)一。這個(gè)步驟可以在前端做也可以用服務(wù)端做我的建議是兩層都做。前端做的好處是圖片在上傳前就變成了統(tǒng)一的格式、合理的尺寸和合適的體積上傳壓力小后端拿到直接存就是規(guī)范文件。前端轉(zhuǎn)換圖片格式的核心工具是Canvas。思路很簡單讀取圖片-繪制到Canvas-用canvas.toBlob()輸出指定格式的Blob對象。關(guān)鍵點(diǎn)在兩個(gè)地方要填白底以及要控制質(zhì)量參數(shù)。填白底的目的是為了防止PNG格式的透明圖片在轉(zhuǎn)換成JPEG后透明區(qū)域變成黑色。Canvas在沒有背景色的情況下導(dǎo)出JPEG透明區(qū)域默認(rèn)是黑色這在視覺上非常突兀。所以在繪制之前必須先用白色填充整個(gè)畫布再畫圖片。這個(gè)坑我見過無數(shù)次前端不填白、后端也不處理最后所有帶透明通道的截圖傳上去都是黑底。function convertImageFile(file, targetType, quality) { return new Promise(function(resolve, reject) { var url URL.createObjectURL(file); var img new Image(); img.onload function() { var canvas document.createElement(canvas); canvas.width img.naturalWidth; canvas.height img.naturalHeight; var ctx canvas.getContext(2d); if (targetType image/jpeg) { ctx.fillStyle #ffffff; ctx.fillRect(0, 0, canvas.width, canvas.height); } ctx.drawImage(img, 0, 0); URL.revokeObjectURL(url); canvas.toBlob(function(blob) { if (blob) { resolve(blob); } else { reject(new Error(canvas.toBlob返回空)); } }, targetType, quality || 0.92); }; img.onerror function() { URL.revokeObjectURL(url); reject(new Error(圖片加載失敗)); }; img.src url; }); }這個(gè)函數(shù)里還隱含了一個(gè)問題如果用戶粘貼的圖片本身來源于跨域資源比如從另一個(gè)域名的網(wǎng)頁上復(fù)制那么img讀取該圖片時(shí)Canvas會被污染toBlob()會直接拋錯(cuò)。但好在我們這個(gè)場景里用戶粘貼的都是剪貼板里的文件或者data URL本質(zhì)上都在本地不涉及跨域所以這個(gè)函數(shù)是安全的。當(dāng)然如果你后續(xù)要處理編輯器里已存在的跨域圖片再壓縮那就需要額外給img加上crossOriginanonymous屬性并且服務(wù)端配合CORS。3. 上傳接口與PHP服務(wù)端處理3.1 前端用FormData異步上傳格式轉(zhuǎn)換完成后把Blob對象放進(jìn)FormData作為普通文件上傳即可。需要注意的一個(gè)細(xì)節(jié)是Blob對象的文件名。如果你不指定文件名某些瀏覽器會以blob作為文件名PHP的$_FILES[file][name]可能會變成blob這會影響后綴判斷。更好的做法是手動(dòng)指定一個(gè)統(tǒng)一后綴的文件名比如paste_1736244109.jpg。function uploadPastedImage(blob, editor) { var fd new FormData(); var filename paste_ Date.now() .jpg; fd.append(file, blob, filename); // 可以帶一個(gè)format參數(shù)告訴服務(wù)端我們希望統(tǒng)一成什么格式 fd.append(format, jpg); fetch(/api/upload.php, { method: POST, body: fd }) .then(function(res) { return res.json(); }) .then(function(json) { if (json.code 0) { editor.insertHtml(img src json.url alt粘貼圖片 /); } else { alert(json.msg || 上傳失敗); } }) .catch(function(error) { console.error(上傳異常, error); }); }我推薦使用fetch但如果你項(xiàng)目的瀏覽器兼容性要求特別老比如需要兼容IE11那就改用XMLHttpRequest邏輯完全一樣。不要用canvas.toDataURL()拿到base64再傳到服務(wù)端去處理那樣數(shù)據(jù)的體積比二進(jìn)制Blob要膨脹三分之一左右徒增傳輸壓力而且服務(wù)端還要多做一步base64解碼。3.2 PHP接收與安全校驗(yàn)PHP側(cè)的第一步工作是接收文件、檢查錯(cuò)誤、判斷大小。這里有兩件事要特別強(qiáng)調(diào)一是$_FILES[file][error]必須檢查這是判斷上傳是否成功的第一道關(guān)卡二是絕對不要信任前端傳過來的文件名和MIME類型。為什么不能信任MIME類型因?yàn)闉g覽器在構(gòu)造multipart/form-data請求時(shí)$_FILES里的type字段完全由客戶端控制偽造image/jpeg沒有任何技術(shù)門檻。如果直接用這個(gè)值決定后續(xù)處理等于把安全門敞開著。正確做法是用PHP的getimagesize()函數(shù)讀取臨時(shí)文件拿到真實(shí)的圖片寬高信息、真實(shí)MIME類型。這個(gè)函數(shù)會檢查圖片文件頭如果文件根本不是圖片它會返回false自然就把偽造攻擊擋掉了。$file $_FILES[file]; if (!$file || $file[error] ! UPLOAD_ERR_OK) { echo json_encode([code 1, msg 上傳失敗]); exit; } if ($file[size] 5 * 1024 * 1024) { echo json_encode([code 1, msg 文件大小不能超過5MB]); exit; } $info getimagesize($file[tmp_name]); if ($info false) { echo json_encode([code 1, msg 文件不是有效圖片]); exit; } $mime $info[mime]; $allowedMimes [ image/jpeg jpg, image/png png, image/gif gif, image/webp webp, image/bmp bmp, ]; if (!isset($allowedMimes[$mime])) { echo json_encode([code 1, msg 不支持的圖片格式]); exit; }這段邏輯就是按真實(shí)內(nèi)容判定格式的原則。前端說它是jpg不管PHP看文件頭判斷出它實(shí)際上是png就按png處理。這樣能保證后續(xù)的格式轉(zhuǎn)換一定成功。3.3 用GD庫統(tǒng)一圖片格式的完整代碼PHP服務(wù)端的格式統(tǒng)一使用的是PHP內(nèi)置的GD庫。相比ImageMagickGD庫的優(yōu)點(diǎn)是幾乎所有PHP環(huán)境默認(rèn)開啟不需要額外安裝擴(kuò)展操作也簡單。它的核心思路是真實(shí)MIME決定怎么解碼目標(biāo)格式?jīng)Q定怎么輸出中間用imagecopyresampled()重采樣。要注意的仍然是白色背景問題。GD庫在把帶透明通道的PNG圖片轉(zhuǎn)成JPEG時(shí)如果不先填充背景色透明區(qū)域會變成黑色。這個(gè)問題如果前端已經(jīng)處理過服務(wù)端可以少操一份心但程序不能假設(shè)前端一定做了服務(wù)端必須再做一次。代碼如下function convertToFormat($srcPath, $format, $quality 92) { $info getimagesize($srcPath); $mime $info[mime]; $width $info[0]; $height $info[1]; switch ($mime) { case image/jpeg: $src imagecreatefromjpeg($srcPath); break; case image/png: $src imagecreatefrompng($srcPath); break; case image/gif: $src imagecreatefromgif($srcPath); break; case image/webp: $src imagecreatefromwebp($srcPath); break; case image/bmp: $src imagecreatefrombmp($srcPath); break; default: return false; } if (!$src) { return false; } // 如果要輸出jpeg先鋪白底 $dst imagecreatetruecolor($width, $height); if ($format jpg) { $white imagecolorallocate($dst, 255, 255, 255); imagefill($dst, 0, 0, $white); } imagecopyresampled($dst, $src, 0, 0, 0, 0, $width, $height, $width, $height); ob_start(); if ($format png) { imagepng($dst); } else { imagejpeg($dst, null, $quality); } $data ob_get_contents(); ob_end_clean(); imagedestroy($src); imagedestroy($dst); return $data; }這里解釋一下為什么用ob_start()配合imagejpeg($dst, null, $quality)而不是直接imagejpeg($dst, $path, $quality)。因?yàn)槿绻阋趦?nèi)存里拿到圖片的二進(jìn)制內(nèi)容最干凈的方式就是讓GD庫往輸出緩沖區(qū)里寫然后再從緩沖區(qū)讀出來。直接指定文件路徑寫入也可以但那樣你還要多一步讀文件而且在確定命名之前就落盤遠(yuǎn)不如內(nèi)存操作干凈。unlink()清理臨時(shí)文件這些細(xì)節(jié)同樣別忽略。如果你還想連尺寸也統(tǒng)一比如超過2000像素的圖片等比縮到2000像素以內(nèi)那就在創(chuàng)建$dst之前做一次目標(biāo)尺寸計(jì)算。這個(gè)擴(kuò)展非常容易但效果很好因?yàn)榫庉嬈髋鋱D一般不需要超過2000px的圖限制尺寸能夠極大降低存儲壓力。3.4 文件命名、目錄與返回URL設(shè)計(jì)格式統(tǒng)一之后就要考慮保存文件的命名規(guī)則和目錄結(jié)構(gòu)。我強(qiáng)烈不建議使用用戶上傳的原始文件名原因有兩個(gè)一是原始文件名可能是中文、特殊字符或者超長字符串直接作為文件名容易產(chǎn)生編碼問題甚至被利用路徑穿越漏洞二是不同瀏覽器粘貼圖片時(shí)的默認(rèn)命名不同達(dá)不到統(tǒng)一規(guī)范的效果。建議的命名規(guī)則按日期分目錄文件名用uniqid()加隨機(jī)字符串再加上統(tǒng)一后的擴(kuò)展名。比如uploads/2024/07/01/65c0a1b2c3d4e5f6a7b8c9d0.jpg。這樣既保證唯一性又方便按日期歸檔目錄也不會無限膨脹。$format isset($_POST[format]) $_POST[format] png ? png : jpg; $convertedData convertToFormat($file[tmp_name], $format, 92); if ($convertedData false) { echo json_encode([code 1, msg 圖片格式轉(zhuǎn)換失敗]); exit; } $dateDir date(Ymd); $filename $dateDir . / . uniqid(img_, true) . . . $format; $absolutePath $uploadDir . $filename; if (!is_dir(dirname($absolutePath))) { mkdir(dirname($absolutePath), 0755, true); } file_put_contents($absolutePath, $convertedData);最后返回的JSON里要包含圖片的完整URL這個(gè)URL是前端用來插入編輯器的。要注意的是URL不要拼PHP代碼里盡量用配置項(xiàng)維護(hù)一個(gè)baseUrl變量方便在不同環(huán)境下切換。比如本地環(huán)境是http://localhost/uploads線上是https://yourdomain.com/uploads如果不統(tǒng)一管理部署環(huán)境和線上環(huán)境很容易出現(xiàn)圖片路徑不一致的問題。$baseUrl https://yourdomain.com/uploads/; echo json_encode([ code 0, url $baseUrl . $filename, size strlen($convertedData), format $format, ]);4. 跨域、回調(diào)與CKEditor插入的銜接4.1 谷歌瀏覽器跨域問題怎么解決抓到圖片之后前端要發(fā)請求到PHP接口如果編輯器的頁面和上傳接口的域名不一致瀏覽器就會攔截跨域請求。這個(gè)在Chrome里表現(xiàn)得尤其嚴(yán)格預(yù)檢請求不通過直接給你打在console里。解決辦法是服務(wù)端設(shè)置CORS響應(yīng)頭允許你的前端域名跨域訪問。// 入口文件或上傳接口文件頭部添加 header(Access-Control-Allow-Origin: https://yourfrontenddomain.com); header(Access-Control-Allow-Methods: POST, OPTIONS); header(Access-Control-Allow-Headers: Content-Type); header(Access-Control-Max-Age: 86400); // 命中預(yù)請求直接返回204 if ($_SERVER[REQUEST_METHOD] OPTIONS) { http_response_code(204); exit; }這里特別提醒一句跨域配置的作用域很小一般只在接口文件里加就行不要全局加免得把整個(gè)站點(diǎn)的CORS都放開反而引入不必要的風(fēng)險(xiǎn)。Access-Control-Allow-Origin不要寫成*一定要寫死你前端的域名。寫*確實(shí)省事但只要你這個(gè)接口稍微有點(diǎn)內(nèi)部屬性比如將來需要帶Cookie做登錄校驗(yàn)?zāi)?就直接廢掉了還得重來。另外如果你做的是前后端分離架構(gòu)前端在localhost:8080、接口在localhost:80這也屬于跨域。本地開發(fā)和線上環(huán)境要分別維護(hù)或者統(tǒng)一走反向代理。這個(gè)小細(xì)節(jié)能省掉很多本地調(diào)試時(shí)莫名其妙的報(bào)錯(cuò)。4.2 上傳成功后把圖片插回編輯器圖片上傳成功、拿到了URL接下來要高保真地把圖片插入編輯器。CKEditor 4里最便捷的方式是editor.insertHtml()把完整的img標(biāo)簽插到光標(biāo)位置。editor.insertHtml(img src json.url alt粘貼圖片 stylemax-width:100%; /);這里插的stylemax-width:100%;建議帶上因?yàn)楹芏嗪笈_編輯器場景里用戶粘貼的圖片可能非常寬如果不設(shè)最大寬度限制大圖片會直接把編輯區(qū)撐爆導(dǎo)致排版崩壞。雖然CSS可以在外部統(tǒng)一定義但每次插入時(shí)帶上內(nèi)聯(lián)樣式是最穩(wěn)妥的它不依賴外部的樣式表是否生效。還要注意CKEditor的過濾機(jī)制。CKEditor 4配置了allowedContent或者extraAllowedContent的話某些標(biāo)簽屬性會被剝離。如果你發(fā)現(xiàn)圖片插入后被過濾掉或者style屬性消失就需要在config.extraAllowedContent里加上img[src,alt,title](*){*}之類的規(guī)則允許圖片保留這些屬性和樣式。4.3 CKEditor4和CKEditor5在API上的差異CKEditor 4的editor.on(paste)這套機(jī)制在CKEditor 5里有比較大的變化。CKEditor 5的粘貼流程走的是它的Clipboard插件體系直接在editor.on(paste)里攔截的寫法不再適用。CKEditor 5監(jiān)聽的是editor.plugins.get(Clipboard)相關(guān)的paste事件而且事件的參數(shù)結(jié)構(gòu)和CKEditor 4不一樣。如果你用的是CKEditor 5可以這樣處理editor.plugins.get(Clipboard).on(paste, function(evt, data) { var items data.dataTransfer.items; // 后續(xù)獲取文件的方式和CKEditor 4類似 });不過老實(shí)說CKEditor 5對于粘貼圖片的默認(rèn)處理更像把圖片上傳并插入圖片鏈接因?yàn)樗诟晃谋揪庉嬈骼镆肓吮容^完整的上傳處理管線。但默認(rèn)配置下它未必會統(tǒng)一格式、未必會走你自己定義的PHP接口所以真正生產(chǎn)級項(xiàng)目里還是建議按你自己的業(yè)務(wù)需求來封裝一層而不是完全依賴編輯器的默認(rèn)行為。如果你的項(xiàng)目還在用CKEditor 4那文章里前段的方案就是可以直接落地的。4.4 兼容性細(xì)節(jié)與不同瀏覽器表現(xiàn)關(guān)于跨瀏覽器兼容性再分享幾個(gè)實(shí)測下來很容易出問題的點(diǎn)。第一個(gè)是Safari的粘貼行為。在macOS上從訪達(dá)復(fù)制圖片文件Safari是可以拿到File對象的但從網(wǎng)頁里復(fù)制一張圖片Safari經(jīng)常只會給出一段包含data:image的HTML。所以前面的extractImageFile()里的第三種方式解析text/html中的data URL就是專門為這種場景兜底的。第二個(gè)是Firefox的dataTransfer.items。Firefox在某些版本里items的length是0但files里有數(shù)據(jù)。所以判斷邏輯一定不要只在一種數(shù)據(jù)源上鉆牛角尖兩種都要檢查。第三個(gè)是Chrome的clipboardData在粘貼事件里的表現(xiàn)。Chrome在粘貼圖片時(shí)dataTransfer.items里會有一個(gè)kind: file、type: image/png的項(xiàng)getAsFile()大概率可以拿到文件。但如果你在paste事件回調(diào)里異步執(zhí)行什么操作比如先setTimeout再讀取剪貼板內(nèi)容那getAsFile()返回的可能就是null因?yàn)榧糍N板數(shù)據(jù)在事件回調(diào)結(jié)束后就會被清空。所以拿到圖片文件后立刻同步處理所有耗時(shí)的格式轉(zhuǎn)換和上傳都放到拿到File之后再做。5. 常見問題與排查技巧實(shí)錄5.1 粘貼圖片后沒反應(yīng)事件根本就沒觸發(fā)多半是綁定時(shí)機(jī)問題。確認(rèn)editor.on(paste)是不是在instanceReady之后綁的。還有一個(gè)常見原因是編輯器沒有獲得焦點(diǎn)用戶鼠標(biāo)焦點(diǎn)還在頁面其他地方粘貼事件發(fā)生在body上而不是編輯器內(nèi)部自然就不會觸發(fā)CKEditor的paste事件。解決方法是引導(dǎo)用戶先把光標(biāo)點(diǎn)到編輯器里或者你在全局document上監(jiān)聽paste再判斷當(dāng)前焦點(diǎn)是否在編輯器內(nèi)。用全局監(jiān)聽的好處是無論用戶焦點(diǎn)在那個(gè)textarea還是編輯器都能捕捉到粘貼事件然后你把圖片處理后通過insertHtml插到編輯器。這種方式我建議做成兜底方案而不是主力因?yàn)槿直O(jiān)聽會和CKEditor內(nèi)部的事件處理產(chǎn)生競爭處理不好容易重復(fù)插入。5.2 圖片上傳成功但插入編輯器后是base64這說明你只做了上傳沒攔住編輯器的默認(rèn)行為。確認(rèn)evt.data.preventDefault()是否真的執(zhí)行了。如果代碼看起來沒問題檢查一下是否綁定了多個(gè)paste事件處理器比如你項(xiàng)目里有其他插件也監(jiān)聽了paste它們可能在你之前執(zhí)行了插入邏輯。5.3 PNG透明背景轉(zhuǎn)JPEG后出現(xiàn)黑塊這是我在評論區(qū)看到最多的問題。PNG帶透明通道直接轉(zhuǎn)JPEG透明區(qū)域在JPEG格式里沒有對應(yīng)編碼GD庫默認(rèn)填充黑色。不管在前端還是后端轉(zhuǎn)JPEG之前先鋪一層白色背景。前端用ctx.fillStyle #ffffff; ctx.fillRect()后端用imagefill函數(shù)。兩個(gè)地方都做是為了防止前后端不一致導(dǎo)致某個(gè)環(huán)節(jié)漏掉。5.4 跨域上傳被瀏覽器攔截報(bào)錯(cuò)信息通常會出現(xiàn)在瀏覽器console里類似CORS policy。確認(rèn)接口文件里加了正確的Access-Control-Allow-Origin響應(yīng)頭確認(rèn)這個(gè)頭的值和前端域名完全一致包括http和https的區(qū)別。Chrome對跨域限制比較嚴(yán)格如果預(yù)檢請求沒通過不光是響應(yīng)沒有連請求都可能看不到。5.5 文件名亂碼和擴(kuò)展名異常服務(wù)端保存文件名時(shí)不要直接用原文件名尤其是從Windows復(fù)制圖片粘貼的場景文件名可能含有中文、空格甚至包含路徑信息。用日期加隨機(jī)字符串重新命名可以一勞永逸地解決這個(gè)問題。擴(kuò)展名必須根據(jù)getimagesize()識別出的真實(shí)MIME來決定不能根據(jù)前端傳的原始文件名和file.type。5.6 常見問題速查表癥狀可能原因處理方法粘貼圖片沒反應(yīng)事件綁定時(shí)機(jī)不對或編輯器無焦點(diǎn)instanceReady后再綁定光標(biāo)先聚焦編輯器插入的是base64字符串沒有攔截默認(rèn)行為確認(rèn)調(diào)用了evt.data.preventDefault()圖片上傳后黑底透明PNG轉(zhuǎn)JPEG未填白底前后端都填充白色背景跨域請求被攔截CORS響應(yīng)頭缺失或不匹配服務(wù)端加Access-Control-Allow-Origin圖片過大撐爆編輯器沒有限制寬度插入img標(biāo)簽時(shí)帶上max-width:100%保存的擴(kuò)展名和格式不一致沒有按真實(shí)MIME判斷getimagesize()識別真實(shí)格式再命名再補(bǔ)充一個(gè)很多人忽略的細(xì)節(jié)前端對圖片格式做統(tǒng)一處理時(shí)如果用戶粘貼的是一張動(dòng)圖GIFCanvas重繪會直接把動(dòng)畫幀拍平變成靜態(tài)圖。如果你的產(chǎn)品需要保留動(dòng)圖效果就得在前端判斷一下截取的圖片類型如果原始格式是GIF且尺寸合理可以考慮跳過Canvas轉(zhuǎn)換直接上傳這個(gè)需要結(jié)合具體業(yè)務(wù)場景來做取舍。5.7 一個(gè)實(shí)操上的建議前端壓縮不要過于激進(jìn)我見過一些項(xiàng)目為了提高上傳速度把圖片壓縮得非常狠質(zhì)量參數(shù)直接壓到0.5。結(jié)果用戶上傳的截圖文字模糊得沒法看又被投訴回來。粘貼的截圖最常出現(xiàn)的大問題不是體積大而是體積確實(shí)大但用戶又希望清晰。我的建議是質(zhì)量參數(shù)控制在0.88到0.92之間這個(gè)區(qū)間視覺損失極小壓縮比例又比較理想。如果尺寸超過2000px再等比壓縮基本就能滿足絕大部分使用場景又不會讓圖片丑得離譜。另外一定要在轉(zhuǎn)換函數(shù)里加入錯(cuò)誤處理分支。Canvas是瀏覽器里比較容易意外的API碰到超大圖片或者解碼失敗整個(gè)流程就會卡住。前端轉(zhuǎn)換失敗時(shí)至少要把原始文件直接上傳讓服務(wù)端來轉(zhuǎn)換而不是讓用戶站在一個(gè)永遠(yuǎn)轉(zhuǎn)圈的上傳狀態(tài)里。寫在最后的一個(gè)經(jīng)驗(yàn)關(guān)于統(tǒng)一格式這件事我想要強(qiáng)調(diào)的意識是不要指望單靠前端或者單靠后端就能徹底解決這是兩段式的工程。前端負(fù)責(zé)體驗(yàn)和初步規(guī)范后端負(fù)責(zé)安全和最終落盤。我自己的項(xiàng)目里前端把圖片統(tǒng)一成JPEG并壓縮質(zhì)量后端再用GD庫驗(yàn)一遍真實(shí)格式、做最終轉(zhuǎn)換、統(tǒng)一命名、按日期歸檔。這套方案上線運(yùn)行了接近一年基本沒再出現(xiàn)過粘貼圖片格式混亂或者透明底變黑的投訴。如果你準(zhǔn)備把方案落地建議先做一個(gè)最小可運(yùn)行的版本一個(gè)簡單的PHP上傳接口加上一段CKEditor的paste攔截腳本用不同瀏覽器分別測試粘貼截圖、粘貼文件、復(fù)制網(wǎng)頁圖片這三種最常見場景。把基礎(chǔ)鏈路跑通再逐步加上格式轉(zhuǎn)換、尺寸壓縮、跨域配置這些增強(qiáng)功能。這樣做的好處是一旦某一步出錯(cuò)你能快速定位問題出在事件監(jiān)聽、文件提取、上傳請求還是服務(wù)端轉(zhuǎn)換這個(gè)環(huán)節(jié)而不是面對一堆復(fù)雜邏輯互相干擾。希望上面的這些踩坑記錄和代碼片段能幫你少走幾步彎路。 CKEditor跨瀏覽器粘貼圖片上傳PHP統(tǒng)一格式方案
寫這篇東西的起因是前陣子有個(gè)朋友在群里吐槽項(xiàng)目用的CKEditor用戶從截圖軟件、微信、word里復(fù)制圖片往編輯器里一貼結(jié)果瀏覽器之間表現(xiàn)完全不一樣。Chrome里粘貼變成base64大長串Firefox里有些圖片能傳有些傳不上去Safari干脆沒反應(yīng)。而且圖片格式五花八門有png有jpg有webp上傳到PHP服務(wù)器后要么擴(kuò)展名和實(shí)際格式對不上要么透明背景變成黑塊。他問我跨瀏覽器用CKEditor粘貼圖片到PHP服務(wù)器到底怎么統(tǒng)一格式這個(gè)問題其實(shí)很多做后臺管理系統(tǒng)、富文本編輯器、CMS、甚至B端工作臺的人都遇到過。編輯器的粘貼圖片上傳本質(zhì)上是三條線的交匯瀏覽器剪貼板API的兼容性處理、CKEditor事件機(jī)制的攔截、PHP服務(wù)端的文件接收與格式重編碼。任何一條線沒處理好就會出各種怪問題。這篇文章把我自己項(xiàng)目里沉淀下來的完整方案拆開講清楚包括前端怎么攔截粘貼事件、怎么跨瀏覽器拿到圖片文件、怎么在前端把格式統(tǒng)一以及服務(wù)端PHP怎么用GD庫做二次兜底轉(zhuǎn)換和安全校驗(yàn)。如果你正在做或者準(zhǔn)備做類似的編輯器和上傳功能這篇文章可以直接當(dāng)作參考方案來用。1. 整體方案設(shè)計(jì)與思路拆解1.1 核心痛點(diǎn)粘貼圖片對編輯器來說究竟意味著什么用戶從外部復(fù)制一張圖片然后粘貼到編輯框里這對CKEditor來說本質(zhì)上是一個(gè)內(nèi)容插入事件。它不像input typefile那樣直接把圖片文件丟給你而是把剪貼板里的數(shù)據(jù)當(dāng)作一段HTML或者文本內(nèi)容塞進(jìn)編輯器。問題就出在這里剪貼板里的圖片在不同瀏覽器里呈現(xiàn)的形式完全不同。Chrome和Edge在粘貼圖片時(shí)默認(rèn)會把圖片轉(zhuǎn)成base64編碼的data URL然后以img srcdata:image/png;base64,...的形式插入編輯器。這種做法的后果是編輯器的內(nèi)容區(qū)會塞進(jìn)一大段幾十KB甚至幾MB的字符串保存到數(shù)據(jù)庫時(shí)會直接把列表頁拖垮。Firefox在這方面相對老實(shí)一點(diǎn)它更多時(shí)候會提供文件對象但不同版本之間表現(xiàn)也不穩(wěn)定。Safari在macOS上從訪達(dá)復(fù)制圖片文件時(shí)可以拿到文件但從網(wǎng)頁內(nèi)復(fù)制圖片時(shí)卻經(jīng)常只有HTML沒有文件對象。早期版本的IE更不用提根本不支持DataTransfer相關(guān)API。除此之外還有一個(gè)隱含的痛點(diǎn)圖片格式五花八門。用戶粘貼的可能是PNG截圖、JPEG照片、webp網(wǎng)頁圖片、甚至從微信復(fù)制過來的不明格式。如果不加干預(yù)保存到服務(wù)器上的就是一堆擴(kuò)展名和實(shí)際格式混亂的文件后續(xù)做圖片處理、兼容性展示、二次壓縮都很麻煩。所以統(tǒng)一格式并不是一個(gè)單純的技術(shù)潔癖問題而是直接關(guān)系到后臺圖片存儲規(guī)范和頁面穩(wěn)定性的實(shí)際需求。1.2 方案選型為什么不讓編輯器自動(dòng)處理而是自己攔截CKEditor 4本身是支持配置圖片上傳的官方文檔里有filebrowserImageUploadUrl這類的配置項(xiàng)配合文件管理器或者自研上傳接口來做圖片上傳。但如果你實(shí)際試過就會知道這個(gè)內(nèi)置流程對粘貼上傳的支持并不理想尤其是跨瀏覽器場景。它更多是為點(diǎn)擊按鈕選擇文件上傳設(shè)計(jì)的粘貼時(shí)它傾向于直接插入base64而不是把圖片當(dāng)作上傳任務(wù)處理。所以更穩(wěn)妥的做法是自己監(jiān)聽編輯器的paste事件在編輯器默認(rèn)邏輯執(zhí)行之前把圖片攔截下來提取成文件對象走自己的上傳接口。這樣有幾個(gè)好處一是可以針對不同瀏覽器分別處理兼容性可控二是可以決定哪些圖片粘貼后上傳、哪些不做處理三是可以在上傳前做格式統(tǒng)一和壓縮而不是把圖片原封不動(dòng)地塞進(jìn)編輯器。從后端視角看服務(wù)端也必須做二次兜底。前端統(tǒng)一格式雖然在大多數(shù)場景下可靠但你不能依賴前端傳過來的文件和參數(shù)完全可信任。而且從Word等富文本工具里粘貼過來的圖片經(jīng)常是嵌入在HTML里的base64或者特殊格式的二進(jìn)制流這些路徑下前端不一定來得及攔截服務(wù)端必須能夠在接收后判斷真實(shí)格式并做轉(zhuǎn)換。前端統(tǒng)一格式解決體驗(yàn)問題后端統(tǒng)一格式解決可靠性和安全問題兩條路同時(shí)走才能保證最終落到服務(wù)器上的文件一定是統(tǒng)一的、規(guī)范的。1.3 整體數(shù)據(jù)流設(shè)計(jì)整套流程走下來可以把數(shù)據(jù)流拆成四個(gè)關(guān)鍵節(jié)點(diǎn)粘貼事件觸發(fā)、前端提取與轉(zhuǎn)換、異步上傳、服務(wù)端接收與再加工。每一步都有它的職責(zé)和容易踩坑的地方我列個(gè)簡表說明節(jié)點(diǎn)關(guān)鍵職責(zé)主要風(fēng)險(xiǎn)點(diǎn)粘貼事件觸發(fā)捕獲剪貼板中的圖片數(shù)據(jù)部分瀏覽器事件獲取時(shí)機(jī)不同前端提取與轉(zhuǎn)換獲取File對象Canvas重編碼為統(tǒng)一格式跨域圖片污染Canvas異步上傳FormData提交到PHP接口跨域CORS配置、超時(shí)服務(wù)端接收與再加工校驗(yàn)真實(shí)格式GD庫重編碼保存擴(kuò)展名偽造、透明通道黑色塊這個(gè)流程里最核心的設(shè)計(jì)原則是前端做體驗(yàn)層優(yōu)化服務(wù)端做兜底和規(guī)范。前端優(yōu)先把圖片轉(zhuǎn)成統(tǒng)一的格式和合理的尺寸減輕服務(wù)端壓力服務(wù)端則無論如何都按真實(shí)內(nèi)容來保存而不是按聲稱的格式來保存。兩層各自獨(dú)立又互相配合。2. 前端攔截粘貼圖片的完整實(shí)現(xiàn)2.1 監(jiān)聽paste事件并讀取剪貼板數(shù)據(jù)CKEditor 4的實(shí)例在instanceReady事件觸發(fā)后我們就可以通過editor.on(paste, handler)來監(jiān)聽粘貼事件。請注意這里的paste事件是CKEditor封裝過的事件對象內(nèi)部會提供evt.data.dataTransfer這個(gè)對象和瀏覽器原生clipboardData基本等價(jià)但在不同瀏覽器里字段的表現(xiàn)形式有細(xì)微差異所以不能只寫一種寫法就指望所有瀏覽器通用。CKEDITOR.on(instanceReady, function(e) { var editor e.editor; editor.on(paste, function(evt) { var dataTransfer evt.data.dataTransfer; if (!dataTransfer) { return; } console.log(剪貼板類型, dataTransfer.types); }); });很多人在這一步就會遇到第一個(gè)坑綁定的時(shí)間不對。如果你在instanceReady之前就去editor.on(paste)那么大部分事件根本不會觸發(fā)因?yàn)榫庉嬈鲀?nèi)部的實(shí)例還沒初始化完成事件機(jī)制還沒掛載。還有一個(gè)非常隱蔽的問題有些瀏覽器在paste事件里dataTransfer雖然有值但items是空的反而files里有數(shù)據(jù)。這個(gè)在下面的跨瀏覽器處理里具體展開。2.2 從不同瀏覽器中可靠地拿到圖片文件拿到dataTransfer之后任務(wù)就從事件監(jiān)聽階段切換到找圖片階段。標(biāo)準(zhǔn)做法是先遍歷dataTransfer.items找type以image/開頭的項(xiàng)然后調(diào)用getAsFile()獲取文件對象。但真實(shí)世界沒有這么理想我整理了三種常見來源對應(yīng)不同的處理方式。第一種也是最常見的dataTransfer.items里存在圖片項(xiàng)getAsFile()能正常返回File對象。這種情況出現(xiàn)在Chrome、Edge、Firefox的新版本里用戶從本地復(fù)制圖片文件或者從截圖工具粘貼時(shí)基本都是這個(gè)路徑。第二種items里沒有圖片項(xiàng)但dataTransfer.files里有文件。這種情況在Safari和部分Firefox版本中經(jīng)常出現(xiàn)。所以判斷順序不能只盯著items看files也要檢查。第三種剪貼板里沒有文件對象但text/html數(shù)據(jù)里嵌著一串base64圖片通常是從網(wǎng)頁上直接復(fù)制圖片時(shí)出現(xiàn)這種情況。這時(shí)候需要從text/html中提取img srcdata:image/...里的data URL再把它轉(zhuǎn)成Blob對象。function extractImageFile(dataTransfer) { // 方式一從 items 中取 var items dataTransfer.items || []; for (var i 0; i items.length; i) { if (items[i].type items[i].type.indexOf(image) ! -1) { var file items[i].getAsFile items[i].getAsFile(); if (file) { return file; } } } // 方式二從 files 中取 if (dataTransfer.files dataTransfer.files.length 0) { return dataTransfer.files[0]; } // 方式三從 text/html 中解析 data URL var html dataTransfer.getData(text/html); if (html html.indexOf(data:image) ! -1) { var match html.match(/src(data:image\/[^])/); if (match) { return dataURLToBlob(match[1]); } } return null; } function dataURLToBlob(dataURL) { var arr dataURL.split(,); var mime arr[0].match(/:(.*?);/)[1]; var bstr atob(arr[1]); var n bstr.length; var u8arr new Uint8Array(n); while (n--) { u8arr[n] bstr.charCodeAt(n); } return new Blob([u8arr], { type: mime }); }這段代碼我建議直接作為工具函數(shù)常駐前端公共庫里不只編輯器用其他地方需要讀取剪貼板圖片也可以用。走通這段邏輯Chrome、Firefox、Edge、Safari這四個(gè)主流瀏覽器基本都能拿到圖片文件了。2.3 攔截默認(rèn)的base64插入行為這是整個(gè)流程里最容易被忽略、但影響最大的一步。如果我們只提取圖片文件而不做攔截那么CKEditor默認(rèn)的粘貼處理器會同時(shí)把base64圖片插入編輯器導(dǎo)致上傳之后編輯器里出現(xiàn)兩個(gè)圖片一個(gè)是你上傳后插入的URL版本一個(gè)是默認(rèn)處理的base64版本。所以拿到圖片文件之后第一時(shí)間要調(diào)用evt.data.preventDefault()阻止默認(rèn)行為。editor.on(paste, function(evt) { var imageFile extractImageFile(evt.data.dataTransfer); if (!imageFile) { return; } evt.data.preventDefault(); handlePastedImage(imageFile); });這里有一個(gè)經(jīng)驗(yàn)點(diǎn)preventDefault()的位置很重要必須在判斷出確實(shí)有圖片文件之后才調(diào)用。如果判斷沒有圖片就放行讓編輯器正常處理文字粘貼或者其他內(nèi)容。一旦誤攔截用戶復(fù)制普通文本也會沒反應(yīng)體驗(yàn)非常糟糕。另外如果你的編輯器開啟了forcePasteAsPlainText這類配置要特別注意它和preventDefault的相互作用處理不好容易導(dǎo)致攔截后插入的內(nèi)容丟失。2.4 前端統(tǒng)一格式用Canvas把圖片轉(zhuǎn)換成目標(biāo)格式拿到File對象之后就要面對統(tǒng)一的第一個(gè)層面格式統(tǒng)一。這個(gè)步驟可以在前端做也可以用服務(wù)端做我的建議是兩層都做。前端做的好處是圖片在上傳前就變成了統(tǒng)一的格式、合理的尺寸和合適的體積上傳壓力小后端拿到直接存就是規(guī)范文件。前端轉(zhuǎn)換圖片格式的核心工具是Canvas。思路很簡單讀取圖片-繪制到Canvas-用canvas.toBlob()輸出指定格式的Blob對象。關(guān)鍵點(diǎn)在兩個(gè)地方要填白底以及要控制質(zhì)量參數(shù)。填白底的目的是為了防止PNG格式的透明圖片在轉(zhuǎn)換成JPEG后透明區(qū)域變成黑色。Canvas在沒有背景色的情況下導(dǎo)出JPEG透明區(qū)域默認(rèn)是黑色這在視覺上非常突兀。所以在繪制之前必須先用白色填充整個(gè)畫布再畫圖片。這個(gè)坑我見過無數(shù)次前端不填白、后端也不處理最后所有帶透明通道的截圖傳上去都是黑底。function convertImageFile(file, targetType, quality) { return new Promise(function(resolve, reject) { var url URL.createObjectURL(file); var img new Image(); img.onload function() { var canvas document.createElement(canvas); canvas.width img.naturalWidth; canvas.height img.naturalHeight; var ctx canvas.getContext(2d); if (targetType image/jpeg) { ctx.fillStyle #ffffff; ctx.fillRect(0, 0, canvas.width, canvas.height); } ctx.drawImage(img, 0, 0); URL.revokeObjectURL(url); canvas.toBlob(function(blob) { if (blob) { resolve(blob); } else { reject(new Error(canvas.toBlob返回空)); } }, targetType, quality || 0.92); }; img.onerror function() { URL.revokeObjectURL(url); reject(new Error(圖片加載失敗)); }; img.src url; }); }這個(gè)函數(shù)里還隱含了一個(gè)問題如果用戶粘貼的圖片本身來源于跨域資源比如從另一個(gè)域名的網(wǎng)頁上復(fù)制那么img讀取該圖片時(shí)Canvas會被污染toBlob()會直接拋錯(cuò)。但好在我們這個(gè)場景里用戶粘貼的都是剪貼板里的文件或者data URL本質(zhì)上都在本地不涉及跨域所以這個(gè)函數(shù)是安全的。當(dāng)然如果你后續(xù)要處理編輯器里已存在的跨域圖片再壓縮那就需要額外給img加上crossOriginanonymous屬性并且服務(wù)端配合CORS。3. 上傳接口與PHP服務(wù)端處理3.1 前端用FormData異步上傳格式轉(zhuǎn)換完成后把Blob對象放進(jìn)FormData作為普通文件上傳即可。需要注意的一個(gè)細(xì)節(jié)是Blob對象的文件名。如果你不指定文件名某些瀏覽器會以blob作為文件名PHP的$_FILES[file][name]可能會變成blob這會影響后綴判斷。更好的做法是手動(dòng)指定一個(gè)統(tǒng)一后綴的文件名比如paste_1736244109.jpg。function uploadPastedImage(blob, editor) { var fd new FormData(); var filename paste_ Date.now() .jpg; fd.append(file, blob, filename); // 可以帶一個(gè)format參數(shù)告訴服務(wù)端我們希望統(tǒng)一成什么格式 fd.append(format, jpg); fetch(/api/upload.php, { method: POST, body: fd }) .then(function(res) { return res.json(); }) .then(function(json) { if (json.code 0) { editor.insertHtml(img src json.url alt粘貼圖片 /); } else { alert(json.msg || 上傳失敗); } }) .catch(function(error) { console.error(上傳異常, error); }); }我推薦使用fetch但如果你項(xiàng)目的瀏覽器兼容性要求特別老比如需要兼容IE11那就改用XMLHttpRequest邏輯完全一樣。不要用canvas.toDataURL()拿到base64再傳到服務(wù)端去處理那樣數(shù)據(jù)的體積比二進(jìn)制Blob要膨脹三分之一左右徒增傳輸壓力而且服務(wù)端還要多做一步base64解碼。3.2 PHP接收與安全校驗(yàn)PHP側(cè)的第一步工作是接收文件、檢查錯(cuò)誤、判斷大小。這里有兩件事要特別強(qiáng)調(diào)一是$_FILES[file][error]必須檢查這是判斷上傳是否成功的第一道關(guān)卡二是絕對不要信任前端傳過來的文件名和MIME類型。為什么不能信任MIME類型因?yàn)闉g覽器在構(gòu)造multipart/form-data請求時(shí)$_FILES里的type字段完全由客戶端控制偽造image/jpeg沒有任何技術(shù)門檻。如果直接用這個(gè)值決定后續(xù)處理等于把安全門敞開著。正確做法是用PHP的getimagesize()函數(shù)讀取臨時(shí)文件拿到真實(shí)的圖片寬高信息、真實(shí)MIME類型。這個(gè)函數(shù)會檢查圖片文件頭如果文件根本不是圖片它會返回false自然就把偽造攻擊擋掉了。$file $_FILES[file]; if (!$file || $file[error] ! UPLOAD_ERR_OK) { echo json_encode([code 1, msg 上傳失敗]); exit; } if ($file[size] 5 * 1024 * 1024) { echo json_encode([code 1, msg 文件大小不能超過5MB]); exit; } $info getimagesize($file[tmp_name]); if ($info false) { echo json_encode([code 1, msg 文件不是有效圖片]); exit; } $mime $info[mime]; $allowedMimes [ image/jpeg jpg, image/png png, image/gif gif, image/webp webp, image/bmp bmp, ]; if (!isset($allowedMimes[$mime])) { echo json_encode([code 1, msg 不支持的圖片格式]); exit; }這段邏輯就是按真實(shí)內(nèi)容判定格式的原則。前端說它是jpg不管PHP看文件頭判斷出它實(shí)際上是png就按png處理。這樣能保證后續(xù)的格式轉(zhuǎn)換一定成功。3.3 用GD庫統(tǒng)一圖片格式的完整代碼PHP服務(wù)端的格式統(tǒng)一使用的是PHP內(nèi)置的GD庫。相比ImageMagickGD庫的優(yōu)點(diǎn)是幾乎所有PHP環(huán)境默認(rèn)開啟不需要額外安裝擴(kuò)展操作也簡單。它的核心思路是真實(shí)MIME決定怎么解碼目標(biāo)格式?jīng)Q定怎么輸出中間用imagecopyresampled()重采樣。要注意的仍然是白色背景問題。GD庫在把帶透明通道的PNG圖片轉(zhuǎn)成JPEG時(shí)如果不先填充背景色透明區(qū)域會變成黑色。這個(gè)問題如果前端已經(jīng)處理過服務(wù)端可以少操一份心但程序不能假設(shè)前端一定做了服務(wù)端必須再做一次。代碼如下function convertToFormat($srcPath, $format, $quality 92) { $info getimagesize($srcPath); $mime $info[mime]; $width $info[0]; $height $info[1]; switch ($mime) { case image/jpeg: $src imagecreatefromjpeg($srcPath); break; case image/png: $src imagecreatefrompng($srcPath); break; case image/gif: $src imagecreatefromgif($srcPath); break; case image/webp: $src imagecreatefromwebp($srcPath); break; case image/bmp: $src imagecreatefrombmp($srcPath); break; default: return false; } if (!$src) { return false; } // 如果要輸出jpeg先鋪白底 $dst imagecreatetruecolor($width, $height); if ($format jpg) { $white imagecolorallocate($dst, 255, 255, 255); imagefill($dst, 0, 0, $white); } imagecopyresampled($dst, $src, 0, 0, 0, 0, $width, $height, $width, $height); ob_start(); if ($format png) { imagepng($dst); } else { imagejpeg($dst, null, $quality); } $data ob_get_contents(); ob_end_clean(); imagedestroy($src); imagedestroy($dst); return $data; }這里解釋一下為什么用ob_start()配合imagejpeg($dst, null, $quality)而不是直接imagejpeg($dst, $path, $quality)。因?yàn)槿绻阋趦?nèi)存里拿到圖片的二進(jìn)制內(nèi)容最干凈的方式就是讓GD庫往輸出緩沖區(qū)里寫然后再從緩沖區(qū)讀出來。直接指定文件路徑寫入也可以但那樣你還要多一步讀文件而且在確定命名之前就落盤遠(yuǎn)不如內(nèi)存操作干凈。unlink()清理臨時(shí)文件這些細(xì)節(jié)同樣別忽略。如果你還想連尺寸也統(tǒng)一比如超過2000像素的圖片等比縮到2000像素以內(nèi)那就在創(chuàng)建$dst之前做一次目標(biāo)尺寸計(jì)算。這個(gè)擴(kuò)展非常容易但效果很好因?yàn)榫庉嬈髋鋱D一般不需要超過2000px的圖限制尺寸能夠極大降低存儲壓力。3.4 文件命名、目錄與返回URL設(shè)計(jì)格式統(tǒng)一之后就要考慮保存文件的命名規(guī)則和目錄結(jié)構(gòu)。我強(qiáng)烈不建議使用用戶上傳的原始文件名原因有兩個(gè)一是原始文件名可能是中文、特殊字符或者超長字符串直接作為文件名容易產(chǎn)生編碼問題甚至被利用路徑穿越漏洞二是不同瀏覽器粘貼圖片時(shí)的默認(rèn)命名不同達(dá)不到統(tǒng)一規(guī)范的效果。建議的命名規(guī)則按日期分目錄文件名用uniqid()加隨機(jī)字符串再加上統(tǒng)一后的擴(kuò)展名。比如uploads/2024/07/01/65c0a1b2c3d4e5f6a7b8c9d0.jpg。這樣既保證唯一性又方便按日期歸檔目錄也不會無限膨脹。$format isset($_POST[format]) $_POST[format] png ? png : jpg; $convertedData convertToFormat($file[tmp_name], $format, 92); if ($convertedData false) { echo json_encode([code 1, msg 圖片格式轉(zhuǎn)換失敗]); exit; } $dateDir date(Ymd); $filename $dateDir . / . uniqid(img_, true) . . . $format; $absolutePath $uploadDir . $filename; if (!is_dir(dirname($absolutePath))) { mkdir(dirname($absolutePath), 0755, true); } file_put_contents($absolutePath, $convertedData);最后返回的JSON里要包含圖片的完整URL這個(gè)URL是前端用來插入編輯器的。要注意的是URL不要拼PHP代碼里盡量用配置項(xiàng)維護(hù)一個(gè)baseUrl變量方便在不同環(huán)境下切換。比如本地環(huán)境是http://localhost/uploads線上是https://yourdomain.com/uploads如果不統(tǒng)一管理部署環(huán)境和線上環(huán)境很容易出現(xiàn)圖片路徑不一致的問題。$baseUrl https://yourdomain.com/uploads/; echo json_encode([ code 0, url $baseUrl . $filename, size strlen($convertedData), format $format, ]);4. 跨域、回調(diào)與CKEditor插入的銜接4.1 谷歌瀏覽器跨域問題怎么解決抓到圖片之后前端要發(fā)請求到PHP接口如果編輯器的頁面和上傳接口的域名不一致瀏覽器就會攔截跨域請求。這個(gè)在Chrome里表現(xiàn)得尤其嚴(yán)格預(yù)檢請求不通過直接給你打在console里。解決辦法是服務(wù)端設(shè)置CORS響應(yīng)頭允許你的前端域名跨域訪問。// 入口文件或上傳接口文件頭部添加 header(Access-Control-Allow-Origin: https://yourfrontenddomain.com); header(Access-Control-Allow-Methods: POST, OPTIONS); header(Access-Control-Allow-Headers: Content-Type); header(Access-Control-Max-Age: 86400); // 命中預(yù)請求直接返回204 if ($_SERVER[REQUEST_METHOD] OPTIONS) { http_response_code(204); exit; }這里特別提醒一句跨域配置的作用域很小一般只在接口文件里加就行不要全局加免得把整個(gè)站點(diǎn)的CORS都放開反而引入不必要的風(fēng)險(xiǎn)。Access-Control-Allow-Origin不要寫成*一定要寫死你前端的域名。寫*確實(shí)省事但只要你這個(gè)接口稍微有點(diǎn)內(nèi)部屬性比如將來需要帶Cookie做登錄校驗(yàn)?zāi)?就直接廢掉了還得重來。另外如果你做的是前后端分離架構(gòu)前端在localhost:8080、接口在localhost:80這也屬于跨域。本地開發(fā)和線上環(huán)境要分別維護(hù)或者統(tǒng)一走反向代理。這個(gè)小細(xì)節(jié)能省掉很多本地調(diào)試時(shí)莫名其妙的報(bào)錯(cuò)。4.2 上傳成功后把圖片插回編輯器圖片上傳成功、拿到了URL接下來要高保真地把圖片插入編輯器。CKEditor 4里最便捷的方式是editor.insertHtml()把完整的img標(biāo)簽插到光標(biāo)位置。editor.insertHtml(img src json.url alt粘貼圖片 stylemax-width:100%; /);這里插的stylemax-width:100%;建議帶上因?yàn)楹芏嗪笈_編輯器場景里用戶粘貼的圖片可能非常寬如果不設(shè)最大寬度限制大圖片會直接把編輯區(qū)撐爆導(dǎo)致排版崩壞。雖然CSS可以在外部統(tǒng)一定義但每次插入時(shí)帶上內(nèi)聯(lián)樣式是最穩(wěn)妥的它不依賴外部的樣式表是否生效。還要注意CKEditor的過濾機(jī)制。CKEditor 4配置了allowedContent或者extraAllowedContent的話某些標(biāo)簽屬性會被剝離。如果你發(fā)現(xiàn)圖片插入后被過濾掉或者style屬性消失就需要在config.extraAllowedContent里加上img[src,alt,title](*){*}之類的規(guī)則允許圖片保留這些屬性和樣式。4.3 CKEditor4和CKEditor5在API上的差異CKEditor 4的editor.on(paste)這套機(jī)制在CKEditor 5里有比較大的變化。CKEditor 5的粘貼流程走的是它的Clipboard插件體系直接在editor.on(paste)里攔截的寫法不再適用。CKEditor 5監(jiān)聽的是editor.plugins.get(Clipboard)相關(guān)的paste事件而且事件的參數(shù)結(jié)構(gòu)和CKEditor 4不一樣。如果你用的是CKEditor 5可以這樣處理editor.plugins.get(Clipboard).on(paste, function(evt, data) { var items data.dataTransfer.items; // 后續(xù)獲取文件的方式和CKEditor 4類似 });不過老實(shí)說CKEditor 5對于粘貼圖片的默認(rèn)處理更像把圖片上傳并插入圖片鏈接因?yàn)樗诟晃谋揪庉嬈骼镆肓吮容^完整的上傳處理管線。但默認(rèn)配置下它未必會統(tǒng)一格式、未必會走你自己定義的PHP接口所以真正生產(chǎn)級項(xiàng)目里還是建議按你自己的業(yè)務(wù)需求來封裝一層而不是完全依賴編輯器的默認(rèn)行為。如果你的項(xiàng)目還在用CKEditor 4那文章里前段的方案就是可以直接落地的。4.4 兼容性細(xì)節(jié)與不同瀏覽器表現(xiàn)關(guān)于跨瀏覽器兼容性再分享幾個(gè)實(shí)測下來很容易出問題的點(diǎn)。第一個(gè)是Safari的粘貼行為。在macOS上從訪達(dá)復(fù)制圖片文件Safari是可以拿到File對象的但從網(wǎng)頁里復(fù)制一張圖片Safari經(jīng)常只會給出一段包含data:image的HTML。所以前面的extractImageFile()里的第三種方式解析text/html中的data URL就是專門為這種場景兜底的。第二個(gè)是Firefox的dataTransfer.items。Firefox在某些版本里items的length是0但files里有數(shù)據(jù)。所以判斷邏輯一定不要只在一種數(shù)據(jù)源上鉆牛角尖兩種都要檢查。第三個(gè)是Chrome的clipboardData在粘貼事件里的表現(xiàn)。Chrome在粘貼圖片時(shí)dataTransfer.items里會有一個(gè)kind: file、type: image/png的項(xiàng)getAsFile()大概率可以拿到文件。但如果你在paste事件回調(diào)里異步執(zhí)行什么操作比如先setTimeout再讀取剪貼板內(nèi)容那getAsFile()返回的可能就是null因?yàn)榧糍N板數(shù)據(jù)在事件回調(diào)結(jié)束后就會被清空。所以拿到圖片文件后立刻同步處理所有耗時(shí)的格式轉(zhuǎn)換和上傳都放到拿到File之后再做。5. 常見問題與排查技巧實(shí)錄5.1 粘貼圖片后沒反應(yīng)事件根本就沒觸發(fā)多半是綁定時(shí)機(jī)問題。確認(rèn)editor.on(paste)是不是在instanceReady之后綁的。還有一個(gè)常見原因是編輯器沒有獲得焦點(diǎn)用戶鼠標(biāo)焦點(diǎn)還在頁面其他地方粘貼事件發(fā)生在body上而不是編輯器內(nèi)部自然就不會觸發(fā)CKEditor的paste事件。解決方法是引導(dǎo)用戶先把光標(biāo)點(diǎn)到編輯器里或者你在全局document上監(jiān)聽paste再判斷當(dāng)前焦點(diǎn)是否在編輯器內(nèi)。用全局監(jiān)聽的好處是無論用戶焦點(diǎn)在那個(gè)textarea還是編輯器都能捕捉到粘貼事件然后你把圖片處理后通過insertHtml插到編輯器。這種方式我建議做成兜底方案而不是主力因?yàn)槿直O(jiān)聽會和CKEditor內(nèi)部的事件處理產(chǎn)生競爭處理不好容易重復(fù)插入。5.2 圖片上傳成功但插入編輯器后是base64這說明你只做了上傳沒攔住編輯器的默認(rèn)行為。確認(rèn)evt.data.preventDefault()是否真的執(zhí)行了。如果代碼看起來沒問題檢查一下是否綁定了多個(gè)paste事件處理器比如你項(xiàng)目里有其他插件也監(jiān)聽了paste它們可能在你之前執(zhí)行了插入邏輯。5.3 PNG透明背景轉(zhuǎn)JPEG后出現(xiàn)黑塊這是我在評論區(qū)看到最多的問題。PNG帶透明通道直接轉(zhuǎn)JPEG透明區(qū)域在JPEG格式里沒有對應(yīng)編碼GD庫默認(rèn)填充黑色。不管在前端還是后端轉(zhuǎn)JPEG之前先鋪一層白色背景。前端用ctx.fillStyle #ffffff; ctx.fillRect()后端用imagefill函數(shù)。兩個(gè)地方都做是為了防止前后端不一致導(dǎo)致某個(gè)環(huán)節(jié)漏掉。5.4 跨域上傳被瀏覽器攔截報(bào)錯(cuò)信息通常會出現(xiàn)在瀏覽器console里類似CORS policy。確認(rèn)接口文件里加了正確的Access-Control-Allow-Origin響應(yīng)頭確認(rèn)這個(gè)頭的值和前端域名完全一致包括http和https的區(qū)別。Chrome對跨域限制比較嚴(yán)格如果預(yù)檢請求沒通過不光是響應(yīng)沒有連請求都可能看不到。5.5 文件名亂碼和擴(kuò)展名異常服務(wù)端保存文件名時(shí)不要直接用原文件名尤其是從Windows復(fù)制圖片粘貼的場景文件名可能含有中文、空格甚至包含路徑信息。用日期加隨機(jī)字符串重新命名可以一勞永逸地解決這個(gè)問題。擴(kuò)展名必須根據(jù)getimagesize()識別出的真實(shí)MIME來決定不能根據(jù)前端傳的原始文件名和file.type。5.6 常見問題速查表癥狀可能原因處理方法粘貼圖片沒反應(yīng)事件綁定時(shí)機(jī)不對或編輯器無焦點(diǎn)instanceReady后再綁定光標(biāo)先聚焦編輯器插入的是base64字符串沒有攔截默認(rèn)行為確認(rèn)調(diào)用了evt.data.preventDefault()圖片上傳后黑底透明PNG轉(zhuǎn)JPEG未填白底前后端都填充白色背景跨域請求被攔截CORS響應(yīng)頭缺失或不匹配服務(wù)端加Access-Control-Allow-Origin圖片過大撐爆編輯器沒有限制寬度插入img標(biāo)簽時(shí)帶上max-width:100%保存的擴(kuò)展名和格式不一致沒有按真實(shí)MIME判斷getimagesize()識別真實(shí)格式再命名再補(bǔ)充一個(gè)很多人忽略的細(xì)節(jié)前端對圖片格式做統(tǒng)一處理時(shí)如果用戶粘貼的是一張動(dòng)圖GIFCanvas重繪會直接把動(dòng)畫幀拍平變成靜態(tài)圖。如果你的產(chǎn)品需要保留動(dòng)圖效果就得在前端判斷一下截取的圖片類型如果原始格式是GIF且尺寸合理可以考慮跳過Canvas轉(zhuǎn)換直接上傳這個(gè)需要結(jié)合具體業(yè)務(wù)場景來做取舍。5.7 一個(gè)實(shí)操上的建議前端壓縮不要過于激進(jìn)我見過一些項(xiàng)目為了提高上傳速度把圖片壓縮得非常狠質(zhì)量參數(shù)直接壓到0.5。結(jié)果用戶上傳的截圖文字模糊得沒法看又被投訴回來。粘貼的截圖最常出現(xiàn)的大問題不是體積大而是體積確實(shí)大但用戶又希望清晰。我的建議是質(zhì)量參數(shù)控制在0.88到0.92之間這個(gè)區(qū)間視覺損失極小壓縮比例又比較理想。如果尺寸超過2000px再等比壓縮基本就能滿足絕大部分使用場景又不會讓圖片丑得離譜。另外一定要在轉(zhuǎn)換函數(shù)里加入錯(cuò)誤處理分支。Canvas是瀏覽器里比較容易意外的API碰到超大圖片或者解碼失敗整個(gè)流程就會卡住。前端轉(zhuǎn)換失敗時(shí)至少要把原始文件直接上傳讓服務(wù)端來轉(zhuǎn)換而不是讓用戶站在一個(gè)永遠(yuǎn)轉(zhuǎn)圈的上傳狀態(tài)里。寫在最后的一個(gè)經(jīng)驗(yàn)關(guān)于統(tǒng)一格式這件事我想要強(qiáng)調(diào)的意識是不要指望單靠前端或者單靠后端就能徹底解決這是兩段式的工程。前端負(fù)責(zé)體驗(yàn)和初步規(guī)范后端負(fù)責(zé)安全和最終落盤。我自己的項(xiàng)目里前端把圖片統(tǒng)一成JPEG并壓縮質(zhì)量后端再用GD庫驗(yàn)一遍真實(shí)格式、做最終轉(zhuǎn)換、統(tǒng)一命名、按日期歸檔。這套方案上線運(yùn)行了接近一年基本沒再出現(xiàn)過粘貼圖片格式混亂或者透明底變黑的投訴。如果你準(zhǔn)備把方案落地建議先做一個(gè)最小可運(yùn)行的版本一個(gè)簡單的PHP上傳接口加上一段CKEditor的paste攔截腳本用不同瀏覽器分別測試粘貼截圖、粘貼文件、復(fù)制網(wǎng)頁圖片這三種最常見場景。把基礎(chǔ)鏈路跑通再逐步加上格式轉(zhuǎn)換、尺寸壓縮、跨域配置這些增強(qiáng)功能。這樣做的好處是一旦某一步出錯(cuò)你能快速定位問題出在事件監(jiān)聽、文件提取、上傳請求還是服務(wù)端轉(zhuǎn)換這個(gè)環(huán)節(jié)而不是面對一堆復(fù)雜邏輯互相干擾。希望上面的這些踩坑記錄和代碼片段能幫你少走幾步彎路。