从报错到成功：Mermaid 流程图语法避坑指南✨

🚀 从报错到成功：Mermaid 流程图语法避坑指南 🚀

🚨 问题背景

在开发文档或技术博客中，我们经常使用 Mermaid 流程图 来可视化代码逻辑。但最近我在尝试绘制一个 Java Stream 转换流程图时，遭遇了以下报错：
🔥 Error: Parse error on line 2... Expecting 'SQE', got 'PS' 🔥
经过多次调试，最终解决了 尖括号转义、特殊符号处理 等关键问题。以下是完整的踩坑记录和解决方案！

---

🔍 错误复现

⚠️ 初始错误代码

flowchart TDA[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&lt;InviteCode&gt; // ✅ 正确写法

📝 修改后代码

flowchart TDA[Start: List&lt;InviteCode&gt; <br> inviteCodes] --> B[Stream&lt;InviteCode&gt; <br> inviteCodes.stream()]...

---

🔧 阶段二：特殊符号包裹问题

🎯 新报错

即使转义了尖括号，仍然报错：Expecting 'SQE', got 'PS' 😱

💡 错误根源

Mermaid 对节点文本中的 空格、括号 和 换行符 <br> 敏感，未包裹的文本会被分割成多个语法元素！

✅ 终极修复

用双引号包裹含特殊符号的文本：

- A[Start: List&lt;InviteCode&gt; <br> inviteCodes]  // 🚫 未包裹
+ A["Start: List&lt;InviteCode&gt; <br> inviteCodes"] // ✅ 双引号包裹

🌟 最终正确代码

---

📜 核心原则总结

1. 转义所有尖括号 🔠
   • < → <
   • > → >
   • 📌 通用规则：所有泛型声明都需要转义！

2. 包裹含特殊符号的文本 📦
   • 如果文本包含 [], (), <br>, / 或空格，必须用双引号包裹：["Text with symbols"]
   • ❗ 重要提示：箭头后的节点定义必须立刻接双引号，例如 --> C["描述文本"]

3. 换行符保留规则 ↵
   • <br> 可以正常使用，但必须位于双引号包裹的文本块内

4. 箭头语法的纯净性 ➡️
   • 确保连接符 --> 后面紧跟节点定义，不要掺杂未包裹的文本

---

🛠️ 验证工具推荐

• Mermaid Live Editor 🔗 https://mermaid.live
实时渲染调试，可快速定位语法错误位置，开发者的救命神器！ 🚑

---

🎉 最终效果

---

💡 经验延伸

• 当 Mermaid 报 Expecting 'XXX', got 'YYY' 时，通常意味着：
• 🚩 符号未转义
• 🚩 文本块未正确包裹
• 🚩 存在非法嵌套结构
• 🔍 优先检查箭头连接符（-->）附近的语法
• 👉 复杂文本建议先在 Mermaid Live Editor 中逐段验证

---

希望这篇博客能帮助您避开 Mermaid 的常见语法陷阱。如果遇到其他问题，欢迎在评论区交流！🎯
Happy Coding! 👨💻👩💻

---

✨ 下期预告：如何用 Mermaid 绘制时序图？订阅专栏不错过更新！🔔