md-editor-v3 入门：Vue 3 Markdown 编辑器

给后台加一个「能写文章」的输入框：左边编辑、右边预览、带工具栏和图片上传——md-editor-v3 一个组件搞定。

它是什么

md-editor-v3 是 Vue 3 生态最完整的 Markdown 编辑器组件，本站写文章页用的就是它。能力清单：

分屏实时预览：左侧编辑 Markdown 源码，右侧同步渲染
工具栏：标题、加粗、列表、代码块、表格、链接等常用操作一键插入
图片上传：贴图/选图后回调你的上传逻辑
扩展语法：Mermaid 图表、KaTeX 数学公式、流程图、甘特图
主题：亮/暗主题，预览样式可自定义

pnpm add md-editor-v3

基本用法

<script setup>
import { ref } from 'vue';
import { MdEditor } from 'md-editor-v3';
import 'md-editor-v3/lib/style.css';

const content = ref('# 开始写作\n\n这里是正文……');
</script>

<template>
  <MdEditor v-model="content" :style="{ height: '600px' }" />
</template>

v-model 绑定 Markdown 字符串——编辑器不关心你的存储和提交逻辑，它只负责「人机交互」，内容就是那个字符串。保存草稿、发布文章，拿到 content.value 走你自己的接口。

图片上传：对接 MinIO/OSS

编辑器内置的图片按钮默认只做「插入本地文件名」，真实项目要接管上传——通过 onUploadImg 回调：

<MdEditor
  v-model="content"
  :on-upload-img="onUploadImg"
/>

<script setup>
async function onUploadImg(files, callback) {
  // files 是 File 数组（支持一次贴多张图）
  const urls = await Promise.all(
    files.map((file) => uploadToMinio(file))   // 你的上传接口
  );
  // 把返回的 URL 列表交给编辑器，它会自动插入 Markdown
  callback(urls);
}
</script>

这个设计的巧妙处：上传逻辑完全解耦。你对接 MinIO、七牛、后端代理都行，编辑器只要求「给我一批 URL，我负责插进正文」。本站走的就是后端统一上传接口，图片落到 MinIO 再回填 URL。

常用配置速查

<MdEditor
  v-model="content"
  theme="dark"                    // 编辑器主题
  previewTheme="github"           // 预览区样式风格
  :toolbars="toolbars"            // 自定义工具栏按钮
  :footers="[]"                   // 去掉底部状态栏
  placeholder="开始创作……"
/>

// 定制工具栏：只留高频操作
const toolbars = [
  'bold', 'italic', 'strikeThrough', '-',
  'title', 'quote', 'unorderedList', 'orderedList', '-',
  'code', 'codeRow', 'image', 'table', '-',
  'preview',      // 预览开关
];

只需要纯预览（不编辑）的场景用 MdPreview 组件——轻量得多，没有工具栏和编辑区，适合展示已保存的 Markdown。

与后端渲染的一致性问题

一个容易忽略的坑：编辑器预览的渲染结果，和后端最终渲染的文章页面，可能不一致。两边如果用不同的 Markdown 解析器，某些扩展语法（任务列表、脚注、特定代码块样式）会呈现差异。

本站的做法是后端用 commonmark（带 GFM 表格、标题锚点等扩展）渲染正文，编辑器预览仅作为「写作时的近似参考」。发布后以前端最终渲染为准。这不完美但务实——要求两边逐像素一致的成本远超收益，只要核心语法（标题、列表、代码、表格、图片）表现一致即可。

性能与体验细节

自动保存配合 v-model 天然好做：

watch(content, debounce((v) => {
  localStorage.setItem('draft', v);      // 本地草稿兜底
}, 1000));

内容很长时（万字文章）编辑器内部有分块渲染优化，但工具栏操作仍可能略卡，这是所有「源码编辑 + 实时预览」模式的共性；关闭实时预览（点工具栏的预览开关）可立刻恢复流畅。

XSS 防御：Markdown 渲染是 HTML 注入的高危区（用户可写 <script>）。md-editor-v3 内部做了 sanitize，但如果你在自己的展示页另用渲染器，务必配置白名单过滤——这是安全底线不是可选项。

小结

md-editor-v3 的定位是「Vue 3 里最省事的完整编辑器」：v-model 接内容、onUploadImg 接上传、主题配置接视觉，一小时内就能做出生产级的写作页。用的时候记住两件事：上传逻辑是你自己的事，渲染一致性以服务端为准。