5 分钟跑通 Mermaid 文本画图：3 种部署方式与 4 个易错点

5 分钟跑通 Mermaid 文本画图3 种部署方式与 4 个易错点【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaidMermaid 是一个用类 Markdown 文本定义直接生成流程图、时序图、ER 图等视觉图表的 JavaScript 图表库它解决一个很多人碰到的痛点架构图和代码各改各的图过一个月就过期了。本文用一张流程图带你把第一张图在浏览器里跑起来并顺带讲清新手最常踩的 4 个坑。痛点为什么文档里的图总是一月就过期图有维护成本问题。传统做法是在设计工具里画好架构图再把图片贴进文档之后接口改了图片不会跟着变下一个看文档的人会被旧图误导。Mermaid 的做法是把图写成文本定义和代码放在同一个仓库里跟着代码一起提交、一起评审。某个节点变了就改一行文字渲染出来的图自动更新图不再是画一次就作废的静态资产。机制读一张图定义只需三步Mermaid 把自己分成三块部署、语法、配置。这一节只讲语法部分怎么工作。第一行声明决定用哪个解析器图定义的第一行声明图表类型解析器据此选择对应的解析逻辑。graph TD是方向从上到下的流程图sequenceDiagram是时序图erDiagram是实体关系图。第一行漏写或类型名拼错整段文本都不会被识别为图页面上只会显示纯文字。节点、连线与形状定义内部一行描述一条连线A[客户端] -- B[服务器]。方括号里是节点文字括号样式决定节点形状方括号是矩形圆括号是胶囊形花括号是菱形。连线可以加标签A --|下单| B。完整形状对照表见 docs/syntax 下的 flowchart 章节。配置有三个入口配置可以写在initialize()调用里可以写在图代码顶部的 frontmatter 里也可以写在线上编辑器的配置面板里三者功能等价按图放在哪里选一个。注意配置项区分大小写拼错的键会被静默忽略不会报错。跟着做两条命令跑通第一张流程图 最短路径是先克隆源码打开现成示例确认环境没问题再动手自己写。克隆源码验证环境# 克隆 mermaid 源码查看自带的演示示例 git clone https://gitcode.com/GitHub_Trending/me/mermaid cd mermaid仓库根目录的 demos/ 里有现成示例用浏览器打开 demos/flowchart.html 就能看到渲染效果确认环境可用后再开始自己写。自己写最小页面新建一个 HTML 文件里面放两样东西一个装着图定义的 pre 标签和一个加载库并调用 initialize 的 script。body pre classmermaid graph TD A[Client] -- B[Load Balancer] B -- C[Server01] /pre script typemodule // 导入 mermaid 库并开启页面加载后自动渲染 import mermaid from ./node_modules/mermaid/dist/mermaid.esm.min.mjs; mermaid.initialize({ startOnLoad: true }); /script /body在页面所在目录执行npm install mermaid引入依赖再用静态服务器如npx serve打开页面浏览器对 file:// 加载模块有限制直接双击打开会报错。一个 pre 标签只放一份图定义多张图各用一个独立的 pre。新手最常翻车的 4 个点 ⚠️这 4 个点覆盖了大部分图渲染不出来和配置不生效的求助。保留字和嵌套形状都要加引号end在流程图和时序图里是保留字想拿它当节点名就加上引号否则图直接断掉。节点文字里出现括号等嵌套形状字符时同理加引号包起来解析器就不会被嵌套括号搞混。渲染失败和不生效是两种不同的故障这是最容易混淆的一点文本里的未知词或拼写错误会直接让图渲染失败报错信息指向对应行但配置参数拼错是静默忽略的图照常渲染只是不生效。所以图渲染不出来时去看报错行号、检查文本用词效果不对时逐个核对配置键名是否拼错。注释里不要写花括号行首%%是注释但注释里如果出现一对{}容易被误判成指令而干扰渲染。注释里需要描述配置时避开花括号。部署代码块、线上编辑器、JS API 三选一按图放在哪里选一种。支持该语法的 Markdown 平台里把定义写进 mermaid 代码块就直接渲染零额外工作。线上编辑器左侧 Code 面板写、右侧出预览可导出 PNG、SVG 或 Markdown也是试语法最快的地方。JS API 就是前面演示的 HTML 方式适合把图嵌进自己的站点装好依赖后还能在 Node 脚本里批量生成 SVG 文件。跑通之后接着看文档目录里的 4 条路径docs 目录里四条路径值得走一遍。docs/intro/syntax-reference.md 汇总了所有图表类型的完整语法还列出了会破坏图的词和符号。docs/syntax/ 目录按流程图、甘特图、时序图分章每章都有形状和参数的对照表。e2e/diagrams/ 下有几个百的 .mmd 示例文件每个都是一份可运行的用例改着玩最划算。想动手扩展新图表类型时先读 docs/community/ 下的贡献指南。接下来打开 demos/sequence.html 看时序图效果改一个节点名再刷新确认图跟着文本变。完成后把 e2e/diagrams/flowchart/ 里挑 3 份示例逐页跑一遍。【免费下载链接】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），仅供参考