如何打开 .mmd 文件

.mmd 文件是一个普通的文本文件，里面装着一张 Mermaid 图。它既不是图片也不是二进制格式——用任何文本编辑器都能打开并读懂。想把它看成图，就拖到下面的方框里。渲染发生在你自己的浏览器中，没有任何内容会送到服务器上。

把 .mmd 文件拖到这里

也接受 .mermaid、.md 和 .txt。文件在浏览器里读取，绝不会被上传。

.mmd 文件是什么

Mermaid 是一套用文字描述图表的语法。你用文字把图讲出来，引擎负责画——就像 Markdown 描述排版、引擎生成页面一样。.mmd 文件里装的就是这段文字，别的什么都没有：没有样式，没有图像数据，没有元信息。

这个格式存在的全部理由就在这里。因为是文本，图就能和它所描述的代码一起放进 Git 仓库，一次改动会显示成一段读得懂的 diff，而不是一个被整体替换的二进制文件。下面就是一个完整而有效的 .mmd 文件：

发布.mmd —— 整个文件，六行
flowchart LR
    提交[推送到 main] --> 构建[运行测试]
    构建 -->|成功| 发布[部署到生产环境]
    构建 -->|失败| 通知[通知提交者]
    发布 --> 冒烟[冒烟测试]
    冒烟 --> 完成[发布结束]

用什么打开 .mmd 文件

简单说：双击几乎打不开 .mmd 文件，因为这个扩展名没有关联到任何应用程序。你真正需要的是能渲染 Mermaid 的东西。下面是我实测过的，以及那些行不通的地方。

本站能打开

立刻把文件渲染出来

把文件拖到上面的方框里就能得到图。没有上传这一步：文件通过 File API 在浏览器里读取，在本地渲染，所以哪怕是不允许外发的图也能这样看。

如果你想改图而不只是看图，用预览下方的链接在编辑器里打开它。

任何文本编辑器能打开

显示源码，而不是图

记事本、Notepad++、vim，什么都行。.mmd 文件是 UTF-8 文本，源码马上就能看到。你看不到图，这并不是坏了——文件里本来就没有可显示的图像。

这也是判断别人发来的文件是不是真的 Mermaid 的最快方式：打开它，看第一个非空行是不是 flowchart、sequenceDiagram、classDiagram、stateDiagram-v2、erDiagram 或 gantt 这样的图类型关键字。

GitHub打不开

能渲染 Markdown 里的 ```mermaid 代码块，但不渲染 .mmd 文件

GitHub 在带围栏的代码块里渲染 Mermaid。文档明确列出了具体位置：issue、Discussions、pull request、wiki 和 Markdown 文件。单独的 .mmd 文件不在这个名单上，在仓库文件浏览器里打开它只会看到源码文本。

所以如果你希望图在 GitHub 上可见，它必须放在 .md 文件的 ```mermaid 代码块里，而不是放在自己的 .mmd 文件中。把 .mmd 作为源文件保留，同时在 README 里重复同样的内容，是一种常见且合理的重复。

GitLab打不开

能渲染 ```mermaid 代码块，但不渲染 .mmd 文件，而且用的还是旧版 Mermaid

和 GitHub 的格局一样：Mermaid 在 Markdown、issue、merge request 和 wiki 的围栏代码块中渲染，但没有任何地方写着单独的 .mmd 文件会被渲染。

还有第二件值得知道的事，因为它确实造成了混乱。GitLab.com 声明支持 Mermaid 第 10 版，而本站运行在 11.12.2 上。第 10 版之后新增的语法在这里能渲染，在那边会报错——「浏览器里好好的，我们 GitLab 上就不行」通常就是这么来的。自建的 GitLab 还有第三个陷阱：当 Cross-Origin-Resource-Policy 响应头设为 same-site 或 same-origin 时，Mermaid 图会静默失败——没有错误，也没有图。

.mmd、.mermaid 和 .md

.mmd 和 .mermaid 是一回事。两者都只装 Mermaid 源码，我知道的所有工具，接受其中一个就接受另一个。.mmd 更短也更常见，官方命令行工具默认用的就是它。在一个项目里挑一个用到底即可——这个选择没有任何技术后果。

.md 则是另一类东西。Markdown 文件是一份文档，里面可以包含一张 Mermaid 图，被一个以三个反引号加 mermaid 开头的代码块包住。图只是一段更大文本里的一个片段。

这个区别是文件渲染不出来的最常见原因，而且它是双向起作用的。把 .md 文件的内容粘进 Mermaid 查看器，它会报错，因为围栏那一行不是 Mermaid 语法。反过来，把一张裸的 Mermaid 图不带围栏地存进 .md 文件，GitHub 会把它当成一段普通文字显示。规则很简单：.mmd 文件必须以图类型关键字开头，而 .md 文件里的图必须放在围栏代码块中。

本查看器接受 .mmd、.mermaid、.md 和 .txt，但会把读到的一切都当作原始 Mermaid。如果你拖进来的是一份图周围还有正文的 Markdown，请先把不是图的部分都删掉。

渲染不出来——到底哪里出了问题

Mermaid 的错误信息精确但不友好。一个管用的窍门是只读信息的结尾：`got` 后面就是解析器卡住的那个记号，它比行号更能说明问题出在哪。下面每一种情况我都在 mermaid 11.12.2 上重现过：错误版本确实会报错，修好的版本确实能渲染。

你会看到

No diagram type detected matching given configuration for text: ```mermaid

原因

你从 Markdown 文件或聊天记录里复制图时，把围栏也一起带过来了。三个反引号属于 Markdown 而不是 Mermaid，所以解析器根本走不到图那里。

解决办法

删掉开头的 ```mermaid 和结尾的 ```。文件必须以图类型关键字开头。

错误写法
```mermaid
flowchart TD
    A[开始] --> B[结束]
```
正确写法
flowchart TD
    A[开始] --> B[结束]

你会看到

Parse error，结尾是：got 'PS'

错误结尾是: got 'PS'

原因

节点标签里有一个左圆括号。在 Mermaid 中圆括号属于形状语法——A(文字) 表示圆角节点——所以方括号里裸露的圆括号会被读成一个新形状的开始。

解决办法

把标签用引号括起来。引号内的一切都按纯文本处理，包括括号。

错误写法
flowchart TD
    A[调用扣款(订单)] --> B[结束]
正确写法
flowchart TD
    A["调用扣款(订单)"] --> B[结束]

你会看到

Parse error，结尾是：got 'end'

错误结尾是: got 'end'

原因

你把 end 当成了节点标识符。小写的 end 用来关闭子图，所以解析器在等待一个节点的位置看到了块结束。这比想象中常见：照着英文示例写的时候，最后一个节点很容易就被命名成了 end，哪怕图的其余部分都是中文。

解决办法

改成大写，或者给这个节点换一个标识符，把这个词移到标签里。用 `结束` 完全没有问题。

错误写法
flowchart TD
    A[开始] --> end
正确写法
flowchart TD
    A[开始] --> 结束[已完成]

你会看到

在你给节点命名的那一行出现 Parse error

原因

节点标识符里有空格。中文本身词与词之间不留空格，所以这个问题比在西方语言里少得多，但它仍然会发生——当标识符里混进了拉丁字母、数字或全角空格的时候。标识符是箭头前面的那个记号，空格会把它截断。

解决办法

给节点一个不含空格的标识符，把可读的文字放进标签。中文汉字本身在标识符里完全可用——实测：`订单`、`付款`、`已发货` 都能正常渲染。

错误写法
flowchart TD
    auth service --> user db
正确写法
flowchart TD
    订单[新订单] --> 付款[已付款]

你会看到

Parse error，结尾是：got 'STR'

错误结尾是: got 'STR'

原因

节点标签里有一个半角双引号。解析器把它当成字符串的开始，随后在等待收尾引号的位置遇到了标签的方括号。

解决办法

把整个标签用半角引号括起来，里面改用中文引号「」，或者把该字符写成 HTML 实体 #quot;。

错误写法
flowchart TD
    A[他说"好的"] --> B[结束]
正确写法
flowchart TD
    A["他说「好的」"] --> B[结束]

你会看到

能渲染，但同一个东西在图里出现了两次

原因

同一个概念用了两种写法。Mermaid 是逐字符比较的，`订单` 和 `訂單` 是两个完全不同的标识符，简繁混用会毫无提示地生成两个框。同样的情况也出现在同义词上，比如 `客户` 和 `顾客`。这是中文写作里最容易踩的静默错误，因为两种写法看上去都对。

解决办法

在一张图里统一简繁，也统一术语。如果图是几个人一起改的，这一点尤其值得在开头用 `%%` 注释写清楚。

错误写法
erDiagram
    客户 ||--o{ 订单 : "下单"
    顾客 ||--o{ 发票 : "开具"
正确写法
erDiagram
    客户 ||--o{ 订单 : "下单"
    客户 ||--o{ 发票 : "开具"

你会看到

能渲染，但状态图里一个状态裂成了好几个框

原因

状态标识符里有空格。和流程图不同，状态图不会报错：它给每一个被空格分开的部分都建一个独立的框，只有第一个连在箭头上。中文通常不写空格，所以这个问题比在西方语言里罕见得多，但只要状态名里夹了数字或拉丁字母，空格就会出现。

解决办法

用 `state "标签" as 标识符` 声明状态，之后一律用标识符引用它。

错误写法
stateDiagram-v2
    [*] --> 等待付款 24 小时
    等待付款 24 小时 --> 已关闭
正确写法
stateDiagram-v2
    state "等待付款 24 小时" as 等待付款
    [*] --> 等待付款
    等待付款 --> 已关闭

你会看到

能渲染，但 ER 图里出现了你没写过的实体

原因

关系标签里有空格却没有加引号。中文关系短语通常不含空格，所以这个陷阱对中文的杀伤力比对西方语言小得多，但只要标签里出现了空格——比如夹了英文词或数字——它就会发作：Mermaid 不报错，只是在第一个空格处把标签截断，把剩下的每个词都变成一个空实体。

解决办法

凡是含空格的关系标签一律加引号。养成永远加引号的习惯最省心。

错误写法
erDiagram
    客户 ||--o{ 订单 : 下单 via API
正确写法
erDiagram
    客户 ||--o{ 订单 : "下单 via API"

你会看到

No diagram type detected matching given configuration for text: sequencediagram

原因

图类型关键字拼错了，或者大小写不对。Mermaid 的关键字区分大小写：sequenceDiagram 可以，sequencediagram 不行。stateDiagram-v2 和 erDiagram 同理。

解决办法

改对大小写。顺带一提，graph 仍然被当作 flowchart 的旧别名接受，所以那套老语法不会成为你的麻烦。

错误写法
sequencediagram
    客户端->>接口: 你好
正确写法
sequenceDiagram
    客户端->>接口: 你好

你会看到

在两条竖线之间的连线标签里出现 Parse error

原因

连线标签里有括号。`|…|` 之间的文本和节点标签受同样的限制：括号在那里也是语法而不是文本。

解决办法

把连线标签也用引号括起来。

错误写法
flowchart TD
    A -->|是 (总是)| B
正确写法
flowchart TD
    A -->|"是 (总是)"| B

你会看到

Parse error 指向图的最后一行

原因

有一个块打开了却从未关闭：alt、opt、loop、par 和 subgraph 都各自需要一个 end。Mermaid 在输入耗尽的地方报错，所以行号指的是文件末尾，而不是那个没关的块。

解决办法

数一数打开的块和你写的 end。错误指向最后一行时，几乎总是这个原因。

错误写法
sequenceDiagram
    客户端->>接口: 请求
    alt 一切正常
        接口-->>客户端: 200
正确写法
sequenceDiagram
    客户端->>接口: 请求
    alt 一切正常
        接口-->>客户端: 200
    end

你会看到

Lexical error on line 1. Unrecognized text.

原因

图类型关键字后面的方向无效。流程图只接受 TB、TD、BT、LR 和 RL，别的都会在词法分析阶段就倒下，那时连一个节点都还没读到。

解决办法

用这五个方向之一。TD 和 LR 覆盖了几乎所有情况。

错误写法
flowchart XY
    A --> B
正确写法
flowchart TD
    A --> B

你会看到

这里能渲染，在 GitLab、Confluence 或某个旧工具里却不行

原因

版本差异。本查看器运行在 Mermaid 11.12.2 上；GitLab.com 文档写的是第 10 版，自建的 wiki 甚至可能落后好几年。在对方版本之后引入的语法在这里能解析，在那边会报错。

解决办法

去问对方引擎的版本。在图里只写一个 info 就能让 Mermaid 把自己的版本号画出来，这比翻更新日志快得多。

正确写法
info

字符编码值得单独说一句，因为在中文文件里它至今仍会让人措手不及。本站和编辑器都按 UTF-8 读取文件，并会去掉开头的 BOM 标记，所以从 Windows 记事本按「UTF-8 带 BOM」保存的文件能正常打开。但按 GB2312、GBK 或 Big5 保存的文件——不少老工具至今还在产出——送过来时汉字就是一堆乱码。如果你看到的是问号或方块而不是汉字，请在编辑器里把文件重新另存为 UTF-8。

另外还有一点值得中文用户特别注意，而它不会给出任何错误：全角标点和全角空格在标识符里是危险的，在标签里却完全没问题。实测：全角空格出现在流程图节点标识符里会直接报 `got 'UNICODE_TEXT'`，而出现在状态标识符里则会静默地把一个状态拆成两个框。如果一张图看上去哪里都对却多出了一个框，先检查有没有混进全角空格。

最后是一件根本不报错的事：在自建的 GitLab 上，Cross-Origin-Resource-Policy 响应头被设为 same-site 或 same-origin 时，Mermaid 图会静默失败。没有提示，没有图，页面上什么都没有。如果一张图在别处都能渲染，唯独在某一套自建环境里不行，那就该往这里查。

转换成 PNG、SVG 或 PDF

在编辑器里打开文件，然后用导出按钮。SVG 把图保存为矢量文字，所以放到多大都清晰，标签还能选中和搜索——用于文档，以及任何以后可能再次导出的场合，这都是正确的选择。PNG 是位图，本站按显示尺寸的二到三倍导出，以便在高密度屏幕上仍然耐看；在不接受 SVG 的地方用它，实际上就是大多数聊天软件和一部分 wiki。

没有 PDF 按钮，与其假装有，我更愿意把这一点写出来。可行的路子是导出 SVG，然后要么把它放进你本来就在写的文档里，要么用浏览器把这个页面打印成 PDF。放进 PDF 里的矢量 SVG 仍然是矢量。

至于一切需要重复执行的场合——构建步骤、批量文件、pre-commit 钩子——官方命令行引擎 @mermaid-js/mermaid-cli 就是为此而生：它接受同样的 .mmd 文件，直接写出图片，不需要浏览器。

常见问题

怎么在线打开 .mmd 文件？
把它拖到本页顶部的方框里。渲染在你的浏览器里完成，不上传，也不需要账号。你也可以打开编辑器，把文件拖到预览面板上。
什么程序能打开 .mmd 文件？
源码用任何文本编辑器都能看，因为文件本身就是纯文本。要看到图，就需要能渲染 Mermaid 的东西：本站、本站的编辑器，或者命令行工具 mermaid-cli。没有哪个桌面程序拥有 .mmd 这个扩展名。
.mmd 和 .mermaid 是一回事吗？
是。两个扩展名装的内容完全一样，可以互换。.mmd 更常见，也是官方命令行工具默认使用的那个。
为什么我的 .mmd 文件在 GitHub 上不渲染？
GitHub 只在 Markdown 文件、issue、Discussions、pull request 和 wiki 里的 ```mermaid 围栏代码块中渲染 Mermaid。单独的 .mmd 文件会按源码文本显示。把同一张图放进 .md 文件的围栏代码块里，它就能在 GitHub 上显示了。
不装任何东西能打开 .mmd 吗？
能——本站就是为此而存在的。渲染是在你的浏览器里以 JavaScript 运行的，所以没有什么要安装，文件也从不离开你的电脑。
汉字能直接用作节点名吗？
可以，而且这一点常被怀疑，所以值得说清楚。实测：`订单`、`付款`、`已发货` 都能直接用作流程图节点标识符、状态名和类名。中文在这方面比印地语和泰语宽松得多——那两种文字在流程图标识符和类名里会被直接拒绝。中文唯一要当心的是空格和全角空格。
汉字显示成了乱码
文件不是 UTF-8。本站按 UTF-8 读取文件，也能正确处理 BOM 标记，但按 GB2312、GBK 或 Big5 保存的文件送过来时汉字会损坏。请在编辑器里重新另存为 UTF-8。
这里能用，我们的 wiki 上却不行，为什么？
几乎总是版本差异。本查看器运行在 Mermaid 11.12.2 上，而很多 wiki 用的是更旧的版本——GitLab.com 文档写的是第 10 版。在对方系统的图里写一个 info，让它把自己运行的版本号打印出来。

你可以在这里打开的图类型

作者：Dominik Malsch · 最后更新:

打开编辑器 →