🚀 从报错到成功：Mermaid 流程图语法避坑指南 🚀
🚨 问题背景
在开发文档或技术博客中，我们经常使用 Mermaid 流程图 来可视化代码逻辑。但最近我在尝试绘制一个 Java Stream 转换流程图时，遭遇了以下报错：
🔥 Error: Parse error on line 2... Expecting 'SQE', got 'PS' 🔥
经过多次调试，最终解决了 尖括号转义、特殊符号处理 等关键问题。以下是完整的踩坑记录和解决方案！
🔍 错误复现
⚠️ 初始错误代码
flowchart TD
A[Start: List<InviteCode> <br> inviteCodes] --> B[Stream<InviteCode> <br> inviteCodes.stream()]
B --> C[For each InviteCode in Stream]
...
❌ 错误现象
Mermaid 解析器报错：Expecting 'SQE', got 'PS'，指向箭头连接符后的节点定义，流程图直接 渲染失败！💥
🛠️ 分步解决方案
🔧 阶段一：尖括号转义问题
🎯 错误原因
Mermaid 会将 < 和 > 识别为 HTML 标签，导致语法树解析混乱。例如 List<InviteCode> 会被误认为 未闭合的标签。
✅ 修复方法
使用 HTML 实体转义符号：
- List<InviteCode> // 🚫 错误写法
+ List<InviteCode> // ✅ 正确写法
📝 修改后代码
flowchart TD
A[Start: List<InviteCode> <br> inviteCodes] --> B[Stream<InviteCode> <br> inviteCodes.stream()]
...
🔧 阶段二：特殊符号包裹问题
🎯 新报错
即使转义了尖括号，仍然报错：Expecting 'SQE', got 'PS' 😱
💡 错误根源
Mermaid 对节点文本中的 空格、括号 和 换行符 <br> 敏感，未包裹的文本会被分割成多个语法元素！
✅ 终极修复
用双引号包裹含特殊符号的文本：
- A[Start: List<InviteCode> <br> inviteCodes] // 🚫 未包裹
+ A["Start: List<InviteCode> <br> inviteCodes"] // ✅ 双引号包裹
🌟 最终正确代码
📜 核心原则总结
-
转义所有尖括号 🔠
•<→<
•>→>
• 📌 通用规则：所有泛型声明都需要转义！ -
包裹含特殊符号的文本 📦
• 如果文本包含[],(),<br>,/或空格，必须用双引号包裹：["Text with symbols"]
• ❗ 重要提示：箭头后的节点定义必须立刻接双引号，例如--> C["描述文本"] -
换行符保留规则 ↵
•<br>可以正常使用，但必须位于双引号包裹的文本块内 -
箭头语法的纯净性 ➡️
• 确保连接符-->后面紧跟节点定义，不要掺杂未包裹的文本
🛠️ 验证工具推荐
• Mermaid Live Editor 🔗 https://mermaid.live
实时渲染调试，可快速定位语法错误位置，开发者的救命神器！ 🚑
🎉 最终效果
💡 经验延伸
• 当 Mermaid 报 Expecting 'XXX', got 'YYY' 时，通常意味着：
• 🚩 符号未转义
• 🚩 文本块未正确包裹
• 🚩 存在非法嵌套结构
• 🔍 优先检查箭头连接符（-->）附近的语法
• 👉 复杂文本建议先在 Mermaid Live Editor 中逐段验证
希望这篇博客能帮助您避开 Mermaid 的常见语法陷阱。如果遇到其他问题，欢迎在评论区交流！🎯
Happy Coding! 👨💻👩💻
✨ 下期预告：如何用 Mermaid 绘制时序图？订阅专栏不错过更新！🔔
