Mermaid图风格统一实践：用CLI与CI让渲染回归标准化

Mermaid图风格统一实践：用CLI与CI让渲染回归标准化

发布时间：2026/9/5 23:36:28
Mermaid图风格统一实践：用CLI与CI让渲染回归标准化 最近技术社区里关于 open code、OSS 协作与 AI 编码工具的讨论明显多了起来。与之相伴的一个小话题很有意思有开发者用“艺术自由”来形容某些开放式 OSS 创作集体产出的 Mermaid 图——同一套文档体系里每张流程图风格都不一样有的节点拥挤有的配色刺眼有的方向混乱。Dex Horthy 的调侃也让“Mermaid 图渲染风格”这个细节进入了更多人的视野。相比追着这句调侃本身讨论更值得做的是把问题拆开看明白 Mermaid 图为什么会出现风格不一致、渲染结果受哪些因素控制以及在一个多人和自动生成内容的环境里如何让图表风格回归统一。本文会从概念、语法、渲染工具链和协作规范四个层面展开适合正在使用 Mermaid 写技术文档、也在尝试 AI 辅助编码的开发者阅读。1. 一句关于“Mermaid 图风格”的吐槽背后藏着什么问题Mermaid 是一种使用文本描述图表的语言。开发者通常把它写在 Markdown 文档的代码块中由渲染器转换成流程图、时序图、类图等。相比传统的可视化拖拽画图工具Mermaid 的最大优势是“图即是代码”可以进入版本管理、支持 Diff 对比、方便在代码评审中被检查和修改。开放式 OSS 创作团队之所以喜欢 Mermaid正是因为它适合多人协作任何成员都可以在文档里修改节点和连线不需要打开专业绘图软件也能通过 Pull Request 提交图表变更。而 AI 编码工具进一步拉低了生成门槛输入需求后就能返回一段 Mermaid 源码放进文档可能就直接渲染出图。但问题也随之而来。当同一个仓库里的 Mermaid 图来自不同成员、不同工具甚至不同 AI 会话时会出现明显的风格割裂有人习惯纵向布局有人使用横向布局。有人使用 Mermaid Live Editor 导出 PNG有人直接让网页端 CDN 渲染。有人使用默认主题有人手工调了节点背景色却只在自己的编辑器里生效。AI 生成的图经常结构复杂、说明性文字冗长稍不注意就会渲染成一张横向撑满屏幕、节点相互挤压的大图。这些都属于图表“渲染风格”问题。Dex Horthy 调侃的其实并不是 Mermaid 本身而是“自主化协作”场景下缺少统一约束导致代码与视觉呈现双双失控。本文从技术角度把这条线捋清楚再给出可落地的工程方案。2. Open Code 与 OSS 创作集体中的 Mermaid先厘清几个相关概念2.1 Open Code 与 OSS 创作集体可能指什么首先要说明单看“Open Code”不同语境下含义差别很大。在本文讨论的社区语境里它往往和“开源、开放协作、AI 辅助编码”绑定在一起描述的是开发者把代码、文档、Prompt 工作流放出来共享并允许他人参与共创的一种方式。OSS 创作集体则更像是“一群人基于开放源码的方式共同产出内容或软件”。它不一定指某个固定组织也可以是一种协作模式有人维护主仓库有人提交 issue有人改进文档AI 工具则负责生成初稿、补齐注释、批量画图。这三组关键词结合在一起说明现在开源协作中已经出现了一条很典型的链路社区成员或 AI 工具先产出 Mermaid 源码随后由渲染器生成图片最终呈现给用户。Mermaid 图风格不一致的问题就是这条链路里缺少中间约束层的体现。2.2 Mermaid 到底是什么Mermaid 的官方定位是基于 JavaScript 的图表绘制工具开发者使用类似 Markdown 的文本语法定义图表。一个最简单的流程图如下flowchart LR A[需求文档] -- B[Mermaid 源码] B -- C[渲染成图]这段文本被 Mermaid 解析器处理后会生成一个横向排列的流程图。Mermaid 支持的类型远比流程图丰富包括flowchart / graph流程图。sequenceDiagram时序图。classDiagram类图。stateDiagram-v2状态图。erDiagram实体关系图。pie饼图。gitGraphGit 分支图。对非专业绘图人员来说掌握 flowchart、sequenceDiagram 和 classDiagram 已经能覆盖绝大多数技术文档场景。2.3 图表“渲染风格”具体包含什么“渲染风格”并不只是颜色是否好看它其实由多个渲染参数共同决定布局方向flowchart 是从上到下还是从左到右。主题default、neutral、dark、forest、base不同主题会改变配色和连线风格。节点样式背景色、边框色、圆角、字体颜色、线条宽度。连线样式是否带箭头、是否使用曲线、是否有文字标签。画布尺寸输出 SVG 或 PNG 的宽高、缩放比例。字体不同操作系统和浏览器对中文、英文、代码字体的渲染结果不同。理解这些参数是统一多人协作产出物的第一步。3. 为什么同一段 Mermaid 源码在不同环境渲染出来不一样很多开发者第一次遇到 Mermaid 风格问题时会觉得很困惑明明源码一模一样为什么本地预览、Mermaid Live Editor、GitHub 渲染和命令行导出的效果各不相同原因主要有四层。3.1 解析器或渲染器版本不同Mermaid 版本迭代很快。旧版本对 classDef、subgraph 的解析规则与新版本可能并不完全兼容。当你的本地 Markdown 编辑器内嵌的是 Mermaid 9.x而项目文档基于 Mermaid 11.x 编写时同一段源码有可能出现节点布局差异、classDef 样式不生效、子图文字位置变化等问题。这类问题最隐蔽因为前端工具通常不会主动提示 Mermaid 内核版本。排查时要把“Mermaid 版本一致”当作第一条检查项。3.2 渲染容器或平台主题不同不同平台会主动套用自己的主题。举例来说渲染端主要特点Mermaid Live Editor在线调试方便可在 UI 中切换 default/dark/neutral/forest 主题GitHub / GitLab内置渲染器风格跟随站点的亮色或暗色模式Typora / VS Code 等本地工具跟随编辑器主题自定义变量设置方式差别较大Mermaid CLI命令行控制可控主题、背景色、缩放比例也就是说同一段 Mermaid 源码在 Mermaid Live Editor 里显示为白底黑框到了某个暗色主题的文档站点里就可能自动变为深色背景。设计文档的人如果没有约定“最终展示以哪套渲染方式为准”风格就会非常飘。3.3 输出尺寸、字体与画布参数不同直接截图和通过 Mermaid CLI 导出 SVG两者对画布尺寸的处理方式完全不同。常见差异包括通过网页截图导出的图片宽高取决于浏览器视口容易裁切。PNG 默认没有透明背景嵌入暗色文档会出现白底方块。同一台机器缺少中文字体时导出 PNG 中的中文可能变成“方框”。SVG 默认宽高可能和文档排版宽度不匹配造成图片过大或过小。这些“看起来像图片问题”的现象其实都和渲染风格强相关。3.4 协作者“手写风格”不稳定多人协作还有一个隐藏因素每个人写 Mermaid 源码的习惯不同。有人习惯graph TD有人喜欢flowchart LR。有人把长文本作为节点标签导致节点宽度爆炸。有人为每个节点都写 style颜色越改越多最终完全失去统一视觉。AI 生成时如果不指定风格更会随机输出不同的布局方向、描述措辞和节点命名。从工程视角看第 4 点比版本差异更容易处理因为它可以通过规范和模板约束。第 3 点则需要引入命令行工具和 CI 进行固定。4. Mermaid 源码与风格控制的几个关键语法点在进入统一风格实操之前有必要先理解 Mermaid 源码里哪些位置会影响最终渲染效果。4.1 布局方向由第一行决定graph是 Mermaid 较早的流程图写法flowchart是改进后的版本二者常用语法大体一致。第一行声明的方向决定了整张图的流向flowchart TB A[准备数据] -- B[编写 Mermaid] B -- C[渲染验证]TB表示从上到下LR表示从左到右。编写多人共享的图时要在模板里固定方向否则同样的逻辑内容会因为TB和LR的切换产生截然不同的排版观感。4.2 subgraph 与节点文本怎么组织会影响可读性当节点数量超过 7 到 8 个继续把所有节点平铺在一条链上视觉效果会大幅下降。此时应该用subgraph把相关的节点圈成组flowchart TB subgraph inputGroup[输入层] A[原始需求] B[代码文件] end subgraph processGroup[处理层] C[解析上下文] D[生成 Mermaid 源码] end subgraph outputGroup[输出层] E[渲染并导出] F[文档展示] end A -- C B -- C C -- D D -- E E -- F每个subgraph可以设置一个分组标题如输入层。在多人协作中如果规定“超过 6 个主节点必须分组”图的可读性会稳定很多。4.3 classDef 是统一节点配色的核心语法很多开发者会直接用style A fill:#f00的方式修改单个节点。但在大图中这种写法会导致每新增一个节点都要复制一条 style 语句非常难维护。更好的方式是使用classDef定义“样式类”再把样式类附加到节点上flowchart LR A[开始]:::startNode -- B{检查环境}:::checkNode B --|通过| C[执行任务]:::taskNode B --|失败| D[输出错误]:::errorNode classDef startNode fill:#EAF2FB,stroke:#2F6F9F,color:#222222,stroke-width:1.5px; classDef checkNode fill:#FFF4CE,stroke:#D29E00,color:#222222; classDef taskNode fill:#FFFFFF,stroke:#7A7A7A,color:#222222; classDef errorNode fill:#FDE7E9,stroke:#C0392B,color:#222222;当团队约定好几种固定样式类后其他成员画图时只需要引用:::startNode、:::errorNode颜色自然统一。4.4 init 指令可以集中控制主题变量Mermaid 允许在源码开头使用%%{init: {...}}%%指令覆盖默认主题配置。例如%%{init: { theme: base, themeVariables: { primaryColor: #EAF2FB, lineColor: #2F6F9F, textColor: #222222 } }}%% flowchart LR A[入口] -- B[处理] B -- C[出口]要注意的是init 指令虽然强大但不是所有渲染平台都会完全执行或允许执行。部分在线平台出于安全考虑会对脚本类配置做限制。因此团队需要提前验证“最终发布平台是否支持 init 指令”不能简单依赖它。4.5 节点文本与特殊字符处理Mermaid 对节点文本的要求比较宽松但当文本中包含括号、引号、HTML 标签时必须放在节点形状内部或使用引号包裹。例如flowchart LR A[请求参数JSON] -- B[响应状态: OK]在自动生成场景中AI 很可能输出包含大量标点和换行的节点文本导致渲染异常。规范中应当约定节点标题尽量使用短名词长说明文字交给 subgraph 分组或图下方的 Markdown 正文承载。5. 实操用 Mermaid CLI 统一导出一套风格一致的图如果团队的目标只是“在文档里插入 Mermaid 代码块让平台自动渲染”那风格的统一度取决于平台。若希望图在文档站、PPT、公众号或离线场景中使用则应当引入命令行工具让图片在 CI 中按统一参数生成。5.1 为什么选择 CLI 而不是人工截图人工截图存在几个明显的工程问题浏览器窗口尺寸不同导出图片宽高不稳定。截图无法固定背景色png 默认可能是白底。每次修改 Mermaid 源码后都重新截图容易出现源码与图片不一致。无法在 Pull Request 流水线中自动校验图片是否过期。使用 Mermaid CLI 的最大价值是让“生成图片”变成一个可重复执行的命令。任何人拉取代码后执行一次渲染都能得到完全相同的图片文件。5.2 安装 mermaid-js/mermaid-cliMermaid CLI 是一个基于 Node.js 和 Puppeteer 的工具。安装前需要确认环境中有 Node.js建议使用 Node.js 18 或 20 的 LTS 版本。项目内安装方式如下npm init -y npm install --save-dev mermaid-js/mermaid-cli安装过程会拉取 Puppeteer 对应的 Chromium。如果安装缓慢或失败通常是网络策略问题可以检查 npm 镜像配置。安装完成后通过 npx 调用npx mmdc --version5.3 渲染单个 Mermaid 文件把 Mermaid 源码保存到.mmd文件中然后执行npx mmdc -i docs/diagrams/workflow.mmd -o docs/images/workflow.svg --theme base -b transparent参数含义如下-i输入文件路径。-o输出文件路径。--theme指定主题。-b指定图片背景色transparent表示透明背景。如果希望导出 PNG可以把扩展名改成.png并增加-s缩放比例npx mmdc -i docs/diagrams/workflow.mmd -o docs/images/workflow.png -s 2 -b white这里-s 2表示按 2 倍分辨率导出适合文档站需要高清图片的场景。5.4 在服务器环境中使用 puppeteer 配置很多 Linux 服务器没有图形界面Chrome 运行时会缺少必要的系统依赖。常见的解决方式是提供 puppeteer 配置让 Chromium 以 no-sandbox 方式运行。新建文件puppeteer-config.json{ args: [ --no-sandbox, --disable-setuid-sandbox ] }渲染时通过-p指定配置文件npx mmdc -p puppeteer-config.json -i docs/diagrams/workflow.mmd -o docs/images/workflow.svg注意--no-sandbox会降低浏览器进程隔离能力在 CI 容器或受限环境中使用时应先确认安全策略允许。5.5 批量渲染脚本项目中的图不只一张建议编写脚本遍历目录中的全部.mmd文件。新建scripts/render-diagrams.sh#!/usr/bin/env bash set -euo pipefail INPUT_DIR${1:-docs/diagrams} OUTPUT_DIR${2:-docs/images} mkdir -p $OUTPUT_DIR for file in $INPUT_DIR/*.mmd; do [ -e $file ] || continue name$(basename $file .mmd) echo Rendering ${name} ... npx mmdc -p puppeteer-config.json \ -i $file \ -o $OUTPUT_DIR/${name}.svg \ --theme base \ -b transparent done给脚本增加执行权限后运行chmod x scripts/render-diagrams.sh ./scripts/render-diagrams.sh在package.json中加入脚本命令方便团队统一调用{ name: docs-render, scripts: { diagrams: bash scripts/render-diagrams.sh }, devDependencies: { mermaid-js/mermaid-cli: ^11.0.0 } }之后项目成员只需执行npm run diagrams即可在本地重新生成全部文档图片。5.6 结果验证渲染完成后检查docs/images目录下是否生成了对应的 SVG 文件。推荐在浏览器中打开 SVG重点确认中文是否正常显示。节点之间是否有重叠。每一层的宽度是否合理。深色模式下透明背景是否正确。如果发现中文乱码可在服务器安装中文字体。以 Debian/Ubuntu 为例apt-get update apt-get install -y fonts-noto-cjk安装后重新执行渲染命令即可。6. 多人/自动生成协作中如何把 Mermaid 风格“关进笼子”仅有命令行渲染还不够。一个活跃的 OSS 仓库中新增图表的人可能完全没有接触过渲染脚本因此必须在仓库层建立一套明确约定。6.1 约定目录与命名规范建议在文档仓库中固定 Mermaid 源码与图片产物的目录docs/ diagrams/ # 存放 *.mmd 源文件 images/ # 存放渲染后的图片命名建议使用英文小写短横线。比如docs/diagrams/ci-workflow.mmd docs/images/ci-workflow.svg源代码与图片分开管理可以避免 Pull Request Diff 把源码和二进制图片混成一团。6.2 提供一个统一的 Mermaid 模板在docs/diagrams/_template.mmd中放一个基础模板让新成员直接复制使用%%{init: { theme: base, themeVariables: { fontFamily: Noto Sans CJK SC, PingFang SC, Microsoft YaHei, primaryColor: #EAF2FB, primaryBorderColor: #2F6F9F, lineColor: #5A5A5A } }}%% flowchart TB subgraph groupA[模块 A] A1[开始] A2[处理] end A1 -- A2模板统一了方向、中文字体、主题变量和分组风格。成员复制后只需要修改节点内容视觉结果天然保持一致。6.3 将渲染纳入 CI如果项目托管在 GitHub可以通过 GitHub Actions 在 Pull Request 阶段自动渲染图片并检查图片是否更新。在.github/workflows/render-diagrams.yml中写入name: render-diagrams on: pull_request: paths: - docs/diagrams/** jobs: render: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Render diagrams run: npm run diagrams - name: Verify no uncommitted images run: | git diff --exit-code docs/images当贡献者只提交了.mmd文件、忘记更新图片时CI 会在最后一步失败提醒他重新执行npm run diagrams并提交图片。如果是内部 GitLab也可以在.gitlab-ci.yml中实现相同逻辑核心思路一致先渲染再用git diff检查产物是否有变化。6.4 面向 AI 编码工具的生成约束标题中提到的 Open Code / autonomous OSS 场景绕不开“AI 自动生成 Mermaid 源码”。想让 AI 生成的内容符合团队风格不能只靠事后修改而是要在 Prompt 阶段给足约束。下面这段提示词可以作为参考模板请生成一段 Mermaid flowchart 源码要求如下 1. 使用 flowchart TB不用 graph TD 2. 节点文本使用中文语义精炼不超过 15 个字 3. 主流程节点数量不超过 6 个 4. 超过 6 个节点时使用 subgraph 按模块分组 5. 不要直接在代码中散落 style 语句用 classDef 定义公共样式 6. 输出内容只包含 Mermaid 源码不要额外解释。对于更成熟的项目可以把这份约束写入仓库根目录的AI_GUIDE.md或CONTRIBUTING.md让所有使用 AI 工具的协作者看到同样的规则。6.5 把代码评审变成图评审在 Pull Request 评审时很多人只 Diff Mermaid 源码没有打开渲染后的图片。对于视觉改动这个习惯需要调整。建议在 PR 描述模板中加入本次变更对应的 Mermaid 源码文件。变更前图片链接。变更后图片链接。变更影响范围新增模块、调整流程、修改文案或仅调整样式。这一步看起来像流程要求实际能避免大量“代码没问题但渲染后一团糟”的返工。7. 常见问题与排查思路问题现象常见原因解决思路同一份 Mermaid 源码在本地和 CI 中渲染结果不同Mermaid 版本不一致或渲染器主题不同锁定 package 版本使用 Mermaid CLI 统一渲染导出 PNG 后中文变成方块运行环境缺少中文字体安装 fonts-noto-cjk 或其他中文字体图太宽在文档中挤压排版主流程节点过多或使用了横向布局而内容超长增加 subgraph 分组拆分为多个小图节点样式在某个平台不生效classDef 语法不兼容或平台不支持该配置在 Mermaid Live Editor 中验证语法并固定平台使用 init 指令后页面不渲染平台出于安全限制禁用了部分配置移除 init改用 CLI 导出图片图片和源码不一致修改 .mmd 后忘记重新导出在 CI 中加入渲染检查步骤AI 生成的图经常出现多余说明或复杂结构Prompt 中缺少风格约束使用标准模板并在 Prompt 中限定节点数量与语法遇到无法解决的渲染问题时推荐把一段最小可复现的 Mermaid 源码粘贴到 Mermaid Live Editor切换不同的 Mermaid 版本和主题做对照实验。这个方法可以快速定位是“源码写法问题”还是“渲染环境问题”。8. 最佳实践让 Mermaid 图成为文档里的稳定构件经过上面的流程团队基本可以实现 Mermaid 图的“可重复构建”。在此基础上有几点工程建议值得直接落地第一把 Mermaid 版本放进依赖锁文件。团队文档应用和 CLI 工具应使用同一条依赖链避免应用自动升级 Mermaid 后旧图片批量出现样式回归。第二让“源码目录”和“图片目录”一一对应。源文件与产物遵循相同命名规则让人看到workflow.mmd就能推测出对应workflow.svg降低维护成本。第三把模板作为仓库中的一等公民。模板文件不仅要放在docs/diagrams/下还要在 README 中说明“新图请从模板复制”让新贡献者一开始就走正确路径。第四给 AI 生成内容设置验收红线。当前 AI 编码工具生成 Mermaid 图的速度很快但生成结果的稳定性不足以直接信任。至少要检查布局方向、节点结构、classDef 是否有效并在本地完成渲染预览后再合入。第五重视图片在文档站点中的展示容器。即使 SVG 导出正确如果页面 CSS 设置了max-width不同宽高比的图仍可能出现显示差异。规范中应约定统一的图片展示宽度和主题色变量。从社区调侃到工程落地Mermaid 图风格不一致不是一件小问题。它影响文档审美也影响协作效率。通过锁定版本、固定命令、提供模板、写入 CI 和约束 AI 生成行为一套看起来“有人味”的图渲染风格完全可以变回稳定的标准化产物。这也是开放式 OSS 协作走向成熟时非常值得补上的一环。