做技术文档这件事我这些年最大的感受就是图的维护成本往往比文字高得多。以前画架构图用一个独立的绘图文件负责人一离职图就没人会改了后来用独立工具画完截图贴进Markdown文字改了图对不上评审时发现一堆过期的图。直到我把整个流程收敛到VSCode Markdown Preview Mermaid Support这套组合里用Mermaid语法直接在文档源码里写图才终于摆脱了图滞后于文的困境。这篇文章不打算泛泛介绍Mermaid而是聚焦在最实用但也最容易被忽略的classDef布局样式语法上——它解决的问题是如何让一张十来二十个节点的流程图不靠手工一个个调颜色也能呈现出清晰、统一、可维护的视觉分层。适合正在用或准备用VSCode写技术文档、维护架构图、做项目汇报材料的人参考。1. 插件认知与安装配置1.1 先搞清楚这个插件解决什么问题Markdown Preview Mermaid Support是VSCode扩展市场里的一个轻量级插件核心能力只有一条让VSCode自带的Markdown预览器认得mermaid代码块并把里面的内容渲染成图表。没有它你在.md文件里写的Mermaid代码只会原样显示成一段灰底代码块装上它之后保存文档的瞬间预览区就会变成SVG矢量图。这看起来很简单但实际解决的是一个很痛的协作问题。团队里技术负责人要看文档产品经理也要看文档如果你贴的是截图他们只能看、不能改想调整一个节点位置还得专门发消息让你改完再导出一遍。而所有参与方都共用同一个Markdown源文件时图本身就是代码谁都能基于源码做修改diff也清清楚楚。同类插件里还有一个功能更强的Markdown Preview EnhancedMPE。MPE能做目录、数学公式、自定义CSS、PDF导出但在Mermaid渲染上反而容易出问题——它内置的Mermaid版本更新节奏不受VSCode控制有时候你在本地用了新语法MPE的预览还在用旧版本解析。反观Markdown Preview Mermaid Support定位更专一跟VSCode原生预览的集成更自然插件更新也更勤快。我的结论是如果只是需要Mermaid渲染选它如果确实需要MPE的高级能力也别让MPE管Mermaid把这部分交给专门插件。1.2 安装与预览三步走具体安装步骤打开VSCode使用快捷键CtrlShiftX进入扩展面板搜索关键词“mermaid”。在结果里找到“Markdown Preview Mermaid Support”确认名称一致后点击Install。安装完成后按CtrlShiftP输入“Reload Window”并回车重载当前窗口让插件生效。然后随便建一个test.md文件写一个最简单的图表graph TD A[开始] -- B[结束]按CtrlShiftV打开预览右侧就会出现对应的流程图。这里有一个很多人忽略的细节VSCode的Markdown预览有两种触发方式CtrlShiftV是在当前标签页旁边打开预览CtrlK V则是把预览独立到另一个标签组。对于长文档后者更舒服你可以把预览区固定在另一个屏幕滚动文档时预览区也能同步滚动。另一个细节是workspace的问题。如果你是用File - Open File直接打开单个md文件而不是通过Open Folder打开整个项目目录插件在某些VSCode版本里会出现预览空白。这跟扩展的激活时机有关——单文件的workspace缺少完整激活插件依赖的上下文。我踩过一次这个坑之后换成以文件夹方式打开文档所在目录就再没复发过。离线环境也有套路。内网机器上扩展市场经常不可用这时可以去VSCode Marketplace页面搜索该插件下载对应版本的.vsix文件拷贝进内网后在扩展面板右上角选择Install from VSIX...选择文件即可完成安装。这个流程不需要外网只需要同版本的VSIX文件属于很实用的一招。如果你需要批量渲染文档里的Mermaid还可以用Mermaid官方的命令行工具mermaid-cli即mmdc在本地用Node.js把代码块转成SVG或PNG这条路线也能完全脱离VSCode工作。1.3 使用前值得知道的配置项插件开箱即用但还是有几个设置项值得提前了解能省掉不少排查时间。第一个是markdown-preview-mermaid-support.mermaid.flowchart.curve。它控制流程图中连线的弯曲算法。默认值是basis也就是贝塞尔曲线连线比较圆滑对于一些节点多、连线密的流程图这种弯来弯去的曲线反而干扰阅读。把它改成linear后所有边变成直线连接视觉上会清爽很多。配置写在settings.json里{ markdown-preview-mermaid-support.mermaid.flowchart.curve: linear }第二个是主题。Mermaid支持多种渲染主题default、neutral、dark、forest、base等。你可以在文档里通过初始化指令覆盖%%{init: {theme: base, themeVariables: {primaryColor: #fff}}}%%如果你发现图渲染出来的颜色和你预期的完全不同优先检查文档里有没有这类init指令或者插件默认主题是不是和你的文档风格冲突而不是一上来就怀疑classDef写错了。第三个是安全相关。VSCode的Markdown预览默认不允许脚本执行这个插件通过iframe和脚本白名单的方式实现Mermaid渲染。当你在文档里用了比较激进的配置——比如自定义htmlLabels或者嵌入HTML——一旦预览报安全错误先升级VSCode到较新版本。老版本对这类特性的支持不完善升级一般能解决。提示如果同时装了MPE和Markdown Preview Mermaid Support右键md文件时会看到多个Open Preview选项。选任何一个都能预览但Mermaid能不能渲染取决于当前预览器归属哪个插件。我的建议是只保留一个Markdown预览扩展避免两个预览器互相抢活。2. Mermaid与classDef的基本功2.1 一分钟看明白Mermaid流程图Mermaid的语法设计哲学是“用最简单的文本描述节点和关系”。一个流程图由三要素组成节点、连线、方向。方向用graph后面的TD、LR、BT、RL声明分别表示从上到下、从左到右、从下到上、从右到左。节点需要用括号决定形状A[文本]普通矩形适合处理步骤。A(文本)圆角矩形适合开始、结束等出入口。A{文本}菱形适合判断分支。A[[文本]]双侧竖线矩形适合子流程调用。A[(文本)]圆柱体适合数据库。A((文本))圆形适合起点终点。连线符号也需要会读A -- B带箭头实线表示有向依赖或流程走向。A --- B不带箭头实线。A -.- B带箭头虚线适合弱关系或可选路径。A B粗箭头适合强调主流程。A -- 文字 -- B带标签的连线。这些基础语法不是这篇的重点但不先交代清楚后面讲classDef时你很难在脑海里建立“节点到底长什么样”的坐标系。classDef不管连线只管节点的“皮肤”连线的样式是另一套体系用linkStyle控制两者分工明确。2.2 为什么需要classDef而不是逐个style很多新手第一次接触Mermaid时用的是style语句style A fill:#f96,stroke:#333,color:#fffstyle的问题在节点少时还好但很快会暴露两个问题。大的问题是不可复用一个图里如果有一批节点需要高亮就得复制同样多的style行改颜色时也要逐行改这跟把CSS写进内联样式没什么区别。小的问题是语义混乱只看style代码你根本看不出这些节点为什么被涂成红色——它们属于关键路径出错分支还是外部接口完全没有语义信息。classDef把“样式”和“语义”绑在了一起。你可以定义一个叫danger的类classDef danger fill:#ffebee,stroke:#c62828,color:#b71c1c;然后在图里把任何节点标为dangerclass A,G,H danger;这样就建立了一个可以反复使用的视觉约定。所有标为danger的节点都是异常或风险路径看源码的人即使不理解图中的业务细节也能从类名推断出视觉含义。这种“类即语义”的方式让图的样式可维护性和可读性同时提升代价仅仅是多学一条classDef语法。2.3 classDef语法拆解与样式属性清单classDef的完整语法classDef className attr1:value1, attr2:value2, ...;它和CSS很像先起一个类名然后用冒号定义属性用逗号分隔不同属性末尾分号结束。定义完之后有三种方式把节点归入这个类。方式一单独一行归组class A,B,C className;方式二在节点定义时直接追加:::类名A[文本]:::highlight -- B[另一节点]方式三与classDef default结合把整个图的默认样式设置成某个类。很多美化需求的标准解法就是它。最常用的属性清单如下表属性作用示例值fill填充色fill:#ffffffstroke边框颜色stroke:#333333color文字颜色color:#000000stroke-width边框粗细stroke-width:2pxstroke-dasharray边框虚线间隔stroke-dasharray:5,5rx / ry圆角半径rx:8font-weight文字粗细font-weight:boldfont-style字体风格font-style:italicopacity透明度opacity:0.6使用属性时要特别注意Mermaid的classDef样式值遵循CSS语法但有自己的兼容口径。我的经验是尽量用十六进制颜色比如fill:#ffffff不要用rgba()或hsl()因为老版渲染器对这些CSS颜色函数的解析经常出问题颜色不生效时排查起来非常抓狂。还有个常见需求——把节点边框变成虚线语法是stroke-dasharray:5,5注意是ASCII半角逗号直接照抄即可。关于节点框大小的问题这里也给一个明确结论classDef没有width或height属性框的大小由节点文本和字体渲染决定。想让框显得更大可以在节点文字里加几个全角空格或者用换行撑高想同时影响字号用font-size属性。不要试图用width/heightMermaid根本不支持。再补一个细节classDef支持“默认类”。写法是把类名写成defaultclassDef default fill:#ffffff,stroke:#333333,color:#000000;这样全图未显式指定类的节点都会变成白底黑字。这正是网上有人问“Mermaid编辑器中设置所有节点为白底黑字的语句”时的标准答案。default类定义之后仍然可以用其他classDef或class语句覆盖个别节点非常灵活。如果你的Mermaid版本比较老这个写法不生效那就手动把所有节点挂同一个类效果一样。3. 从简单到复杂的三档实战3.1 给流程图上“语义色”先说一个可以直接抄作业的场景支付系统下单流程。我需要把主流程、判断、异常三种角色用颜色区分但整体观感不能乱。graph TD A[用户提交订单] -- B{库存校验} B --|通过| C[扣减库存] C -- D[创建支付单] D -- E[调起支付] E --|支付成功| F[更新订单状态] E --|支付失败| G[订单标记未支付] B --|不通过| H[返回库存不足] classDef normal fill:#fff,stroke:#333,color:#000; classDef process fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20; classDef judge fill:#fff3e0,stroke:#ef6c00,color:#e65100; classDef error fill:#ffebee,stroke:#c62828,color:#b71c1c; class A normal; class C,D,F process; class B,E judge; class G,H error;我在实际维护这类图时有个习惯把所有classDef集中放在图定义的最上方节点和边写在中间class归组写在最后。这样后面看源码的人第一眼能看见图例式的样式约定接着读完业务逻辑最后看到哪个节点属于哪个类思路非常清晰。这里再补充一个真实经验classDef是为“语义”服务的不是为“装饰”服务的。我早期也干过把节点涂成七彩虹的事结果图看着花里胡哨信息层级反而更乱了。后来收敛到三到四种语义色每种颜色对应一种角色图的阅读效率反而大幅提升。3.2 子图与模块架构图的批量样式Mermaid的subgraph可以当成一个区域容器。把一组节点包进去图就形成了模块边界。classDef并不直接作用于subgraph但它可以通过给subgraph里面的节点挂类达到间接区分模块的效果。来看一个微服务调用的例子graph LR subgraph gateway[网关层] A[API Gateway] end subgraph order[订单服务] B[订单Controller] C[订单Service] end subgraph pay[支付服务] D[支付Service] E[支付回调] end A -- B B -- C C -- D E -- C classDef gw fill:#e3f2fd,stroke:#1565c0,color:#0d47a1; classDef ord fill:#fff3e0,stroke:#ef6c00,color:#e65100; classDef pay fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20; class A gw; class B,C ord; class D,E pay;这样每个节点都会按所属模块被染上不同颜色同一模块内的节点自然视觉统一。子图本身的样式需要单独用style例如style gateway fill:#f5f5f5,stroke:#333给子图容器加浅灰背景和边框。子图容器与节点是两套样式体系这是最容易踩晕的地方classDef管节点style管子图两者不能互相顶替。如果嫌手动给每个节点挂类太啰嗦可以在每个subgraph内部直接使用:::subgraph order[订单服务] B[订单Controller]:::ord C[订单Service]:::ord end不过我个人还是推荐用单独class语句集中管理因为当节点数增多时把所有挂类关系集中在文件尾部比散落在各个节点定义行里更好审查和diff。3.3 大型架构图的classDef维护策略当图超过三四十个节点classDef的管理价值就完全体现了。说一个我在某个内部系统的架构图上的实际组织方式core类黄色粗边框表示核心交易链路。new类灰色虚线表示规划中、尚未上线的模块。db类紫底表示各类存储服务。ext类粉底表示外部依赖系统。对应的classDef定义这样组织classDef core fill:#fff9c4,stroke:#f57f17,color:#000,stroke-width:2px; classDef new fill:#fff,stroke:#ccc,color:#999,stroke-dasharray:4 4; classDef db fill:#ede7f6,stroke:#5e35b1,color:#311b92; classDef ext fill:#fce4ec,stroke:#c2185b,color:#880e4f;整个图有60多个节点但样式控制只有这四行。任何一次迭代需要把某个节点从“规划中”改成“已上线”我要做的就是从new类的列表里移除它加进core类的列表。这种维护方式还有两个附带优势。第一diff非常干净代码评审时看到的就是一行class归组的变更而不是整块样式代码的翻动。第二可以沉淀成团队规范把常用的classDef定义放在一个公共md文件片段里新成员写图时直接复制就能保证整个仓库的图表风格一致。以上是内容层面的经验。如果你追求的是布局更精细、位置更可控比如指定节点坐标、控制连线折点Mermaid其实不是最合适的工具。classDef擅长的是视觉风格统一而不是精确排版。遇到这些需求我会先用Mermaid画出大体结构导出SVG后再用专业图形工具做微调然后把最终图当作图片放进文档。如果一定要在源码层面精确控制布局那就应该考虑PlantUML的布局控制或专业的图形库而不是硬磕Mermaid。4. 常见问题与排查技巧4.1 classDef不生效的三大原因classDef写好了但节点没变化这大概是使用率最高的一个问题。根据我的排查经验九成以上跑不出几个原因。第一个是分号问题。classDef语句的末尾分号不能省略尤其在样式值里含有逗号或空格时classDef done fill:#fff,stroke:#333,stroke-dasharray:5 5;如果把末尾分号漏了Mermaid解析器很可能把后面的内容吞进样式值里导致整段classDef失效甚至整张图渲染失败。我在写classDef时一定会带上结尾分号这算是我能给出的最朴素的建议。第二个是类名大小写不一致。classDef important定义的是important后面写class A,B important时如果写成Important那就是另一个类样式自然不会生效。:::挂类也一样A[节点]:::important和A[节点]:::Important是两个类。遇到不生效先把两处的类名逐字对齐。第三个是classDef被放在了解析器不期望的位置。比如在一个流程图的节点语句之间硬插入classDef有些版本的解析器会直接报错。我的约定是把所有classDef放在graph声明之后、节点语句之前如果实在想放后面也要确保它们独立成行而不是夹在连线和节点中间。补充一个容易混淆的点如果某个节点既被style定义又被classDef挂类style会优先覆盖classDef的效果。这是有意设计但也是排查时容易忽略的地方。我的处理原则是图上个别需要特殊强调的节点单独用style其余一律走classDef统一管理。4.2 预览不渲染的排查顺序预览不渲染这个问题即便用了插件多年的人也会遇到。我的排查顺序是固定的。第一步看代码块的InfoString是否准确是mermaid。有时从网页或聊天工具复制的代码块会出现mermaid前后带空格、或变成mermaid-foo的情况预览器不认识这个语言类型自然不渲染。第二步看预览标签页是否真的对应这个插件。如果同环境装了多个Markdown预览插件比较容易打开的是MPE的预览标签页。MPE本身也有Mermaid支持但它的默认渲染状态和原生预览不一致。看预览标签页标题和插件状态栏图标能判断当前是哪家的预览。第三步打开开发者工具看Console。把焦点放到预览面板按CtrlShiftI进入开发者工具切到Console标签查看有没有红色的Mermaid解析错误。这里最常见的情况是语法版本不兼容——本地插件版本比较老而文档里用了新版语法旧解析器直接拒绝渲染。升级插件到最新版基本可以解决。第四步如果Console没有报错但图还是空的那么大概率是初始化配置出了问题。比如代码块顶部写了%%{init: {theme: dark}}%%但某个配置项拼写有误或值不合法Mermaid会静默失败。我的做法是暂时删掉init行先用纯语法看能否渲染。能渲染就说明是配置问题逐个配置项放回去很快能定位。4.3 导出协作与团队规范建议做文档不只是写给自己看还要交付给同事、领导甚至外部客户。Mermaid渲染出来是SVG在这方面有几点经验。如果只是贴到Wiki或群里直接截屏最快。因为SVG是矢量图形截屏在高DPI屏幕上也很清晰完全够用。如果需要更高精度的交付物可以在预览面板中手动拷贝SVG源码保存成.svg文件后续用专业工具做进一步编辑。如果文档要打印深色背景的图会费墨打印出来也容易糊。我在准备纸质材料时会临时把classDef统一改成白底黑字或浅色系等打印完再改回来。也可以利用default类做一套打印专用样式classDef default fill:#fff,stroke:#000,color:#000; classDef core fill:#fff,stroke:#000,color:#000,stroke-width:2px;团队协作层面我建议在仓库的docs目录下准备一个markdown片段里面只放一份标准的classDef定义和类名注释比如“core表示核心链路、new表示规划中”。所有人写新图时复制这份头。这种做法执行起来很简单但对文档体系的一致性帮助特别大。一张图能不能让读者快速理解往往就取决于这类约定有没有被统一遵守。最后聊点个人体会。classDef这东西单独看只是一条样式语法但真正用顺手之后它会倒逼你想清楚图的语义结构。以前我画图是先想有哪些节点再想怎么连现在我会先想这一张图里有哪几类角色的节点每类用一个classDef然后再往里面填具体节点。这个顺序一旦调转过来画图速度不但没变慢反而因为色彩语义清晰连错误都更容易暴露——某个异常节点忘了挂error类一眼就能从颜色缺失上发现。再分享一个我坚持了很久的小技巧在文档或者仓库的公共模板里保留一段“图例”节点。也就是把一个不参与业务链路的角落节点故意挂上每一类classDef让读者一打开文档就能看到每种颜色代表什么意思。这个图例节点本身不连接任何流程渲染出来只是几个示意色块但它的存在能大幅度降低其他人理解图的门槛。配合Markdown Preview Mermaid Support的实时预览团队成员打开文档后两三秒内就能建立对全文档视觉约定的认知。这个方法不复杂难的是坚持在每一份文档里都放如果能做到整个团队的文档可读性会上一个台阶。
做技术文档这件事我这些年最大的感受就是图的维护成本往往比文字高得多。以前画架构图用一个独立的绘图文件负责人一离职图就没人会改了后来用独立工具画完截图贴进Markdown文字改了图对不上评审时发现一堆过期的图。直到我把整个流程收敛到VSCode Markdown Preview Mermaid Support这套组合里用Mermaid语法直接在文档源码里写图才终于摆脱了图滞后于文的困境。这篇文章不打算泛泛介绍Mermaid而是聚焦在最实用但也最容易被忽略的classDef布局样式语法上——它解决的问题是如何让一张十来二十个节点的流程图不靠手工一个个调颜色也能呈现出清晰、统一、可维护的视觉分层。适合正在用或准备用VSCode写技术文档、维护架构图、做项目汇报材料的人参考。1. 插件认知与安装配置1.1 先搞清楚这个插件解决什么问题Markdown Preview Mermaid Support是VSCode扩展市场里的一个轻量级插件核心能力只有一条让VSCode自带的Markdown预览器认得mermaid代码块并把里面的内容渲染成图表。没有它你在.md文件里写的Mermaid代码只会原样显示成一段灰底代码块装上它之后保存文档的瞬间预览区就会变成SVG矢量图。这看起来很简单但实际解决的是一个很痛的协作问题。团队里技术负责人要看文档产品经理也要看文档如果你贴的是截图他们只能看、不能改想调整一个节点位置还得专门发消息让你改完再导出一遍。而所有参与方都共用同一个Markdown源文件时图本身就是代码谁都能基于源码做修改diff也清清楚楚。同类插件里还有一个功能更强的Markdown Preview EnhancedMPE。MPE能做目录、数学公式、自定义CSS、PDF导出但在Mermaid渲染上反而容易出问题——它内置的Mermaid版本更新节奏不受VSCode控制有时候你在本地用了新语法MPE的预览还在用旧版本解析。反观Markdown Preview Mermaid Support定位更专一跟VSCode原生预览的集成更自然插件更新也更勤快。我的结论是如果只是需要Mermaid渲染选它如果确实需要MPE的高级能力也别让MPE管Mermaid把这部分交给专门插件。1.2 安装与预览三步走具体安装步骤打开VSCode使用快捷键CtrlShiftX进入扩展面板搜索关键词“mermaid”。在结果里找到“Markdown Preview Mermaid Support”确认名称一致后点击Install。安装完成后按CtrlShiftP输入“Reload Window”并回车重载当前窗口让插件生效。然后随便建一个test.md文件写一个最简单的图表graph TD A[开始] -- B[结束]按CtrlShiftV打开预览右侧就会出现对应的流程图。这里有一个很多人忽略的细节VSCode的Markdown预览有两种触发方式CtrlShiftV是在当前标签页旁边打开预览CtrlK V则是把预览独立到另一个标签组。对于长文档后者更舒服你可以把预览区固定在另一个屏幕滚动文档时预览区也能同步滚动。另一个细节是workspace的问题。如果你是用File - Open File直接打开单个md文件而不是通过Open Folder打开整个项目目录插件在某些VSCode版本里会出现预览空白。这跟扩展的激活时机有关——单文件的workspace缺少完整激活插件依赖的上下文。我踩过一次这个坑之后换成以文件夹方式打开文档所在目录就再没复发过。离线环境也有套路。内网机器上扩展市场经常不可用这时可以去VSCode Marketplace页面搜索该插件下载对应版本的.vsix文件拷贝进内网后在扩展面板右上角选择Install from VSIX...选择文件即可完成安装。这个流程不需要外网只需要同版本的VSIX文件属于很实用的一招。如果你需要批量渲染文档里的Mermaid还可以用Mermaid官方的命令行工具mermaid-cli即mmdc在本地用Node.js把代码块转成SVG或PNG这条路线也能完全脱离VSCode工作。1.3 使用前值得知道的配置项插件开箱即用但还是有几个设置项值得提前了解能省掉不少排查时间。第一个是markdown-preview-mermaid-support.mermaid.flowchart.curve。它控制流程图中连线的弯曲算法。默认值是basis也就是贝塞尔曲线连线比较圆滑对于一些节点多、连线密的流程图这种弯来弯去的曲线反而干扰阅读。把它改成linear后所有边变成直线连接视觉上会清爽很多。配置写在settings.json里{ markdown-preview-mermaid-support.mermaid.flowchart.curve: linear }第二个是主题。Mermaid支持多种渲染主题default、neutral、dark、forest、base等。你可以在文档里通过初始化指令覆盖%%{init: {theme: base, themeVariables: {primaryColor: #fff}}}%%如果你发现图渲染出来的颜色和你预期的完全不同优先检查文档里有没有这类init指令或者插件默认主题是不是和你的文档风格冲突而不是一上来就怀疑classDef写错了。第三个是安全相关。VSCode的Markdown预览默认不允许脚本执行这个插件通过iframe和脚本白名单的方式实现Mermaid渲染。当你在文档里用了比较激进的配置——比如自定义htmlLabels或者嵌入HTML——一旦预览报安全错误先升级VSCode到较新版本。老版本对这类特性的支持不完善升级一般能解决。提示如果同时装了MPE和Markdown Preview Mermaid Support右键md文件时会看到多个Open Preview选项。选任何一个都能预览但Mermaid能不能渲染取决于当前预览器归属哪个插件。我的建议是只保留一个Markdown预览扩展避免两个预览器互相抢活。2. Mermaid与classDef的基本功2.1 一分钟看明白Mermaid流程图Mermaid的语法设计哲学是“用最简单的文本描述节点和关系”。一个流程图由三要素组成节点、连线、方向。方向用graph后面的TD、LR、BT、RL声明分别表示从上到下、从左到右、从下到上、从右到左。节点需要用括号决定形状A[文本]普通矩形适合处理步骤。A(文本)圆角矩形适合开始、结束等出入口。A{文本}菱形适合判断分支。A[[文本]]双侧竖线矩形适合子流程调用。A[(文本)]圆柱体适合数据库。A((文本))圆形适合起点终点。连线符号也需要会读A -- B带箭头实线表示有向依赖或流程走向。A --- B不带箭头实线。A -.- B带箭头虚线适合弱关系或可选路径。A B粗箭头适合强调主流程。A -- 文字 -- B带标签的连线。这些基础语法不是这篇的重点但不先交代清楚后面讲classDef时你很难在脑海里建立“节点到底长什么样”的坐标系。classDef不管连线只管节点的“皮肤”连线的样式是另一套体系用linkStyle控制两者分工明确。2.2 为什么需要classDef而不是逐个style很多新手第一次接触Mermaid时用的是style语句style A fill:#f96,stroke:#333,color:#fffstyle的问题在节点少时还好但很快会暴露两个问题。大的问题是不可复用一个图里如果有一批节点需要高亮就得复制同样多的style行改颜色时也要逐行改这跟把CSS写进内联样式没什么区别。小的问题是语义混乱只看style代码你根本看不出这些节点为什么被涂成红色——它们属于关键路径出错分支还是外部接口完全没有语义信息。classDef把“样式”和“语义”绑在了一起。你可以定义一个叫danger的类classDef danger fill:#ffebee,stroke:#c62828,color:#b71c1c;然后在图里把任何节点标为dangerclass A,G,H danger;这样就建立了一个可以反复使用的视觉约定。所有标为danger的节点都是异常或风险路径看源码的人即使不理解图中的业务细节也能从类名推断出视觉含义。这种“类即语义”的方式让图的样式可维护性和可读性同时提升代价仅仅是多学一条classDef语法。2.3 classDef语法拆解与样式属性清单classDef的完整语法classDef className attr1:value1, attr2:value2, ...;它和CSS很像先起一个类名然后用冒号定义属性用逗号分隔不同属性末尾分号结束。定义完之后有三种方式把节点归入这个类。方式一单独一行归组class A,B,C className;方式二在节点定义时直接追加:::类名A[文本]:::highlight -- B[另一节点]方式三与classDef default结合把整个图的默认样式设置成某个类。很多美化需求的标准解法就是它。最常用的属性清单如下表属性作用示例值fill填充色fill:#ffffffstroke边框颜色stroke:#333333color文字颜色color:#000000stroke-width边框粗细stroke-width:2pxstroke-dasharray边框虚线间隔stroke-dasharray:5,5rx / ry圆角半径rx:8font-weight文字粗细font-weight:boldfont-style字体风格font-style:italicopacity透明度opacity:0.6使用属性时要特别注意Mermaid的classDef样式值遵循CSS语法但有自己的兼容口径。我的经验是尽量用十六进制颜色比如fill:#ffffff不要用rgba()或hsl()因为老版渲染器对这些CSS颜色函数的解析经常出问题颜色不生效时排查起来非常抓狂。还有个常见需求——把节点边框变成虚线语法是stroke-dasharray:5,5注意是ASCII半角逗号直接照抄即可。关于节点框大小的问题这里也给一个明确结论classDef没有width或height属性框的大小由节点文本和字体渲染决定。想让框显得更大可以在节点文字里加几个全角空格或者用换行撑高想同时影响字号用font-size属性。不要试图用width/heightMermaid根本不支持。再补一个细节classDef支持“默认类”。写法是把类名写成defaultclassDef default fill:#ffffff,stroke:#333333,color:#000000;这样全图未显式指定类的节点都会变成白底黑字。这正是网上有人问“Mermaid编辑器中设置所有节点为白底黑字的语句”时的标准答案。default类定义之后仍然可以用其他classDef或class语句覆盖个别节点非常灵活。如果你的Mermaid版本比较老这个写法不生效那就手动把所有节点挂同一个类效果一样。3. 从简单到复杂的三档实战3.1 给流程图上“语义色”先说一个可以直接抄作业的场景支付系统下单流程。我需要把主流程、判断、异常三种角色用颜色区分但整体观感不能乱。graph TD A[用户提交订单] -- B{库存校验} B --|通过| C[扣减库存] C -- D[创建支付单] D -- E[调起支付] E --|支付成功| F[更新订单状态] E --|支付失败| G[订单标记未支付] B --|不通过| H[返回库存不足] classDef normal fill:#fff,stroke:#333,color:#000; classDef process fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20; classDef judge fill:#fff3e0,stroke:#ef6c00,color:#e65100; classDef error fill:#ffebee,stroke:#c62828,color:#b71c1c; class A normal; class C,D,F process; class B,E judge; class G,H error;我在实际维护这类图时有个习惯把所有classDef集中放在图定义的最上方节点和边写在中间class归组写在最后。这样后面看源码的人第一眼能看见图例式的样式约定接着读完业务逻辑最后看到哪个节点属于哪个类思路非常清晰。这里再补充一个真实经验classDef是为“语义”服务的不是为“装饰”服务的。我早期也干过把节点涂成七彩虹的事结果图看着花里胡哨信息层级反而更乱了。后来收敛到三到四种语义色每种颜色对应一种角色图的阅读效率反而大幅提升。3.2 子图与模块架构图的批量样式Mermaid的subgraph可以当成一个区域容器。把一组节点包进去图就形成了模块边界。classDef并不直接作用于subgraph但它可以通过给subgraph里面的节点挂类达到间接区分模块的效果。来看一个微服务调用的例子graph LR subgraph gateway[网关层] A[API Gateway] end subgraph order[订单服务] B[订单Controller] C[订单Service] end subgraph pay[支付服务] D[支付Service] E[支付回调] end A -- B B -- C C -- D E -- C classDef gw fill:#e3f2fd,stroke:#1565c0,color:#0d47a1; classDef ord fill:#fff3e0,stroke:#ef6c00,color:#e65100; classDef pay fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20; class A gw; class B,C ord; class D,E pay;这样每个节点都会按所属模块被染上不同颜色同一模块内的节点自然视觉统一。子图本身的样式需要单独用style例如style gateway fill:#f5f5f5,stroke:#333给子图容器加浅灰背景和边框。子图容器与节点是两套样式体系这是最容易踩晕的地方classDef管节点style管子图两者不能互相顶替。如果嫌手动给每个节点挂类太啰嗦可以在每个subgraph内部直接使用:::subgraph order[订单服务] B[订单Controller]:::ord C[订单Service]:::ord end不过我个人还是推荐用单独class语句集中管理因为当节点数增多时把所有挂类关系集中在文件尾部比散落在各个节点定义行里更好审查和diff。3.3 大型架构图的classDef维护策略当图超过三四十个节点classDef的管理价值就完全体现了。说一个我在某个内部系统的架构图上的实际组织方式core类黄色粗边框表示核心交易链路。new类灰色虚线表示规划中、尚未上线的模块。db类紫底表示各类存储服务。ext类粉底表示外部依赖系统。对应的classDef定义这样组织classDef core fill:#fff9c4,stroke:#f57f17,color:#000,stroke-width:2px; classDef new fill:#fff,stroke:#ccc,color:#999,stroke-dasharray:4 4; classDef db fill:#ede7f6,stroke:#5e35b1,color:#311b92; classDef ext fill:#fce4ec,stroke:#c2185b,color:#880e4f;整个图有60多个节点但样式控制只有这四行。任何一次迭代需要把某个节点从“规划中”改成“已上线”我要做的就是从new类的列表里移除它加进core类的列表。这种维护方式还有两个附带优势。第一diff非常干净代码评审时看到的就是一行class归组的变更而不是整块样式代码的翻动。第二可以沉淀成团队规范把常用的classDef定义放在一个公共md文件片段里新成员写图时直接复制就能保证整个仓库的图表风格一致。以上是内容层面的经验。如果你追求的是布局更精细、位置更可控比如指定节点坐标、控制连线折点Mermaid其实不是最合适的工具。classDef擅长的是视觉风格统一而不是精确排版。遇到这些需求我会先用Mermaid画出大体结构导出SVG后再用专业图形工具做微调然后把最终图当作图片放进文档。如果一定要在源码层面精确控制布局那就应该考虑PlantUML的布局控制或专业的图形库而不是硬磕Mermaid。4. 常见问题与排查技巧4.1 classDef不生效的三大原因classDef写好了但节点没变化这大概是使用率最高的一个问题。根据我的排查经验九成以上跑不出几个原因。第一个是分号问题。classDef语句的末尾分号不能省略尤其在样式值里含有逗号或空格时classDef done fill:#fff,stroke:#333,stroke-dasharray:5 5;如果把末尾分号漏了Mermaid解析器很可能把后面的内容吞进样式值里导致整段classDef失效甚至整张图渲染失败。我在写classDef时一定会带上结尾分号这算是我能给出的最朴素的建议。第二个是类名大小写不一致。classDef important定义的是important后面写class A,B important时如果写成Important那就是另一个类样式自然不会生效。:::挂类也一样A[节点]:::important和A[节点]:::Important是两个类。遇到不生效先把两处的类名逐字对齐。第三个是classDef被放在了解析器不期望的位置。比如在一个流程图的节点语句之间硬插入classDef有些版本的解析器会直接报错。我的约定是把所有classDef放在graph声明之后、节点语句之前如果实在想放后面也要确保它们独立成行而不是夹在连线和节点中间。补充一个容易混淆的点如果某个节点既被style定义又被classDef挂类style会优先覆盖classDef的效果。这是有意设计但也是排查时容易忽略的地方。我的处理原则是图上个别需要特殊强调的节点单独用style其余一律走classDef统一管理。4.2 预览不渲染的排查顺序预览不渲染这个问题即便用了插件多年的人也会遇到。我的排查顺序是固定的。第一步看代码块的InfoString是否准确是mermaid。有时从网页或聊天工具复制的代码块会出现mermaid前后带空格、或变成mermaid-foo的情况预览器不认识这个语言类型自然不渲染。第二步看预览标签页是否真的对应这个插件。如果同环境装了多个Markdown预览插件比较容易打开的是MPE的预览标签页。MPE本身也有Mermaid支持但它的默认渲染状态和原生预览不一致。看预览标签页标题和插件状态栏图标能判断当前是哪家的预览。第三步打开开发者工具看Console。把焦点放到预览面板按CtrlShiftI进入开发者工具切到Console标签查看有没有红色的Mermaid解析错误。这里最常见的情况是语法版本不兼容——本地插件版本比较老而文档里用了新版语法旧解析器直接拒绝渲染。升级插件到最新版基本可以解决。第四步如果Console没有报错但图还是空的那么大概率是初始化配置出了问题。比如代码块顶部写了%%{init: {theme: dark}}%%但某个配置项拼写有误或值不合法Mermaid会静默失败。我的做法是暂时删掉init行先用纯语法看能否渲染。能渲染就说明是配置问题逐个配置项放回去很快能定位。4.3 导出协作与团队规范建议做文档不只是写给自己看还要交付给同事、领导甚至外部客户。Mermaid渲染出来是SVG在这方面有几点经验。如果只是贴到Wiki或群里直接截屏最快。因为SVG是矢量图形截屏在高DPI屏幕上也很清晰完全够用。如果需要更高精度的交付物可以在预览面板中手动拷贝SVG源码保存成.svg文件后续用专业工具做进一步编辑。如果文档要打印深色背景的图会费墨打印出来也容易糊。我在准备纸质材料时会临时把classDef统一改成白底黑字或浅色系等打印完再改回来。也可以利用default类做一套打印专用样式classDef default fill:#fff,stroke:#000,color:#000; classDef core fill:#fff,stroke:#000,color:#000,stroke-width:2px;团队协作层面我建议在仓库的docs目录下准备一个markdown片段里面只放一份标准的classDef定义和类名注释比如“core表示核心链路、new表示规划中”。所有人写新图时复制这份头。这种做法执行起来很简单但对文档体系的一致性帮助特别大。一张图能不能让读者快速理解往往就取决于这类约定有没有被统一遵守。最后聊点个人体会。classDef这东西单独看只是一条样式语法但真正用顺手之后它会倒逼你想清楚图的语义结构。以前我画图是先想有哪些节点再想怎么连现在我会先想这一张图里有哪几类角色的节点每类用一个classDef然后再往里面填具体节点。这个顺序一旦调转过来画图速度不但没变慢反而因为色彩语义清晰连错误都更容易暴露——某个异常节点忘了挂error类一眼就能从颜色缺失上发现。再分享一个我坚持了很久的小技巧在文档或者仓库的公共模板里保留一段“图例”节点。也就是把一个不参与业务链路的角落节点故意挂上每一类classDef让读者一打开文档就能看到每种颜色代表什么意思。这个图例节点本身不连接任何流程渲染出来只是几个示意色块但它的存在能大幅度降低其他人理解图的门槛。配合Markdown Preview Mermaid Support的实时预览团队成员打开文档后两三秒内就能建立对全文档视觉约定的认知。这个方法不复杂难的是坚持在每一份文档里都放如果能做到整个团队的文档可读性会上一个台阶。
