Mermaid 图表工具入门教程：10 分钟跑起来，几行文本画出流程图与序列图

Mermaid 图表工具入门教程：10 分钟跑起来，几行文本画出流程图与序列图

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid

Mermaid 是一个开源的图表工具，你用几行 Markdown 风格的文本就能渲染出流程图、序列图、甘特图、类图等专业图表。它适合写技术文档的开发者、需要画架构图的产品经理，以及任何希望"图在文档里、文档和代码同步更新"的人。这篇文章带你从零完成 Mermaid 安装，并在本地跑起实时预览环境。

为什么值得试试

1. 图即文本，改需求只改几行字传统绘图工具里改一个节点要点来点去，而 Mermaid 的图表定义就是几行文本，可以放进同一个仓库做版本管理、做 diff 评审。需求变了，改文本、图自动重绘，不会像截图那样"画完就过期"。

2. 一套语法覆盖主流图表类型流程图、时序图、类图、甘特图、状态图、ER 图、思维导图等全部共用同一套语法体系。仓库里docs/syntax/目录按图种逐个给出语法说明，从流程图到象限图几乎你能想到的都齐了。

3. 本地开发环境自带实时编辑器不需要先学 API：克隆仓库、装完依赖，一条命令启动开发服务器，就能在浏览器里边写边看渲染效果，调主题、换图种都是即时反馈的。

10 分钟跑起来 🚀

① 环境自检Mermaid 要求 Node 16 或更高，仓库用 pnpm 管理依赖。先确认这两样：

node -v # 应显示 v16 或更高 pnpm -v # 没有 pnpm 可执行 npm install -g pnpm

② 克隆仓库并安装依赖

git clone https://gitcode.com/GitHub_Trending/me/mermaid.git cd mermaid pnpm install

③ 启动开发服务器，验证成功

pnpm dev

启动后打开浏览器访问http://localhost:9000，看到开发页面能加载、图表能渲染，就说明环境跑通了。如果 9000 端口被占用，可以通过环境变量MERMAID_DEV_PORT指定其他端口。

真实场景演示

场景一：梳理业务流程graph TD开头几行就能描述"条件判断—执行—结束"的逻辑，节点用方括号、判断用花括号。

场景二：画出接口调用时序sequenceDiagram声明参与者后，用->>和-->>区分请求与响应，一张系统交互图几行写完。

场景三：排项目进度甘特图任务按日期排布，支持排除周末等特定日期后自动调整任务时间线，进度管理文档里非常好用。

常用配置

主题切换：全站用 initialize，单图用 frontmatter内置 default、neutral、dark、forest 四个主题，另有一个可深度定制的 base 主题。全局设置写在初始化代码里，这段代码的作用是告诉 Mermaid 使用哪个主题并在页面加载时自动渲染：

import mermaid from 'mermaid'; mermaid.initialize({ theme: 'forest', // 可选 default / neutral / dark / forest startOnLoad: true, });

只想改某一张图的主题时，在图表定义顶部加 frontmatter 即可：

--- config: theme: 'dark' --- graph TD a --> b

securityLevel：控制点击与 HTML 能力默认值strict会把节点文本中的 HTML 标签转义并禁用点击跳转。如果你信任图表来源、需要节点可点击，可在 initialize 中改为loose或antiscript；渲染不可信内容时建议保持strict或改用sandbox。

避坑 FAQ

现象：节点里的 HTML 显示成纯文本、点击没反应→ 原因：securityLevel默认为 strict，会转义标签并禁用交互。 → 解决：在mermaid.initialize()中把securityLevel设为loose，前提是图表来源可信。

现象：pnpm install卡住或报错→ 原因：本地 store 缓存异常或网络中断。 → 解决：执行pnpm store prune清理缓存后，再用pnpm install --force重试。

现象：图不渲染，页面上只有原始文本→ 原因：通常是语法拼写错误或 initialize 之后才渲染导致配置未生效。 → 解决：打开浏览器控制台看报错信息定位语法问题；确认先调用mermaid.initialize()再触发渲染。

现象：改了主题配置，图没变化→ 原因：配置在渲染之后才写入，本次渲染已按旧配置完成。 → 解决：调整调用顺序，让 initialize 先于渲染执行，或修改后手动重新渲染。

生态与资源

• 官方文档入口：docs/
• 各图种语法参考：docs/syntax/
• 配置项说明：docs/config/setup/
• 主题定制详解：docs/config/theming.md
• 本地演示页面集合：demos/
• 核心源码：packages/mermaid/src/
• 社区参与指南：docs/community/

写在最后

Mermaid 的价值就在"文本驱动"三个字：图随文档走，文档随代码走。现在你已经在本地跑起了开发环境，下一步建议打开demos/flowchart.html这类演示页，把里面的图定义改成自己的业务，感受从文本到成图的完整链路。上手了流程图，再按docs/syntax/逐个图种推进，用不了几天就能覆盖你日常文档里 90% 的画图需求 ✏️

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid