Vloam Mermaid

文档

Mermaid 常见错误排查

修好在本编辑器里最常导致预览失败的 Mermaid 写法问题：缺少图类型、括号引号不成对、全角标点、箭头混用，以及把失败图缩到三行再逐步加回的调试步骤。

预览失败时，先读错误提示。多数情况改一处就能好。

缺少图类型

每张图的第一行都要有类型：

  • flowchart TD
  • sequenceDiagram
  • classDiagram
  • stateDiagram-v2

如果只粘贴了图的中间部分，Mermaid 不知道该用哪套规则。先补上头部，再试一次。

括号或引号不成对

标签需要成对出现：

  • [文字] [[文字]] (文字) {文字} "文字"

少了一个 ] 或 "，错误常常出现在文件末尾附近。先检查你刚改过的最后几行。

标签里的特殊字符

节点标签里的某些字符会干扰解析。把整段标签用引号包起来：

flowchart LR
  A["步骤: 保存并退出"] --> B[完成]

如果混进了中文全角标点（： ， ？），改成半角（: , ?），或给标签加引号。

箭头和图类型不匹配

流程图用 -->。时序图用 ->> 和 -->>。类图用 <|-- 和 -->。混用通常会失败。

切换图类型后，请重写连线。不要把时序图箭头直接贴进流程图。

同一 id 用了不同形状

在流程图里，一个 id 只能对应一种形状。下面这种会坏：

A[开始]
A{准备好了吗?}

给 A 只保留一种形状，或给判断节点换一个新 id。

内容是空的

只有空白时，界面会显示为空，不一定报错。如果误清空了编辑器，用工具栏的模板重新开始。

快速排查步骤

  1. 把图缩到仍会失败的三行。
  2. 先修好这三行。
  3. 再加回下一个节点或消息。
  4. 重复，直到完整故事能渲染。

编辑器会把最近草稿留在浏览器里。大改之前先复制一份可用版本，就不怕试错。