做后臺管理系統(tǒng)的人早晚會碰到富文本編輯器這道坎。文章發(fā)布、商品詳情、公告通知、幫助文檔、售后條款只要頁面里需要排版就繞不開它。我從 Vue2 時代的 UEditor、TinyMCE 一路用過來中間還折騰過 Quill 和 wangEditor踩的坑足夠?qū)懸槐拘宰?。這篇就聚焦一個很具體的問題在 vue3 項目里把 wangEditor 用起來、用對、用到生產(chǎn)環(huán)境不翻車。這不是一篇搬運官方文檔的教程而是我在幾個真實后臺系統(tǒng)里反復(fù)打磨后留下的記錄包括選型的取舍、組件的封裝方式、上傳接口怎么接、只讀模式怎么切、以及那些官方文檔里不會寫但一定會遇到的詭異故障。剛上手 vue3 的同學能照著抄出一個可用組件帶過項目的同學也能在里面找到幾個能省下半天排查時間的細節(jié)。1. 選型前的冷靜判斷wangEditor 到底適合誰1.1 富文本編輯器其實分三條技術(shù)路線在動手寫代碼之前先想清楚富文本編輯器這個領(lǐng)域到底有幾種做法因為選錯方向比寫錯代碼更致命。第一條路線是基于 contenteditable 直接操作 DOMUEditor、wangEditor 早期版本、Quill 都算這一類特點是實現(xiàn)直觀、可控性強但瀏覽器兼容和光標處理是一大堆臟活。第二條是基于文檔模型如 ProseMirror、Slate的編輯器像 Tiptap、飛書文檔編輯器數(shù)據(jù)以結(jié)構(gòu)化 schema 存儲協(xié)同編輯、撤銷重做、節(jié)點級操作都很優(yōu)雅學習曲線也陡。第三條是Markdown 編輯器比如 Vditor、md-editor-v3輸入的是純文本輸出靠解析適合技術(shù)博客但不太適合運營同學寫商品詳情。wangEditor 屬于第一條路線的成熟產(chǎn)物。它的取舍非常明確上手快、中文文檔友好、開箱即用代價是深度定制能力不如 Tiptap 這類模型驅(qū)動的編輯器。選擇它之前先問自己一個問題——我要的是能寫、能排版、能傳圖還是要做類 Notion 的塊級編輯、要支持多人協(xié)同。如果是前者wangEditor 很合適如果是后者直接去看 Tiptap別在小工具上耗時間。1.2 v5 相比 v4 是一次重寫別混著用很多人栽的第一個跟頭是把 v4 的用法套到 v5 上。這兩個大版本幾乎是兩個不同的庫。v4 的用法是new E(#editor)通過editor.txt.html()讀寫內(nèi)容菜單配置是一套老的對象結(jié)構(gòu)。v5 全面轉(zhuǎn)向了模塊化核心包是wangeditor/editorVue 封裝包是wangeditor/editor-for-vue編輯器實例通過createEditor創(chuàng)建內(nèi)容通過 v-model 或editor.getHtml()獲取銷毀必須顯式調(diào)用editor.destroy()。這個變化帶來的直接影響是你在網(wǎng)上搜到的大部分中文教程如果是 2022 年以前寫的八成是 v4直接抄會報錯最典型的就是TypeError: xxx is not a function。判斷版本有個簡單辦法——看安裝的包名。npm i wangeditor裝的是 v4npm i wangeditor/editor裝的才是 v5。v5 新增了mode: simple這種更簡潔的工具欄形態(tài)也把菜單配置統(tǒng)一收進了MENU_CONF整體更符合現(xiàn)代前端工程化的習慣。1.3 和其他主流方案的橫向?qū)Ρ裙庹f wangEditor 好沒有意義得放到坐標系里看。我把實際項目里用過的幾款放在一起做了個對比判斷維度就三個接入成本、定制深度、生態(tài)活躍度。編輯器數(shù)據(jù)模型上手成本深度定制中文支持典型場景wangEditor v5HTML 字符串低中優(yōu)秀后臺管理、CMSTinyMCEHTML 字符串中高商業(yè)版更強良好企業(yè)級表單Quill 2.xDelta 模型中中高一般輕量嵌入TiptapProseMirror 文檔樹高極高一般協(xié)同、塊編輯md-editor-v3Markdown 文本低中優(yōu)秀技術(shù)社區(qū)從表格能看出來wangEditor 在接入成本低和中文支持好這兩個維度上優(yōu)勢明顯正好命中后臺管理系統(tǒng)的核心訴求——運營同學要的是一個打開就能用、工具欄看得懂、圖片能拖拽上傳的編輯器而不是一個需要專門培訓(xùn)的協(xié)同工具。所以接下來的內(nèi)容都建立在后臺管理系統(tǒng) Vue3 TypeScript Element Plus這個組合上這也是目前國內(nèi)企業(yè)項目最主流的形態(tài)。2. 環(huán)境搭建依賴裝錯后面全是白費2.1 先把項目基線和 Node 版本確認清楚開工前先node -v看一眼。wangEditor v5 依賴現(xiàn)代瀏覽器 API構(gòu)建側(cè)對 Node 版本有要求Node 16 以下在 Vite 4/5 環(huán)境下經(jīng)常出現(xiàn)依賴解析失敗。我的習慣是 Node 18 LTS 起步配合 Vite 5 和 Vue 3.4這個組合目前最穩(wěn)。如果你接手的是一個老項目用 Vue CLI 5 Webpack 5 也能跑只是打包體積優(yōu)化空間會小一些。用 Vite 創(chuàng)建項目的話一路默認走下去就行npm create vitelatest my-admin -- --template vue-ts cd my-admin npm install裝完之后檢查package.json里 vue 的版本確保是 3.2 以上。3.2 之前沒有script setup的穩(wěn)定支持而 wangEditor 的 Vue 封裝在組合式 API 下寫起來最舒服。這一步看著啰嗦但我見過太多次編輯器渲染不出來最后發(fā)現(xiàn)是 Vue 版本太老或者依賴裝了兩份的問題——尤其是當項目里已經(jīng)存在一個舊版本編輯器依賴時npm 的扁平安裝策略會把兩個版本都塞進node_modules運行時就隨機命中癥狀是偶發(fā)的白屏。2.2 兩個包各管什么一個都不能少v5 的 Vue3 集成需要裝兩個包這是很多人第一次會困惑的地方npm install wangeditor/editor npm install wangeditor/editor-for-vuenext第一個wangeditor/editor是編輯器內(nèi)核包含編輯器實例、菜單、插件、樣式體積大頭都在這里。第二個wangeditor/editor-for-vue是 Vue 的組件封裝把Editor和Toolbar兩個組件暴露出來讓你能在模板里直接寫Editor /。注意next這個標簽非常關(guān)鍵。Vue3 版本必須用next不加的話會裝上適配 Vue2 的版本然后在script setup里 import 就報錯。裝完可以確認一下版本號npm list wangeditor/editor-for-vue正常應(yīng)該看到wangeditor/editor-for-vue5.x.x之類。如果看到的是 1.x那就是裝錯了卸載重裝。2.3 樣式文件必須單獨引入這是新手最容易漏的一步也是導(dǎo)致工具欄變成一堆無樣式的文字鏈接這個經(jīng)典問題的元兇。wangEditor 的樣式不在組件內(nèi)部自動注入需要你手動引入一次import wangeditor/editor/dist/css/style.css引入位置有講究。寫在script setup頂部是最簡單的方式但要注意它會被打進當前頁面的 chunk。如果你在多個頁面都用編輯器可以把這個引入放到全局的main.ts里代價是首屏會多加載一份樣式。我更推薦的做法是配合路由懶加載讓編輯器頁面的 chunk 自己帶上樣式首屏用戶不受影響。還有個坑是style scoped。有些同學想在 scoped 樣式里覆蓋編輯器的樣式比如改工具欄背景色結(jié)果發(fā)現(xiàn)不生效。原因是 wangEditor 的 DOM 結(jié)構(gòu)是動態(tài)生成的scoped 的屬性選擇器加不到那些節(jié)點上。要覆蓋樣式得用:deep()或者干脆寫一個不帶 scoped 的全局樣式塊專門管編輯器。3. 組件封裝從能跑到好用3.1 最小可用版本與 shallowRef 的生死線先上能跑起來的最小版本。新建src/components/RichEditor.vuetemplate div classrich-editor-wrapper :style{ border: 1px solid #dcdfe6 } Toolbar :editoreditorRef :defaultConfigtoolbarConfig :modemode classeditor-toolbar / Editor :defaultConfigeditorConfig :modemode :style{ height: height px, overflowY: hidden } v-modelvalueHtml onCreatedhandleCreated onChangehandleChange / /div /template script setup langts import wangeditor/editor/dist/css/style.css import { onBeforeUnmount, ref, shallowRef } from vue import { Editor, Toolbar } from wangeditor/editor-for-vue import type { IDomEditor, IEditorConfig, IToolbarConfig } from wangeditor/editor const props withDefaults( defineProps{ modelValue: string height?: number mode?: default | simple readonly?: boolean }(), { modelValue: , height: 400, mode: default, readonly: false } ) const emit defineEmits{ (e: update:modelValue, value: string): void }() const editorRef shallowRefIDomEditor() const valueHtml ref(props.modelValue) const mode props.mode const toolbarConfig: PartialIToolbarConfig { excludeKeys: [group-video, insertVideo] } const editorConfig: PartialIEditorConfig { placeholder: 請輸入內(nèi)容... } const handleCreated (editor: IDomEditor) { editorRef.value editor if (props.readonly) editor.disable() } const handleChange (editor: IDomEditor) { emit(update:modelValue, editor.getHtml()) } onBeforeUnmount(() { const editor editorRef.value if (editor) editor.destroy() }) /script這段代碼里最需要強調(diào)的是shallowRef。editorRef必須用shallowRef絕對不能用ref或者reactive。原因是 Vue3 的ref會對對象做深度響應(yīng)式代理而 wangEditor 內(nèi)部維護了大量 DOM 引用和循環(huán)引用被 Proxy 包一層之后編輯器在獲取選區(qū)、操作節(jié)點時會拿不到原始對象癥狀是光標亂跳、菜單點擊無響應(yīng)、插入圖片報錯。這個坑我在兩個項目里都踩過第二次才反應(yīng)過來是響應(yīng)式代理的問題。官方文檔里提了一句但很容易被忽略這里我必須再強調(diào)一次。3.2 工具欄裁剪與模式切換默認工具欄把所有菜單都堆出來視頻、公式、代碼塊全在對一個只發(fā)公告的后臺系統(tǒng)來說太冗余。toolbarConfig的excludeKeys負責排除insertKeys負責插入或調(diào)整順序。常用的菜單 key 我整理了一份方便你對著刪功能分類菜單 key建議標題/引用headerSelect, blockquote保留基礎(chǔ)格式bold, underline, italic, through, code保留顏色color, bgColor按需字號字色fontSize, fontFamily, lineHeight按需列表縮進bulletedList, numberedList, indent, delIndent保留對齊justifyLeft, justifyCenter, justifyRight, justifyJustify保留圖片uploadImage, insertImage保留 uploadImage鏈接insertLink保留表格insertTable按需代碼塊codeBlock技術(shù)類保留分割線divider保留撤銷重做undo, redo保留全屏fullScreen保留視頻group-video后臺一般刪掉mode有兩個取值default是完整模式simple是簡潔模式工具欄只留最核心的十幾個菜單視覺上更輕。選哪個取決于使用場景——面向運營的公告編輯器用simple面向內(nèi)容編輯的 CMS 用default。注意mode一般只在初始化時設(shè)置運行中動態(tài)切換會導(dǎo)致工具欄重建體驗上會有閃動不建議做成用戶可切換的選項。3.3 圖片上傳必須從 base64 切換到服務(wù)端不加任何配置時wangEditor 插入圖片走的是 base64 內(nèi)聯(lián)。寫幾篇文章沒問題但要是一篇長圖文里插了十幾張高清圖生成的 HTML 字符串會膨脹到幾兆存進數(shù)據(jù)庫字段會直接崩接口傳輸也會超時。所以圖片上傳必須改成服務(wù)端模式。配置位置在editorConfig.MENU_CONF[uploadImage]editorConfig.MENU_CONF[uploadImage] { server: /api/file/upload, fieldName: file, maxFileSize: 5 * 1024 * 1024, allowedFileTypes: [image/*], headers: { Authorization: Bearer getToken() }, customInsert(res, insertFn) { if (res.code ! 200) return insertFn(res.data.url, res.data.name, res.data.url) }, onFailed(file, res) { ElMessage.error(圖片上傳失敗 (res.message || 未知錯誤)) } }幾個要點拆開說。server是上傳地址走相對路徑讓 Vite 的代理去轉(zhuǎn)發(fā)避免開發(fā)環(huán)境跨域。fieldName要和后端接口約定的字段名一致后端用MultipartFile接的話通常就是file。maxFileSize單位是字節(jié)5MB 是我個人的經(jīng)驗值太大容易拖慢接口太小運營會抱怨截圖傳不上去。真正關(guān)鍵的是customInsert。默認情況下 wangEditor 會按自己的規(guī)則去解析返回數(shù)據(jù)它假設(shè)返回體里有個data.url字段。但你項目后端的返回結(jié)構(gòu)很可能不是這個形狀比如是{ code, msg, data: { fileUrl, fileName } }這時候默認解析就插不進去控制臺能看到 undefined。customInsert給了你完全接管解析的機會拿到res之后自己取出 URL調(diào)用insertFn(url, alt, href)插進去就行三個參數(shù)分別是圖片地址、替代文字、跳轉(zhuǎn)鏈接后兩個可以傳空字符串。如果你的上傳邏輯更復(fù)雜比如要先拿簽名再傳對象存儲用customUpload完全接管上傳過程editorConfig.MENU_CONF[uploadImage] { async customUpload(file, insertFn) { const formData new FormData() formData.append(file, file) const { data } await request.post(/api/upload, formData) insertFn(data.url, data.name, data.url) } }用一個/upload接口同時處理粘貼圖片和拖拽上傳是最省心的做法。3.4 v-model 綁定要繞開光標跳動這個雷直觀上大家會寫v-modelvalueHtml然后監(jiān)聽valueHtml的變化往外傳。這能跑但有個隱患編輯器內(nèi)部也會修改valueHtml如果你在外層又監(jiān)聽valueHtml并回寫父組件父組件再把值傳回來就形成了一個回環(huán)。光標位置在每次回寫后都會被重置到開頭用戶打字時感覺像有人在搶鍵盤。更穩(wěn)的做法是放棄v-model的自動雙向綁定改用onChange手動往外拋Editor :defaultConfigeditorConfig :modemode onCreatedhandleCreated onChangehandleChange /const handleChange (editor: IDomEditor) { emit(update:modelValue, editor.getHtml()) }父組件用v-model:modelValue接收即可。這里要理解一個原則——編輯器的內(nèi)容只有兩個出口初始化時的賦值和用戶編輯時的 onChange。除此之外任何時候去改編輯器的內(nèi)容都可能觸發(fā)重渲染和光標問題?；仫@歷史數(shù)據(jù)時直接把值放到初始化的valueHtml里之后就別再動它。4. 高頻故障排查與避坑清單4.1 編輯器實例為 null 和重復(fù)創(chuàng)建最常見的報錯是Cannot read properties of undefined (reading getHtml)原因通常是你在onCreated之前就去調(diào)用了editorRef.value的方法。editorRef是在handleCreated回調(diào)里才被賦值的而handleCreated在組件 mounted 之后才觸發(fā)。所以任何需要在編輯器就緒后做的事比如回填內(nèi)容、設(shè)置只讀、聚焦都得放在handleCreated里面或者用一個isReady標志位守著。第二個坑是重復(fù)創(chuàng)建。如果你在onMounted里手動createEditor同時又用了Editor組件編輯器會被創(chuàng)建兩次頁面上出現(xiàn)兩個工具欄或者內(nèi)容區(qū)閃爍。用官方組件就不要自己 create兩套東西二選一。還有一種情況是熱更新導(dǎo)致的重復(fù)實例開發(fā)時改代碼觸發(fā)熱更新舊實例沒銷毀干凈表現(xiàn)是切換頁面后舊內(nèi)容殘留。解決方式就是在onBeforeUnmount里老老實實editor.destroy()一行都不能省。editor.destroy()不只是清理 DOM它還會解綁所有事件監(jiān)聽、清空內(nèi)部定時器和選區(qū)緩存。漏掉它長時間運行的 SPA 會在連續(xù)打開關(guān)閉幾十個編輯器頁面后明顯卡頓內(nèi)存占用一路往上漲。4.2 樣式丟失與下拉菜單被遮擋工具欄渲染成純文字、菜單彈層藏在別的元素底下這兩類是樣式問題的高發(fā)區(qū)。第一個問題的解法前面說過補上style.css的引入。如果引入了還是不生效檢查一下項目里是不是有其他全局樣式把.w-e-*類的樣式覆蓋了尤其是那些用*選擇器重置 margin、padding 的老代碼會把編輯器的間距全干掉。下拉菜單被遮擋的根源是z-index。wangEditor 的彈層默認層級不算太高如果編輯器放在 Element Plus 的 Dialog 或者 Drawer 里而那個容器的層級更高菜單就會被壓住。常規(guī)解法是給外層容器和編輯器加個更大的z-index.rich-editor-wrapper { position: relative; z-index: 100; }如果彈層還是出不來可以用editorConfig里的scroll配置成false讓工具欄不吸頂某些布局下能繞開層級計算。我遇到過最麻煩的一次是編輯器在抽屜里抽屜本身有transform動畫導(dǎo)致position: fixed的彈層定位基準錯亂最后是把編輯器移到抽屜外的做法才徹底解決。所以選容器的時候盡量別把富文本編輯器塞進有動畫的浮層里。4.3 與 Element Plus 表單聯(lián)動的校驗問題后端管理系統(tǒng)基本都配 Element Plus編輯器要嵌進el-form-item里做必填校驗。這里有兩個細節(jié)。第一個是觸發(fā)時機。el-form-item的trigger要設(shè)成change然后編輯器的onChange里手動觸發(fā)校驗const handleChange (editor) { const html editor.getHtml() emit(update:modelValue, html) formRef.value?.validateField(content) }不手動觸發(fā)的話用戶輸入完內(nèi)容點提交校驗規(guī)則拿到的還是舊值會誤報內(nèi)容不能為空。第二個是內(nèi)容為空的判斷。用戶如果只敲了幾個空格或者插入了一張圖片editor.getHtml()返回的是pbr/p或者pimg ...//p直接判空字符串是不準的。穩(wěn)妥的做法是先剝標簽再判空const isEmptyHtml (html) { return html.replace(/[^]/g, ).replace(/nbsp;/g, ).trim() }這里要注意純圖片的內(nèi)容會被判成空但業(yè)務(wù)上往往認為有圖就算有內(nèi)容。所以更精細的規(guī)則可以判斷是否包含img標簽包含則視為非空。這種邊界判斷看著瑣碎卻直接決定上線后運營會不會天天來找你。4.4 只讀模式的幾種實現(xiàn)方式對比詳情頁展示歷史內(nèi)容時需要只讀商品預(yù)覽時需要只讀審核頁面也需要只讀。wangEditor v5 提供了幾種實現(xiàn)各有適用場景實現(xiàn)方式寫法優(yōu)點局限disable()editor.disable()靈活、可動態(tài)切換需拿實例時機要對defaultConfig 中設(shè) readOnly{ readOnly: true }初始化即生效無法運行中切換點擊后 blureditor.blur()簡單只擋焦點仍可編輯換純 HTML 渲染v-html不加載編輯器性能好無編輯器樣式能力我的選擇是需要保留編輯器樣式且隨時可能切回編輯態(tài)的場景用editor.disable()純展示、不打算再編輯的場景直接v-html渲染 HTML 字符串別加載整個編輯器內(nèi)核。這個區(qū)分很重要詳情頁如果也加載編輯器首屏體積白白多幾百 KB明明用戶只是想看文章。順帶說一個只讀相關(guān)的細節(jié)。editor.disable()生效后工具欄上的菜單會變灰但如果你希望工具欄整個隱藏用v-if控制Toolbar的渲染更干凈Toolbar v-if!readonly :editoreditorRef /另外要提醒切換只讀狀態(tài)后editor.getHtml()依然能正常調(diào)用別擔心 disable 之后拿不到內(nèi)容。4.5 常見問題速查表把上面這些整理成一張排查表出問題時對著找能省不少時間?，F(xiàn)象可能原因處理方式工具欄無樣式未引入 style.css補上全局樣式引入光標跳到開頭v-model 雙向回寫改用 onChange 單向拋出菜單點擊無效editorRef 用了 ref/reactive換成 shallowRef插入圖片報錯返回結(jié)構(gòu)不匹配配置 customInsert內(nèi)容拿不到在 onCreated 之前調(diào)用加 isReady 守位頁面切換后卡頓未調(diào)用 destroyonBeforeUnmount 中銷毀彈層被遮z-index 沖突調(diào)高層級或換容器內(nèi)容判空不準空標簽被判為有內(nèi)容剝標簽后再判空開發(fā)環(huán)境正常、線上白屏樣式 chunk 未跟隨檢查懶加載配置5. 進階內(nèi)容安全、框架集成與體積控制5.1 富文本的 XSS 防護不能省富文本編輯器最容易被忽視的安全問題就是 XSS。用戶尤其是后臺運營提交的 HTML 會原樣存儲如果詳情頁用v-html直接渲染攻擊者只要在編輯器里塞一段帶事件的標簽比如img srcx onerroralert(document.cookie)頁面一打開就可能被利用。雖然 wangEditor 編輯時過濾了一部分危險標簽但通過接口直接提交構(gòu)造好的 HTML編輯器的過濾根本不起作用。所以渲染側(cè)必須自己再過一道。我的做法是引入 DOMPurify在提交前和渲染前各清洗一次import DOMPurify from dompurify const safeHtml DOMPurify.sanitize(rawHtml, { ALLOWED_TAGS: [p, br, strong, em, u, h1, h2, h3, ul, ol, li, a, img, blockquote, table, tr, td, th], ALLOWED_ATTR: [href, src, alt, title, target, style, class] })白名單式過濾比黑名單靠譜得多只放行你明確需要的標簽和屬性其余一律去掉。注意style屬性本身也可能藏東西如果你對安全要求更高可以把 style 也去掉改用自定義類名控制樣式。這一步做起來有點煩但一旦內(nèi)容被注入事故等級完全不一樣值得花兩個小時配好。5.2 在若依、JeecgBoot 這類框架里集成的注意點很多同學是在若依RuoYi-Vue3或者 JeecgBoot 的 Vue3 版本里做二次開發(fā)這些框架本身有自己的請求封裝、全局樣式、權(quán)限指令直接塞編輯器會撞上幾個問題。第一個是請求實例?？蚣芾锿ǔ０?axios 封裝成了request或者service帶了統(tǒng)一的 token 注入、錯誤提示、結(jié)果解包。圖片上傳時最好復(fù)用這個實例而不是在新開一個 axios否則會出現(xiàn) token 沒帶上、上傳接口 401 的情況。如果用 wangEditor 的server配置走內(nèi)置上傳記得在headers里手動補上 Authorization或者直接用customUpload走項目自己的 request。第二個是全局樣式污染。若依那套后臺框架有一大堆覆蓋性的全局 CSS有時候會把編輯器里的列表符號干掉、把表格邊框清掉。排查方式是在編輯器的樣式后面追加一段更高優(yōu)先級的覆蓋.w-e-text-container ul { list-style: disc !important; } .w-e-text-container table { border-collapse: collapse; }第三個是 TypeScript 報錯。有些框架的 tsconfig 開了strict而wangeditor/editor的類型聲明在某些版本里不夠嚴謹會在editorRef.value的賦值處提示類型不匹配。簡單處理是用shallowRefIDomEditor | undefined()拿到實例后做一次非空斷言別為了消錯就把它改成any那等于把類型檢查全關(guān)了。5.3 體積優(yōu)化別讓編輯器拖慢首屏我把wangeditor/editor單獨打出來看過gzip 后大概兩百多 KB對于一個管理后臺來說不算夸張但如果它被打進首屏 chunk登錄頁的加載時間會明顯變長——用戶根本用不到編輯器憑什么要等他加載。解法是讓它按需進入路由 chunk。如果你用的是 Vite路由懶加載本身就做了這件事只要編輯器組件被用在懶加載路由里它就不會進首屏const routes [ { path: /article/edit, component: () import(/views/article/Edit.vue) } ]如果編輯器被用在一個不懶加載的公共布局里用defineAsyncComponent包一層const RichEditor defineAsyncComponent(() import(/components/RichEditor.vue))配合Suspense或者加載占位用戶體驗會好很多。還有一個容易被忽略的體積點——如果項目里只用到了基礎(chǔ)排版能力可以在toolbarConfig里把視頻、公式這些重插件的菜單去掉雖然不能直接搖掉這部分代碼但能避免加載相關(guān)資源。5.4 詳情頁只讀展示的取舍最后聊聊詳情頁。我見過太多項目在詳情頁也掛一個完整的編輯器組件只為展示一段富文本。這樣做有兩個代價一是多加載兩百多 KB 的編輯器內(nèi)核二是編輯器的 DOM 結(jié)構(gòu)比直接渲染 HTML 復(fù)雜得多列表長了之后頁面滾動會明顯發(fā)澀。如果詳情頁不需要任何編輯能力正確做法是只渲染 HTMLtemplate div classarticle-detail v-htmlsafeHtml/div /template然后在全局樣式里給富文本標簽補上基礎(chǔ)樣式讓它看起來和編輯器里一致。這里有個小技巧——把編輯器里用到的樣式抽一份到公共樣式文件里編輯態(tài)和展示態(tài)共用避免出現(xiàn)編輯時好看、展示時排版全亂的尷尬.article-detail img { max-width: 100%; height: auto; } .article-detail table { border-collapse: collapse; width: 100%; } .article-detail p { margin: 8px 0; line-height: 1.8; }如果詳情頁確實需要保留編輯器外殼比如用戶要看到和編輯時一樣的界面再退回用editor.disable()。判斷標準很簡單用戶在這頁會改內(nèi)容嗎會用編輯器不會用 v-html。6. 一些不那么官方但很有用的經(jīng)驗折騰了這么多項目有幾個體會想單獨拎出來說。第一個是關(guān)于版本鎖定。wangEditor v5 更新頻率不算高但每次小版本升級偶爾會帶出小問題比如菜單配置字段微調(diào)、樣式類名變化。生產(chǎn)項目里我建議把版本號寫死不要用^放開次版本號等新版本在測試環(huán)境跑過一輪再升。這個建議對所有第三方 UI 依賴都適用編輯器尤其敏感因為它的行為直接暴露給運營同學。第二個是關(guān)于封裝粒度的取舍。我一開始把編輯器封成了支持十幾項配置的萬能組件結(jié)果每次維護都要在一堆 props 里翻找。后來改成只暴露四個核心 propsmodelValue、height、readonly、mode圖片上傳配置通過一個uploadConfig對象整體傳入。這樣既保證了復(fù)用又不至于讓組件變成一個配置黑洞。組件這東西暴露的接口越少別人越愿意用。第三個是關(guān)于圖片上傳的聯(lián)調(diào)。開發(fā)環(huán)境和生產(chǎn)環(huán)境的圖片域名經(jīng)常不一樣配置里寫的server如果是絕對地址切環(huán)境就得改代碼。我現(xiàn)在的做法是統(tǒng)一走相對路徑讓 Nginx 或者 Vite 代理去轉(zhuǎn)發(fā)配置里一行都不用改。如果后端返回的圖片地址是完整的對象存儲域名那在customInsert里可以做一層轉(zhuǎn)換開發(fā)環(huán)境替換成代理前綴生產(chǎn)環(huán)境原樣輸出。第四個是關(guān)于內(nèi)容回顯的時機。從接口拿到歷史 HTML 之后不要急著往valueHtml里塞。因為編輯器初始化是異步的你在onMounted里賦值的時候組件可能還沒 ready內(nèi)容會被吃掉。穩(wěn)妥的流程是接口數(shù)據(jù)先存進一個變量在handleCreated里再賦給編輯器的初始內(nèi)容或者直接用editor.setHtml()主動設(shè)置。這一點我在兩個項目里都翻過車癥狀是編輯已有文章時內(nèi)容展示不出來排查半天才發(fā)現(xiàn)是時序問題。最后一個提醒關(guān)于測試。富文本編輯器的坑大多不是邏輯問題而是瀏覽器差異和時序問題所以別只在 Chrome 里點兩下了事。至少要在你要支持的瀏覽器里各走一遍完整流程新建內(nèi)容、插入圖片、加表格、保存、回顯、切只讀、再切回編輯。尤其是插入圖片后內(nèi)容能否正確保存是最容易在不同環(huán)境表現(xiàn)不一致的環(huán)節(jié)。我現(xiàn)在的習慣是給編輯器頁面寫一個兩分鐘的冒煙 checklist每次升級依賴或者改樣式前都過一遍花的時間很少省下的事故排查時間卻很多。 Vue3集成wangEditor v5：后臺富文本編輯器封裝與避坑
做后臺管理系統(tǒng)的人早晚會碰到富文本編輯器這道坎。文章發(fā)布、商品詳情、公告通知、幫助文檔、售后條款只要頁面里需要排版就繞不開它。我從 Vue2 時代的 UEditor、TinyMCE 一路用過來中間還折騰過 Quill 和 wangEditor踩的坑足夠?qū)懸槐拘宰?。這篇就聚焦一個很具體的問題在 vue3 項目里把 wangEditor 用起來、用對、用到生產(chǎn)環(huán)境不翻車。這不是一篇搬運官方文檔的教程而是我在幾個真實后臺系統(tǒng)里反復(fù)打磨后留下的記錄包括選型的取舍、組件的封裝方式、上傳接口怎么接、只讀模式怎么切、以及那些官方文檔里不會寫但一定會遇到的詭異故障。剛上手 vue3 的同學能照著抄出一個可用組件帶過項目的同學也能在里面找到幾個能省下半天排查時間的細節(jié)。1. 選型前的冷靜判斷wangEditor 到底適合誰1.1 富文本編輯器其實分三條技術(shù)路線在動手寫代碼之前先想清楚富文本編輯器這個領(lǐng)域到底有幾種做法因為選錯方向比寫錯代碼更致命。第一條路線是基于 contenteditable 直接操作 DOMUEditor、wangEditor 早期版本、Quill 都算這一類特點是實現(xiàn)直觀、可控性強但瀏覽器兼容和光標處理是一大堆臟活。第二條是基于文檔模型如 ProseMirror、Slate的編輯器像 Tiptap、飛書文檔編輯器數(shù)據(jù)以結(jié)構(gòu)化 schema 存儲協(xié)同編輯、撤銷重做、節(jié)點級操作都很優(yōu)雅學習曲線也陡。第三條是Markdown 編輯器比如 Vditor、md-editor-v3輸入的是純文本輸出靠解析適合技術(shù)博客但不太適合運營同學寫商品詳情。wangEditor 屬于第一條路線的成熟產(chǎn)物。它的取舍非常明確上手快、中文文檔友好、開箱即用代價是深度定制能力不如 Tiptap 這類模型驅(qū)動的編輯器。選擇它之前先問自己一個問題——我要的是能寫、能排版、能傳圖還是要做類 Notion 的塊級編輯、要支持多人協(xié)同。如果是前者wangEditor 很合適如果是后者直接去看 Tiptap別在小工具上耗時間。1.2 v5 相比 v4 是一次重寫別混著用很多人栽的第一個跟頭是把 v4 的用法套到 v5 上。這兩個大版本幾乎是兩個不同的庫。v4 的用法是new E(#editor)通過editor.txt.html()讀寫內(nèi)容菜單配置是一套老的對象結(jié)構(gòu)。v5 全面轉(zhuǎn)向了模塊化核心包是wangeditor/editorVue 封裝包是wangeditor/editor-for-vue編輯器實例通過createEditor創(chuàng)建內(nèi)容通過 v-model 或editor.getHtml()獲取銷毀必須顯式調(diào)用editor.destroy()。這個變化帶來的直接影響是你在網(wǎng)上搜到的大部分中文教程如果是 2022 年以前寫的八成是 v4直接抄會報錯最典型的就是TypeError: xxx is not a function。判斷版本有個簡單辦法——看安裝的包名。npm i wangeditor裝的是 v4npm i wangeditor/editor裝的才是 v5。v5 新增了mode: simple這種更簡潔的工具欄形態(tài)也把菜單配置統(tǒng)一收進了MENU_CONF整體更符合現(xiàn)代前端工程化的習慣。1.3 和其他主流方案的橫向?qū)Ρ裙庹f wangEditor 好沒有意義得放到坐標系里看。我把實際項目里用過的幾款放在一起做了個對比判斷維度就三個接入成本、定制深度、生態(tài)活躍度。編輯器數(shù)據(jù)模型上手成本深度定制中文支持典型場景wangEditor v5HTML 字符串低中優(yōu)秀后臺管理、CMSTinyMCEHTML 字符串中高商業(yè)版更強良好企業(yè)級表單Quill 2.xDelta 模型中中高一般輕量嵌入TiptapProseMirror 文檔樹高極高一般協(xié)同、塊編輯md-editor-v3Markdown 文本低中優(yōu)秀技術(shù)社區(qū)從表格能看出來wangEditor 在接入成本低和中文支持好這兩個維度上優(yōu)勢明顯正好命中后臺管理系統(tǒng)的核心訴求——運營同學要的是一個打開就能用、工具欄看得懂、圖片能拖拽上傳的編輯器而不是一個需要專門培訓(xùn)的協(xié)同工具。所以接下來的內(nèi)容都建立在后臺管理系統(tǒng) Vue3 TypeScript Element Plus這個組合上這也是目前國內(nèi)企業(yè)項目最主流的形態(tài)。2. 環(huán)境搭建依賴裝錯后面全是白費2.1 先把項目基線和 Node 版本確認清楚開工前先node -v看一眼。wangEditor v5 依賴現(xiàn)代瀏覽器 API構(gòu)建側(cè)對 Node 版本有要求Node 16 以下在 Vite 4/5 環(huán)境下經(jīng)常出現(xiàn)依賴解析失敗。我的習慣是 Node 18 LTS 起步配合 Vite 5 和 Vue 3.4這個組合目前最穩(wěn)。如果你接手的是一個老項目用 Vue CLI 5 Webpack 5 也能跑只是打包體積優(yōu)化空間會小一些。用 Vite 創(chuàng)建項目的話一路默認走下去就行npm create vitelatest my-admin -- --template vue-ts cd my-admin npm install裝完之后檢查package.json里 vue 的版本確保是 3.2 以上。3.2 之前沒有script setup的穩(wěn)定支持而 wangEditor 的 Vue 封裝在組合式 API 下寫起來最舒服。這一步看著啰嗦但我見過太多次編輯器渲染不出來最后發(fā)現(xiàn)是 Vue 版本太老或者依賴裝了兩份的問題——尤其是當項目里已經(jīng)存在一個舊版本編輯器依賴時npm 的扁平安裝策略會把兩個版本都塞進node_modules運行時就隨機命中癥狀是偶發(fā)的白屏。2.2 兩個包各管什么一個都不能少v5 的 Vue3 集成需要裝兩個包這是很多人第一次會困惑的地方npm install wangeditor/editor npm install wangeditor/editor-for-vuenext第一個wangeditor/editor是編輯器內(nèi)核包含編輯器實例、菜單、插件、樣式體積大頭都在這里。第二個wangeditor/editor-for-vue是 Vue 的組件封裝把Editor和Toolbar兩個組件暴露出來讓你能在模板里直接寫Editor /。注意next這個標簽非常關(guān)鍵。Vue3 版本必須用next不加的話會裝上適配 Vue2 的版本然后在script setup里 import 就報錯。裝完可以確認一下版本號npm list wangeditor/editor-for-vue正常應(yīng)該看到wangeditor/editor-for-vue5.x.x之類。如果看到的是 1.x那就是裝錯了卸載重裝。2.3 樣式文件必須單獨引入這是新手最容易漏的一步也是導(dǎo)致工具欄變成一堆無樣式的文字鏈接這個經(jīng)典問題的元兇。wangEditor 的樣式不在組件內(nèi)部自動注入需要你手動引入一次import wangeditor/editor/dist/css/style.css引入位置有講究。寫在script setup頂部是最簡單的方式但要注意它會被打進當前頁面的 chunk。如果你在多個頁面都用編輯器可以把這個引入放到全局的main.ts里代價是首屏會多加載一份樣式。我更推薦的做法是配合路由懶加載讓編輯器頁面的 chunk 自己帶上樣式首屏用戶不受影響。還有個坑是style scoped。有些同學想在 scoped 樣式里覆蓋編輯器的樣式比如改工具欄背景色結(jié)果發(fā)現(xiàn)不生效。原因是 wangEditor 的 DOM 結(jié)構(gòu)是動態(tài)生成的scoped 的屬性選擇器加不到那些節(jié)點上。要覆蓋樣式得用:deep()或者干脆寫一個不帶 scoped 的全局樣式塊專門管編輯器。3. 組件封裝從能跑到好用3.1 最小可用版本與 shallowRef 的生死線先上能跑起來的最小版本。新建src/components/RichEditor.vuetemplate div classrich-editor-wrapper :style{ border: 1px solid #dcdfe6 } Toolbar :editoreditorRef :defaultConfigtoolbarConfig :modemode classeditor-toolbar / Editor :defaultConfigeditorConfig :modemode :style{ height: height px, overflowY: hidden } v-modelvalueHtml onCreatedhandleCreated onChangehandleChange / /div /template script setup langts import wangeditor/editor/dist/css/style.css import { onBeforeUnmount, ref, shallowRef } from vue import { Editor, Toolbar } from wangeditor/editor-for-vue import type { IDomEditor, IEditorConfig, IToolbarConfig } from wangeditor/editor const props withDefaults( defineProps{ modelValue: string height?: number mode?: default | simple readonly?: boolean }(), { modelValue: , height: 400, mode: default, readonly: false } ) const emit defineEmits{ (e: update:modelValue, value: string): void }() const editorRef shallowRefIDomEditor() const valueHtml ref(props.modelValue) const mode props.mode const toolbarConfig: PartialIToolbarConfig { excludeKeys: [group-video, insertVideo] } const editorConfig: PartialIEditorConfig { placeholder: 請輸入內(nèi)容... } const handleCreated (editor: IDomEditor) { editorRef.value editor if (props.readonly) editor.disable() } const handleChange (editor: IDomEditor) { emit(update:modelValue, editor.getHtml()) } onBeforeUnmount(() { const editor editorRef.value if (editor) editor.destroy() }) /script這段代碼里最需要強調(diào)的是shallowRef。editorRef必須用shallowRef絕對不能用ref或者reactive。原因是 Vue3 的ref會對對象做深度響應(yīng)式代理而 wangEditor 內(nèi)部維護了大量 DOM 引用和循環(huán)引用被 Proxy 包一層之后編輯器在獲取選區(qū)、操作節(jié)點時會拿不到原始對象癥狀是光標亂跳、菜單點擊無響應(yīng)、插入圖片報錯。這個坑我在兩個項目里都踩過第二次才反應(yīng)過來是響應(yīng)式代理的問題。官方文檔里提了一句但很容易被忽略這里我必須再強調(diào)一次。3.2 工具欄裁剪與模式切換默認工具欄把所有菜單都堆出來視頻、公式、代碼塊全在對一個只發(fā)公告的后臺系統(tǒng)來說太冗余。toolbarConfig的excludeKeys負責排除insertKeys負責插入或調(diào)整順序。常用的菜單 key 我整理了一份方便你對著刪功能分類菜單 key建議標題/引用headerSelect, blockquote保留基礎(chǔ)格式bold, underline, italic, through, code保留顏色color, bgColor按需字號字色fontSize, fontFamily, lineHeight按需列表縮進bulletedList, numberedList, indent, delIndent保留對齊justifyLeft, justifyCenter, justifyRight, justifyJustify保留圖片uploadImage, insertImage保留 uploadImage鏈接insertLink保留表格insertTable按需代碼塊codeBlock技術(shù)類保留分割線divider保留撤銷重做undo, redo保留全屏fullScreen保留視頻group-video后臺一般刪掉mode有兩個取值default是完整模式simple是簡潔模式工具欄只留最核心的十幾個菜單視覺上更輕。選哪個取決于使用場景——面向運營的公告編輯器用simple面向內(nèi)容編輯的 CMS 用default。注意mode一般只在初始化時設(shè)置運行中動態(tài)切換會導(dǎo)致工具欄重建體驗上會有閃動不建議做成用戶可切換的選項。3.3 圖片上傳必須從 base64 切換到服務(wù)端不加任何配置時wangEditor 插入圖片走的是 base64 內(nèi)聯(lián)。寫幾篇文章沒問題但要是一篇長圖文里插了十幾張高清圖生成的 HTML 字符串會膨脹到幾兆存進數(shù)據(jù)庫字段會直接崩接口傳輸也會超時。所以圖片上傳必須改成服務(wù)端模式。配置位置在editorConfig.MENU_CONF[uploadImage]editorConfig.MENU_CONF[uploadImage] { server: /api/file/upload, fieldName: file, maxFileSize: 5 * 1024 * 1024, allowedFileTypes: [image/*], headers: { Authorization: Bearer getToken() }, customInsert(res, insertFn) { if (res.code ! 200) return insertFn(res.data.url, res.data.name, res.data.url) }, onFailed(file, res) { ElMessage.error(圖片上傳失敗 (res.message || 未知錯誤)) } }幾個要點拆開說。server是上傳地址走相對路徑讓 Vite 的代理去轉(zhuǎn)發(fā)避免開發(fā)環(huán)境跨域。fieldName要和后端接口約定的字段名一致后端用MultipartFile接的話通常就是file。maxFileSize單位是字節(jié)5MB 是我個人的經(jīng)驗值太大容易拖慢接口太小運營會抱怨截圖傳不上去。真正關(guān)鍵的是customInsert。默認情況下 wangEditor 會按自己的規(guī)則去解析返回數(shù)據(jù)它假設(shè)返回體里有個data.url字段。但你項目后端的返回結(jié)構(gòu)很可能不是這個形狀比如是{ code, msg, data: { fileUrl, fileName } }這時候默認解析就插不進去控制臺能看到 undefined。customInsert給了你完全接管解析的機會拿到res之后自己取出 URL調(diào)用insertFn(url, alt, href)插進去就行三個參數(shù)分別是圖片地址、替代文字、跳轉(zhuǎn)鏈接后兩個可以傳空字符串。如果你的上傳邏輯更復(fù)雜比如要先拿簽名再傳對象存儲用customUpload完全接管上傳過程editorConfig.MENU_CONF[uploadImage] { async customUpload(file, insertFn) { const formData new FormData() formData.append(file, file) const { data } await request.post(/api/upload, formData) insertFn(data.url, data.name, data.url) } }用一個/upload接口同時處理粘貼圖片和拖拽上傳是最省心的做法。3.4 v-model 綁定要繞開光標跳動這個雷直觀上大家會寫v-modelvalueHtml然后監(jiān)聽valueHtml的變化往外傳。這能跑但有個隱患編輯器內(nèi)部也會修改valueHtml如果你在外層又監(jiān)聽valueHtml并回寫父組件父組件再把值傳回來就形成了一個回環(huán)。光標位置在每次回寫后都會被重置到開頭用戶打字時感覺像有人在搶鍵盤。更穩(wěn)的做法是放棄v-model的自動雙向綁定改用onChange手動往外拋Editor :defaultConfigeditorConfig :modemode onCreatedhandleCreated onChangehandleChange /const handleChange (editor: IDomEditor) { emit(update:modelValue, editor.getHtml()) }父組件用v-model:modelValue接收即可。這里要理解一個原則——編輯器的內(nèi)容只有兩個出口初始化時的賦值和用戶編輯時的 onChange。除此之外任何時候去改編輯器的內(nèi)容都可能觸發(fā)重渲染和光標問題?；仫@歷史數(shù)據(jù)時直接把值放到初始化的valueHtml里之后就別再動它。4. 高頻故障排查與避坑清單4.1 編輯器實例為 null 和重復(fù)創(chuàng)建最常見的報錯是Cannot read properties of undefined (reading getHtml)原因通常是你在onCreated之前就去調(diào)用了editorRef.value的方法。editorRef是在handleCreated回調(diào)里才被賦值的而handleCreated在組件 mounted 之后才觸發(fā)。所以任何需要在編輯器就緒后做的事比如回填內(nèi)容、設(shè)置只讀、聚焦都得放在handleCreated里面或者用一個isReady標志位守著。第二個坑是重復(fù)創(chuàng)建。如果你在onMounted里手動createEditor同時又用了Editor組件編輯器會被創(chuàng)建兩次頁面上出現(xiàn)兩個工具欄或者內(nèi)容區(qū)閃爍。用官方組件就不要自己 create兩套東西二選一。還有一種情況是熱更新導(dǎo)致的重復(fù)實例開發(fā)時改代碼觸發(fā)熱更新舊實例沒銷毀干凈表現(xiàn)是切換頁面后舊內(nèi)容殘留。解決方式就是在onBeforeUnmount里老老實實editor.destroy()一行都不能省。editor.destroy()不只是清理 DOM它還會解綁所有事件監(jiān)聽、清空內(nèi)部定時器和選區(qū)緩存。漏掉它長時間運行的 SPA 會在連續(xù)打開關(guān)閉幾十個編輯器頁面后明顯卡頓內(nèi)存占用一路往上漲。4.2 樣式丟失與下拉菜單被遮擋工具欄渲染成純文字、菜單彈層藏在別的元素底下這兩類是樣式問題的高發(fā)區(qū)。第一個問題的解法前面說過補上style.css的引入。如果引入了還是不生效檢查一下項目里是不是有其他全局樣式把.w-e-*類的樣式覆蓋了尤其是那些用*選擇器重置 margin、padding 的老代碼會把編輯器的間距全干掉。下拉菜單被遮擋的根源是z-index。wangEditor 的彈層默認層級不算太高如果編輯器放在 Element Plus 的 Dialog 或者 Drawer 里而那個容器的層級更高菜單就會被壓住。常規(guī)解法是給外層容器和編輯器加個更大的z-index.rich-editor-wrapper { position: relative; z-index: 100; }如果彈層還是出不來可以用editorConfig里的scroll配置成false讓工具欄不吸頂某些布局下能繞開層級計算。我遇到過最麻煩的一次是編輯器在抽屜里抽屜本身有transform動畫導(dǎo)致position: fixed的彈層定位基準錯亂最后是把編輯器移到抽屜外的做法才徹底解決。所以選容器的時候盡量別把富文本編輯器塞進有動畫的浮層里。4.3 與 Element Plus 表單聯(lián)動的校驗問題后端管理系統(tǒng)基本都配 Element Plus編輯器要嵌進el-form-item里做必填校驗。這里有兩個細節(jié)。第一個是觸發(fā)時機。el-form-item的trigger要設(shè)成change然后編輯器的onChange里手動觸發(fā)校驗const handleChange (editor) { const html editor.getHtml() emit(update:modelValue, html) formRef.value?.validateField(content) }不手動觸發(fā)的話用戶輸入完內(nèi)容點提交校驗規(guī)則拿到的還是舊值會誤報內(nèi)容不能為空。第二個是內(nèi)容為空的判斷。用戶如果只敲了幾個空格或者插入了一張圖片editor.getHtml()返回的是pbr/p或者pimg ...//p直接判空字符串是不準的。穩(wěn)妥的做法是先剝標簽再判空const isEmptyHtml (html) { return html.replace(/[^]/g, ).replace(/nbsp;/g, ).trim() }這里要注意純圖片的內(nèi)容會被判成空但業(yè)務(wù)上往往認為有圖就算有內(nèi)容。所以更精細的規(guī)則可以判斷是否包含img標簽包含則視為非空。這種邊界判斷看著瑣碎卻直接決定上線后運營會不會天天來找你。4.4 只讀模式的幾種實現(xiàn)方式對比詳情頁展示歷史內(nèi)容時需要只讀商品預(yù)覽時需要只讀審核頁面也需要只讀。wangEditor v5 提供了幾種實現(xiàn)各有適用場景實現(xiàn)方式寫法優(yōu)點局限disable()editor.disable()靈活、可動態(tài)切換需拿實例時機要對defaultConfig 中設(shè) readOnly{ readOnly: true }初始化即生效無法運行中切換點擊后 blureditor.blur()簡單只擋焦點仍可編輯換純 HTML 渲染v-html不加載編輯器性能好無編輯器樣式能力我的選擇是需要保留編輯器樣式且隨時可能切回編輯態(tài)的場景用editor.disable()純展示、不打算再編輯的場景直接v-html渲染 HTML 字符串別加載整個編輯器內(nèi)核。這個區(qū)分很重要詳情頁如果也加載編輯器首屏體積白白多幾百 KB明明用戶只是想看文章。順帶說一個只讀相關(guān)的細節(jié)。editor.disable()生效后工具欄上的菜單會變灰但如果你希望工具欄整個隱藏用v-if控制Toolbar的渲染更干凈Toolbar v-if!readonly :editoreditorRef /另外要提醒切換只讀狀態(tài)后editor.getHtml()依然能正常調(diào)用別擔心 disable 之后拿不到內(nèi)容。4.5 常見問題速查表把上面這些整理成一張排查表出問題時對著找能省不少時間?，F(xiàn)象可能原因處理方式工具欄無樣式未引入 style.css補上全局樣式引入光標跳到開頭v-model 雙向回寫改用 onChange 單向拋出菜單點擊無效editorRef 用了 ref/reactive換成 shallowRef插入圖片報錯返回結(jié)構(gòu)不匹配配置 customInsert內(nèi)容拿不到在 onCreated 之前調(diào)用加 isReady 守位頁面切換后卡頓未調(diào)用 destroyonBeforeUnmount 中銷毀彈層被遮z-index 沖突調(diào)高層級或換容器內(nèi)容判空不準空標簽被判為有內(nèi)容剝標簽后再判空開發(fā)環(huán)境正常、線上白屏樣式 chunk 未跟隨檢查懶加載配置5. 進階內(nèi)容安全、框架集成與體積控制5.1 富文本的 XSS 防護不能省富文本編輯器最容易被忽視的安全問題就是 XSS。用戶尤其是后臺運營提交的 HTML 會原樣存儲如果詳情頁用v-html直接渲染攻擊者只要在編輯器里塞一段帶事件的標簽比如img srcx onerroralert(document.cookie)頁面一打開就可能被利用。雖然 wangEditor 編輯時過濾了一部分危險標簽但通過接口直接提交構(gòu)造好的 HTML編輯器的過濾根本不起作用。所以渲染側(cè)必須自己再過一道。我的做法是引入 DOMPurify在提交前和渲染前各清洗一次import DOMPurify from dompurify const safeHtml DOMPurify.sanitize(rawHtml, { ALLOWED_TAGS: [p, br, strong, em, u, h1, h2, h3, ul, ol, li, a, img, blockquote, table, tr, td, th], ALLOWED_ATTR: [href, src, alt, title, target, style, class] })白名單式過濾比黑名單靠譜得多只放行你明確需要的標簽和屬性其余一律去掉。注意style屬性本身也可能藏東西如果你對安全要求更高可以把 style 也去掉改用自定義類名控制樣式。這一步做起來有點煩但一旦內(nèi)容被注入事故等級完全不一樣值得花兩個小時配好。5.2 在若依、JeecgBoot 這類框架里集成的注意點很多同學是在若依RuoYi-Vue3或者 JeecgBoot 的 Vue3 版本里做二次開發(fā)這些框架本身有自己的請求封裝、全局樣式、權(quán)限指令直接塞編輯器會撞上幾個問題。第一個是請求實例?？蚣芾锿ǔ０?axios 封裝成了request或者service帶了統(tǒng)一的 token 注入、錯誤提示、結(jié)果解包。圖片上傳時最好復(fù)用這個實例而不是在新開一個 axios否則會出現(xiàn) token 沒帶上、上傳接口 401 的情況。如果用 wangEditor 的server配置走內(nèi)置上傳記得在headers里手動補上 Authorization或者直接用customUpload走項目自己的 request。第二個是全局樣式污染。若依那套后臺框架有一大堆覆蓋性的全局 CSS有時候會把編輯器里的列表符號干掉、把表格邊框清掉。排查方式是在編輯器的樣式后面追加一段更高優(yōu)先級的覆蓋.w-e-text-container ul { list-style: disc !important; } .w-e-text-container table { border-collapse: collapse; }第三個是 TypeScript 報錯。有些框架的 tsconfig 開了strict而wangeditor/editor的類型聲明在某些版本里不夠嚴謹會在editorRef.value的賦值處提示類型不匹配。簡單處理是用shallowRefIDomEditor | undefined()拿到實例后做一次非空斷言別為了消錯就把它改成any那等于把類型檢查全關(guān)了。5.3 體積優(yōu)化別讓編輯器拖慢首屏我把wangeditor/editor單獨打出來看過gzip 后大概兩百多 KB對于一個管理后臺來說不算夸張但如果它被打進首屏 chunk登錄頁的加載時間會明顯變長——用戶根本用不到編輯器憑什么要等他加載。解法是讓它按需進入路由 chunk。如果你用的是 Vite路由懶加載本身就做了這件事只要編輯器組件被用在懶加載路由里它就不會進首屏const routes [ { path: /article/edit, component: () import(/views/article/Edit.vue) } ]如果編輯器被用在一個不懶加載的公共布局里用defineAsyncComponent包一層const RichEditor defineAsyncComponent(() import(/components/RichEditor.vue))配合Suspense或者加載占位用戶體驗會好很多。還有一個容易被忽略的體積點——如果項目里只用到了基礎(chǔ)排版能力可以在toolbarConfig里把視頻、公式這些重插件的菜單去掉雖然不能直接搖掉這部分代碼但能避免加載相關(guān)資源。5.4 詳情頁只讀展示的取舍最后聊聊詳情頁。我見過太多項目在詳情頁也掛一個完整的編輯器組件只為展示一段富文本。這樣做有兩個代價一是多加載兩百多 KB 的編輯器內(nèi)核二是編輯器的 DOM 結(jié)構(gòu)比直接渲染 HTML 復(fù)雜得多列表長了之后頁面滾動會明顯發(fā)澀。如果詳情頁不需要任何編輯能力正確做法是只渲染 HTMLtemplate div classarticle-detail v-htmlsafeHtml/div /template然后在全局樣式里給富文本標簽補上基礎(chǔ)樣式讓它看起來和編輯器里一致。這里有個小技巧——把編輯器里用到的樣式抽一份到公共樣式文件里編輯態(tài)和展示態(tài)共用避免出現(xiàn)編輯時好看、展示時排版全亂的尷尬.article-detail img { max-width: 100%; height: auto; } .article-detail table { border-collapse: collapse; width: 100%; } .article-detail p { margin: 8px 0; line-height: 1.8; }如果詳情頁確實需要保留編輯器外殼比如用戶要看到和編輯時一樣的界面再退回用editor.disable()。判斷標準很簡單用戶在這頁會改內(nèi)容嗎會用編輯器不會用 v-html。6. 一些不那么官方但很有用的經(jīng)驗折騰了這么多項目有幾個體會想單獨拎出來說。第一個是關(guān)于版本鎖定。wangEditor v5 更新頻率不算高但每次小版本升級偶爾會帶出小問題比如菜單配置字段微調(diào)、樣式類名變化。生產(chǎn)項目里我建議把版本號寫死不要用^放開次版本號等新版本在測試環(huán)境跑過一輪再升。這個建議對所有第三方 UI 依賴都適用編輯器尤其敏感因為它的行為直接暴露給運營同學。第二個是關(guān)于封裝粒度的取舍。我一開始把編輯器封成了支持十幾項配置的萬能組件結(jié)果每次維護都要在一堆 props 里翻找。后來改成只暴露四個核心 propsmodelValue、height、readonly、mode圖片上傳配置通過一個uploadConfig對象整體傳入。這樣既保證了復(fù)用又不至于讓組件變成一個配置黑洞。組件這東西暴露的接口越少別人越愿意用。第三個是關(guān)于圖片上傳的聯(lián)調(diào)。開發(fā)環(huán)境和生產(chǎn)環(huán)境的圖片域名經(jīng)常不一樣配置里寫的server如果是絕對地址切環(huán)境就得改代碼。我現(xiàn)在的做法是統(tǒng)一走相對路徑讓 Nginx 或者 Vite 代理去轉(zhuǎn)發(fā)配置里一行都不用改。如果后端返回的圖片地址是完整的對象存儲域名那在customInsert里可以做一層轉(zhuǎn)換開發(fā)環(huán)境替換成代理前綴生產(chǎn)環(huán)境原樣輸出。第四個是關(guān)于內(nèi)容回顯的時機。從接口拿到歷史 HTML 之后不要急著往valueHtml里塞。因為編輯器初始化是異步的你在onMounted里賦值的時候組件可能還沒 ready內(nèi)容會被吃掉。穩(wěn)妥的流程是接口數(shù)據(jù)先存進一個變量在handleCreated里再賦給編輯器的初始內(nèi)容或者直接用editor.setHtml()主動設(shè)置。這一點我在兩個項目里都翻過車癥狀是編輯已有文章時內(nèi)容展示不出來排查半天才發(fā)現(xiàn)是時序問題。最后一個提醒關(guān)于測試。富文本編輯器的坑大多不是邏輯問題而是瀏覽器差異和時序問題所以別只在 Chrome 里點兩下了事。至少要在你要支持的瀏覽器里各走一遍完整流程新建內(nèi)容、插入圖片、加表格、保存、回顯、切只讀、再切回編輯。尤其是插入圖片后內(nèi)容能否正確保存是最容易在不同環(huán)境表現(xiàn)不一致的環(huán)節(jié)。我現(xiàn)在的習慣是給編輯器頁面寫一個兩分鐘的冒煙 checklist每次升級依賴或者改樣式前都過一遍花的時間很少省下的事故排查時間卻很多。