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、边文字、特殊符号周围），复杂图也不容易崩。