最近在整理 WordPress 历史文章时，我遇到了一个 Mermaid 流程图语法问题。
文章中的流程图已经迁移到了 MerPress 的 Mermaid 区块中，但前台并没有正常显示，而是直接出现：
Syntax error in text
mermaid version 11.9.0
Syntax error in text，Mermaid 版本为 11.9.0一开始我以为只是流程图声明写错了，但实际排查下来发现，真正关键的问题并不只在第一行。
最终有效的解决方式是：
A["节点文本"]
而不是：
A[节点文本]
尤其是节点中包含 test()、main()、go test() 这类函数名和中英文混合文本时，这个区别非常重要。
一、最开始发现的第一个问题：流程图 TD
原始 Mermaid 内容中，第一行写成了：
流程图 TD
这当然不是合法的 Mermaid 流程图声明。
Mermaid 应该使用：
flowchart TD
或者：
graph TD
因此最开始我把：
流程图 TD
修改成了：
flowchart TD
例如原来的代码：
流程图 TD
A[程序启动] --> B[主协程启动，执行go test()]
B --> C[子协程test()启动，就绪态]
B --> D[主协程执行自身for循环]
修改为：
flowchart TD
A[程序启动] --> B[主协程启动，执行go test()]
B --> C[子协程test()启动，就绪态]
B --> D[主协程执行自身for循环]
这个修改本身是正确的。
但是保存后再看前台，结果仍然是：
Syntax error in text
mermaid version 11.9.0
也就是说：
流程图 TD 确实有问题，但并不是这张流程图里唯一的问题。
二、flowchart TD 已经正确，为什么还是报错？
继续看流程图代码，可以发现很多节点都采用了这种写法：
B[主协程启动，执行go test()]
以及：
C[子协程test()启动，就绪态]
还有其他场景中的：
B[主协程启动，执行test()（无go关键字）]
C[test()输出hello,world 1]
H[main()输出hello:golang 1]
这些节点文本里面混合了：
test()
main()
go test()
同时还有：
- 中文；
- 英文半角括号
()； - 中文括号
（）； - 逗号；
- 冒号；
- 数字；
- 英文函数名。
这时候，继续只盯着：
flowchart TD
已经没有意义了。
真正需要处理的是：
节点文本的写法。
三、真正有效的解决方案：A["节点文本"]
最终采用的办法很简单：
把：
A[节点文本]
统一改成：
A["节点文本"]
例如：
B[主协程启动，执行go test()]
修改为：
B["主协程启动，执行go test()"]
原来的：
C[子协程test()启动，就绪态]
修改为：
C["子协程test()启动，就绪态"]
再比如：
B[主协程启动，执行test()（无go关键字）]
修改为：
B["主协程启动，执行test()（无go关键字）"]
这才是这次 Syntax error in text 最关键的修复。
也就是说，这次问题可以非常简单地总结为：
A[节点文本]
改成：
A["节点文本"]
四、完整修复后的 Mermaid 示例
以其中一张 goroutine 执行流程图为例，原来的代码大致是：
flowchart TD
A[程序启动] --> B[主协程启动，执行go test()]
B --> C[子协程test()启动，进入就绪态]
B --> D[主协程继续执行自身for循环]
C --> E[子协程输出hello,world 1]
D --> F[主协程输出hello:golang 1]
E --> G[子协程休眠1秒，让出CPU，进入等待态]
F --> H[主协程休眠1秒，让出CPU，进入等待态]
G --> I[子协程休眠结束，进入就绪态，等待调度]
H --> J[主协程休眠结束，进入就绪态，等待调度]
I --> K[调度器分配执行权，子协程输出hello,world 2]
J --> L[调度器分配执行权，主协程输出hello:golang 2]
K --> M[子协程休眠1秒]
L --> N[主协程休眠1秒]
M --> O[重复执行，直到两者都执行10次]
N --> O
O --> P[主协程执行完毕，退出]
O --> Q[子协程执行完毕，退出]
P --> R[程序终止]
Q --> R
最终修改为：
flowchart TD
A["程序启动"] --> B["主协程启动，执行go test()"]
B --> C["子协程test()启动，进入就绪态"]
B --> D["主协程继续执行自身for循环"]
C --> E["子协程输出hello,world 1"]
D --> F["主协程输出hello:golang 1"]
E --> G["子协程休眠1秒，让出CPU，进入等待态"]
F --> H["主协程休眠1秒，让出CPU，进入等待态"]
G --> I["子协程休眠结束，进入就绪态，等待调度"]
H --> J["主协程休眠结束，进入就绪态，等待调度"]
I --> K["调度器分配执行权，子协程输出hello,world 2"]
J --> L["调度器分配执行权，主协程输出hello:golang 2"]
K --> M["子协程休眠1秒"]
L --> N["主协程休眠1秒"]
M --> O["重复执行，直到两者都执行10次"]
N --> O
O --> P["主协程执行完毕，退出"]
O --> Q["子协程执行完毕，退出"]
P --> R["程序终止"]
Q --> R
修改完成后，流程图终于可以正常渲染。
go test()、test()、中文说明以及分支箭头均能够正常渲染五、为什么以后我会优先使用 A["节点文本"]
严格来说，并不是所有 Mermaid 节点都必须写成：
A["节点文本"]
一些简单节点，例如：
A[程序启动]
本身也可能正常解析。
但是对于技术博客来说，流程图节点经常会包含：
test()
main()
time.Sleep()
go test()
runtime.Gosched()
hello,world
hello:golang
同时还会混合中文说明。
如果每次都去判断：
- 哪个括号可能导致问题；
- 哪个标点需要转义；
- 哪种组合 Mermaid 11.9.0 能正常接受；
- 哪种组合又可能触发解析错误；
反而没有必要。
对于普通文字矩形节点，我更倾向于直接统一写成：
A["节点文本"]
例如：
A["程序启动"]
B["主协程启动，执行go test()"]
C["子协程test()启动，就绪态"]
D["主协程执行自身for循环"]
这样简单很多。
六、为什么后来又处理了整篇 WordPress 源码
当时这篇文章里并不只有一张 Mermaid 流程图，而是存在多个 MerPress Mermaid 区块。
既然已经确定修复规则就是：
A[节点文本]
改成：
A["节点文本"]
那如果还在 WordPress 编辑器里逐个打开每张流程图，再一行一行修改，就比较麻烦了，也容易漏掉某一个节点。
所以我后来直接从 WordPress 的源代码编辑器里复制了整篇 Gutenberg 源码，交给 ChatGPT 一次性处理。
这里需要特别说明：
复制整篇 Gutenberg 源码并不是解决 Mermaid 错误的必要步骤。
它只是为了：
已经知道怎么修以后，一次性把文章里的多张 Mermaid 流程图全部改完。
如果一篇文章里只有一张流程图，完全可以直接在 Mermaid 区块中修改：
A[节点文本]
为：
A["节点文本"]
不需要处理整篇 WordPress 源码。
七、这次问题真正的排查顺序
回头看整个过程，实际经历的是：
前台出现：
Syntax error in text
mermaid version 11.9.0
首先发现：
流程图 TD
于是修改为：
flowchart TD
但仍然报错。
然后继续检查节点，发现：
B[主协程启动，执行go test()]
这类节点大量存在。
最终统一改为：
B["主协程启动，执行go test()"]
流程图恢复正常。
所以这次问题并不是：
flowchart TD写错了。
而应该准确地说：
Mermaid 源码存在多处语法兼容问题，修正流程图声明后，节点文本仍然导致解析失败；最终通过给节点文本统一加双引号解决。
八、以后遇到 Syntax error in text，我会怎么处理
如果再次看到：
Syntax error in text
首先还是应该检查流程图声明：
flowchart TD
或者：
flowchart LR
是否正确。
接下来检查：
[]
()
{}
这些括号有没有不完整。
然后重点看节点文本。
例如遇到：
A[test()]
B[执行go test()]
C[main()执行结束]
我会优先直接改成：
A["test()"]
B["执行go test()"]
C["main()执行结束"]
对于技术博客中的普通文字节点，这已经可以作为一个比较实用的默认规则。
九、这也补充了我的历史文章迁移规则
这次问题是在处理 WordPress 历史文章格式迁移时遇到的。
过去很多流程图、终端输出、代码和说明内容都被放在 SyntaxHighlighter 之类的历史代码区块中。
迁移时，并不是所有内容都应该机械转换成 Code Block Pro。
例如真正的流程图内容，更适合转换为：
MerPress / Mermaid
因此迁移验收也不能简单要求：
原 SyntaxHighlighter 数量
=
新 Code Block Pro 数量
更合理的最低要求应该是：
SyntaxHighlighter = 0
原来的内容可以根据实际类型分别迁移成：
Code Block Pro
Mermaid
普通段落
其他更合适的 Gutenberg 区块
但对于 Mermaid，又需要额外增加一个验证条件：
区块存在还不够，必须保证 Mermaid 源码能够实际渲染。
因为：
<!-- wp:merpress/mermaidjs -->
存在，只能说明 Gutenberg 区块已经创建成功。
如果内部源码存在问题，前台仍然会显示：
Syntax error in text
所以以后 Mermaid 迁移的验收应该包含：
Mermaid 区块存在
+
源码结构正确
+
前台能够正常渲染
十、总结
这次遇到的错误是：
Syntax error in text
mermaid version 11.9.0
最开始发现流程图第一行写成了：
流程图 TD
修改为：
flowchart TD
之后，错误仍然存在。
继续检查后，最终确定真正有效的解决方式是：
A[节点文本]
修改为：
A["节点文本"]
尤其是节点中包含：
test()
main()
go test()
time.Sleep()
或者中英文、括号、标点混合内容时，统一使用双引号会更加稳妥。
所以这次最值得记住的其实不是复杂的排查流程，而只有这一条：
flowchart TD
A["节点文本"]
而不是：
flowchart TD
A[节点文本]
后来之所以把整篇 Gutenberg 源码复制出来处理，只是因为文章里存在多张 Mermaid 流程图，方便一次性全部修改，并不是解决问题所必需的步骤。
最终，修复后的流程图已经能够正常显示。
图3：最终修复后的 Mermaid 11.9.0 流程图正常渲染，不再出现 Syntax error in text
这次也算给后续 WordPress 历史文章迁移增加了一条很实用的经验：
Mermaid 普通文字节点优先使用 A["节点文本"]，不要等前台出现语法错误后再逐个处理。
需要长期技术维护或远程问题排查？
我是拥有 15+ 年经验的 PHP / Go 后端工程师，长期关注已有系统维护、Bug 修复、性能优化、服务器排查、WordPress 网站维护和小功能迭代。
如果你的项目遇到以下情况，可以先从一次小问题排查开始合作：
- ✅ PHP / Laravel / Yii2 老项目无人维护
- ✅ Go / Gin 后端接口需要排查或优化
- ✅ WordPress 网站访问慢、报错或插件冲突
- ✅ Nginx / MySQL / Redis / Linux 服务器异常
- ✅ CDN / Cloudflare / DNS / HTTPS 配置问题
- ✅ 需要长期远程技术支持或兼职维护
更多介绍请查看：关于我 & 合作
微信：13980074657
邮箱：shuijingwanwq@gmail.com
Telegram：@shuijingwan
GitHub：https://github.com/shuijingwan
发表回复