GitHub 如何渲染 Mermaid
GitHub 会渲染语言标记为 mermaid 的围栏代码块。它们在 README 及其他 markdown 文件、Issue、Pull Request、讨论区和 Wiki 中都能生效。
渲染发生在 GitHub 自己的沙箱管线里,使用的是 GitHub 自行掌控、按自己节奏升级的 Mermaid 版本。这个版本通常落后于最新的 Mermaid 发布版,这也是大多数「本地能跑、GitHub 上却崩了」问题的根源。
```mermaid
flowchart LR
dev[编写 Mermaid] --> check[检查兼容性]
check --> ship[发布到 README]
```哪些能稳定渲染
长期稳定的图表类型是最安全的选择:flowchart / graph、sequenceDiagram、classDiagram、stateDiagram-v2、erDiagram、gantt、pie 和 journey。
普通节点形状、带标签的连线、子图,以及标准方向(TD、LR)都能稳定渲染。如果你的图表只用到这些,基本都能安全过关。
常见的失败场景
较新的图表类型(timeline、mindmap、quadrantChart、sankey、block、architecture 等 beta 类型)只有在 GitHub 部署的 Mermaid 版本已经支持它们时才能用。在 README 里正式采用某个新类型之前,请先在 GitHub 上实测确认。
交互功能被禁用:图表内的 click 指令和链接在 GitHub 的沙箱环境中不起作用。
主题和 init 指令(%%{init: ...}%%)可能被忽略,或者与 GitHub 自己的浅色/深色主题产生冲突。如果图表依赖自定义颜色来传达含义,可能会变得难以辨认。
非常庞大的图表可能渲染失败或被截断。GitHub 还会把图表渲染在固定宽度的列里,所以即使技术上能渲染出来,极宽的流程图也会难以阅读。
flowchart 节点标签里出现小写的 'end' 是个经典的解析陷阱——把它大写即可。
调试被 GitHub 拒绝渲染的图表
GitHub 只会显示一个笼统的报错框,而不是详细的解析信息。想找到真正出错的那一行,把同样的源码贴到一个能给出真实诊断信息的 Mermaid 编辑器里即可。
MermaidPen 的 Studio 使用 Mermaid 11 渲染,能精确指出出错的行,用 GitHub-safe 预设标记出对 GitHub 有风险的语法,还能自动去除脆弱的指令。
发布前检查清单
除非你已经在自己的仓库里验证过某个较新类型能正常渲染,否则请坚持使用稳定的图表类型。
移除 %%{init}%% 主题代码块,或者接受 GitHub 可能会覆盖它们这个事实。
避免使用 click 指令;把图表当作静态图片来对待。
保持图表窄一些,把密集的图表拆分成几个更小的图表。
如果需要保证一定能渲染出来(比如发布页面、营销向的 README 部分),改为导出 SVG 并嵌入图片——同时把 Mermaid 源码放在旁边作为唯一可信来源。