Showing Posts From

Mermaid

Soulock
2026年06月01日
- 技术

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

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"| RPsubgraph 加引号 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 版本差异较大，加引号是最兼容的防御性写法。

Soulock
2026年06月01日
- 工具分享

Mermaid 复杂流程图渲染失败？五个改起来最快的写法

Mermaid 是文档利器，画时序图、流程图不用切工具。但节点文本里稍微带点特殊字符——冒号、括号、中文——渲染就报错。总结几个"看着简单但真被咬"的改法。症状：节点文本有 : 或 () 写： HN[Hardhat Node :8545] Backend[Go Backend :8080] RP[rpc-proxy :8546]有些 Mermaid 版本会把 : 当分隔符炸掉。改成用引号包住整段文本，或者换成 (8545) 这种： HN["Hardhat Node (8545)"] Backend["Go Backend (8080)"] RP["rpc-proxy (8546)"]通用规则：节点文本里出现非字母数字字符（中文除外），一律用双引号包起来。症状：中文 + 特殊形状节点圆柱体节点 [(...)]： OS[(OrderStore 内存)]某些渲染器对中文 + 圆柱体混用敏感。加引号： OS[("OrderStore 内存")]不行就退回矩形： OS[OrderStore]症状：subgraph 名字带空格写： subgraph Backend[Go Backend :8080]改成： subgraph Backend["Go Backend (8080)"]subgraph 的显示名称和标题一样，遇到特殊字符必须引号。症状：边上的中文文字有些老版本对边文字里的空格敏感： UI -->|9. 轮询 processedOrders| RP用引号： UI -->|"9. 轮询 processedOrders"| RP或去空格： UI -->|9.轮询processedOrders| RP引号版本更清晰。症状：复合 arrow 之间冲突 -.->|"文字"| 和 -->|"文字"| 混用时，某些版本解析 -. 的 dashed 箭头出错。检查每个箭头的正确写法：想要语法实线箭头 -->虚线箭头 -.->粗线箭头 ==>无箭头连线 ---带文字 `-->不要在 -. 中间插空格，- . -> 是错的。一个可复用的修复清单复制过去一份混乱的流程图，按这四步过一遍：所有节点文本都用 ["..."] 双引号包 subgraph 用 subgraph X["Y"] 引号包边上文字全部 |"..."| 引号包把 : 换成 () 或去掉改完再渲染基本就通了。快速验证工具不用等博客/Notion 重新渲染，直接：mermaid.live 官方在线编辑器，实时看错误 VSCode 装 "Mermaid Preview" 插件本地预览一句话总结 "Mermaid 报错 = 有特殊字符没加引号"。四类地方都用 "..." 包起来（节点、subgraph、边文字、特殊符号周围），复杂图也不容易崩。