如果你经常要写技术文档、做汇报PPT或者给论文配图大概率经历过这种崩溃流程图改了三个版本Visio 里拖好的框线全乱用画图工具画时序图调了半天对齐领导说“逻辑再改一下”最气的是E-R图画了一下午第二天要改一个字段又得重新拉线。我自己就是从这套流程里爬出来的后来换成了 Mermaid再配合官方免费的 Mermaid Live Editor才算彻底把这摊事理顺。你不需要安装任何桌面软件打开浏览器就能画图不需要拖动任何框线用类似写代码的方式描述图表结构改图就是改文字。这篇就围绕这个在线图表编辑器展开从 Mermaid 核心语法讲到“学校教学管理E-R图”完整案例再把 Typora 升级、macOS 打开这类高频问题一并说清楚。里面所有姿势都是我反复试过、踩过坑之后沉淀下来的直接照着做就行。1. 为什么选 Mermaid Live Editor在线编辑器的定位与优势1.1 绘图这件事为什么我最后留在了 Mermaid先说个背景。市面上画图工具并不少桌面端有 Visio、draw.io在线端有 ProcessOn、Excalidraw笔记软件里还有各种白板插件。我早期是 Visio 用户那时候画一张跨部门流程图光是对齐、调箭头、改配色就能耗掉半天。后来换到 draw.io虽然免费但每次改图都要重新打开文件、重新找图层版本管理基本靠文件名加日期混乱程度不亚于电脑桌面。真正让我转到 Mermaid 的契机是发现它可以和 Markdown 完美嵌合。我那时候已经在用 Typora 写文档突然发现代码块里写几行 mermaid 语法就能直接渲染成图还能跟着文档一起保存。这意味着图表不再是一张孤立图片而是和文字一样是可版本化、可 diff、可复用的文本内容。配合 Git 管理文档时改动图表就像改代码一样一目了然。后来我在网页项目里也用了 Mermaid发现它还有 JavaScript 库可以在前端动态渲染这彻底打开了我的思路一张图可以在 Live Editor 里调试在 Typora 里展示在网页里动态生成三种场景共用一份 mermaid 代码。有人可能会问既然 Mermaid 这么方便为什么还要专门用 Live Editor 这个在线编辑器答案是本地环境不够用。无论是 Typora 还是 VS Code它们的 Mermaid 渲染内核版本都不一定是最新的而且本地安装的环境不统一经常出现“我这能显示你那儿报错”的问题。Live Editor 是 Mermaid 官方维护的在线调试环境版本最新、环境统一、打开即用做语法验证和代码调试是最合适的。1.2 Live Editor 解决了本地工具的三个老大难我用下来的感受是Live Editor 精准解决了三类痛点这也是我向别人推荐时反复强调的。第一安装和环境问题。很多同事并不是程序员让他们装 Node.js、配环境再跑 Mermaid 命令行工具门槛太高。但 Live Editor 只需要一个现代浏览器Chrome、Edge、Safari 都行打开 mermaid.live 就能干活。公司的安全策略再怎么严格也不能禁止你开一个网页。第二版本不一致问题。Typora 内置的 Mermaid 渲染内核是随软件版本走的你软件不更新内核就停在旧版。而 Live Editor 由官方持续维护界面上还可以切换 Mermaid 版本。我一般先在 Live Editor 里把代码调好确认新版语法没问题再复制回 Typora如果 Typora 报错那基本能肯定是内核版本落后解决方案就清楚多了。第三协作和分享问题。Live Editor 的每个图表配置都编码在 URL 里相当于一个带状态的链接。把编辑链接发给同事对方打开看到的是同一个图不需要传文件、不需要装软件。改完点一下更新再把新链接发回去整个协作过程非常轻量。其实还有一个隐性优势Live Editor 的实时预览。你每敲一个字符右侧图表立即刷新语法错误也会即时高亮。这种“即改即见”的反馈让学习 Mermaid 语法的成本大幅降低也让我在调试复杂图表时节省了大量时间。对比一下维度Mermaid Live EditorTypora 内置渲染Draw.io / ProcessOn安装成本零安装浏览器打开需安装 Typora桌面版需安装 / 在线版需注册渲染内核版本官方最新可切换随软件版本固定不涉及 Mermaid实时预览强轻量需切到预览模式所见即所得图表复用性文本代码可嵌入 Markdown文本代码可嵌入文档通常导出图片难复用协作方式分享带状态的链接传文件账号协作或导出分享这个表格也直观回答了“为什么我最后留在 Mermaid”因为图表的本质应该是一段可维护的结构化描述而不是一堆无法检索的像素点。Live Editor 则是这段描述最好的试验场。2. 从零上手Mermaid 核心语法与 Live Editor 操作速览2.1 第一次打开 Live Editor界面布局与基本操作第一次打开 mermaid.live 时你看到的是左右两栏布局左侧是代码编辑器区域右侧是实时渲染预览区。顶部有一条功能栏左侧是示例、清空、下载、编辑等按钮右侧是主题切换、缩放比例、视图选项等内容。我的建议是打开后第一步先别急着写代码把右上角的“Sample Diagrams”或示例库点开挑一个和你要画的图最接近的样例在它的基础上改。这样比自己从零写要快得多也能顺便学到官方推荐的写法。我早期画时序图就是从一个官方示例改出来的比自己翻文档高效多了。代码输入区默认是空白的你在里面写 Mermaid 代码右侧就会实时渲染。如果右侧出现红色报错信息先别慌绝大多数情况是符号写错了比如中文冒号、少了括号、箭头写反。报错信息里会定位到行和列照着修就行。习惯之后我通常会调整这几个操作主题切换顶部主题下拉框里有 default、neutral、dark、forest 等我一般用 default 做日常调试dark 用于深色演示文稿截图。缩放控制预览区右下角有放大缩小按钮复杂图表建议缩放查看局部。下载导出顶部下载按钮支持 PNG、SVG、Markdown 格式。导出 PNG 时系统会按当前缩放比例和背景色渲染我记得默认是透明背景如果需要白底可以在主题或导出选项里调整。还有一个很容易被忽略的功能编辑链接。顶部的“Edit this diagram”或“Copy Link”按钮可以把当前图表状态保存为 URL分享给任何人打开就是同一张图。这个功能在做群内讨论、远程求助时极其好用比我用截图来回发清晰得多。2.2 必须掌握的五类基础图表语法Mermaid 支持的图表类型很多但在日常文档里真正高频出现的其实就五类流程图、时序图、类图、E-R图、甘特图。我个人还会用到饼图但概率低一些。下面把这五类的入门语法过一遍每段代码都可以直接粘到 Live Editor 里试。流程图是最常用的关键字是flowchart或旧的graph。比如flowchart TD A[开始] -- B{是否注册?} B --|是| C[进入系统] B --|否| D[去注册]这里的TD表示从上到下排列LR表示从左到右。节点形状用中括号表示矩形、花括号表示菱形、圆括号表示圆角矩形。连线上可以加文字用|文字|写在箭头中间。这一段足够覆盖 80% 的流程图画法。时序图的关键字是sequenceDiagram语法更接近自然语言sequenceDiagram participant 用户 participant 系统 用户-系统: 发起登录请求 系统--用户: 返回验证码这里-表示实线箭头--表示虚线回传participant可以自定义参与者的显示名和顺序。时序图常用于接口调用流程、登录认证流程等场景在技术方案设计文档里出镜率极高。类图的关键字是classDiagram适合描述面向对象设计classDiagram class User { String name login() bool } class Admin { manageUsers() bool } User |-- Admin|--表示继承关系也可以画关联、组合等关系。不常画类图的读者可以先把这段存着等写系统设计文档时再用。E-R图的关键字是erDiagram这个我后面会专门用一个章节来讲。它主要用于数据库设计画实体、属性和关系。甘特图的关键字是gantt用于排期gantt title 项目排期 dateFormat YYYY-MM-DD section 开发 需求评审 :done, 2025-01-01, 3d 编码开发 :active, 2025-01-04, 10d甘特图在项目管理里用处很大不过我一般只在写项目章程或周期性汇报时用。对多数读者来说先掌握流程图、时序图、E-R图这三种就已经能覆盖日常文档的绝大多数需求。2.3 常用配置主题、缩放与导出格式Mermaid Live Editor 在图表配置上提供了很高的自由度但很多新手不知道在哪里调。我建议从两个入口入手顶部工具栏的“主题”下拉框以及代码里的init指令或图表头部配置。主题切换是最直观的直接在下拉框选不同主题右侧预览立即变化。常见场景是日常写博客用 default 明亮主题做汇报 PPT 截图时切 dark 主题排版会更高级。如果你有品牌色要求还可以自定义主题变量但那是进阶玩法入门阶段用默认主题就够。缩放导出是另一个高频操作。我导出图片的固定流程是先在预览区把缩放调整到合适的比例再点下载按钮选择 PNG 或 SVG。导出 SVG 的优点是矢量清晰放到 PPT 或网页里放大不糊导出 PNG 则适合直接贴到聊天工具里。在 Live Editor 里SVG 和 PNG 都可以一键下载不需要额外工具。提示如果导出的 PNG 出现文字被截断多半是预览区的画布尺寸没调好。先把图表完整显示在预览区内保持四周留白再调高缩放比例后导出基本能解决。另外我再提一个实用细节Live Editor 的代码编辑区支持外部文本粘贴你在 Typora 或其他编辑器里写好的 Mermaid 代码可以直接粘进来调试。反过来在 Live Editor 里调好的代码也可以一键复制回文档。代码在两边的显示效果有细微差异这主要是两边渲染内核版本不同造成的不是代码本身错了后面第4章我会专门讲这个问题。3. 实战案例用 Live Editor 绘制学校教学管理 E-R 图3.1 需求拆解教学管理涉及哪些实体与关系下面进入本篇文章的重头戏用 Mermaid 画“学校教学管理E-R图”。这个场景在课程设计、毕业论文、数据库课程作业里都很常见网上能找到不少参考但很多图的 E-R 设计是残缺的实体随意、关系含糊。我这里给出一套相对完整且能直接运行的设计。先做业务拆解。一个典型的学校教学管理系统至少涉及学生、教师、学院、专业、班级、课程这几个核心实体。如果深入一点还会有选课记录、授课安排、成绩单等关联实体。为了不过度复杂我把范围控制在七个实体以内但把关系讲透。学院Department管理教学工作的行政单位。专业Major学院下设的培养方向。班级Class按照专业划分的学生行政班。学生Student系统的主要服务对象。教师Teacher承担教学任务的工作人员。课程Course教学的基本单元。选课记录Enrollment学生和课程之间的多对多关联同时保存成绩等属性。明确了实体之后再梳理关系一个学院下设多个专业一个专业通常包含多个班级一个班级里有多名学生一个教师属于某个学院一个教师可以讲授多门课程一个学生可以选择多门课程一个课程也可以被多个学生选择。这些关系捋清楚E-R 图的主干就成型了。其实这个设计思路也适用于其他业务场景先找名词实体再找动词关系最后补属性。很多人画 E-R 图画不好不是语法不会而是业务分析这步跳过了。我建议你先拿纸笔把这个列表写出来再动鼠标。3.2 ER 图 Mermaid 代码设计与逐行解读在 Mermaid Live Editor 里E-R 图用erDiagram关键字声明之后是实体定义和关系定义。实体和关系可以混合书写没有严格的先后顺序。我写的这套教学管理 E-R 图代码如下erDiagram DEPARTMENT ||--o{ MAJOR : 包含 MAJOR ||--o{ CLASS : 包含 CLASS ||--o{ STUDENT : 包含 DEPARTMENT ||--o{ TEACHER : 聘请 TEACHER ||--o{ COURSE : 讲授 STUDENT ||--o{ ENROLLMENT : 产生 COURSE ||--o{ ENROLLMENT : 被选 DEPARTMENT { string dept_id PK string dept_name string office_phone } MAJOR { string major_id PK string major_name string dept_id FK } CLASS { string class_id PK string class_name string major_id FK int grade } STUDENT { string stu_id PK string stu_name string gender date birth_date string class_id FK } TEACHER { string teacher_id PK string teacher_name string title string dept_id FK } COURSE { string course_id PK string course_name float credit int hours string teacher_id FK } ENROLLMENT { string stu_id FK string course_id FK int score string semester }这段代码里实体名字我习惯全大写这在 Mermaid 里不是硬性要求但大写实体名和小写属性名区分度高预览效果更清晰。关系部分用||--o{这种符号表示一对多其中||表示“一”的一侧o{表示“多”的一侧中间连接线表示关系方向。关系标签用双引号包裹可以写中文。属性块放在实体名后面的大括号里每行一个属性格式是“类型 属性名”末尾可以用PK或FK标注主键、外键。Mermaid 不会对 PK/FK 做严格校验但它会在渲染时高亮显示帮助读者理解字段角色。这里有个细节我在实际中踩过坑关系定义和属性定义如果混在一段代码里建议顺序一致先列完所有关系再列所有属性块这样代码可读性最好。如果属性块写在了关系定义的中间Mermaid 也能正确解析但你自己维护起来容易眼花。把这段代码粘到 Live Editor 里右侧就能看到完整的 E-R 图。你会发现 Mermaid 会自动调整实体框的布局不需要手动排版。这也是文本驱动绘图的最大优势逻辑正确布局交给渲染器处理。3.3 导出与嵌入论文、PPT、网页的使用姿势E-R 图画好之后接下来的问题是怎么用。根据使用场景不同我推荐三种不同方式。第一种写论文或课程设计报告。建议在 Live Editor 里把主题调成默认或 neutral导出 SVG 格式插入 Word 或 LaTeX。SVG 是矢量图放大不模糊印刷效果也比位图好。如果你的论文提交系统不支持 SVG可以导出高清 PNG导出前把缩放调高一点。第二种做 PPT 汇报。这时候最好用 dark 主题导出或者导出 SVG 后在 PPT 里再叠加你的模板配色。PPT 里不要直接截图截图分辨率往往不够投影放大后边缘发虚。我自己的习惯是导出 SVG在 PPT 里转成可编辑的形状这样还能局部高亮某个实体。第三种嵌入网页或内部系统。这时不建议导出图片而是直接把 Mermaid 代码交给前端用 Mermaid 的 JavaScript 库在浏览器里动态渲染。这样做的好处是图表和数据实时联动数据一改图就跟着变。Live Editor 在此时的作用是调试语法先把代码验证正确再交给开发落地。注意在 Live Editor 里调好的代码复制到 Typora 后关系标签和中文显示一般没问题但个别新特性可能因为 Typora 内置 Mermaid 版本偏旧而无法识别。遇到这种情况先不要怀疑代码写错了多半是渲染内核版本不同后面第4章有具体排查方法。我实际体会最深的一点是E-R 图的价值不止在于最终那张图更在于设计过程中把实体、属性、关系梳理清楚。用 Mermaid 写一遍 E-R 图等于替数据库表结构做了一次预建模后面建表、写接口都会顺利很多。4. 版本与运行环境Typora 升级和 macOS 打开问题一次说清4.1 Typora 里的 Mermaid 怎么升级很多人在 Typora 里写完 Mermaid 代码发现语法报错或渲染效果和官方文档不一样第一反应是自己代码写错了。但更常见的原因是 Typora 内置的 Mermaid 内核版本相对滞后。Typora 把 Mermaid 作为一个内置组件打包进软件里它没有提供单独升级 Mermaid 的按钮你要获得更新的渲染内核只能通过升级 Typora 软件本身。具体操作很简单打开 Typora进入“帮助”菜单选择“检查更新”按提示下载并安装新版本。安装完成后重启软件Mermaid 渲染内核会随新版本更新。需要注意的是请通过官方渠道获取安装包不要轻信第三方下载站安全第一。如果你因为某些原因暂时不能升级 Typora也有变通方案在 Mermaid Live Editor 里把代码验证好确认语法没问题后直接把代码粘进 Typora。理论上兼容范围内的代码都能正常渲染如果 Typora 依然报错说明你用的语法特性超出了内置内核的支持范围。此时要么调整语法要么用 Live Editor 导出 SVG 或 PNG 图片插入文档绕开渲染兼容问题。4.2 在 macOS 上打开和使用 Mermaid 的几种方式macOS 用户接触 Mermaid 的频率很高因为不少程序员和写作者都用 Mac。打开 Mermaid 的方式其实很多我按使用习惯排个序。第一种浏览器直接打开 Mermaid Live Editor。这是最通用的方式和操作系统无关。你在即将发布的 Live Editor 里测试代码或者查看别人分享的编辑链接浏览器都能直接打开。Safari、Chrome、Edge 都可以我平时主力用 Chrome兼容性最好。第二种用支持 Mermaid 的 Markdown 编辑器。除了 TyporamacOS 上常见的还有 Obsidian、VS Code Markdown Preview Mermaid Support 插件、Logseq 等。这些工具都内置了 Mermaid 渲染写文档时顺手画个流程图很舒服。Obsidian 我偶尔用来做知识库它的 Mermaid 渲染效果不错主题还能联动。第三种通过命令行工具。Mermaid 官方提供mermaid-js/mermaid-cli也就是mmdc命令。它需要 Node.js 环境适合需要批量把 Mermaid 代码转成图片的自动化场景。比如你有一堆.mmd文件想统一渲染成 SVG 输出到一个目录用 mmdc 一条命令就能完成。这个工具在 macOS 和 Linux 下都跑得很好Windows 也不差就是安装前得先把 Node.js 配好。如果你只是想在 Mac 上“打开”一个.mmd文件即 Mermaid 代码源文件也可以直接拖进支持 Mermaid 的编辑器里查看比如 Typora、Obsidian或 VS Code 对应插件。.mmd本质就是纯文本任何文本编辑器都能打开看源码只是未必能渲染成图。4.3 版本差异导致的语法兼容问题Mermaid 语法本身在不断演进不同版本之间存在兼容性差异。我在实际使用中遇到过几个典型的版本相关坑这里集中说明。第一类是图表关键字的演进。老的语法用graph声明流程图新版推荐用flowchart。两者大部分场景兼容但flowchart支持更多特性比如特定的方向控制、子图命名方式。如果你在 Typora 里使用flowchart正常而某些老旧编辑器里只能用graph就要注意版本问题了。第二类是部分图表类型在旧版本里不存在。比如stateDiagram-v2、journey、gitGraph这些较晚引入的图表类型老版本内核直接无法识别会报“Diagram type not supported”之类的错误。遇到这种情况更新软件或换到 Live Editor 是最直接的解法。第三类是渲染细节的差异。比如饼图pie的标题写法老版本不显示标题新版本显示且支持中文sequenceDiagram中消息换行的写法也在不同版本有细微区别。这些差异很难靠直觉判断我的解决思路是把 Live Editor 当作“标准环境”在它上面验证最新语法再回本地渲染如果本地报错就去查本地软件的更新渠道而不是反复改代码。提示Live Editor 本身也提供了 Mermaid 版本切换能力。如果通过链接分享的图表在别人那边渲染异常可以先让对方确认打开的 Live Editor 版本再对比是否和本地环境一致。版本一致是排除兼容问题最快的方式。5. 常见问题与排查技巧实录5.1 语法报错类最常见也最好解决语法报错几乎每个 Mermaid 新手都会遇到。这些报错信息里会给出行号和列号但说实话报错提示有时候比较抽象尤其是在长代码里。我按自己踩过的频率整理了三个高发错误。第一个是标点符号用了中文全角。Mermaid 语法里的冒号、分号、括号、逗号都必须是英文半角符号。在中文输入法下切换不及时很容易打出中文冒号。刚写完代码时右侧预览区若是一片红色报错先检查全角符号这个概率最大。第二个是节点文本里的特殊符号没处理。如果在节点文本[ ]或{ }里直接用英文括号、引号可能会被 Mermaid 误判成语法结构。解决办法是使用双引号把文本包起来比如A[获取用户信息(缓存)]。我一般习惯在文本较长或包含特殊符号时都加双引号一劳永逸。第三个是关系符号写错。Mermaid 的关系符号种类比较多--、---、-.-、等等写错一个箭头页面可能直接渲染失败。我每次写完连线多的流程图都会先检查箭头方向是否和预想一致。E-R 图里还有||--o{、}o--||这类一对多符号更容易打错建议直接从文档复制示例再改实体名而不是手敲符号。下面这个表格可以直接收藏遇到报错对照排查现象常见原因快速解决预览区整体报错关键字拼写错误检查是否为flowchart、sequenceDiagram等个别节点的位置报错全角符号全面替换为半角符号图表能显示但连线异常关系符号多写或少写对照官方示例检查箭头中文显示为乱码导出设置或浏览器字体换主题或调整缩放后重新导出5.2 渲染不显示类图不出现时别急着删代码有时候代码看着没错但右侧预览区就是空白。这种情况我遇到的最多两类原因一类是浏览器缓存或页面状态异常另一类是代码里用了当前 Mermaid 版本不支持的语法。如果是浏览器问题最简单的操作是刷新页面或者新开一个无痕窗口打开 Live Editor。因为 Live Editor 的状态存在 URL 里刷新一般不会丢失代码。如果还是白屏可以把代码复制到本地记事本保存再重新打开 Live Editor 粘回去。这套操作我屡试不爽。如果是语法版本问题报错信息通常会在预览区顶部显示“Syntax error in text”或类似提示但有时候提示很不明确。我的排查方法是二分法先把代码整体注释掉一部分或者把大段代码缩减成最小片段逐段验证。比如 E-R 图不显示先只保留erDiagram关键字和一个实体确认能渲染了再逐步加关系、加属性直到定位到出问题的代码行。这个方法虽然原始但在任何绘图工具里都通用。另外有些代码在 Live Editor 里能正常显示但在 Typora 或 Obsidian 里就是空白。这不是代码问题而是本地编辑器的 Mermaid 内核不认某些新语法。碰上这种情况我一般看编辑器有没有更新可用如果没有就按兼容性降级写法调整或者干脆导出图片使用。5.3 中文显示与样式调整的独门技巧Mermaid 对中文的支持一直是可以用的但默认渲染效果往往差强人意。比如导出 PNG 后中文偏小、字体不明显或者预览时中文挤在一起。这里分享几个我摸索出来的实用技巧。第一中文字体优先在主题配置里指定。Mermaid 支持通过init指令自定义主题变量比如设置fontFamily。在 Live Editor 的代码开头可以放这样一段%%{init: {theme: default, themeVariables: {fontFamily: PingFang SC, Microsoft YaHei, sans-serif}}}%%这段配置会让图表优先使用苹方或微软雅黑渲染中文导出 PNG 时字体观感会好很多。如果不用配置Mermaid 默认使用浏览器字体在 Mac 上是英文优先中文渲染偶尔会发虚。第二导出 PNG 时把缩放适当调大。Mermaid Live Editor 的导出 PNG 会根据预览区域的缩放比例计算最终像素。如果你想在 Word 里插入清晰大图先在预览区缩放到 150% 或 200% 再导出能明显提升清晰度。但缩放太大时节点文字可能被截断建议导出后检查一遍四周留白。第三中文节点文本尽量用双引号包裹。比如A[学生信息]这样中文里的空格或标点不会被 Mermaid 误解析。在关系标签处||--o{ 包含 : ...这种写法也建议把中文标签用引号包住能避免个别版本解析异常。注意Mermaid Live Editor 默认导出的 PNG 背景是透明的。如果你的文档页面是白色建议在导出时选择纯白背景或在主题变量里设置背景色否则图表插入 Word 后可能出现透明区域和底色不一致的情况。最后一个个人心得我会在 Live Editor 里维护一份自己的“图表模板集”。平时遇到画得好的流程图、时序图、E-R 图就把 Mermaid 代码存下来按类型归档。需要时打开模板改几行文本新图就出来了。这个习惯让我从“每次从零画图”变成了“基于模板改图”效率提升非常明显。你现在看到的这篇教学管理 E-R 图就是我从模板库里抽出来再加工的一版你也可以照这个思路建立自己的素材库。