PlantUML vs Mermaid 语法对照：7 种常用图逐行对照

puml.online
  2026-08-04 09:30 2026-08-04 09:30 创建   2026-08-14 21:34:29 2026-08-14 21:34:29 更新    

看完上篇的宏观对比，这一篇是「实际想画图时」的 cheat sheet。每个图类型都给到：最小例子 → 关键差异 → 容易踩的坑——你只需复制粘贴就能跑。

总览：哪些图类型是「同等强」的

图类型 PlantUML Mermaid 谁更强
时序图 ✅ ✅ PlantUML（fragment / step / ref）
类图 ✅ ✅ PlantUML（关联语义完整）
流程图 ✅ ✅ Mermaid（语法更直观）
ER 图 ✅ ✅ 平
状态图 ✅ ✅ PlantUML（嵌套 / 并发）
甘特图 ✅ ✅ Mermaid（任务依赖更直观）
C4 架构 ✅ 内置 stdlib ❌ 需插件 PlantUML

接下来逐图对照。

1. 时序图（Sequence）

最小例子：Alice/Bob 鉴权流程

PlantUML：

1
2
3
4
5
6
7
8
9
@startuml
actor User
User -> FE: 输入用户名密码
FE -> API: POST /login
API -> Auth: 校验 token
Auth --> API: token 有效
API --> FE: 200 OK + JWT
FE --> User: 跳转首页
@enduml

Mermaid：

1
2
3
4
5
6
7
8
sequenceDiagram
    actor User
    User->>FE: 输入用户名密码
    FE->>API: POST /login
    API->>Auth: 校验 token
    Auth-->>API: token 有效
    API-->>FE: 200 OK + JWT
    FE-->>User: 跳转首页

关键差异：

维度 PlantUML Mermaid
起始标记 @startuml / @enduml sequenceDiagram 关键字
实线箭头 -> ->>
虚线箭头 --> -->>
自调用 A -> A: ... A->>A: ...
异步消息 ->> ⇢ ->> 不分；用 Note right of A: async 标记
分组（alt/else/opt/loop） 原生 alt/else/opt/loop/end 原生 alt/else/opt/loop/end
注释 note left of User: ... Note left of User: ...（首字母大写）
参与者声明 actor User / participant "User Service" as US actor User / participant US as User Service
编号 自动 自动
激活生命线 activate A / deactivate A activate A / deactivate A
跨图引用 ref over A: ... v11+：ref over A: ...

踩坑：

  • Mermaid 的 actor 必须放在 sequenceDiagram 之后的作用域，不能挪到图中间
  • PlantUML 注释 note left/right/over 关键字不能拼错（note 全小写）
  • 两者 alt 块内必须带 else 或 end（Mermaid 严格，PlantUML 容忍）

2. 类图（Class Diagram）

最小例子：User / Order

PlantUML：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
@startuml
class User {
  -id: Long
  -name: String
  +login(pwd: String): Token
}

class Order {
  -id: Long
  -amount: Decimal
  +pay(): void
}

User "1" --> "*" Order: places
User ..> Token: <<create>>

interface Payable {
  +pay(): void
}
Order .|> Payable
@enduml

Mermaid：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
classDiagram
  class User {
    -id: Long
    -name: String
    +login(pwd: String) Token
  }
  class Order {
    -id: Long
    -amount: Decimal
    +pay() void
  }
  User "1" --> "*" Order : places
  User ..> Token : <<create>>
  class Payable {
    <<interface>>
    +pay() void
  }
  Order ..|> Payable

关键差异：

维度 PlantUML Mermaid
可见性 +/-/#/~ +/-/#/~（同）
静态 / 抽象 {static} / {abstract} <<static>> / <<abstract>> 泛型
关联箭头 -->（实）--|>（继承）..|>（实现）..>（依赖） --> --|> ..|> ..>（同）
多重性 "1" --> "*" "1" --> "*"（同）
注释 note left of User: ... note for User "..."（v11+）
包 / 命名空间 package com.example { ... } namespace com.example { ... }
泛型 class List~T~ class List~T~（同）
接口 interface Payable <<interface>> 标签
枚举 enum Status { ACTIVE INACTIVE } 不支持原生枚举（用 class 模拟）

踩坑：

  • Mermaid 实现接口用 ..|>（不是 ..>），很多人写错
  • Mermaid 嵌套类支持较弱，复杂层级建议用 PlantUML
  • PlantUML 的 +login(pwd: String): Token 冒号后类型不能写带空格的方法体

3. 流程图（Flowchart）

最小例子：用户登录决策树

PlantUML：

1
2
3
4
5
6
7
8
9
10
11
12
@startuml
(*) --> "输入用户名密码"
if "校验通过?" then
  -->[是] "生成 JWT"
  --> "返回 token"
  --> (*)
else
  -->[否] "返回错误"
  --> "记录失败日志"
  --> (*)
endif
@enduml

Mermaid：

1
2
3
4
5
6
7
8
flowchart TD
    A[输入用户名密码] --> B{校验通过?}
    B -->|是| C[生成 JWT]
    C --> D[返回 token]
    D --> End1([完成])
    B -->|否| E[返回错误]
    E --> F[记录失败日志]
    F --> End2([完成])

关键差异：

维度 PlantUML Mermaid
方向 top to bottom direction 默认 flowchart TD / LR 显式
节点形状 rectangle / diamond / circle 关键字 [ ] { } (( )) ([ ]) 等符号
标签 node1 --> "label text" `node1 –>
子图 rectangle cluster { ... } subgraph ... end
样式 node1 #lightblue classDef + class 绑定
链向节点 (*) 起止 ([ ]) stadium
注释 单行受限 %% 行注释

踩坑：

  • Mermaid 节点 label 含特殊字符（/、[]、()）要加引号
  • PlantUML flowchart 不如 sequence/class 强；复杂流程建议用 Mermaid 或升到 PlantUML activity 图
  • Mermaid v10+ 才支持 subgraph 同名复用

4. ER 图（Entity Relationship）

最小例子：User / Order / Product

PlantUML：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
@startuml
entity User {
  *id: Long <<PK>>
  --
  name: String
  email: String
}
entity Order {
  *id: Long <<PK>>
  --
  user_id: Long <<FK>>
  amount: Decimal
}
entity Product {
  *id: Long <<PK>>
  --
  name: String
  price: Decimal
}
User ||--o{ Order: places
Order }o--|| Product: contains
@enduml

Mermaid：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
erDiagram
  USER ||--o{ ORDER : places
  ORDER }o--|| PRODUCT : contains

  USER {
    Long id PK
    String name
    String email
  }
  ORDER {
    Long id PK
    Long user_id FK
    Decimal amount
  }
  PRODUCT {
    Long id PK
    String name
    Decimal price
  }

关键差异：

维度 PlantUML Mermaid
外键标注 <<FK>> 内嵌属性 Long user_id FK（属性名后）
主键 <<PK>> PK 后缀
基数 ||--o{ }o--|| 同
关系名 User --> Order: places USER ||--o{ ORDER : places
弱实体 entity Weak + 关系上 ..|> ❌ 不支持
继承 Parent <|-- Child ❌ 不支持

踩坑：

  • Mermaid 关键字 PK/FK 要紧跟字段名（空格分隔）
  • PlantUML ER 图本质是 entity 类图，可以加方法；Mermaid ER 图只能放字段
  • 复杂 schema（十几张表）建议 PlantUML；简单 3-5 张表 Mermaid 写起来更快

5. 状态图（State Machine）

最小例子：订单状态机

PlantUML：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@startuml
[*] --> Pending
Pending --> Paid: 支付
Paid --> Shipped: 发货
Shipped --> Delivered: 确认收货
Paid --> Refunded: 退款
Delivered --> [*]
Refunded --> [*]

state Paid {
  [*] --> AwaitingShipping
  AwaitingShipping --> Shipping
}
@enduml

Mermaid：

1
2
3
4
5
6
7
8
9
10
11
12
13
stateDiagram-v2
    [*] --> Pending
    Pending --> Paid : 支付
    Paid --> Shipped : 发货
    Shipped --> Delivered : 确认收货
    Paid --> Refunded : 退款
    Delivered --> [*]
    Refunded --> [*]

    state Paid {
        [*] --> AwaitingShipping
        AwaitingShipping --> Shipping
    }

关键差异：

维度 PlantUML Mermaid
起始标记 [*] [*]（同）
嵌套 state Outer { state Inner { ... } } state Outer { ... }
并发 state A { -- || ==} 不支持
选择 state c1 <<choice>> state c1 <<choice>>（同）
历史状态 state X <<history>> ❌ 不支持
注释 note right of State: ... note right of State : ...
入口/出口动作 State : entry / action 不支持

踩坑：

  • Mermaid 必须用 stateDiagram-v2（v1 已废弃）
  • PlantUML 嵌套层级深时容易乱，建议用 package 包起来
  • Mermaid 嵌套状态缩进必须严格（4 空格或 2 空格，不要混）

6. 甘特图（Gantt）

最小例子：两周 sprint 计划

PlantUML：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@startuml
title Sprint 23
dateformat YYYY-MM-DD
scale 1920 width

[需求评审] as [需求] lasts 1 days
[设计] as [设计] starts at [需求]'s end
[开发] as [开发] starts at [设计]'s end
[开发] lasts 5 days
[联调] as [联调] starts at [开发]'s end
[联调] lasts 2 days
[提测] as [提测] starts at [联调]'s end
[发布] as [发布] starts at [提测]'s end
[发布] lasts 1 days
@enduml

Mermaid：

1
2
3
4
5
6
7
8
9
10
11
12
gantt
    title Sprint 23
    dateFormat YYYY-MM-DD
    section 准备
    需求评审       :a1, 2026-08-04, 1d
    设计           :a2, after a1, 2d
    section 开发
    开发           :a3, after a2, 5d
    section 验收
    联调           :a4, after a3, 2d
    提测           :a5, after a4, 1d
    发布           :a6, after a5, 1d

关键差异：

维度 PlantUML Mermaid
任务依赖 starts at [任务]'s end after a1（用 alias）
里程碑 今天 is milestone :milestone, m1, 2026-08-10, 0d
进度 [任务] lasts 5 days and is 60% completed :a3, after a2, 5d + done 状态
状态 done active crit done active crit
分组 隐式（按顺序） section 显式
日期格式 dateformat YYYY-MM-DD dateFormat YYYY-MM-DD
工作日 monday are closed 不支持

踩坑：

  • PlantUML 的 alias 必须 [a] as [b] 写在前面才能后面引用
  • Mermaid milestone 用 0d 标记
  • PlantUML 缺少 section 显式分组，长甘特图会乱

7. C4 架构图

最小例子：System Context

PlantUML（用 C4-PlantUML stdlib）：

1
2
3
4
5
6
7
8
9
10
@startuml
!include <C4/C4_Context>

Person(user, "用户", "使用系统")
System(webapp, "Web 应用", "提供 UI")
System_Ext(payment, "支付服务", "外部支付")

Rel(user, webapp, "使用")
Rel(webapp, payment, "调用支付 API", "HTTPS")
@enduml

Mermaid（v11+ 实验性支持）：

1
2
3
4
5
6
7
8
%%{init: {"theme": "default"}}%%
C4Context
    title 系统上下文图
    Person(user, "用户", "使用系统")
    System(webapp, "Web 应用", "提供 UI")
    System_Ext(payment, "支付服务", "外部支付")
    Rel(user, webapp, "使用")
    Rel(webapp, payment, "调用支付 API", "HTTPS")

关键差异：

维度 PlantUML Mermaid
C4 支持 官方 stdlib（25+ 内置图） v11+ 实验性，需要 %%{init}%%
Container / Component / Dynamic 都有 也有（v11+）
主题 LAYOUT_WITH_LEGEND() 几十种 默认 1 种
部署图 Deployment_Node C4Deployment
风险 无（成熟） v11+ 改 API 多次，文档不全

结论：C4 这块 PlantUML 完胜。Mermaid 在 v11+ 才有 C4，但语法飘忽，文档跟不上。

速查表：五个最常掉的坑

  1. Mermaid 注释：note left of A: ...（首字母大写）
  2. PlantUML 注释：note left of A: ...（首字母小写）
  3. 箭头方向：Mermaid 实线 ->> 虚线 -->>（双 >）；PlantUML 实线 -> 虚线 -->
  4. 类图实现：两者都是 ..|>（不是 ..>）
  5. 状态图起始：Mermaid 必须 stateDiagram-v2，不能用 stateDiagram

跨工具迁移提示

  • PlantUML → Mermaid：类图和时序图迁移最稳，ER 和 state 容易掉属性
  • Mermaid → PlantUML：语法更宽松，几乎一定能转；注意 flowchart 转 PlantUML activity 时会丢一些节点形状
  • 自动转换工具：推荐 mermaid-to-plantuml（Node CLI）和 plantuml-to-mermaid（Python，损失较大）

怎么决定：用哪个画？

回到决策：

  • 简单流程图 / README / 文档嵌入 → Mermaid（copy-paste 即用）
  • UML 严格 / 复杂类图 / C4 → PlantUML
  • GitHub README → Mermaid（原生 ```mermaid）
  • CI 自动批量校验 → PlantUML（CLI 严谨）
  • 跨语言（中文/日文/emoji） → 优先 Mermaid（字体问题少）

延伸阅读

  • 标题: PlantUML vs Mermaid 语法对照：7 种常用图逐行对照
  • 作者: puml.online
  • 创建于 : 2026-08-04 09:30:00
  • 更新于 : 2026-08-14 21:34:29
  • 链接: https://puml.online/blog/plantuml-mermaid-syntax/
  • 版权声明: 本文章采用 CC BY-NC-SA 4.0 进行许可。
目录
PlantUML vs Mermaid 语法对照：7 种常用图逐行对照
  1. 总览：哪些图类型是「同等强」的
  2. 1. 时序图（Sequence）
  3. 2. 类图（Class Diagram）
  4. 3. 流程图（Flowchart）
  5. 4. ER 图（Entity Relationship）
  6. 5. 状态图（State Machine）
  7. 6. 甘特图（Gantt）
  8. 7. C4 架构图
  9. 速查表：五个最常掉的坑
  10. 跨工具迁移提示
  11. 怎么决定：用哪个画？
  12. 延伸阅读