---
title: Mermaid 常见错误排查
canonical: "https://mermaid.vloam.com/zh/docs/common-errors/"
pubDate: 2026-09-13
author: Vloam
description: 修好在本编辑器里最常导致预览失败的 Mermaid 写法问题：缺少图类型、括号引号不成对、全角标点、箭头混用，以及把失败图缩到三行再逐步加回的调试步骤。
---

预览失败时，先读错误提示。多数情况改一处就能好。

## 缺少图类型

每张图的第一行都要有类型：

- `flowchart TD`
- `sequenceDiagram`
- `classDiagram`
- `stateDiagram-v2`

如果只粘贴了图的中间部分，Mermaid 不知道该用哪套规则。先补上头部，再试一次。

## 括号或引号不成对

标签需要成对出现：

- `[文字]` `[[文字]]` `(文字)` `{文字}` `"文字"`

少了一个 `]` 或 `"`，错误常常出现在文件末尾附近。先检查你刚改过的最后几行。

## 标签里的特殊字符

节点标签里的某些字符会干扰解析。把整段标签用引号包起来：

```mermaid
flowchart LR
  A["步骤: 保存并退出"] --> B[完成]
```

如果混进了中文全角标点（`：` `，` `？`），改成半角（`:` `,` `?`），或给标签加引号。

## 箭头和图类型不匹配

流程图用 `-->`。时序图用 `->>` 和 `-->>`。类图用 `<|--` 和 `-->`。混用通常会失败。

切换图类型后，请重写连线。不要把时序图箭头直接贴进流程图。

## 同一 id 用了不同形状

在流程图里，一个 id 只能对应一种形状。下面这种会坏：

```text
A[开始]
A{准备好了吗?}
```

给 `A` 只保留一种形状，或给判断节点换一个新 id。

## 内容是空的

只有空白时，界面会显示为空，不一定报错。如果误清空了编辑器，用工具栏的模板重新开始。

## 快速排查步骤

1. 把图缩到仍会失败的三行。
2. 先修好这三行。
3. 再加回下一个节点或消息。
4. 重复，直到完整故事能渲染。

编辑器会把最近草稿留在浏览器里。大改之前先复制一份可用版本，就不怕试错。