在网页里嵌入三种模式的 Markdown 编辑器（Vditor）

Markdown 在论坛、博客、笔记和后台管理系统里用得越来越普遍，只要产品里有「写点东西」的地方，就要选一个编辑器组件塞进去。可选项的取舍很分明：一部分只做分屏预览，编辑区和预览区上下分开；一部分同时支持所见即所得与分屏，但所见即所得模式下 Markdown 语法的排版还原并不完整；至于 Typora 那种边写边渲染的即时体验，能集成的组件里几乎没有。

Vditor 是用 TypeScript 写的浏览器端 Markdown 编辑器，支持所见即所得、即时渲染、分屏预览三种模式，输入 Markdown 输出 HTML，供嵌入网页使用。谁需要它：要给自己网站或后台加一个 Markdown 输入框的前端开发者，以及需要在不熟悉 Markdown 的普通用户和熟悉 Markdown 的写作用户之间做兼容的产品团队。

这三种模式各自对应一类使用场景。分屏预览适合大屏下逐段校对排版；所见即所得对没接触过 Markdown 语法的人友好，写过 Markdown 的人也能直接上手；即时渲染把语法标记就地变成排版效果，写的时候注意力留在内容上。仓库地址是 https://github.com/Vanessa219/vditor，采用 MIT 许可证，主要语言 TypeScript（占比 75.8%），当前 11357 star、1088 fork、76 watcher，开放 Issue 96 个，最近一次提交在 2026-10-02。

它不做什么

Vditor 是前端组件，仓库里不带后端。图片上传、录音发布这一类动作，README 的说明是「通过指定接口上传到服务器」，也就是说上传接口要你自己写，组件只负责发起请求、显示进度和处理跨域。

资源默认从 CDN 加载。参数 cdn 的默认值是 https://unpkg.com/vditor@${VDITOR_VERSION}，纯内网或离线环境需要改这个地址，把资源放到自己的服务器上。

它也不是一个开箱即用的完整应用。仓库里提供 demo 与示例源码，但不含账号体系、权限、内容存储，这些属于你集成时自己要补的部分。

用之前先准备好什么

走 npm 路线的话，本地要有能跑 npm install 的环境；走 HTML 直引路线的话，页面上要能访问 unpkg 或你自建的 CDN。

需要准备一个挂载点。new Vditor(id, ...) 的第一个参数可以传元素的 id，也可以直接传 HTMLElement 本身。传 HTMLElement 时有个硬性前提：必须设置 options.cache.id，或者把 options.cache.enable 设为 false。

模式要先想清楚。默认是 ir，如果你的用户群完全不认识 Markdown，初始化时把 mode 改成 wysiwyg 更合适。

如果要接入图片上传，先把服务端接口和跨域头准备好，组件本身支持 CORS 跨域上传，但接口不存在的话这条链路是空的。

主要功能

三种编辑模式。初始化参数 mode 可选 sv（分屏预览）、ir（即时渲染）、wysiwyg（所见即所得），默认值 ir。同一套内容可以在三种模式间切换，不用重写业务代码。

语法与图表渲染。实现 CommonMark 与 GFM 规范，覆盖表格、任务列表、删除线、自动链接、XSS 过滤；扩展语法包含脚注、ToC、自定义标题 ID、YAML Front Matter。图表方面，流程图、时序图、甘特图通过 Mermaid 支持，另有 Graphviz、通过 WaveDrom 的数字波形图、通过 ECharts 的折线图与饼图与脑图、通过 abc.js 的五线谱，数学公式由 MathJax 和 KaTeX 支持。

可自定义的工具栏。工具栏包含 36 项以上操作，每一项的快捷键、提示文字、提示位置、图标、点击事件、类名和子工具栏都可以改。初始化后还能通过 customWysiwygToolbar(type, element) 自定义 wysiwyg 模式下的工具栏，移动端对应 customWysiwygMobileToolbar。

上传与粘贴。支持拖拽上传和剪贴板粘贴上传，显示实时上传进度，支持 CORS 跨域。粘贴 HTML 会自动转成 Markdown；粘贴内容里带有外链图片时，可以指定接口把图片上传到服务器。上传相关回调有 options.upload.xhr 和 options.upload.cancel。

主题体系。编辑器主题内置 classic、dark 两套；内容主题内置 ant-design、light、dark、wechat 四套；代码块主题内置 github 等 36 套。运行期可以调 setTheme、setContentTheme、setCodeTheme 切换。

导出与外部平台适配。提供导出功能，以及复制到微信公众号、复制到知乎的能力，图片支持懒加载。

中文语境优化。中西文之间自动插入空格，修正术语拼写，把中文后面跟着的英文逗号句号替换成中文标点。这些开关大多可以单独配置是否启用。

多语言与辅助功能。内置 de_DE、en_US、es_ES、fr_FR、ja_JP、ko_KR、pt_BR、ru_RU、sv_SE、vi_VN、zh_CN、zh_TW，默认 zh_CN。另有大纲、字符计数、打字机模式、实时保存、语音阅读与录音支持。

安装与最短示例

npm 方式先装依赖：

npm install vditor --save

然后在代码里引入并初始化：

import Vditor from 'vditor'
import "vditor/src/assets/less/index"

const vditor = new Vditor(id, {options...})

不想走构建工具的话，直接在 HTML 里引 CSS 和 JS：

<link rel="stylesheet" href="https://unpkg.com/vditor/dist/index.css" />
<script src="https://unpkg.com/vditor/dist/index.min.js"></script>

初始化时至少把 id 和 mode 定下来，其余走默认值也能出一块可用的编辑区。仓库里给了完整示例：demo/index.js 是编辑器用法，demo/render.js 是纯渲染用法。

关键参数

尺寸类有 height（默认 auto）、minHeight、width（支持百分比）。placeholder 是输入区为空时的提示，默认空字符串。

外观类有 theme（classic 或 dark，默认 classic）、icon（ant 或 material，默认 ant）、lang（默认 zh_CN）、typewriterMode（打字机模式，默认 false）。

行为类有 value（初始化值，默认空）、undoDelay（历史记录间隔）、debugger（是否显示日志，默认 false）、tab（tab 键插入的字符串）、cdn（自建资源地址）。

回调类有 after（异步渲染完成后触发）、input、focus、blur、keydown、esc、ctrlEnter、select、unSelect。扩展类有 customRenders，接受 {language, render} 结构的数组，用来挂自定义渲染器。

结果在哪里看

编辑器渲染在你传入的那个元素里，挂载完成会触发 after 回调，这是判断初始化是否结束的信号。debugger 打开后终端或浏览器控制台会输出日志。

Markdown 渲染出来的 HTML 要按预期显示，承载它的元素必须加 class="vditor-reset"，否则内容主题不生效。内容主题由 options.preview.theme 或 IPreviewOptions.theme 指定。

需要拿到 HTML 的场景，仓库提供 md2html 接口，签名为 md2html(mdText: string, options?: IPreviewOptions): Promise<string>，返回的是 Promise，不是同步结果。

实际使用中的坑

有一类问题在仓库里仍然挂着。wysiwyg 与 ir 模式下代码块的编辑体验，在 Issue 里被描述为「非常头疼」：上千行的代码块进入编辑态时会重新生成位置，原先定位到的行号要重新找，行号也无法正常显示。这条 Issue 有 18 条评论，状态为待解决。

自动聚焦曾经是个争议点。论坛底部留言这类场景里，用户进页面并不希望光标直接跳进编辑框，Issues 里有 33 条评论在讨论这件事，后来加的 autofocus 参数就是用来控制是否自动聚焦的，这条已经解决。如果你的页面有类似需求，先确认这个参数。

框架集成上踩过资源加载的坑。Nuxt3 项目里出现过 Lute is not defined，现象是 Network 面板显示 lute.min.js 已经加载，但运行时仍报未定义，相关 Issue 16 条评论，已解决。同类还有用 method.min 的 preview 渲染数学公式时频繁出现 katex is not defined，出错时不会请求字体文件，正常时会请求，这条也已解决。这两类问题都指向 CDN 资源的加载时序，自建 CDN 时要留意。

移动端调用工具栏方法是另一个高频诉求，58 条评论，要求提供类似 boldSelect 的接口让移动端键盘顶部的按钮能直接输入 Markdown，已解决。移动端体验本身也有过一轮优化，37 条评论。

横向对照

下表里的 tiptap 和 canvas-editor 与 Vditor 同属可集成的编辑器组件，放在一起看的是定位差异，不是谁更强。

如果你的核心诉求是「Markdown 写作体验」，Vditor 的三种模式和即时的公式、图表渲染是它相对完整的地方。反过来说，如果你要做的是一个结构高度定制的块编辑器，需要自己控制每个节点的渲染与交互，tiptap 那种 headless 的路子更合适——Vditor 把工具栏、主题、预览样式都替你决定了，改起来要顺着它的类名和 less 变量走，自由度不如从零搭。canvas-editor 处理的是另一件事，它以 Canvas/SVG 承载排版，和 Markdown 编辑器不构成直接替代关系，列在这里只是给同类选型的人一个参照。

适合谁

适合正在给自有产品加 Markdown 输入能力的前端开发者，尤其是需要在一个编辑器里兼容「不懂 Markdown 的普通用户」和「熟悉语法的写作用户」的场景；也适合需要公式、流程图、甘特图、五线谱这类扩展语法开箱可用的团队，以及面向中文用户、在意标点和中西文混排细节的产品。它对移动端有专门处理，做社区、论坛、博客后台的人用得上。

不适合想要一个完整写作应用的人——仓库里没有账号、存储和后端，这些要自己配。也不适合只需要一个极简文本域的场景，引入它意味着同时接受它的主题体系、CDN 依赖和一整套配置项，投入产出不划算。如果产品完全不需要 Markdown，只想要一个块结构的富文本编辑器，也应该先去评估 tiptap 这类方案。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.9 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。