1. 为什么在 Vue 项目里选富文本编辑器会让人头疼
做过后台管理系统的朋友大概率都碰过这个场景：产品经理甩过来一个需求，说文章发布页要能加粗、能插图片、能调字号、能传视频，最好还能支持表格和代码块。你打开 npm 一搜，富文本编辑器一抓一大把，Quill、TinyMCE、CKEditor、wangEditor……每个都号称功能齐全，但真正集成到 Vue 项目里，尤其是 Vue 3 + Vite 的组合下，能让你少掉几根头发的其实没几个。
wangEditor 是我在多个中后台项目里反复用过的方案，原因很直接：它是国人写的，中文文档齐全，API 设计得比较符合国内开发者的直觉，开箱即用的 UI 也还算清爽。但"能用"和"用好"之间隔着一条坑坑洼洼的路。我自己在至少四个项目里集成过它，从 Vue 2 的 Options API 到 Vue 3 的 Composition API，从 webpack 到 Vite，从简单的文本编辑到自定义上传图片、粘贴 Word 内容、SSR 兼容，几乎每一轮都会踩到新的坑。
这篇内容就是把这些年攒下来的经验一次性倒出来。我会讲清楚 wangEditor 在 Vue 项目里的正确集成姿势、版本选择背后的逻辑、图片上传为什么总是失败、v-model 双向绑定怎么处理、编辑器实例什么时候该销毁、以及那些官方文档一笔带过但实际会卡你半天的细节。不管你是第一次接富文本需求，还是已经用过但被某些诡异 bug 折磨过，应该都能从里面找到能直接抄的代码和能避开的雷。
需要先说明一点：wangEditor 目前主流是 v5 版本，v4 和 v5 的 API 差异非常大，网上很多老教程还是 v4 的写法，直接抄过来会报一堆错。所以下面所有内容默认以 v5 为准，涉及 v4 差异的地方我会单独标出来。
2. 版本选择与依赖安装：别一上来就装错
2.1 v4 和 v5 的核心差异到底在哪
很多人踩的第一个坑不是代码写错，而是版本装错。wangEditor v4 的包名是wangeditor，v5 改成了@wangeditor/editor加@wangeditor/editor-for-vue。这两个是完全不同的东西，API 也不兼容。
v4 时代，编辑器的创建方式是new E('#editor')，配置项挂在editor.config上，菜单配置用editor.create()。v5 改成了工厂函数createEditor和createToolbar，配置通过editorConfig和toolbarConfig传入，而且官方专门为 Vue 封装了@wangeditor/editor-for-vue组件包。这个组件包又分 Vue 2 和 Vue 3 两个版本，装错了同样跑不起来。
我整理了一张对照表，方便你一眼看清该装哪个：
| 项目环境 | 需要安装的包 | 组件引入方式 |
|---|---|---|
| Vue 2 + wangEditor v5 | @wangeditor/editor@wangeditor/editor-for-vue | import { Editor, Toolbar } from '@wangeditor/editor-for-vue' |
| Vue 3 + wangEditor v5 | @wangeditor/editor@wangeditor/editor-for-vue@next | import { Editor, Toolbar } from '@wangeditor/editor-for-vue' |
| Vue 2 + wangEditor v4 | wangeditor | import E from 'wangeditor' |
注意 Vue 3 项目里@wangeditor/editor-for-vue必须装@next标签的版本，也就是 5.x 的 beta 系列。如果你直接npm install @wangeditor/editor-for-vue，默认拉到的可能是给 Vue 2 用的版本，然后在 Vue 3 里就会报Cannot read property 'component' of undefined之类的错误。这个坑我见过太多人中招。
2.2 安装命令与版本锁定
实际安装命令长这样：
# Vue 3 项目 npm install @wangeditor/editor npm install @wangeditor/editor-for-vue@next # Vue 2 项目 npm install @wangeditor/editor npm install @wangeditor/editor-for-vue装完之后建议去package.json里确认一下版本号。@wangeditor/editor应该是 5.x，@wangeditor/editor-for-vue在 Vue 3 下应该是 5.1.x 的 beta 版本。如果发现editor-for-vue装成了 1.x，那基本可以确定是装错了。
提示：生产项目里建议把版本号锁死，不要用
^或~。wangEditor 的 beta 版本之间偶尔会有 breaking change，某次小版本升级导致工具栏渲染异常的情况我真实遇到过。
2.3 样式文件的引入时机
v5 的样式需要单独引入，而且必须在编辑器组件挂载之前引入，否则会出现工具栏图标错位、下拉菜单样式丢失的问题。标准做法是在入口文件或者使用编辑器的组件里引入：
import '@wangeditor/editor/dist/css/style.css'如果你用的是按需加载或者路由懒加载，把样式放在使用编辑器的那个页面组件里引入也没问题，但一定要保证它在<Editor>组件渲染之前执行。我试过放在onMounted里动态 import，结果第一次打开页面时工具栏是裸的，刷新一下才正常，这就是样式加载时序的问题。
3. 在 Vue 3 里把编辑器跑起来的最小闭环
3.1 组件封装的基本结构
直接在每个页面里写编辑器逻辑不是不行，但一旦有多个页面需要富文本，复制粘贴就会变成维护噩梦。我的习惯是封装一个RichEditor.vue组件，对外暴露v-model，内部处理编辑器的创建、销毁和数据同步。
先看一个能跑起来的最小实现：
<template> <div class="rich-editor"> <Toolbar :editor="editorRef" :defaultConfig="toolbarConfig" mode="default" /> <Editor :defaultConfig="editorConfig" :modelValue="modelValue" mode="default" @onCreated="handleCreated" @onChange="handleChange" /> </div> </template> <script setup> import { shallowRef, onBeforeUnmount } from 'vue' import { Editor, Toolbar } from '@wangeditor/editor-for-vue' import '@wangeditor/editor/dist/css/style.css' const props = defineProps({ modelValue: { type: String, default: '' } }) const emit = defineEmits(['update:modelValue']) const editorRef = shallowRef(null) const toolbarConfig = {} const editorConfig = { placeholder: '请输入内容...' } const handleCreated = (editor) => { editorRef.value = editor } const handleChange = (editor) => { emit('update:modelValue', editor.getHtml()) } onBeforeUnmount(() => { const editor = editorRef.value if (editor) editor.destroy() }) </script>这段代码里有几个关键点值得展开说。
第一，editorRef必须用shallowRef而不是ref。因为编辑器实例是一个庞大的对象，内部有大量循环引用和 DOM 节点，如果用ref包裹，Vue 会尝试对它做深度响应式代理，轻则性能暴跌，重则直接栈溢出报错。这是官方明确强调的，但很多人不看文档就写ref，然后遇到页面卡死。
第二，onBeforeUnmount里必须调用editor.destroy()。编辑器在创建时会绑定一堆全局事件监听、创建 DOM 节点、注册 MutationObserver。如果不销毁，组件切换几次之后内存就会明显上涨，而且可能出现多个编辑器实例同时响应键盘事件的情况。我见过一个后台项目，用户来回切换五个 tab 之后输入框开始乱跳，最后定位就是没销毁编辑器。
3.2 v-model 双向绑定的正确姿势
上面的代码里，数据回传是通过@onChange里emit('update:modelValue', editor.getHtml())实现的。但这里有个细节：Editor组件的modelValue属性和@onChange事件配合使用时，如果父组件传进来的值在编辑器内部被修改，可能会触发循环更新。
更稳妥的做法是只在onChange里往外发，不依赖modelValue做实时同步。也就是说，modelValue只用于初始化内容，后续所有变更都通过onChange往外抛。如果你确实需要外部修改内容后编辑器同步更新，那要用editor.setHtml()手动设置，而不是改modelValue。
// 外部需要更新编辑器内容时 const updateContent = (html) => { if (editorRef.value) { editorRef.value.setHtml(html) } }另外，getHtml()拿到的是带标签的 HTML 字符串，如果你需要纯文本，用editor.getText()。需要 JSON 格式的用editor.children。这几个方法在提交表单、做内容校验、存草稿时各有用途，别只会用一个getHtml()。
3.3 工具栏配置的常见定制
默认工具栏会显示所有菜单，但实际项目里往往只需要一部分。toolbarConfig支持excludeKeys和insertKeys两种方式：
const toolbarConfig = { excludeKeys: [ 'group-video', // 去掉视频 'fullScreen', // 去掉全屏 'emotion', // 去掉表情 'insertTable', // 去掉表格 ] }如果你想把某个菜单挪到特定位置，用insertKeys配合index来插入。不过说实话，wangEditor 的工具栏布局定制能力有限，它不像某些编辑器那样支持完全自定义分组。如果产品对工具栏排列有严格要求，可能得考虑用toolbarConfig隐藏默认工具栏，然后自己用editor.getMenuConfig()和editor.insertMenu()手动拼一个。这个工作量不小，非必要不建议。
4. 图片上传：十个人里有八个卡在这里
4.1 默认上传为什么必然失败
wangEditor 默认的图片上传是把图片转成 base64 直接塞进 HTML 里。这个设计在 demo 阶段很方便，但放到真实项目里就是灾难：一张 2MB 的图转成 base64 之后体积膨胀约 33%，如果一篇文章插十张图，HTML 字符串能到几十 MB，存数据库直接爆字段长度，传给后端接口也可能触发请求体大小限制。
所以真实项目必须配置自定义上传。配置项在editorConfig.MENU_CONF['uploadImage']里：
const editorConfig = { placeholder: '请输入内容...', MENU_CONF: { uploadImage: { server: '/api/upload/image', fieldName: 'file', maxFileSize: 5 * 1024 * 1024, allowedFileTypes: ['image/*'], headers: { Authorization: 'Bearer xxx' }, customInsert(res, insertFn) { // res 是服务端返回的数据 insertFn(res.data.url, res.data.alt, res.data.href) } } } }这里有几个高频踩坑点。
4.2 server 路径与跨域问题
server填的是上传接口地址。如果你填的是相对路径/api/upload/image，那请求会打到当前页面的域名下。开发环境里通常有代理，问题不大；但生产环境如果前端和后端不同域，就会遇到跨域。这时候要么后端配 CORS，要么前端把server写成完整地址，同时确保后端允许该来源。
还有一种情况是接口需要携带 token，但 wangEditor 默认不会带上你的 axios 拦截器里配置的 header。所以必须在headers里手动写死，或者用customUpload完全接管上传逻辑。
4.3 customUpload 完全自定义上传
当默认的server模式满足不了需求时（比如要用项目统一的 request 封装、要加签名、要分片），就用customUpload：
MENU_CONF: { uploadImage: { async customUpload(file, insertFn) { const formData = new FormData() formData.append('file', file) try { const res = await yourRequest.post('/upload', formData) insertFn(res.url, res.name, res.url) } catch (err) { console.error('上传失败', err) } } } }insertFn接收三个参数：图片地址、alt 文本、跳转链接。第三个参数不传也行，但传了之后图片会带超链接。注意insertFn必须在异步完成后调用，而且只能调用一次，重复调用会插入多张图。
4.4 上传失败时的用户反馈
默认情况下上传失败是静默的，用户点了上传按钮，转了一圈，什么都没发生。这个体验很糟糕。wangEditor 提供了onFailed回调：
uploadImage: { server: '/api/upload', onFailed(file, res) { console.error('上传失败', file.name, res) // 这里可以调用项目的 message 组件提示用户 }, onSuccess(file, res) { console.log('上传成功', file.name) } }我一般会在onFailed里根据res的状态码给出具体提示，比如 413 就提示"图片太大"，401 就提示"登录已过期"。这比统一弹一个"上传失败"有用得多。
注意：
onFailed和customInsert不要同时用。如果你用了customUpload，那成功和失败都要自己在回调里处理，onFailed不会触发。
5. 那些官方文档没写清楚的坑
5.1 编辑器在弹窗或 tab 切换后高度异常
这是个非常经典的问题。当编辑器被放在el-dialog、el-tabs或者v-show控制的容器里时，初始渲染时容器可能是display: none或者高度为 0，导致编辑器计算出来的高度不对，表现为工具栏和内容区挤在一起，或者内容区只有一条线。
根本原因是 wangEditor 在创建时会读取容器的实际尺寸来设置内部布局。如果创建时容器不可见，读到的就是 0。
解决方案有两个。一是用v-if代替v-show，确保编辑器只在容器可见时才创建。二是如果必须用v-show，那在容器显示后手动调用editor.blur()再editor.focus()触发重排，或者直接editor.destroy()后重新创建。我一般推荐第一种，简单可靠。
5.2 粘贴内容带了一堆内联样式
从 Word 或者某些网页复制内容粘贴进编辑器，会带进来大量style="font-family: 宋体; font-size: 12pt; ..."这样的内联样式，导致文章样式混乱。wangEditor 提供了粘贴过滤配置：
editorConfig = { hoverbarKeys: {}, MENU_CONF: {}, pasteFilterStyle: true, // 过滤粘贴的样式 pasteIgnoreImg: false, // 是否忽略粘贴的图片 }pasteFilterStyle设为true会去掉大部分内联样式，但有时候过滤得太狠，连合理的加粗、斜体也一起干掉了。如果产品对粘贴格式有精细要求，可以用customPaste完全接管：
editorConfig.customPaste = (editor, event) => { const html = event.clipboardData.getData('text/html') const text = event.clipboardData.getData('text/plain') // 自己处理 html 和 text，然后插入 editor.insertText(text) return false // 返回 false 表示阻止默认粘贴行为 }5.3 SSR 场景下的 window is not defined
如果项目用了 Nuxt 或者自己做了 SSR，直接在服务端渲染 wangEditor 会报window is not defined，因为编辑器内部大量依赖 DOM API。解决办法是用<ClientOnly>包裹，或者用动态 import 在客户端加载：
const Editor = defineAsyncComponent(() => import('@wangeditor/editor-for-vue').then(m => m.Editor) )同时样式引入也要放到客户端。这个坑在纯 SPA 项目里遇不到，但一旦上了 SSR 就必踩。
5.4 编辑器内容为空时的判断
表单提交时经常需要校验富文本是否为空。但editor.getHtml()在空内容时返回的不是空字符串，而是<p><br></p>。所以不能简单用if (!html)判断，得先去掉标签：
const isEmpty = (html) => { const text = html.replace(/<[^>]+>/g, '').trim() return text.length === 0 }或者直接用editor.getText().trim() === ''。后者更准确，因为它会忽略纯图片内容——如果你的业务允许"只发图不写字"，那用getText判断就会误判为空，这时候得结合editor.children里是否有 image 节点来判断。
6. 性能与体积优化：别让编辑器拖慢首屏
6.1 按需加载编辑器
wangEditor 的完整包体积不小，gzip 之后大概在 200KB 左右。如果它只在文章编辑页用到，就没必要打进首屏 chunk。用路由懒加载配合动态 import 是最简单的优化：
const RichEditor = defineAsyncComponent(() => import('@/components/RichEditor.vue'))这样编辑器相关的代码只会在进入编辑页时才下载。配合 Vite 的代码分割，效果很明显。我在一个项目里做过对比，把编辑器从首屏剥离之后，首屏 JS 体积减少了约 180KB，Lighthouse 的 TTI 指标提升了将近 1 秒。
6.2 大文档的编辑卡顿
当文章内容特别长（比如超过 5000 字，或者包含几十张图片）时，编辑器的输入会变得卡顿。这是因为每次输入都会触发全量的 DOM diff 和重新渲染。缓解办法有几个：
一是关闭实时字数统计，如果不需要的话。二是把editorConfig里的scroll设为false，让编辑器不自己管理滚动，交给外层容器。三是对于超长文档，考虑分页编辑或者用 Markdown 编辑器替代。
不过说实话，wangEditor 在长文档场景下的表现已经算同级别里不错的了。如果卡顿严重到影响使用，那可能得换方案，比如用 CodeMirror 做 Markdown 编辑，或者上 ProseMirror 自己搭。
6.3 图片懒加载与 CDN
编辑器里的图片默认是直接<img src="...">，如果一篇文章有几十张图，打开页面时会同时发起大量请求。可以在customInsert里给图片加上loading="lazy"属性：
customInsert(res, insertFn) { insertFn(res.url, res.alt, res.href) // 插入后手动给图片加懒加载 nextTick(() => { const imgs = editorRef.value.getElemsByType('image') imgs.forEach(img => img.setAttribute('loading', 'lazy')) }) }更彻底的做法是后端返回的图片地址就走 CDN，并且支持按尺寸裁剪。这样既减轻了源站压力，也加快了加载速度。
7. 我踩过的几个真实坑与排查过程
7.1 编辑器内容在切换路由后丢失
有个项目里，用户在编辑页写了半天，点了一下侧边栏的另一个菜单再回来，内容全没了。排查发现是路由切换时组件被销毁，编辑器实例也跟着销毁，但内容没有及时保存到父组件或者 store 里。
根因在于onChange的触发是有延迟的，用户输入后如果立刻点路由跳转，最后一次变更可能还没 emit 出去。解决办法是在onBeforeUnmount里强制同步一次内容：
onBeforeUnmount(() => { if (editorRef.value) { emit('update:modelValue', editorRef.value.getHtml()) editorRef.value.destroy() } })同时配合路由守卫做草稿自动保存，双保险。
7.2 上传接口返回 200 但图片不显示
这个坑排查了很久。后端接口返回的是{ code: 0, data: { url: '...' } }，但 wangEditor 默认期望的响应格式是{ errno: 0, data: { url: '...' } }。字段名对不上，编辑器就认为上传失败，但 HTTP 状态码是 200，所以控制台也不报错。
解决方式是在customInsert里自己解析响应，或者用customUpload完全接管。如果坚持用server模式，那就得让后端按 wangEditor 的格式返回，或者在前端加一层适配。我建议直接用customUpload，省得跟后端扯皮。
7.3 多个编辑器实例导致菜单冲突
一个页面里放了两个编辑器（比如一个编辑正文，一个编辑摘要），结果点第一个的加粗按钮，第二个的内容也变了。这是因为两个编辑器实例共享了某些全局状态。
wangEditor v5 理论上支持多实例，但需要确保每个实例有独立的editorRef和独立的配置对象。如果editorConfig是同一个对象引用，就可能出问题。解决办法是每个编辑器用工厂函数返回独立的配置：
const createEditorConfig = () => ({ placeholder: '请输入...', MENU_CONF: { /* ... */ } })另外，工具栏和编辑器必须一一对应，不能一个工具栏控制两个编辑器。
7.4 移动端键盘弹起后光标错位
在移动端浏览器里，点击编辑器唤起软键盘后，光标位置经常跑偏，输入的文字出现在错误的位置。这是移动端富文本编辑的通病，wangEditor 也没完全解决。
缓解办法是给编辑器容器设置min-height，并且在focus事件里手动滚动到可视区域：
editorConfig.onFocus = (editor) => { setTimeout(() => { editor.getEditableContainer().scrollIntoView({ behavior: 'smooth', block: 'center' }) }, 300) }如果产品对移动端编辑体验要求高，老实说 wangEditor 不是最优选，可能得考虑专门为移动端优化的方案。但如果只是"能用就行"，上面这招能缓解大部分问题。
8. 写在最后的一点个人习惯
用了这么久 wangEditor，我最大的体会是：不要把它当成一个黑盒组件，遇到问题先去翻它的源码。它的源码结构其实挺清晰的，@wangeditor/editor里核心就是createEditor和各个 module，@wangeditor/editor-for-vue只是薄薄一层封装。很多看似诡异的问题，读一遍源码就能找到原因。
另外，每次集成新项目，我都会先写一个最小的 demo 页面，把编辑器跑通、图片上传调通、v-model 验证通过，再往业务页面里搬。这样能把环境问题和业务代码问题隔离开，排查起来快很多。直接往复杂页面里塞编辑器，一旦出问题，你分不清是编辑器本身的坑还是页面逻辑的锅。
最后提醒一句：wangEditor 的 beta 版本更新比较频繁，升级前一定先看 changelog，并且在测试环境跑一遍核心流程。我有一次手贱升了个小版本，结果自定义菜单的图标全没了，回滚才恢复。锁版本、看日志、先测试，这三件事能帮你省下不少加班时间。
