如果你经常写技术文档、画接口说明、梳理业务逻辑一定经历过“流程图怎么画、改起来还快”这种纠结。我一直推荐 Mermaid它本质是用 Markdown 风格的纯文本描述图表然后自动渲染成流程图、时序图、甘特图、思维导图甚至 ER 图。最大的好处是图和代码同源需求改了改几行文本保存后图表自动更新不用像 Visio、ProcessOn 那样拖完框还要重新连线。这篇教程我把从第一张流程图到离线环境搭建、再到几种实战场景用户管理模块、算法流程、MyBatis 源码分析的完整经验拆开讲最后汇总我踩过的坑你可以直接照做。1. 为什么我坚持用 Mermaid 画流程图1.1 文本化图形带来的本质改变先说结论Mermaid 不是要替代专业画图工具而是为了解决“画图过程中的协作和变更成本”这个更隐蔽的痛点。以前画业务流程图最怕的不是画得丑而是产品经理周五下午改了判断条件你周一早上才发现文档里的图已经和代码对不上了。拖拽式工具改一次图少则三五分钟多则半小时而且重画完之后你还得睁大眼睛对比“哪里变了”。Mermaid 把图表变成一段可以被 Git 跟踪的文本后整个逻辑就变了流程图可以跟随代码仓库一起走PR 评审时能直接 diff 出“哪个判断分支变了”“哪条线指向了新的节点”。图里的每个元素都是可搜索的文档多了以后用编辑器全局搜一个节点名就能定位到对应段落。可以像写代码一样搞模板公共的登录鉴权流程抽成一段子图复制到任何业务文档里改几个节点即可。不依赖任何在线服务离线照样写、照样渲染不会因为平台接口调整就全部作废。我现在的习惯是凡是需要放进 README、接口文档、技术方案评审资料的图一律用 Mermaid只有需要给客户做高保真、强视觉冲击力的 PPT 展示图时才用专业的绘图软件精修。两者分工明确。1.2 这一套语法能覆盖哪些常用图型很多人以为 Mermaid 只能画普通的“方框箭头”流程图实际它能画的类型相当多我列几个最常用的图表类型语法关键字典型使用场景流程图graph / flowchart业务逻辑、模块调用、算法步骤时序图sequenceDiagram接口交互、分布式事务、登录鉴权状态图stateDiagram-v2订单状态流转、任务状态机ER 图erDiagram数据库表设计、数据模型评审甘特图gantt项目排期、迭代计划思维导图mindmap需求拆解、知识梳理统计饼图pie占比展示用户旅程图journey用户操作路径分析类图classDiagram面向对象设计、代码结构说明BPMN 图bpmn业务流程建模与流程引擎设计你可以从热词里看到不少人在搜“用户管理模块流程图”“MyBatis 中 TypeHandler 的工作流程图”“BFS 和 DFS 算法流程图”这些场景用上面任意一种图型基本都能覆盖。尤其是 BPMN 里的网关Gateway概念Mermaid 也能用菱形判断节点近似表达虽然不如专业 BPMN 工具严谨但用来做开发设计沟通完全够用。2. 基础语法精讲从第一张图到能表达复杂逻辑2.1 方向、节点形状与连线规则Mermaid 流程图语法非常简单核心就三件事声明方向、定义节点、画连线。声明方向写在最前面graph TD其中字母代表布局方向TD / TB从上到下LR从左到右RL从右到左BT从下到上我习惯用 TD 画业务流程用 LR 展示模块调用关系。左到右的图在屏幕较窄时容易横向溢出实际排版时优先考虑 TD。定义节点时方括号就是普通矩形圆括号表示圆角矩形花括号表示菱形判断节点双层括号表示圆形graph TD A[普通矩形节点] B(圆角矩形节点) C{条件判断节点} D[(数据库节点)]连线分几种A -- B带箭头实线最常用A --- B不带箭头实线A -.- B带箭头虚线一般表示可选或异步路径A B带箭头粗线表示主流程或强依赖A -- 文字 -- B带文字标签的连线A --|yes| B用管道符加标签效果等价组合写就是graph TD A[开始] -- B{判断是否登录} B -- 是 -- C[进入首页] B -- 否 -- D[跳转登录页]这段代码你要是从来没接触过 Mermaid也能直接看懂一个“开始”节点连到“判断是否登录”的菱形两条分支分别指向“进入首页”和“跳转登录页”。实际渲染出来的效果就是标准的流程图。2.2 条件分支、循环与子图的表达业务流程里最复杂的就是各种分支和循环。分支用菱形节点加多条连线即可比如订单超时场景graph TD A[创建订单] -- B{30分钟内是否支付} B -- 是 -- C[进入待发货] B -- 否 -- D[自动取消订单] D -- E[通知用户]循环怎么画Mermaid 没有专门的循环语法但可以用“回边”表达即从后置节点再连回前面的判断节点。比如重试机制graph TD A[调用外部接口] -- B{调用是否成功} B -- 成功 -- C[处理响应] B -- 失败 -- D{重试次数是否小于3} D -- 是 -- A D -- 否 -- E[记录异常并告警]这里“D-- 是 -- A”就是一条回边渲染后能看到一个清晰的循环结构。当图里的节点比较多时一定要用子图来分组。子图语法是 subgraph 子图标题 endgraph TD subgraph 用户端 A[用户下单] B[在线支付] end subgraph 服务端 C[校验订单] D[扣减库存] end A -- B B -- C C -- D子图在视觉上会给同一组节点加一个外框特别适合表达“哪个模块负责哪些动作”。我在画用户管理模块流程图时就习惯把前端操作放一个子图后端接口放一个子图权限校验单独放一个子图整体复杂度一下就降下来了。2.3 样式定制与主题切换默认渲染其实已经够用但如果要放进正式评审文档可以稍作美化。单个节点用 style 指定graph TD A[开始] -- B[处理] style A fill:#e1f5fe,stroke:#0288d1,stroke-width:2px style B fill:#f3e5f5,stroke:#7b1fa2多节点统一风格用 classDef 和 classgraph TD classDef success fill:#c8e6c9,stroke:#2e7d32 classDef danger fill:#ffcdd2,stroke:#c62828 A[校验通过]:::success -- B[校验失败]:::danger类名还可以直接加在节点上配合 classDef 定义适合表达“正常流程 vs 异常流程”这种语义差异。主题层面Mermaid v10 之后支持 themeVariables但多数时候我们根本不用改直接用默认主题和 dark 主题就够。Typora 里可以设置跟随编辑器主题VS Code 预览插件也自动适配深色模式这块不用花太多时间。3. 离线环境搭建没有在线工具也能随手出图3.1 VS Code 里最顺手的渲染方案日常写 Mermaid 我首选 VS Code工作流是写 Markdown 文档Mermaid 代码块保存后自动预览。你要装的插件有两个Markdown Preview Enhanced它对 Mermaid 支持相当好还能导出 HTML、PDF、PNG。Markdown Preview Mermaid Support如果只想轻量预览流程图这个插件更省事。操作流程新建一个 .md 文件用围栏代码块包住 Mermaid 源码然后打开预览面板。Markdown Preview Enhanced 还支持右键“Export”导出图片分辨率可以配置放到接口文档里很清晰。有个小技巧如果图比较复杂开发时先单独建一个 test.md 只放这张图改起来渲染速度更快等全部调好了再复制到正式文档。预览插件每次保存都会全量刷新文档里图多了会很卡单独文件能避免这种烦扰。3.2 Typora 如何更新 Mermaid 版本很多人在 Typora 里画图时遇到过旧语法渲染报错比如 stateDiagram 不识别或者某些新特性不支持。这里先说明一个关键事实Typora 内置的 Mermaid 渲染器是打包在软件里的不能像普通 npm 包那样手动单独升级。我的建议是分三步走先确认 Typora 版本设置里打开“Markdown”查看 Mermaid 相关选项如果版本过旧升级 Typora 本身通常就能带上新版 Mermaid。如果公司环境不允许升级或者等不到官方跟进就用外部渲染替代装一个全局的 Mermaid CLI下面会讲把图导出为 PNG/SVG再拖进 Typora。平时写代码时优先用兼容性最好的基础语法因为 Typora 对某些 Mermaid 新特性的支持比官方 CLI 慢半拍比如最新的 gantt 自定义样式就别指望 Typora 能吃透。另外Typora 对 Mermaid 代码块要求必须在代码块的“语言”位置写 mermaid这个细节经常有人漏掉导致只看到源码没有图表。3.3 用命令行批量渲染导出图片如果你需要批量生成流程图或者想在 CI 里自动更新文档配图那就必须用官方 CLInpm install -g mermaid-js/mermaid-cli安装好后常用命令是这样mmdc -i input.mmd -o output.svg mmdc -i input.mmd -o output.png -w 1920 mmdc -i input.mmd -o output.pdf -b whiteinput.mmd 就是包含了 Mermaid 源码的纯文本文件注意文件里只要写代码本身不用写围栏代码块的三个反引号。第一次运行时 CLI 会拉取无头浏览器Puppeteer 相关依赖国内网络环境下可能比较慢设置一下 npm 镜像源就能解决。渲染 PDF 或 PNG 时建议加 -b white 指定背景色否则默认透明背景在部分文档软件里显示发灰。CLI 方案配合脚本就能做到“Markdown 里改了图源文件构建时自动导出新图替换旧图”我把它接进了一个内部知识库的构建流程里效果比手动截图省心太多。4. 高频实战案例拆解直接可以抄的三张图4.1 用户管理模块流程图角色、权限与操作闭环“用户管理模块流程图”能上热搜说明这是个被反复画的图而且往往画的时候没有标准答案。我给出一个我在后台管理系统中常用的版本覆盖了用户的增删改查和权限控制。graph TD subgraph 前端操作 A[用户登录] -- B{是否已认证} B -- 否 -- C[返回登录页] B -- 是 -- D[进入用户管理页面] D -- E[查询用户列表] D -- F[新增用户] D -- G[编辑用户] D -- H[禁用/启用用户] end subgraph 后端服务 E -- I[GET /api/users] F -- J[POST /api/users] G -- K[PUT /api/users/:id] H -- L[PATCH /api/users/:id/status] end subgraph 权限校验 I -- M{是否有 list 权限} J -- M K -- M L -- M M -- 无权限 -- N[返回 403] end I -- O[分页查询数据库] J -- P[校验参数并落库] K -- Q[更新用户信息] L -- R[更新用户状态]这张图的思路是“纵向三段式”上面是操作入口、中间是接口、下面是权限和数据处理。权限校验我特意画在接口之后这符合大多数后台系统的真实逻辑先路由到接口层在进入业务逻辑前做鉴权。画图时别把权限画成每个操作前都挂一个大菱形那样图会变得没法看统一收敛到一个判断节点上语义更清楚。如果你用的是若依这类开源框架还可以把“角色管理”“部门管理”继续扩展成子图挂在用户管理旁边。这种图最大的价值不是美术效果而是能让前后端开发对齐“页面操作到底调用了哪个接口、经过哪些权限校验”。4.2 算法流程图整除判断与 BFS/DFS 遍历现在很多计算机相关课程都要求学生手画算法流程图经常有人搜“判断一个数 n 能否同时被 3 和 5 整除”这类题目。这种题用 Mermaid 画其实是最快的graph TD A[开始] -- B[输入整数 n] B -- C{n % 3 0 ?} C -- 否 -- D[输出不能同时被3和5整除] C -- 是 -- E{n % 5 0 ?} E -- 否 -- D E -- 是 -- F[输出可以同时被3和5整除] F -- G[结束] D -- G这里的关键点是“两个判断串行”先判断能否被 3 整除再判断能否被 5 整除。很多新手会直接写“n % 3 0 n % 5 0”画图时也想用一个判断节点表达但流程图要表达的是“计算过程中的判断序列”所以拆成两步更符合课程要求。再来看 BFS 和 DFS 的算法流程图。BFS 是层序遍历核心是队列graph TD A[将起始节点入队] -- B{队列是否为空} B -- 空 -- C[遍历结束] B -- 非空 -- D[队首节点出队] D -- E[访问该节点并标记] E -- F[将该节点的所有未访问邻居入队] F -- BDFS 则是递归或栈graph TD A[从起始节点开始] -- B{当前节点是否已访问} B -- 是 -- C[返回上一层] B -- 否 -- D[标记当前节点为已访问] D -- E[处理当前节点] E -- F[依次递归访问未被访问的邻居] F -- B这两张图放在一起对比着看队列和栈的差异在流程结构上一目了然BFS 的流程是“入队出队循环”DFS 的流程是“递归进入、回溯返回”。面试准备时用 Mermaid 画完这两张图比纯文字背步骤牢固得多。4.3 MyBatis TypeHandler 工作流程图源码级梳理MyBatis 的 TypeHandler 是很多人学 ORM 框架时的一堵墙因为它的工作横跨 JDBC 层的 setParameter 和 getResult。被搜到说明大家都在找现成的图我自己整理过一个精简版核心是两条主线graph TD subgraph 写操作 setParameter A[PreparedStatement 设置参数] -- B{TypeHandler 是否存在} B -- 不存在 -- C[使用 UnknownTypeHandler 反射判断] B -- 存在 -- D[调用 typeHandler.setParameter] D -- E[ps.setXxx 写入 JDBC] end subgraph 读操作 getResult F[从 ResultSet 读取列值] -- G{ResultSet 类型} G -- 普通列 -- H[调用 typeHandler.getResult] G -- 游标/存储过程 -- I[调用 getResult 对应重载] H -- J[返回 Java 对象] end A -. 持有 Handler. -- D F -. 查找 Handler. -- H这张图里最值得注意的点是“UnknownTypeHandler 反射判断”这个分支这是很多人没搞懂的细节当 MyBatis 没有为字段配置显式 TypeHandler 时会走一个隐式的类型解析过程先通过 Java 类型和 JdbcType 匹配内置 handler匹配不上才会报错。把这个分支画进流程图比直接在代码里看逻辑更容易记住。顺带说一下“MyBatis 中 XMLConfigBuilder 的工作流程图”。XMLConfigBuilder 的核心工作是从 XML 配置里解析出 Configuration 对象解析 settings、typeAliases、plugins、mappers 等节点。画这种源码级流程图的建议是不要画到方法调用那种粒度而是画“配置节点→解析器→配置对象”这个层面的流转比如graph LR A[XMLConfigBuilder] -- B{解析 mapper 节点} B -- C[XMLMapperBuilder] C -- D{解析 statement 节点} D -- E[XMLStatementBuilder] E -- F[添加到 Configuration]这类图的价值在于理解 MyBatis 的分层委派设计四个 Builder 类各有分工画完你对源码的脉络会清晰很多。5. 常见问题与排查技巧实录5.1 渲染失败先检查这三类原因Mermaid 渲染失败的报错信息有时候比较抽象我在实战中总结了三个高频原因基本覆盖九成问题。症状常见原因处理方法整段代码原样输出没有图表代码块标记不是 mermaid或平台不支持 MermaidTypora/VS Code 中确认围栏语言写 mermaidGitHub 仓库直接在 .md 里写即可提示语法错误指向某个特殊字符节点文字里含有引号、括号未转义节点文字中的双引号改成单引号或者去掉圆括号文字改用引号包裹图能渲染但逻辑线混乱方向设置不合理或没有使用子图分组长图用 subgraph 分组优先 TD 布局具体来说最容易踩的坑是节点文字里带括号。比如你想写“调用接口(带重试)”如果直接写在方括号里Mermaid 会把括号当成语法结构的一部分导致解析错乱。解决办法是把节点文字用双引号包起来graph TD A[调用接口(带重试)] -- B[处理结果]另外中文逗号和中文分号在部分旧版本里也会引起诡异问题我现在的习惯是节点文字里尽量用空格或顿号代替逗号省得排查半天。5.2 中文乱码、字体发虚与图片导出问题Mermaid 在浏览器里渲染中文一般没问题但通过 CLI 导出 PNG 时偶尔出现中文乱码或方块字这本质是 Puppeteer 调用的无头浏览器缺少中文字体。解决步骤# Ubuntu/Debian 安装中文字体 apt-get install fonts-noto-cjk # CentOS 安装中文字体 yum install wqy-zenheiWindows 和 macOS 本地环境一般没问题CI 服务器上容易踩这个坑。CLI 导出 PNG 时如果觉得字太小可以用 -s 参数缩放倍数比如 -s 2 输出双倍分辨率再插入文档清晰度会好很多。5.3 图太大放不下布局优化三板斧流程图越来越大时默认渲染会显得拥挤。我一般按顺序做三件事调整方向左右往下的图拉太长改成 LR 试试上下结构过长就换回 TD。拆子图把超过 15 个节点的图拆成两张或者引入 subgraph 布尔分组让视觉上有“区”的概念。用注释和换行保持可读性Mermaid 支持 %% 注释我在每个子图前面都会写一行注释说明这块的职责别人接手时不用逐行猜。特别提醒一句Mermaid 里换行可以通过标签实现但并不是所有渲染环境都支持Typora 和 VS Code 的插件基本没问题碰到不支持的环境就退回到短文本节点。5.4 版本差异为什么同一段代码在不同的地方效果不一样这是最容易被忽视的坑。Mermaid 从 v8 到 v10 的语法演进过程中部分旧写法被移除。比如状态图早期用 stateDiagramv10 推荐 stateDiagram-v2流程图早期支持 graph现在也兼容 flowchart但有些新特性只在 flowchart 关键字下生效。我给你的建议是- 通用场景统一用 graph 和 flowchart 都兼容的最小语法子集别用冷门特性。遇到“我的代码在官网示例里能跑在 Typora 里报错”先确认 Typora 内置版本再决定是降级语法还是换渲染工具。团队协作时把 Mermaid 版本写进文档规范大家用同一个渲染环境减少“我这里正常你那里报错”的争议。一些使用习惯与收尾做 Mermaid 这几年我最深的一个体会是它强在“图和代码共生”的形态而不是画面多精美。因此真正提高效率的关键不在多复杂的语法而在于画图前的结构设计——先想清楚有几个子模块、哪些判断是关键路径、哪些分支是异常路径再用 text 把结构表达出来最后微调样式。实际操作中可以在源码里写 %% 注释记录改动原因这样每次更新流程时你还能看出当时为什么这么改。最后补充一个小技巧写完一张重要流程图后顺手点一次 CLI 导出 PDF 放在附件目录既方便评审也能当备份。这套流程你坚持用两周再回头看那些纯拖拽式的画图工具大概率就回不去了。