Mermaid Flowchart 语法常见报错：冒号、圆柱节点、边标签空格的修复

Soulock
2026年06月01日
- 技术

Mermaid flowchart 渲染失败通常没有明确报错信息，图表直接显示为空白或语法错误提示。以下是三类最常见的问题。

问题一：节点文本含冒号

端口号和 URL 路径中的冒号会让部分 Mermaid 版本解析失败：

HN[Hardhat Node :8545]   ← 可能报错

修复：用括号替代冒号，或加引号包裹整个文本：

HN["Hardhat Node (8545)"]
RP["rpc-proxy (8546)"]
Backend["Go Backend (8080)"]

问题二：圆柱节点 [( )] 与中文混用

OS[(OrderStore 内存)]   ← 部分渲染器报错

修复：改用英文，或改为普通方块节点：

OS[("OrderStore")]
OS[OrderStore]

问题三：边标签含空格

UI -->|9. 轮询 processedOrders| RP   ← 旧版本可能报错

修复：用双引号包裹边标签：

UI -->|"9. 轮询 processedOrders"| RP

subgraph 加引号

subgraph 名称含中文、括号、空格时，用双引号包裹避免问题：

subgraph Frontend["React Frontend"]
subgraph Backend["Go Backend (8080)"]

修复后完整示例

flowchart TB
    subgraph Frontend["React Frontend"]
        UI["用户界面"]
        MM["MetaMask钱包"]
    end

    subgraph Backend["Go Backend (8080)"]
        API["Gin HTTP API"]
        OS["OrderStore"]
    end

    subgraph Chain["以太坊链"]
        HN["Hardhat Node (8545)"]
        PG["PaymentGateway 合约"]
    end

    UI -->|"1. POST /api/orders"| API
    API -->|"2. 创建订单"| OS
    HN -->|"3. 执行合约"| PG
    PG -.->|"Deposit事件"| HN

通用规则

节点文本有特殊字符（:、/、(）→ 加双引号
边标签有空格或特殊字符 → 加双引号
中文混合复杂格式 → 尽量简化或加引号

Mermaid 版本差异较大，加引号是最兼容的防御性写法。