企业官网建设流程全解析

1. 先搞清楚 mermaid 渲染风格为什么会成为讨论点

mermaid 是这些年很常用的图表工具，把文字描述转成流程图、时序图、类图、甘特图、饼图等。对开发者和写文档的人来说，它最直接的价值是不需要拖拽画图，写好代码就能生成图。实际使用中，不同工具打开同一段 mermaid 代码，渲染出来的效果经常不一样，比如节点形状、连接线方向、配色、字体间距、文字换行位置、分支布局，甚至中文字符的显示宽度。这不只是美观问题，在一些需要对外展示的文档、评审说明、架构图里，布局乱掉会直接影响阅读效率和结论表达。

我在本地编辑器、在线编辑器、支持 mermaid 的文档平台里都跑过同一段代码，得到的图经常看起来像不同人画的。原因多种多样，比如渲染器版本不同、主题配置不同、浏览器字体影响、节点文本长度和空格处理不同、布局算法在复杂图上的表现差异。更麻烦的是，协作场景里每个人用的工具不同，极易出现“我这边好好的，发过去就乱了”的局面。

这篇内容围绕一个比较有讨论度的现象展开：当团队或个人在开放协作、多人共同撰写技术内容，尤其是 OSS 相关的文档、架构方案、流程梳理时，mermaid 图的渲染风格往往因为工具链不同而出现风格不统一的问题。标题里提到的“Dex Horthy 调侃 open code autonomous OSS 创作集体的 mermaid 图渲染风格”，更像是在说一群人、一套协作流程或一种自动生成文档的模式下，mermaid 图成了被审视的对象。核心不是去评价某个人对错，而是借着这个现象把 mermaid 在实际创作流程中的问题拆清楚：为什么同一段图代码在不同地方不一样、怎么统一风格、怎么排查布局混乱、怎么让多人协作时图能保持稳定。

所以，这篇文章适合谁看？平时自己写技术博客、维护开源项目文档、用自动生成内容工具做资料整理、团队共享架构文档的人，都应该把 mermaid 图作为一个正经技术问题看待。不是说会把几个方框连起来就够了，而是要理解它从代码到渲染结果的完整链路。

如果你目前在协作中发现 mermaid 图不一致，或者想在自己参与的内容项目里建立一套相对稳定的图表规范，下面这些内容值得逐段看完。我不会只讲 mermaid 基础语法，而是围绕实际会踩到的问题，按验证链路拆开讲。

2. mermaid 从代码到最终图，中间发生了什么

很多人有个误解：mermaid 代码写对了，图就应该在各处长得一样。真实情况完全不是这样。理解 mermaid 的渲染链路，是排查一切风格问题的前提。

2.1 mermaid 不是图片文件，而是一套解析后实时绘制的规则

mermaid 的输入是文本代码，输出到页面上的是 SVG 或者 Canvas 图形。不同工具使用时，并不是把一张图片从一个地方复制到另一个地方，而是各自加载 mermaid 解析库，然后在前端根据代码动态绘图。

这带来一个关键特征：渲染结果取决于谁在解析、用什么版本解析、在什么环境里绘制。

如果用一句话概括，mermaid 是“规则 + 渲染器 = 图”，规则变化少，渲染器变化多。两套不同环境跑同一段代码，即使代码完全一致，出来的图也可能不同。

2.2 版本差异是风格不统一的第一个来源

mermaid 的版本迭代速度不慢。不同大版本之间，布局算法可能改动，默认主题值会调，图形间距、字体、节点圆角都会变化。小版本之间的差异在某些特殊图上也可能明显。

举例来说，在早期版本里绘制复杂流程时，节点之间如果有多个分支，分支的排布可能相对紧凑；新版本可能通过更合理的空间分配让图形更清晰，但代价是整体宽度变大。不同版本对中文节点文本的处理也不一样，早期版本对中文换行支持不够友好，后期做了不少优化。

在自动生成文档或者多人协作的组织里，如果有人在本地用最新版本 mermaid，有人用的开发库比较旧，还有人粘贴代码到在线编辑器默认版本，大家看到的结果自然是“群图乱舞”。

2.3 主题和配置让同一段代码彻底分化

mermaid 支持通过配置项设定主题。默认配置包括：

• 主题基础色，比如背景色、节点填充色、边框颜色、文字颜色。
• 节点形状的表现细节，比如圆角程度、边框粗细。
• 连接线的样式和箭头类型。
• 字体族、字体大小、行高。
• 思维导图、流程图、类图等各自不同的布局参数。

很多编辑器会在菜单里默认套用一套主题。比如有些平台默认使用“default”或“base”主题，另一些提供了“dark”“forest”“neutral”可选。不同文档系统在渲染 mermaid 的时候，后台可能也有自己的默认配置。

从实际效果看，主题一变，同一段 mermaid 代码在别人眼里就是完全不同的一套图。这很容易被误读为“代码写错了”或者“语法不兼容”，但实际上只是主题配置没对齐。

2.4 浏览器、字体和屏幕渲染环境也会插一脚

即使同一份代码、同一个 mermaid 版本、同一套主题，在 Chrome、Firefox、Safari 里渲染也可能存在像素级差异。影响较大的通常是字体：如果系统里没有图里指定的字体，渲染器就会用默认字体替代，替代后文字宽度变化，导致节点宽度重新计算，然后整个布局被牵连。

Windows、macOS、Linux 系统自带的字体差异很明显。比如在中文字体渲染上，换成不同字体后，同一节点文本可能多出一两个字宽，继而影响节点排布。

还有一个实际问题：同一个 mermaid 文件在不同人手里因为系统缩放比例、浏览器窗口宽度不同，生成的 SVG 图片整体比例也有差异。

2.5 数据缓存和加载时序问题容易被忽略

在多人协作或自动生成内容平台里，还有一类问题很难排查：第一次打开某篇文章时 mermaid 图加载失败，刷新后正常；或者教程里明明写了某个工具能实时渲染，实际使用时图要等很久才出现。这往往不是因为 mermaid 语法错了，而是渲染脚本在页面加载时才执行，如果网络情况不好、脚本加载慢或冲突了，图就可能渲染不出来。

在团队文档系统里，页面缓存可能导致新提交的 mermaid 代码没能触发重新渲染，需要强制刷新才能看到更新。

理解了上述链路后，再去看“谁调侃谁的渲染风格”时，重点就不该放在个人审美争执上，而应该放在是否建立了统一的渲染基线。多人协作时如果不明确用哪个 mermaid 版本、哪个主题、哪类语法、哪个输出流程，风格问题只会反复发生。

3. 以一段示例代码为例，观察不同渲染结果带来的差异

我挑一个比较典型的流程：多人参与的开源项目里，从提交代码到合并到主分支的评审流程。这种流程描述在 OSS 文档里很常见，代码本身不难，但不同渲染器下的效果差异很能说明问题。

示例 mermaid 代码如下：

graph TD A[提交 PR] --> B{CI 检查是否通过} B -- 通过 --> C[代码评审] B -- 不通过 --> D[回到修改] C --> E{是否有评审意见} E -- 有 --> D E -- 没有 --> F[合并到主分支] D --> B

这段代码对 mermaid 而言是很常规的流程图。字母 A 到 F 是节点 ID，方括号里是节点文本，花括号表示判断节点，--后面带文字是连接线标签，graph TD表示从上到下布局。

如果全部环境都用默认主题、相近版本的渲染器，这张图通常会正常显示，但细节还是有变数：

• 节点 B 和 E 表示判断、条件分支，有些渲染器会把文字自动换行，有些则强制撑宽。
• 连接线上“通过”“不通过”两个标签在不同版本中的字号和间距不同。
• “回到修改”这个存在循环分支的地方，布局算法决定 D 和 B 之间的距离、两条连线的位置，连线的路径在不同版本中可能差异很大。
• 整体画布宽度也可能有很大出入。

如果这时候有人在文档里写了：

A [提交 PR]

中间的空格数量不同，在解析时可能容忍，但也可能影响结果显示。特别是从第三方编辑器复制代码时，容易混入不同空格或制表符。

为了把现场感拉出来，我把同一段代码放在以下三个位置分别跑了一遍：

这一轮跑下来最明显的感受是：代码是同一份，但图的“气质”完全不同。有人说某一版干净，另一版松散；有人说某一版箭头位置不顺眼；其实都没有真正写错，是渲染器处理后的结果差别。

对普通写文档的人来说，可能觉得这只是观感。但到了自动生成、多人协作、生成式内容工作流中，这就是基础质量问题，直接影响阅读者理解流程。因此 mermaid 使用不应该停留在“写代码出图”这层，而应该有意识地建立自己的一套检查流程。

4. 多人协作和自动生成场景里，mermaid 风格为何更难统一

在单纯自己写博客时，风格问题不会显得太致命。最多是自己在本地看是好的，导出到博客平台后图变了，自己调一下即可。但当 docs 由多个人共同维护，或者文档是自动生成的时候，mermaid 风格混乱会明显放大。

4.1 每个人本地环境的“隐性参数”不统一

每个人本地的编辑器插件版本、全局 CSS、主题、字体配置、mermaid CLI 版本都可能不同。提交到公共仓库后，如果每个人都把渲染图截图直接贴在文档里，那么图本身就带上了个人环境的印记。若更新了代码但没更新截图，图与代码还会不一致。

4.2 代码评审时 mermaid 的可读性成为瓶颈

多人协作时，每次改动 mermaid 图代码后，reviewer 很难只看代码判断图是否满足要求。如果你没有统一约定，reviewer 需要自行运行渲染，然后等待生成结果对比，这会把简单事情变得繁琐。这也是标题里“open code review”值得展开的地方：对自动生成内容的集体创作而言，审查不只要看文本和代码逻辑，也要看渲染后的图是否具备一致的可读性。一套新配色、更宽的画布，可能让原本的流程图整体比例发生变化，阅读顺序会受影响。

4.3 自动生成的 OSS 文档里，mermaid 图必须“一次成形”

有些开源项目或内容自动化工作流中，会通过脚本把 mermaid 代码转换成图片放进文档。这类“生成内容”非常依赖渲染环境的稳定性。如果在自动构建流程中，不同机器、不同系统、不同版本的环境跑出来的图不一致，文档产出就会不稳定。

这里列出比较常用的渲染方式：

如果要在多人、多文件、多机器的协作场景里统一 mermaid 输出样式，第一步不是告诉所有人“代码要规范”，而是先锁定渲染环境。

4.4 自动生成内容场景下的特殊要求

自动生成场景与传统文档不同，通常会：

• 大量段落是脚本生成的，mermaid 代码也是模板拼出来的。
• 图代码里可能包含变量、动态变化的节点文本、自动生成的分支。
• 输出格式可能不只是嵌入网页，还要导出 PNG、PDF 等。

这种情况下，mermaid 图必须有较强的可预测性。不能靠人工手动调位置，更不能容忍不同环境间随机性过大。

有些团队会预渲染所有 mermaid 为 SVG 文件存入仓库。这样生成文本和图片是独立的，审查时只要确认 SVG 和代码版本同步即可。这个方案解决了风格一致性问题，代价是需要把 mermaid 工具链纳入构建流程，更新图代码时不能忘记重新生成图片。

5. 实际操作：怎么统一 mermaid 图的渲染风格

不管你是不是在做自动生成内容项目，如果想在团队或自己的长期文档体系里让 mermaid 图保持稳定，可以参考下面几条链路。

5.1 先锁定 mermaid 版本

最基础的一步：统一解析器版本。所有本地写作、在线编辑、自动构建工具，尽量接近同一版本。

如果你用 npm 包，在package.json里锁定精确版本，不要用^或~范围。举例：

{ "dependencies": { "mermaid": "11.x.x" } }

本地如果经常用某一个在线编辑器，那就在文档体系里写明建议使用的版本或截图日期。因为在线编辑器本身会升级，如果把它当作团队统一渲染工具，版本变化会导致旧文档的图变化。

如果团队文档量比较大，用 mermaid CLI 是比较可靠的。命令大致如下：

mmdc -i input.mmd -o output.svg

如果是自动构建：

npx @mermaid-js/mermaid-cli -i docs/diagrams/input.mmd -o docs/images/output.svg -c mmdc.json

我建议把配置文件和输出路径都纳入版本管理，这样别人可以一键复现。

5.2 统一主题和关键配置

mermaid 支持init配置。常用字段包括：

一个示例配置：

{ "theme": "base", "themeVariables": { "fontSize": "16px", "primaryColor": "#ffffff", "primaryBorderColor": "#2d6cdf", "primaryTextColor": "#1f2328" }, "flowchart": { "curve": "linear", "nodeSpacing": 50, "rankSpacing": 60 } }

这套配置偏向浅色、清晰、线条直接，比较适合技术文档。

5.3 给 mermaid 代码约定一个书写规范

不是只有渲染配置要统一，源文件代码本身的规范也很重要。多人维护时没有任何规范，改图很容易乱。

推荐约定：

• 节点 ID 使用有语义的英文大写或短横线命名，比如PR_SUBMIT、ci-check。
• 节点文本统一不使用 HTML 标签，避免特殊转义。
• 代码每行只写一个语句；条件过多时，使用不同分支更容易追踪。
• 分支文本使用简明中文或英文，避免过多文字撑宽图形。
• 代码块统一缩进，不要混用空格和制表符。
• 连接线文字尽量简短，长句放进节点或放到文档中表述。

示例：

graph TD PR[提交 PR] --> CI{CI 检查} CI -- 通过 --> REVIEW[代码评审] CI -- 失败 --> FIX[修改代码] REVIEW --> COMMENT{有意见?} COMMENT -- 有 --> FIX COMMENT -- 无 --> MERGE[合入主分支] FIX --> CI

这样文字更简洁，节点宽度更可控，布局差异会减小。

5.4 输出链路：直接嵌 mermaid 代码还是导出 SVG

不同使用场景有不同选择。我的建议是，把决策规则定成这几条：

• 如果你发布的是静态博客、GitHub 仓库和 Markdown 网页，可以直接贴 mermaid 代码块，由平台渲染，好处是 diff 轻；但注意不同平台效果可能不同。
• 如果对版式要求比较高，或者需要写报告、出 PDF，直接生成 SVG 并放进文档更稳妥。SVG 是真正的矢量图，缩放不会模糊。
• 如果是在线多人协作文档，比如常见的企业知识库或云文档平台，要留意平台是否内置 mermaid 插件、能不能自定义版本。不能自定义的时候，图表风格会被平台锁定。
• 如果是 CI 流程、需要统一风格的文档产物，优先用容器或固定版本 CLI 渲染。

5.5 在自动生成工作流中，容器化是减少分歧的高效路径

自动生成的集体创作场景中，稳定性高于手工微调。推荐直接把渲染环境容器化：

FROM node:20-alpine RUN npm install -g @mermaid-js/mermaid-cli puppeteer WORKDIR /workspace CMD ["mmdc", "-i", "input.mmd", "-o", "output.svg"]

整套环境塞进容器后，运行它的机器版本、系统差别都被隔离了。不同人拉取镜像后，生成图几乎可以做到完全一致。注意puppeteer需要带浏览器环境，容器里要装相应依赖，否则可能启动失败。这个细节使用mermaid-cli时非常常见。安装puppeteer的过程中，如果服务器网络受限或系统依赖不全，启动浏览器时容易报错。这个时候不是 mermaid 的问题，而是浏览器运行环境没补齐。

6. 想让 mermaid 图稳定，这几种生成/审查方式对文档维护更友好

讨论了渲染和协作后，再看一看 mermaid 图在不同文档维护模式下的表现。不同模式对图的要求不同，取舍也不同。

结合标题里对“autonomous OSS 创作集体”的讨论来看，如果由一组人共同自动生成与审阅文档，他们真正该控住的不是某个人的本地 mermaid 显示效果，而是整个内容管线产出的图，是否满足发布标准。这个标准必须有可验证的基础：

• mermaid 代码与相关文档同一次提交是否同步？有无未更新但已滞后的图？
• 自动生成的 mermaid 代码里是否存在 HTML 或脚本注入风险？
• 引用其他模块的节点命名是否可能引发不同渲染器解析差异？
• 渲染环境锁定在哪一个版本？是否有配置记录文件？

这些内容都可以在一份DIAGRAM_GUIDE.md文档里约定，内容包括“渲染版本、常用命令、主题配置、代码风格、审阅清单”。开源项目文档里常见这种做法，内部团队也适用。

7. mermaid 图审阅时该怎么判断“行不行”

对不熟悉 mermaid 的人来说，审阅一张图时往往只会说：这里好乱、那里不美观。这种反馈没法直接驱动修改。我把审阅标准拆成四个可执行判断：

7.1 结构是否完整，信息有没有丢失

对比文字描述和 mermaid 代码表达的内容。只要能表达的步骤、分支、参与者没有漏，结构性目标就达到了。审阅者要确认的是每个节点和连线是否有明确语义。不要出现“一个节点连线到另一个节点却没说清条件”，也不要在文档里写了但图上没有。

7.2 阅读顺序是否自然

查看默认布局时，从左上角开始跟着主链路走，看能不能顺畅走完。如果分支来回拐弯太多，或者判断节点位置把主流程打断，优先考虑调整节点顺序或拆图，而不是只调间距。

大图不要硬塞在一张里，节点数超过 10 个左右，优先拆成多张局部图。

7.3 渲染风格是否统一

统一不只是配色统一，还包括节点间距、箭头位置、字体与字号、文字换行。常规检查时把同一批次的多张图放一起看：横向画布宽度、节点之间的间距、不同图中同一层级的位置呈现。风格统一的项目，读者不会感到跳跃。

7.4 导出文件是否适配目标环境

如果图的最终位置是博客页面，要看页面宽度。mermaid 生成的 SVG 有时会比正文宽度大，需要调整缩放或使用横向代码块。如果导 PDF、幻灯片，要考虑字体嵌入、透明背景、画布边距。如果不检查，上传后可能出现“图被截断”或“文字过小”的问题。

8. 如果自动生成过程中 mermaid 频繁出问题，优先排查哪些点

自动生成或文档处理脚本跑 mermaid 时，报错和异常比手工操作更烦人。很多时候脚本、页面中图没出来，不代表 mermaid 本身有问题，要从几个方面排查。

8.1 先看语法和输入格式

mermaid 报错信息有时不直观，常见的包括语法错误、期望某个标记但实际找到别的、节点文本里引号未闭合。建议先用官方 live editor 校验，但注意 live editor 默认版本可能不是本地版本。

8.2 检查渲染环境和浏览器依赖

如果使用mermaid-cli，它会调用无头浏览器生成图片。此时下列问题很常见：

• 系统缺libgbm、libnss3等运行依赖，浏览器启动失败。
• 乱设PUPPETEER_SKIP_DOWNLOAD之后浏览器二进制不完整。
• 容器内存不足，页面加载时崩溃。
• 中文环境中缺少字体，图里出现豆腐块或文字溢出。

排查顺序基本是：先直接跑命令行看报错，再检查浏览器能否正常启动，最后用一条极简 mmd 文件测试。

8.3 检查安全配置和特殊字符

mermaid 出于安全考虑，默认禁用 HTML 标签，若配置里securityLevel过低或过高，影响范围会很广。若节点文本里有特殊允许的标签，在不同环境下效果不一致。建议自动生成时关闭或严格限制相关功能，确保所有输出使用纯文本。

8.4 检查构建缓存和输出目录

构建流程里，如果输出文件名长期不变，缓存可能导致旧图不会被覆盖，需注意：- 输出文件名包含版本哈希。

• 更新 mermaid 代码后，清理目标文件再执行。
• 确认进程有权限写入输出目录。

仓库文档为例的运行命令如下：

clean: rm -rf docs/assets/*.svg build-diagrams: npx mmdc -i docs/diagrams/*.mmd -o docs/assets/ all: - clean - build-diagrams

这可以防止残留旧图片掩盖新改动。

8.5 向 mermaid 社区反馈或自行定位解析库问题

遇到针对 mermaid 本身的报错，影响多人协作时，靠谱流程是去项目 issue 区搜索，或者直接查看代码库版本。不要停留在“谁的工具显示更准”的争论，应收集“输入代码、渲染器版本、配置、报错信息”后去定位。

9. 为什么开放编辑、自动生成的协作产线上，mermaid 规范很重要

“open code”“open code review”“OSS”这几个词的高频出现说明技术内容创作正变得更开放，更像一个多人共创的内容项目。多人各自维护的文档，一旦 mermaid 不受控，维护者们的时间会被浪费在无谓的渲染差异上。

我见过不少团队情况：

• 一个开发者本地预览 mermaid 一切正常，提交后在线文档里图变形严重。
• 一次文档更新中，修改了某个节点文案，渲染后的画布宽度比之前大了，导致全图比例失调。
• 自动生成报告时，同样输入在不同机器上跑出了两种视觉风格的图。
• 有人为了样式好看，在 mermaid 里插入了大量 HTML 片段和 CSS 类，结果其他环境完全渲染不出来。

这些问题一旦出现，开会讨论是浪费时间的。更稳妥的方式是把图和代码的“产线规范”前置。

9.1 对“开放编辑”的集体创作：把渲染差异变成可修复的输入问题

一旦所有 mermaid 代码都遵循同一套规范，并且版本约束清晰，那么差异就只剩“输入差异”。输入差异是可修复的、可审查的。反之，若人人都能改出专属风格，那每个图都是新的“问题现场”。

9.2 自动生成时，mermaid 代码本身就是一类代码

按代码工程标准要求它，它才会稳定。比如 mermaid 文件可算作源码的一部分，应纳管、评审、自动验证，避免格式和非法节点。

9.3 代码与图不必完全绑定，但要保持同步

直接写 mermaid 代码在浏览器渲染最简单，最符合开放协作趋势。如果你的核心是持续集成与正式发布文档，则建议提交代码时一并生成 SVG。既保留源头文本可追踪，又确保最终画面的统一。

10. 从实践层面聊聊：常见的 mermaid 错误认知

结合使用经历，我整理了一些被误读为“mermaid 不行”的情况，其实常是流程问题。

10.1 “mermaid 渲染不了复杂逻辑”

不少场景下能绘制。只是复杂逻辑生成结果不够直观，难以单图表达。此时应该采用子图、拆图、抽象层级，而不是无止境加节点。

“复杂”指的是真实绘图结果和阅读负担。一张图有一两百个节点，还想要清晰易懂，本身就是反直觉的。成熟的方案是先拆分主流程和管理面，用不同图描述。

10.2 “所有在线文档平台都能用同一套 mermaid”

平台版本、主题、默认配置本身会不同。有的还允许修改主题，许多则不支持。因此“通用 mermaid”只存在于语法层面，展示层面差异需要花时间适配。

10.3 “截图贴进文档最稳”

流程草稿用多图快速协作可以。但代码改动后截图不更新，最终文档风险更大。只要一个图变了，需要同步改截图，长期频繁更新会产生滞后。文本代码可以用 diff 呈现变更，截图却做不到。

10.4 “局部样式越多越好看”

mermaid 提供交互能力和样式定制空间，但更多人协同维护时，不建议使用大量 CSS class 和应用端逻辑，原因如下：

• 不同渲染器不同版本可能不支持。
• 只会在预览阶段生效的部分，发布后可能失效。
• 某个环节升级后，图的结构性与样式会同时崩坏。

与其用大量 CSS hack 做特殊样式，不如尽量用主题变量解决整体外观。需要换肤时只需切换主题，不需要逐图改配置。

10.5 “渲染结果不稳定一定是 mermaid bug”

经常是配置、版本或系统字体差异导致的。真正 bug 出现前，先扣题排查环境和输入。实践中先用极简 mermaid 代码跑一遍环境，再填复杂节点，能帮快速定位问题。

11. 给自己或团队定一套 mermaid 内容生产规范（附清单）

以下参考规范可以写入文档。我自己在做文档或者参与自动生成内容时，会遵守以下清单，避免反复改图。

11.1 目录和文件约定

docs/ diagrams/ source/ pr-flow.mmd architecture.mmd generated/ pr-flow.svg architecture.svg README.md

源码收拢在source，输出图为generated。这样分开避免了 mermaid 图和生成图互相混淆。

11.2 源文件头注释写清信息

建议每个.mmd文件开头写清创作者、更新时间、适用流程，便于后续知道该找哪个维护者：

%% 标题：PR 合并流程 %% 维护者：docs-team %% 更新时间：2026-XX-XX %% 渲染命令：npx mmdc -i source/pr-flow.mmd -o generated/pr-flow.svg

11.3 提交前检查 checklist

可以集成到 Pull Request 描述或共同维护的文档里：

• mermaid 代码是否可以解析，并在统一环境跑通。
• 是否按规范确定输出文件名，防止覆盖旧图。
• 若文档与代码同步提交，是否重新生成了对应的 SVG。
• 是否补充了必要说明文字，不依赖图自行解释复杂信息。
• 是否存在“主流程之外”的额外分支，需要拆图处理。
• 使用字段是否统一，避免不同环境的换行影响。

11.4 进阶：用脚本验证 mermaid 图

内容量较大的项目，可以写脚本读取所有.mmd文件，解析并输出结果。示例项目结构简化如下。如果是 mermaid-cli，遇到超时、无头浏览器崩溃等复杂问题，可以配合超时和重试参数，不要让管线中途死掉。

find docs/diagrams/source -name '*.mmd' -print0 | while IFS= read -r -d '' f; do out="docs/diagrams/generated/$(basename "${f%.mmd}").svg" npx mmdc -i "$f" -o "$out" -c mmdc.json || exit 1 done

对于开放创作工作流尤其重要：如果人为遗忘，所有校验都会白做。

12. 聊回那个开放式创作集体与 mermaid 的关系：核心是共识

标题中出现的 Dex Horthy 和 open code，我未掌握其背景，但讨论反映出的议题——“代码/内容起草者与审阅者如何在自动生成内容中形成共识”，值得反复体量。

在软件领域里，代码评审如果没人定义 eslint、prettier、go fmt，那代码风格必然混乱。mermaid 同样需要 lint 或 standard。

那些看起来“谁在用哪个 markdown 工具生成不同风格图”的调侃，很容易被人当成纯工具对比。但把 mermaid 放到长期协作的中台，大家真正追求的不是所有人用一致编辑器，而是有一个让任何环境都可以产出一致结果的规范共识。这个共识是什么？

• 统一版本
• 固定主题配置
• 一套约定俗成的代码规范
• 明确的渲染流程
• 每个人都遵守“改代码、刷新输出、核图”的规范
• 线上审查时依据同一套判据，而非局部观感

自动生成的集体，看似更自由，实则更需要节点级约束。没有约束，无法高效协调，反而让自己变成众口难调。

如果你也打算做一个协作共创、产线化的 mermaid 规范化改造，可以从下面这件事入手：新建一个仅包含版本号、一段示例、一张参考 SVG 的文档，约定全组照此执行。再有争议，就把对应代码丢到统一环境渲染，围绕结果讨论。

如果产出的图仍有差异，原因是版本、输入或配置未对齐，把线下的讨论搬到统一基准线上。多数情况下，这不是审美问题，而是流程标准未落地执行的人问题。

13. 总结可以省，但这几条建议留下

回到最初的问题：mermaid 图渲染风格为何值得被调侃，又怎么规范化？核心早就超出“用哪款编辑器”层面了：

其一，mermaid 是文本，意味着它可以像代码一样被审查、自动生成、版本管理。这个特性决定了它在多人协作中的优势一定是在规范基础上，而不是在每个人的浏览器截图基础上。

其二，风格统一不是“好看”议题，而是阅读效率和内容一致性问题。对协作越频繁、发布频率越高的文档体系，越应尽早规范。要用文档系统普及的早期，就订好渲染基线。

其三，自动生成内容场景，遇到 mermaid 输出不稳时，不要急着改 mermaid 语法，而是看向环境。绝大多数顽固情况与环境有关。

我相信不同人绘制同名图架构时的选择各异，但如果大家想在同一个“文本创作集散地”里共同成就一套内容，那渲染风格的统一就不是闲谈，而是基础设施的一部分。基础设施越早建设，后续代价越小。

你可以先搭一个示例目录、装一遍 mermaid-cli、写一张真实方案图，把本文中的检查项跑一遍。跑完后，再遇到“你的图怎么和我的不一样”，就不会停留在调侃层面，而能直接回到版本和配置上，快速达成共识。