GitLab 如何渲染 Mermaid
GitLab 会在 markdown 文件、Issue、Merge Request 和 Wiki 中渲染语言标记为 mermaid 的围栏代码块。
和 GitHub 一样,GitLab 也锁定了自己的 Mermaid 版本,并随 GitLab 发布节奏升级。自托管的 GitLab 实例可能运行的版本比 GitLab.com 旧得多,所以一个在 GitLab.com 上能渲染的图表,在自建实例上仍可能失败。
```mermaid
sequenceDiagram
Dev->>GitLab: 推送带 Mermaid 的 markdown
GitLab-->>Dev: 在 MR 中渲染出图表
```体积与性能限制
GitLab 对 Mermaid 代码块施加限制以保护页面性能:源码过大,或节点和连线数量过多的图表,可能会被截断、拒绝渲染,或者需要手动点击才会渲染。
如果一个图表在 GitLab 上悄无声息地渲染失败,但在别处正常,体积是首先要排查的原因。把一个大图表拆成几个小图表是最可靠的解决办法。
常见的失败场景
较新或 beta 阶段的图表类型依赖于实例部署的 Mermaid 版本——在正式依赖它们之前请先验证,尤其是在自托管实例上。
交互式的 click 指令不可用。
自定义的 init 和主题指令可能与 GitLab 自身的样式冲突,深色模式下尤其明显。
和其他平台一样的解析陷阱依然存在:flowchart 标签里的小写 'end'、标签中未加引号的特殊字符,以及多余的制表符,都可能导致解析失败。
安全的编写流程
在 MermaidPen 的 Studio 里用 GitLab-safe 预设起草图表,该预设偏向长期稳定的语法,并会标记出有风险的写法。
让每个图表保持精简;用几个聚焦的小图表,而不是一张什么都想画进去的大图。
对于绝不能出错的文档(运维手册、新人上手文档),从 Studio 导出 SVG,把图片和 Mermaid 源码一起提交到仓库。