Mermaid作为轻量级图表文本工具，在文档和代码中越来越常用。但不少人在定义节点时，习惯把说明文字用中括号套圆括号写出来，结果页面直接报语法错。这背后其实是Mermaid词法解析对符号边界的严格约定，而不是编辑器抽风。
一、为什么中括号里直接写圆括号会报错
Mermaid的流程图语法里，中括号[ ]专门用来标记矩形节点的显示文本。解析器在扫描到第一个[后，会一直找到与之配对的]作为节点内容结束。如果你在中间又写了圆括号，例如A[状态(B)]，虽然看起来合理，但某些Mermaid版本在处理嵌套括号时，会因为词法状态切换异常而抛出“Error: Parse error on line 1”的提示。
更麻烦的是，当文本里出现英文逗号、分号或者引号时，解析器可能提前截断节点定义。这不是你写错了逻辑，而是Mermaid默认把很多符号当作语法分隔符。理解这一点，才能选择合适的写法避开冲突。
1.1 常见报错代码片段
下面这段代码在多数在线Mermaid编辑器中都会失败：
flowchart LR
A[开始(初始化)] --> B[处理(C)]
B --> C[结束]
报错信息通常指向第二行，说找不到合法的节点形状。其实只要把内层圆括号转义或者换写法就能解决。
二、三种正确的中括号使用方法
针对节点名称里需要附带括号说明的场景，社区总结出三种稳定写法。它们各有适用面，也存在细微渲染差异。
2.1 使用双引号包裹整个文本
最省事的办法是用双引号把节点显示内容包起来，这样内部的中括号和圆括号都会被当作纯文本：
flowchart LR
A["开始(初始化)"] --> B["处理(C)"]
B --> C["结束"]
这种写法兼容性好，几乎所有Mermaid版本都支持。缺点是如果文本本身含双引号，还需要用HTML实体"替换。在生成脚本里拼字符串时要特别注意转义层级。
2.2 对内部符号进行HTML实体转义
如果不想用双引号，可以把圆括号转义成(和)：
flowchart LR
A[开始(初始化)] --> B[处理(C)]
B --> C[结束]
转义后解析器不再把圆括号当语法符号，节点能正常渲染。适合需要保持中括号原生写法、且内容简单的场景。不过可读性下降，维护时容易看错。
2.3 拆分节点与注解
从图表语义看，把状态名和说明分开更清晰。可以用圆括号节点做说明，中括号节点做主步骤：
flowchart LR
A[开始] --> B[处理]
B --> C[结束]
B --- D((初始化参数))
</p>
<p>这里<code>D((初始化参数))</code>是圆形注解节点，不干扰主流程中括号。适合复杂业务图，但图形会变拥挤。</p>
<h2>三、不同图表类型里的注意点</h2>
<p>除了流程图，时序图和状态图对括号的处理也不完全一样。时序图里直接用<code>participant A[名称(备注)]</code>往往没问题，因为参与者定义语法更宽松；但状态图里的状态名若带中括号嵌套，仍建议加双引号。</p>
<table border="1">
<tr><th>图表类型</th><th>中括号嵌套圆括号</th><th>推荐写法</th></tr>
<tr><td>flowchart</td><td>易报错</td><td>双引号包裹</td></tr>
<tr><td>sequence</td><td>多数支持</td><td>原生写法</td></tr>
<tr><td>stateDiagram</td><td>偶发报错</td><td>双引号或转义</td></tr>
</table>
<p>实际项目中，如果图表由脚本自动生成，统一采用双引号方案能减少条件判断。手动写文档则可按类型灵活选。</p>
<h2>四、编辑器误报与排查建议</h2>
<p>有些IDE插件版本滞后，会把合法的双引号写法标红。这时可用命令行<code>mmdc</code>本地渲染验证：</p>
<pre class=brush:shell;toolbar:false>
npx @mermaid-js/mermaid-cli -i test.mmd -o test.svg
若命令行通过而编辑器报错，基本是插件问题。另外提交到文档仓库前，用CI加一步Mermaid校验，能挡住大部分符号冲突导致的构建失败。
掌握这几条规则后，节点名称里的括号不再是障碍。关键记住：中括号是语法边界，里面要放自由文本就得靠引号或转义隔离，别让解析器猜你的意图。