Mermaid 文本画图实操指南从选型、渲染到排错的完整流程【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaidMermaid 把流程图、序列图、甘特图这类技术图表写成纯文本代码再渲染成图形是开源社区里最流行的文本到图表方案之一。这篇指南不逐条罗列语法特性而是按一张图从诞生到归档的完整路径展开先选渲染方式再按场景选图型然后写流程图与甘特图统一主题样式最后处理最常见的报错让图表代码顺利进入版本库长期维护。 第一步选渲染路径一次性出图、文档嵌文本还是前端集成写代码之前先定图长在哪里这决定了后续所有习惯。临时画一张就丢用在线的 Live Editor左边写代码、右边实时预览配置面板里可以直接调参数。仓库里也自带一个可离线跑的本地编辑器packages/mermaid-local-editor/ 装好依赖启动即可不依赖任何外部服务。Mermaid 编辑器的代码、预览与配置三栏界面文档要长期维护把 Mermaid 文本直接写进 Markdown 或仓库文档图随代码一起提交每次修改都能在 diff 里看到。要批量导图片或嵌进网站用命令行工具或 JS API。npx mermaid-js/mermaid-cli -i flow.mmd -o flow.svg这条命令把一个.mmd源文件渲染成 SVG加-o flow.png就能换输出格式。学会它之后CI 里自动生成一批文档配图也只是加一行配置的事。前端集成走的是另一条路引入 Mermaid 后调用mermaid.initialize({ ... })传入全局配置之后页面上的图表统一生效主题、曲线样式这些细节在官方文档的配置章节有完整清单。️ 按图要回答什么问题选图型Mermaid 支持的图型超过十种新手常犯的错是先挑了图型再想内容。反过来问一句这张图要回答什么问题选择就清楚了要回答的问题图型关键字一个流程怎么走完、在哪里分叉flowchart几个组件按什么顺序来回通信sequenceDiagram对象之间谁继承谁、各自有哪些字段方法classDiagram一个对象或请求有哪些状态、怎么迁移stateDiagram数据表之间怎么关联erDiagram项目排期与依赖gantt各部分占多少pie一组对象按两个维度怎么分布quadrantChartMermaid 渲染的序列图客户端、服务端与数据库按时间顺序交互以序列图为例它的行就是时间轴每一行是一次通信Client-Server是同步消息Server--Client带虚线的双箭头表示返回。客户端把请求发给服务端服务端查库、拿回结果再响应——四行就讲清了整条调用链。写这类图前先列出参与者再按时间把消息一行行摆上去图自然成形。✍️ 一张能上文档的流程图要掌握的五件事方向、节点、连线、条件分支、子图是流程图里真正会用到的全部部件。五个知识点从这段代码里都能拿到第一行flowchart TD声明从上到下的布局换成LR就是横向A[...]的方括号里是显示文本A本身是内部 id{...}是菱形判断框|是|给连线加标签subgraph到end之间把几个节点收进分组框。节点文本里出现特殊字符时用引号包住即可。Mermaid 渲染的流程图效果两个容易踩的坑方向声明必须在开头中途再写direction只对子图内部生效同一个节点写多次文本时最后一次生效。更多形状与边类型的完整清单见流程图语法文档。 甘特图写排期排期表从此可以直接进文档排期信息最怕的就是截图日期一改图就过期。Mermaid 的甘特图把任务、分组、依赖都写进文本排期调整等于改几行代码。section把任务分组done、active、crit、milestone是四种状态标签必须写在任务名后的最前面任务之间用after 任务id表达依赖不写开始日期就默认接在前一个任务后面。excludes这条指令处理非工作日它的行为值得单独说清被排除的日期落在任务中间时任务条会整体向右延长而不是在条里留空档落在两个连续任务之间时则直接跳过那段空白后一个任务紧跟排除日期之后开始。排除日期落在任务中间时任务条整体右移条内不留空档连续任务之间遇到被排除的周末空白被跳过后一个任务顺延开始完整指令表见甘特图语法文档。 用 frontmatter 统一团队风格一次 initialize 加逐图覆盖样式不一致是团队图表最常见的观感问题。Mermaid 8.7.0 之后是两级配置全局用mermaid.initialize设一次单个图用代码块顶部的 frontmatter 覆盖只影响这一张。--- config: theme: base themeVariables: primaryColor: #BB2528 lineColor: #F8B229 ---内置主题有default、neutral适合打印的浅色调、dark、forest绿色系四种成品外加一个base。base是唯一允许自定义的主题通过themeVariables改primaryColor、primaryTextColor、lineColor等颜色变量就能让深色文档里的图和页面融为一体。全部变量清单在主题配置文档里。️ 渲染报错先查这三处Mermaid 的报错大多出在解析阶段而不是渲染阶段错误信息里带行号直接对应源码位置。三个高频坑节点文本里出现小写的end。它会和子图的结束关键字冲突把词整个大写End、END或用引号包住即可这条警告直接写在官方流程图文档开头。箭头后紧跟以o或x开头的节点名。A---oB会被解析成圆形边A---xB是交叉边。节点名首字母加空格或大写就能绕开。特殊字符没加引号。文本里带(、[、:等字符时用双引号包裹整段文本。拿不准写法时不要凭记忆猜仓库里的 docs/syntax/ 目录就是每种图的语法手册e2e/diagrams/下还有大量真实用例可以直接照着写。一张图从选型、写码、渲染到进库靠的就是上面这五步。Mermaid 让图表以文本形式进入版本管理之后改动留痕、评审对着 diff 讨论、新人接手时直接改代码都成了顺手的事。团队落地时不必一步到位先挑一张最常被重画的流程图或排期表写成 Mermaid 代码提交进文档之后每次调整排期的人改的是代码而不是重新截图发群。【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考