Mermaid图表渲染失败？罪魁祸首可能只是一个分号！——深入解析’got SEMI’语法错误

原创已于 2025-08-19 16:30:24 修改 · 1k 阅读

10 ·

CC 4.0 BY-SA版权

文章标签：

#mermaid

于 2025-08-19 16:29:36 首次发布

Mermaid 专栏收录该内容

53 篇文章

订阅专栏

Mermaid图表渲染失败？罪魁祸首可能只是一个分号！——深入解析’got SEMI’语法错误

在技术文档和博客写作中，Mermaid 已成为我们绘制流程图、时序图等图表的利器。它能让我们用简单的文本描述生成清晰、专业的图表。然而，正是这种“简单”的语法，有时会与我们根深蒂固的编程习惯发生冲突，导致一些令人困惑的错误。

今天，我们就来复盘一次真实的 Mermaid 调试经历，从一个看似复杂的解析错误 Parse error... got 'SEMI' 出发，最终发现罪魁祸首竟然是我们最熟悉的标点符号——分号。

案发现场：一个无法渲染的流程图

我们精心编写了一个 Mermaid 流程图，用于展示一个 Vue 应用中“生产者-状态中心-消费者”的数据流转过程。代码如下：

原始代码 (错误版本):

%%{init: {"theme": "base", ...}}%%
graph TD
    classDef producer fill:#E74C3C,stroke:#C0392B,color:#fff;
    classDef store fill:#F1C40F,stroke:#F39C12;
    classDef consumer fill:#5DADE2,stroke:#3498DB,color:#fff;
    classDef event fill:#2ECC71,stroke:#27AE60,color:#fff;

    A["用户缩放窗口<br>或页面加载"] --> B["App.vue (生产者)"];
    B --> C["执行 resizeTable() 计算高度"];
    C --> D["调用 AppModule.SetTableHeight(height)"];
    D --> E["Vuex Store (状态中心)"];
    E --> F["Mutation 更新 tableHeight state"];
    F --> G["product-list-dialog.vue (消费者)"];
    G --> H["计算属性 tableHeight 自动更新"];
    H --> I["el-table 重新渲染固定高度"];

    class A,event;
    class B,C,D producer;
    class E,F store;
    class G,H,I consumer;

然而，当我们将这段代码粘贴到 Markdown 编辑器中时，得到的不是漂亮的流程图，而是一条冰冷的错误信息：

DbZp2DL_.js:570 Error: Parse error on line 16:
...;    class A,event;    class B,C,D pr
---------------------^
Expecting 'SPACE', 'AMP', 'COLON', 'DOWN', 'DEFAULT', 'NUM', 'COMMA', 'NODE_STRING', 'BRKT', 'MINUS', 'MULT', 'UNICODE_TEXT', got 'SEMI'
    at q1.parseError (DdZCvoVO.js:9:33592)
    at q1.parse (DdZCvoVO.js:11:173)
    at Ut.parse (DdZCvoVO.js:15:14)
    at Diagram.fromText (DbZp2DL_.js:545:398)
    at getDiagramFromText (DbZp2DL_.js:552:3701)
    at Object.parse (DbZp2DL_.js:546:1994)
    at DbZp2DL_.js:552:7270
    at new Promise (<anonymous>)
    at performCall (DbZp2DL_.js:552:7237)
    at executeQueue (DbZp2DL_.js:552:7070)

在这里插入图片描述

错误直指第17行，但初看之下，class A,event; 似乎并没有什么大问题。那么，这个神秘的 SEMI 到底是什么意思？

探寻真凶：`SEMI` 是什么？

要理解这个错误，我们首先要站在解析器 (Parser) 的角度看问题。解析器在读取我们的代码时，会将字符流分解成一个个有意义的单元，称为 “词法单元” (Token)。每个 Token 都有一个类型名，以便后续的语法分析。

SEMI 就是解析器内部给分号 ; 这个字符起的类型名。

它是缩写吗？ 是的。
全称是什么？ Semicolon (分号)。

所以，这条错误信息 Expecting 'SPACE', 'AMP', 'COLON', ... got 'SEMI' 就可以翻译成大白话：

“我在第17行的这个位置，本来期望看到的是一个空格、一个’&'符号、一个冒号或者其他一些合法的字符，结果我却收到了一个分号 (SEMI)。这不符合我的语法规则，所以我报错了。”

问题根源：肌肉记忆的“背叛”

知道了 SEMI 的含义，问题就清晰了。错误的原因是我们在 class 赋值语句的末尾画蛇添足地加上了分号。

这几乎是所有写过 JavaScript, Java, C++, CSS 等语言的开发者的“肌肉记忆”。在这些语言中，分号是语句结束的标志，是不可或缺的一部分。

然而，Mermaid 是一种领域特定语言 (DSL, Domain-Specific Language)，它有自己的一套更简洁的语法规则。在 Mermaid 的流程图语法中，class 语句的结尾不应有任何标点符号，它由换行符终止。

我们的肌肉记忆在这里“背叛”了我们，让我们不自觉地在每一行 class 语句后都加上了分号，从而导致了解析失败。

此外，仔细观察还能发现另一个小错误：class A,event; 的写法也是不正确的。正确的语法是将所有要应用样式的节点ID用逗号隔开，然后跟上样式名，即 class A event。

解决方案：回归 Mermaid 的纯粹语法

解决方案非常简单：移除所有多余的分号，并修正语法。

修正后的代码:

改动点:

将 class A,event; 修正为 class A event。
移除了所有 class 语句行末的分号 (;)。

将这段代码放回编辑器，一个漂亮的、带有自定义样式的流程图便成功渲染了出来。

经验总结 🧠

这次看似简单的 Bug 修复，却给了我们几个深刻的启示：

尊重每一种语言的“方言” (DSL)：当我们从一种通用编程语言切换到一种领域特定语言（如 Mermaid, Dockerfile, SQL）时，要时刻提醒自己放下固有的语法习惯，遵循其自身的规则。
学会解读解析器错误：Expecting... got... 是解析器错误的经典模式。学会将 SEMI, BRKT (Bracket), COLON 等 Token 名称翻译成对应的符号，能帮助我们快速定位语法问题。
简单即是答案：当遇到复杂的解析错误时，不妨回归到最简单的语法规则。很多时候，问题就出在我们“想当然”地添加了多余的符号。
文档是最终的权威：如果不确定某个语法，查阅官方文档永远是最高效、最准确的解决途径。

希望这次的调试经历，能帮助你在未来的 Mermaid 图表绘制之旅中，避开类似的“分号陷阱”。Happy Diagramming! 📊