作为一个经常写技术文档、做方案汇报的人我对“画图”这件事又爱又恨。流程图、时序图、ER图每一样都离不开但桌面画图软件要么收费要么操作繁琐要么导出的图片丑得没法见人。直到我用上Mermaid Live Editor这个免费在线图表编辑工具才算真正把画图这件事从“负担”变成了“顺手就做的事”。这篇文章我会把手头这套玩法完整拆开为什么选它、核心语法怎么记、实际操作怎么用、怎么把它接到 Typora、macOS 上怎么打开还会附上一个可以直接复制跑的“学校教学管理 E-R 图”完整示例。适合刚接触 Mermaid 的新手也适合已经会写一点、想系统梳理流程的老手。1. 为什么我坚持用 Mermaid Live Editor 而不是桌面工具1.1 画图这件事的痛点以前画流程图我常用的路径是打开 Visio、Draw.io 或者 ProcessOn用鼠标拖拽方框、连线、对齐、调样式。一张图少说十分钟多则半小时。问题还不是慢而是改图最痛苦需求一变整个布局全乱重新拖一遍。等图终于能看了想放进文档里又遇到图片清晰度、格式统一、版本管理的问题。后来我开始用代码画图PlantUML、Graphviz 都试过但它们要么语法繁琐要么环境配置麻烦。Mermaid 是这里面最轻量、最顺手的。而Mermaid Live Editor作为官方提供的在线编辑器把“写代码”和“看渲染结果”做到了同一个页面左写右看实时出图连保存和导出都一并解决了。1.2 Live Editor 对比本地工具的优势我用过的方案不算少这里直接放一个对照表方便你判断什么场景下选什么工具对比维度Mermaid Live Editor桌面画图软件Visio/Draw.io本地编辑器 Mermaid 插件安装成本无需安装浏览器打开即用需要下载安装部分收费需要安装编辑器与插件上手门槛低记住少量语法即可较低拖拽即可但做复杂图慢中等要看插件文档改图效率改代码即改图支持批量替换需要逐个调整元素效率高但依赖本地环境协作分享分享链接或代码即可需要导出文件再发送需要同步代码或文件导出格式PNG、SVG、Markdown 等格式多但部分收费取决于环境是否支持版本追踪代码是纯文本可进 Git二进制文件难以 diff天然支持代码进版本库我能明显感受到的差异是当我把图表以“代码”形式嵌入到文档工程里之后图就不再是“一张不能改的图片”而是“一段可以被 review、被复用、被部署的文本资产”。这在团队协作里价值极大。1.3 什么时候它并不合适说句公道话Mermaid Live Editor 不是万能的。如果你的需求是画复杂的架构图、严格像素级控制的视觉稿、或者带有大量手绘风格的示意图它并不合适。比如画一个精美的产品原型图或者需要精确控制每个节点坐标的网络拓扑图用 Mermaid 会非常痛苦。Mermaid 擅长的是“结构化图表”流程、时序、类关系、ER 关系、状态流转、甘特计划。这些图的特点是“内容大于形式”读者关心的是逻辑关系而不是美术效果。所以我的经验是能用结构化方式表达的图优先用 Mermaid需要视觉精致度的图才动用专业画图工具。2. Mermaid 语法速查够用的核心子集2.1 流程图 Flowchart最常写的图Flowchart 是 Mermaid 里使用频率最高的一类核心语法就那么几条看一遍就能上手。flowchart TD A[开始] -- B{判断条件} B -- 是 -- C[执行操作] B -- 否 -- D[结束]短短三行就画出了一个带分支的流程。TD 表示方向从上到下还有 LR 表示从左到右。节点里方括号[]表示矩形节点花括号{}表示决策节点圆括号()表示圆角节点这些记清楚基本就够日常用了。连线方面--是普通箭头---是实线-.-是虚线箭头是加粗箭头。2.2 时序图 Sequence Diagram梳理交互必备写接口调用、业务交互的时候时序图是我最常用的。Mermaid 的时序图语法跟画图工具里拖 lifeline 完全是两种体验写起来非常快sequenceDiagram participant 用户 participant 前端 participant 后端 用户-前端: 点击提交按钮 前端-后端: POST /api/submit 后端--前端: 返回结果 前端--用户: 展示反馈participant可以自定义参与者的展示名称-表示实线箭头--表示虚线返回。这就是时序图的核心剩下的是把业务逻辑填进去。注意消息文本后要跟冒号文本内容里尽量别有特殊字符否则容易解析报错。2.3 类图与 ER 图写技术方案时靠它撑场面类图和 ER 图在 Mermaid 里写法高度类似ER 图用erDiagram声明类图用classDiagram声明。ER 图在数据建模、数据库设计文档中非常实用。erDiagram CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE_ITEM : contains CUSTOMER { int id string name string email } ORDER { int id string status date created_at } LINE_ITEM { int id int product_id int quantity }这里||--o{表示“一”到“零或多”的关系Mermaid 用这些符号表示基数。写 entity 字段时在花括号里写类型 字段名即可语法非常简单。类图类似用/-表示可见性可以标注方法。2.4 饼图、甘特图等其他类型偶尔救急也不错除了上面三类Mermaid 还支持饼图、甘特图、状态图、旅程图等。饼图的语法更是简单到令人发指pie title 项目时间分布 需求分析 : 20 开发编码 : 50 测试修复 : 30甘特图适合做项目排期语法稍复杂需要定义日期和任务依赖关系。这些不常写但当别人都在用 Excel 做排期时你直接甩一个可视化甘特图出来效果非常好。3. Live Editor 实操流程从打开页面到导出图片3.1 上手第一步打开页面左右分栏Mermaid Live Editor 的界面非常简洁打开后默认是左右两栏。左侧是代码区右侧是预览区。在左侧输入 Mermaid 代码右侧会实时渲染出图。它会在你输入的同时就更新基本感受不到延迟。第一次用的时候建议先把示例代码全部删掉自己从一行graph TD开始敲感受一下“代码即图”的感觉。我常用的做法是先在 Live Editor 里把代码调试到满意再决定最终怎么使用。导出按钮在预览区的上方支持 PNG 和 SVG。SVG 的清晰度更好适合印刷和 PPT 里放大PNG 则适合直接粘贴到文档中。3.2 三步定位语法错误写代码最容易碰到的就是语法错误。Mermaid 的报错信息不算友好但定位问题其实有套路。首先看预览区是否出现了错误提示框框里一般会描述错误类型。其次看左侧代码区有没有红色下划线或波浪线标记这些标记通常就指向错误位置。最后如果还定位不了就用二分法把代码注释掉一半看是否恢复渲染逐步缩小问题范围。常见错误有三种单引号或双引号不匹配、中文字符误写成了全角符号、节点文字里出现了英文冒号和方括号的组合。3.3 导出高清图的参数选择导出图片时PNG 格式有个缩放选项可以选择。很多人在这一步只缩放宽度结果导出后字体模糊。我的经验是如果图片要放进印刷材料直接导出 SVG如果只能传 PNG把宽高设置成实际用图的两倍再把图片等比缩小放进来清晰度会好很多。另外Live Editor 还支持直接复制 Markdown 格式它会生成一段带代码块的 Markdown 文本粘到支持 Mermaid 的平台里就能直接渲染。这种方式非常适合写博客和文档。4. 教学管理 E-R 图案例一份可以直接抄的 Mermaid 代码4.1 需求拆解网上热搜词里有“学校教学管理 E-R 图”需求我在做数据建模方案时也经常被问到这块。教学管理涉及的核心实体不外乎学生、教师、课程、班级、成绩。关系上一个班级有多名学生一个学生可选多门课程一个教师教多门课程一个学生修一门课程会有一个成绩。这些用 ER 图表达非常合适。先理清楚实体和关系再动手写代码这也是写 Mermaid 的通用思路先有逻辑再有代码。4.2 完整代码与说明下面这段代码是我实际在用的一份教学管理 E-R 图可以直接复制到 Mermaid Live Editor 或任何支持 Mermaid 的平台运行。erDiagram SCHOOL_CLASS ||--o{ STUDENT : 包含 TEACHER ||--o{ COURSE : 讲授 STUDENT ||--o{ ENROLLMENT : 选择 COURSE ||--o{ ENROLLMENT : 接收 ENROLLMENT }o--|| SCORE : 对应 SCHOOL_CLASS { int class_id PK string class_name int grade string major } STUDENT { int student_id PK string student_name string gender date birth_date int class_id FK } TEACHER { int teacher_id PK string teacher_name string title string department } COURSE { int course_id PK string course_name int credit int teacher_id FK } ENROLLMENT { int student_id FK int course_id FK date enroll_date } SCORE { int student_id FK int course_id FK int score_value string grade_level }代码里有几点值得注意。实体名我用的全大写这是 ER 图常见惯例。每个实体的主键标了PK外键标了FK关系上用了||--o{来表达一对多。ENROLLMENT本质上是学生和课程之间的关联实体成绩从属于选课关系所以我把成绩表和选课表之间用}o--||连接逻辑上更严谨。4.3 如何把这个图用到文档、PPT、论文里代码写好了实际落地有三个路径。路径一是直接在 Live Editor 里导出 PNG/SVG放进 Word、PPT、论文里这是最通用的方式。路径二是把代码块粘到支持 Mermaid 的 Markdown 编辑器里比如 Typora、Obsidian、GitHub、语雀保存后自动渲染。路径三是把代码放进项目仓库用 Mermaid CLI 在 CI 流程里自动生成图片这套适合文档持续更新的团队。我个人最推荐第二种因为图跟文档在同一个地方维护改图时不用重新截图。5. 高频场景问答Typora 升级 Mermaid、Mac 打开、以及那些“卡壳”瞬间5.1 在 Typora 里使用和升级 Mermaid 渲染Typora 原生支持 Mermaid这功能很多人知道。在 Typora 里新建一个代码块语言选mermaid然后写语法退出代码块图就会自动渲染。但如果你用的 Typora 版本比较旧可能会遇到语法不支持、新类型图渲染不了的情况。Typora 本身不提供插件机制它的 Mermaid 渲染能力直接内置在软件版本里。所以所谓“升级 Mermaid”实际上是升级 Typora 软件版本。操作路径是Typora 菜单栏 - 偏好设置 - 通用 - 检查更新。如果你用 macOS可以直接在“关于 Typora”里看版本号然后去官网下载最新版覆盖安装。升级前要注意备份主题和自定义样式不过 Typora 升级一般不会动用户配置覆盖安装风险很低。升级后那些新增的图表类型比如mindmap、timeline就能正常渲染了。5.2 macOS 用户如何打开和使用macOS 下打开 Mermaid Live Editor 很简单打开浏览器Safari、Chrome 都行直接在地址栏输入 mermaid.live 或者 mermaid.ink 等官方网址回车就是。不需要安装任何东西。如果你想在本地写 MermaidmacOS 上常用的方案有 Typora、VS Code 装 Markdown Preview Mermaid Support 插件、Obsidian。有一个小坑是如果你用 Safari 打开 Live Editor部分版本的导出 PNG 功能可能行为异常。这时候换个 Chrome 或者 Edge 就好了。另外macOS 的预览工具没法直接预览.mmd文件所以如果你把 Mermaid 代码保存成了.mmd后缀文件想预览还是得打开 Live Editor 或 VS Code 插件。5.3 Live Editor 之外的工作流整合Live Editor 适合单次画图但如果在项目里频繁用图建议把 Mermaid 代码直接放进文档工程。GitHub 和 GitLab 的 Markdown 渲染都原生支持 Mermaid代码块标mermaid语言就可以。VS Code 里装插件后Markdown 预览也能渲染 Mermaid。Obsidian 更是把 Mermaid 当作一等公民代码块直接渲染不需要额外配置。我的习惯是项目文档里统一使用 Mermaid 代码块画图图片不单独存放。这样代码评审时图的变化可以 diff版本管理也不会出现“图更新了但文档忘记改”的问题。6. 常见报错与排查技巧实录6.1 报错速查表实践里经常碰到的问题我整理成了一张速查表报错现象可能原因解决办法Syntax error in text节点文字里有未转义的特殊字符给文字加引号或用#转义图形预览空白代码块开头少了类型声明检查是否写了flowchart、sequenceDiagram等声明方向不对忘记指定TD/LR在 flowchart 后加上方向参数中文乱码编码问题或字体缺失确认文件保存为 UTF-8导出图片时选 SVG时序图消息不显示消息文本前漏了冒号检查-、--后面是否有冒号和空格ER 图关系不显示关系符号写错确认使用 6.2 几个我踩过的坑第一个坑是英文双引号和中文引号混用。Mermaid 对引号非常敏感有时候报错提示根本不指向真正的问题行而是指向下一行。排查时先看有没有全角符号这是最常见的隐形杀手。第二个坑是节点 ID 和文字问题。Mermaid 的节点 ID 不能包含空格也不能用纯数字开头。如果你写A[这是一个节点]ID 是 A文字是括号里的内容这没问题。但如果你括号里的文字包含英文方括号比如[用户[管理员]]就会解析失败。解决办法是给文字加上双引号A[用户[管理员]]。第三个坑是图太大超出页面。Live Editor 的预览区有缩放按钮但如果你导出的图在文档里显示太小不要放大图片而是应该调整渲染参数比如 flowchart 的节点间距或字体大小。第四个坑我花了不少时间才搞明白同一张图里的实体名不能重复。在 ER 图里如果你不小心把两个实体定义成同名Mermaid 会直接报错甚至卡住。命名时我习惯给实体加前缀比如SYS_USER、BIZ_ORDER既避免冲突又让语义更清晰。7. 这套工作流我还在继续扩展写到最后说点我自己的真实体会。Mermaid Live Editor 解决了我 80% 的日常画图需求剩下的 20% 我会结合截图、手绘图或者其他专业工具去补。但核心思路始终是能用文本表达的图表坚决不用鼠标拖拽。因为文本可以版本管理、可以搜索、可以复用这一优势在长期维护的文档里体现得尤其明显。最后再分享一个小技巧如果你经常写 Mermaid可以在浏览器里把 Live Editor 加到书签同时把代码组织成自己的“代码片段库”。我就在电脑里存了一个mermaid-snippets.md文件把常用的 flowchart 模板、时序图模板、ER 图模板都放在里面要用的时候复制改改就行基本不用从零开始写。效率提升非常明显建议你也试试。