绘图优雅系列：Mermaid 绘图报错排查

一、写在前面的话

在 Markdown 里用 Mermaid 画流程图体验极佳，不过我遇到过这种情况：代码明明没写错，但在 GitHub、Obsidian 或第三方编辑器里就是渲染不出来，一直 Parse error / Lexical error。

我刚开始用Mermaid的时候真的怎么都查不出问题，真的见鬼了

这篇笔记里我把 Mermaid 常见的报错原因做了个复盘。

---

二、平台差异与旧版阉割

Live Editor 永远运行着最新版的 Mermaid.js，支持所有花哨的新语法（比如 flowchart 的某些高级连线、sequenceDiagram 的新特性）。但很多第三方软件内置的 Mermaid 版本可能是一两年前的，不认识这些新词。

---

三、常见报错排查

• 特殊标点与符号：节点标签 [这里面的文字] 中如果混入了未转义的半角逗号、双引号、括号，或者特殊的模板变量，旧版解析器会把它当成代码 token 而报错。
• 样式少换行：某些节点/边的样式声明（style 或 classDef）要求独立一行，如果不小心跟在连线后面，会报 Expecting NEWLINE。
• 子图冲突：在子图里混用 TD（上下）与 LR（左右）方向，或者搞跨子图的反向连线。

---

四、高兼容写法

容易报错的写法（新版）	稳妥的高兼容写法（旧版）	原因剖析
flowchart TD	graph TD	很多老平台只认 graph 关键字，不支持 flowchart 引入的新特性。换成 graph 能解决 80% 的不兼容。
各种 subgraph、style	纯节点与连线	旧版对子图、样式类 (classDef) 的解析极其脆弱。排错时先全部删掉，只保留基础结构。
包含全角/半角标点的中文	去标点的中文 / 纯英文	去掉标签文字里的逗号、问号、句号，或者直接改用空格替代。
复杂的行内样式	分离声明	避免在 --> 后面紧跟样式或注释。

---

五、举例

这里提供两个成功的模板：

版本 A：中文无标点

使用老语法 graph TD，去除了所有可能引起歧义的标点符号，完全依靠形状 []、()、{} 来区分节点。

graph TD
  A0([开始]) --> A1[输入初始硬币数量]
  A1 -->|非法或负数| A2[提示错误 重新输入]
  A1 -->|合法| A3[设置找零状态]
  A3 --> A4[显示设备状态]

  A4 --> A5{投入硬币}
  A5 -->|输入非法| A6[提示输入无效 等待刷新] --> A4
  A5 -->|取消| A7([结束程序])
  
  A5 -->|合法硬币| A9[选择商品]
  A9 -->|选择有效| A11{判断库存}
  A11 -->|充足| A12[送出商品 更新找零]
  A11 -->|不足| A13[提示无货 退币]
  
  A12 --> A4
  A13 --> A4

版本 B：纯英文

如果遇到某些极度古老的平台连中文或全角空格都报错，可以使用这套纯英文字母与数字的版本。

graph TD
  S0([Start]) --> S1[Input initial coin count]
  S1 -->|invalid| S2[Error reenter]
  S1 -->|valid| S3[Update status]
  
  S3 --> S4{Insert coin}
  S4 -->|invalid| S5[Invalid input wait refresh] --> S3
  S4 -->|valid| S6[Dispense item]
  S6 --> S3

---

👉 点击这里继续阅读：《Hexo Matery 代码显示问题排查与修复》