在开发团队的日常协作中流程图是一类非常“尴尬”的文档。需求评审时它很重要代码评审时它又往往没人维护产品经理改了逻辑技术负责人打开 draw.io 手动拖拽一遍三周后需求再变又拖一遍。每次调整都离不开“在图表编辑器里重绘”这个动作而这恰恰是流程图文档流失、过期、和代码对不上的根本原因。Mermaid flowcharts 提供的是另一种维护方式把流程图写成纯文本代码渲染交给 Mermaid 引擎去完成。Mermaid 是一个基于 JavaScript 的图表绘制库也定义了一套类似 Markdown 的文本语法。它的价值不在于把图画得漂亮而在于让“图的变更”可以被 git 跟踪、被代码评审、被自动校验。换句话说改一行文字流程图就变了改十行文字流程图的版本历史就完整保留了。下面的内容围绕一个核心目标展开让流程图不再依赖图表编辑器反复重绘。你会看到一个 Mermaid 流程图从语法基础、本地渲染、复杂案例、迁移方案、渲染问题排查再到团队协作规范的完整落地路径最后还有一份可以直接贴进团队的检查清单。1. 为什么流程图要在代码里维护而不是在图形编辑器里重绘1.1 图形编辑器里维护流程图的真实成本很多团队不缺少流程图缺少的是“能跟上需求变化的流程图”。在 Visio、draw.io、ProcessOn 这类图形编辑器里流程图以文件或图片形式存在表面上看很好维护实际维护成本往往被低估了。第一个成本是版本比较。图片是二进制或者私有格式两个版本之间发生了什么变化只能靠肉眼对比如果两个同事同时更新了同一份文档合并起来非常痛苦。第二个成本是业务语义丢失。图形编辑器里的节点是矩形、圆角矩形、菱形但这些形状分别代表什么业务含义并不能被搜索引擎检索也不能在评审时快速定位。第三个成本是修改成本。流程图越大手动拖拽调整连线、避开遮挡、对齐节点的时间就越长改一次图可能比写一次代码还累。对比维度图形编辑器维护Mermaid 文本维护版本 diff困难依赖人工对比容易图为纯文本可直接 diff多人协作容易冲突合并复杂可走代码评审冲突可解决修改成本高要拖拽和布局低改文本即可检索能力弱图片