Mermaid 语法避坑指南：解决中文图表渲染失败的两大核心策略

在使用 Mermaid 绘制流程图时，许多用户（尤其是中文用户）常遇到代码逻辑无误，却频繁报错的情况。最典型的错误提示往往是 Lexical error 或 Unrecognized text。

本文将通过一段“由错变对”的代码演变，解析导致 Mermaid 渲染失败的两个根本原因及其解决方案。

一、核心对比：错误代码 vs 正确代码

常见的错误写法（易报错）：

(注：在部分不支持自动换行的编辑器中，上述代码会被合并为一行，导致解析失败。)
健壮的正确写法：

这段正确代码之所以能成功，是因为它同时解决了 「排版格式」 和 「字符解析」 两个层面的根本问题。

二、根本问题一：排版层面的换行符丢失

1. 现象

报错信息通常显示代码被“挤”在了一起：

ERROR: ... Unrecognized text.
graph LR    A[入门：搞懂基本概念] --> B[系统课：学
----------------^

解析器错误地将声明语句 graph LR 和节点定义 A[...] 识别为了同一行内容。

2. 原因

Mermaid 解析器高度依赖 换行符 来判断一条指令的结束。

• 标准写法中，graph LR 后必须换行。
• 若您使用的 Markdown 编辑器或渲染环境会自动去除“多余”的换行符，或者将代码压缩成纯文本，就会导致 graph LR 与后续代码粘连。解析器认为指令未结束，从而抛出语法错误。

3. 解决方案：使用分号 ; 强制断句

代码变化：

原理：
分号 ; 是 Mermaid 语法中的标准 “语句结束符”。它的作用相当于显式地告诉解析器：“这条指令结束了，请处理下一条。”

• 引入分号后，即使编辑器删掉了物理换行符，分号依然能从逻辑上隔开不同指令，完美规避环境对换行符的兼容性问题。

三、根本问题二：解析层面的特殊字符干扰

1. 现象

报错光标往往指向节点 ID 或方括号内部：

... Unrecognized text.
A[入门...]
^

2. 原因

Mermaid 节点文本中若包含 中文字符 或 特殊符号（如全角冒号 ：、括号等），在某些渲染引擎版本中可能产生歧义。

• 解析器可能将方括号 [] 内的字符误判为语法结构的一部分，而非显示文本，导致词法分析错误。

3. 解决方案：使用双引号 "" 包裹文本

代码变化：

原理：
双引号明确界定了数据的类型。加上引号后，解析器会将方括号内的内容视为 “纯文本字符串”。

• 这是一种“转义”机制，解析器会忽略文本内部的特殊符号结构，只将其作为展示内容渲染。这是编写包含中文的 Mermaid 图表的最佳实践。

四、辅助优化：关键字升级

除了上述两个核心修复，建议将 graph 关键字升级为 flowchart。

• graph：早期 Mermaid 语法关键字，功能相对基础。
• flowchart：Mermaid 更新后的标准写法，对复杂布局（如子图、多向连接）支持更好，容错率通常也更高。

五、总结：健壮代码的成功公式

为了确保 Mermaid 图表在各类编辑器（Typora, Obsidian, Notion, Git等）中均能稳定渲染，建议遵循以下公式：
成功代码 = 显式分隔符(😉 + 文本引号包裹(“”)

• ; 解决了 “环境不吃换行” 的排版问题。
• "" 解决了 “中文或特殊字符干扰语法” 的解析问题。
  推荐的标准写法模板：

flowchart LR;A["节点文本"]-->B["节点文本"];