Mermaid 渲染报错怎么排查：Parse error、空白字符与 flowchart 迁移

约 8 分钟读完 · 更新于 2026-10-21 · 文中每条都能在下面的配套工具里动手验证

渲染出来是空白 + 一行 Parse error on line 7，八成不是图错了

Mermaid 的解析发生在渲染之前：整段代码先被词法分析，语法有任何一处不合法就直接抛错，一个节点都不会画出来。所以报错时看到空白是正常现象，错误信息里的行号才是唯一线索。真正的高频原因只有三类：节点文本里出现了会被当成语法的字符（括号、冒号、逗号、全角标点）、代码里混进了不可见字符（零宽空格、全角空格、复制时带进来的软换行）、以及新旧语法混用（graph 与 flowchart 混用、旧版箭头语法配新版）。

报错信息 → 病灶 → 修法：照着反查

Mermaid 的报错文本通常很短，但每一条几乎都对应固定的一类问题。下面六条覆盖了绝大多数情况。

flowchart TD
  A["提交工单"] --> B{"校验通过?"}
  B -->|是| C["进入处理"]
  B -->|否| D["退回并通知"]
  C --> E["归档"]

· 首行必须是图类型，且顶格
· 所有中文标签加双引号，避免括号 / 冒号被当语法
· 箭头只能写 -- 或 -->，别用 →

sequenceDiagram
  autonumber
  participant U as 用户
  participant G as 网关
  participant S as 订单服务

  U->>G: POST /orders
  activate G
  G->>S: 创建订单
  alt 库存充足
    S-->>G: 201 Created
  else 库存不足
    S-->>G: 409 Conflict
  end
  deactivate G
  G-->>U: 返回结果

  loop 每 30s 重试
    U->>G: GET /orders/{id}
  end

graph TD            → v10+ 起 graph 已更名，首行改 flowchart
  A[开始（第一步）]   → 括号未加引号，解析器当成子语法

A --> B(第二步: 处理)  → 冒号在未加引号的标签里会截断标签

flowchart LR
  A["a"] --> B["b"];
  B --> C["c";]        → 分号在引号内会进标签，但引号外的分号在部分版本报错

中文标签里最危险的三类字符：括号、冒号、书名号

Mermaid 的语法先于文本生效。中文写作里几乎无处不在的三类字符正好都是语法符号：圆括号与方括号会被当作节点形状，花括号被当作判断节点，冒号在部分上下文里会截断标签文本，书名号《》有时会被当成 HTML 标签起始。修法统一成一条：所有中文标签一律用双引号包起来，形如 A["提交工单（第一步）"]。引号包裹后，内部任何字符都只当普通文本处理；如果标签文本本身需要引号，用 #quot; 实体。

时序图五种常见错法：报错信息往往指向错的那一行

1. participant 声明之后引用了别名：声明 participant U as 用户 后，消息里必须写 U，写「用户」会报找不到节点——中文名只是显示标签。
2. alt / loop / opt 忘了 end：每个块的开头都必须有对应的 end 收尾，缺一个就会连带报出后面几行的解析错误，看起来像后面那行写错了。
3. activate 与 deactivate 不配对：每条 activate 都要有对应的 deactivate，且必须落在同一条消息序列内，错位时报出的行号往往在别处。
4. 箭头方向语义搞混：->> 是实线箭头（请求），-->> 是虚线箭头（响应）。返回结果用实线是语法合法但读图误导，等于把调用链画反。
5. 在时序图里用 flow 的节点语法：时序图没有 A[标签] 这种写法，所有说明文字都写在消息冒号之后，写成节点会直接报 Parse error。

空白字符：看不见的那一半错误

• 零宽空格（U+200B）：从网页、聊天记录、在线文档复制时最容易带进来，肉眼完全看不见，一个标签里有一个就渲染失败。
• 全角空格（U+3000）与不换行空格（U+00A0）：中文排版工具常用来对齐，粘进代码块后被当成普通空白处理，缩进层级错乱。
• 软换行与硬换行混用：从 PDF 或富文本粘贴，一段逻辑可能中间断了一行，Markdown 风格的换行在 Mermaid 里没有续行语义。
• Tab 与空格缩进：不同渲染器对缩进的处理不一致，不要指望缩进能被保留——Mermaid 用箭头方向决定布局，缩进只是给人看的。
• 处理办法：把源码整体做一次转义清理（或重新手工敲一遍结构行），再粘进渲染器；仍报错时用二分法——删掉一半节点，只保留首行与前三个节点，逐步加回，定位到具体是哪一行炸的。

排查顺序：从最小复现开始，别在整张图上找

1. 把出错的图缩到最小：只留图类型声明与两三个节点，确认这部分能渲染，再把节点一批批加回去。整张图上找错误是效率最低的做法。
2. 逐行加引号：中文标签一律加双引号。这一步能一次性解决括号、冒号、逗号带来的绝大多数报错，成本极低，建议在缩图阶段就全部加上。
3. 换版本验证：把同一段代码在 mermaid 渲染器与目标平台（GitHub、博客、Notion）各跑一次。同一段代码在两处表现不同，问题往往出在版本而非语法——多数平台用的是 v10，渲染器里可能跑的是 v11。
4. 看真实错误行号：报错里的行号可能因开头空行而偏移，先删掉首部空行再看行号，能对上就省一轮猜测。
5. 固化可用版本：把跑通的代码模板存下来，后面新建图从复制开始改，比每次从零写更省时间，也不容易再踩版本差异。

渲染之后：从 SVG 到长图还有一段链路

渲染成功只是开始。要放进文章或社交平台，还要处理三件事：导出的 SVG 常常带着冗余属性与过长的数值，先过一遍 SVG 优化再嵌入，能省下可观体积；需要位图时按用途选格式——社交平台与文档用 PNG，需要透明背景时必须 PNG 或 WebP，JPEG 会把透明区域填成黑色；需要长图时按内容类型选工具，静态图文导成长图 PNG，界面操作类演示则录屏转 GIF 更合适。三步各有对应的工具，不必用同一套流程硬套所有场景。

常见问题