Mermaid vs PlantUML 软件架构图：架构基线该选谁？
只比较正式软件架构建模能力，PlantUML 更强，应作为架构基线的默认选择；Mermaid 适合服务地图和频繁变化的资源总览。 如果你需要整体工具对比，请看 Mermaid vs PlantUML 系列总览；如果只关心 C4 语法和成熟度，可以直接看 Mermaid C4 vs C4-PlantUML。
本文的官方资料统一核验于 2026-07-22。这里的“架构基线”指要在评审、设计归档和跨团队沟通中长期维护的图，而不是每一张服务关系草图。需要 UML 专用的组件或部署表示法、共享样式、可复用 include 和长期治理时，应选 PlantUML；服务与资源关系随实现频繁调整时，Mermaid 更合适。
“软件架构图”范围很大，可能指简单服务地图、UML 组件图、部署拓扑，也可能指 C4 Context 或 Container 视图。不先说明视图类型，任何工具比较都会变得空泛。本文会把这些任务拆开。
核心结论
- 架构基线优先 PlantUML：组件接口、部署节点和样式复用都有专用表达。
- Mermaid Architecture Diagram 适合服务与资源总览，但不等同于 UML Deployment Diagram。
- Mermaid 官网最新版已增加布局控制；本项目锁定的 11.6.0 不能直接使用 11.15.0、11.16.0 新增语法。
- C4 关注抽象层级，时序图关注消息级交互，二者不应互相替代。
官方能力参考：
- Mermaid Architecture Diagram 官方文档
- Mermaid Block Diagram 官方文档
- PlantUML Component Diagram 官方文档
- PlantUML Deployment Diagram 官方文档
Mermaid vs PlantUML 软件架构图核心差异是什么？
| 架构任务 | Mermaid | PlantUML | 更好的默认选择 |
|---|---|---|---|
| 临时服务地图 | Flowchart 或 Architecture Diagram | 组件风格图 | Mermaid |
| 系统上下文 | C4、Flowchart 或 Architecture Diagram | C4-PlantUML 或组件图 | 临时上下文说明选 Mermaid，架构基线选 C4-PlantUML |
| 组件接口 | 用 Architecture、Block、Flowchart 或 C4 近似 | 内置 component、port 和 interface 语法 | PlantUML |
| 部署拓扑 | Architecture 或 experimental C4 Deployment 可说明资源 | 内置 node、artifact、database、queue 和嵌套部署元素 | PlantUML |
| 云与资源总览 | Architecture Diagram 的 group、service、junction 和 icon | 部署图加标准库图标 | 取决于所需细节和规范程度 |
| 共享图形规范 | 主题和配置，部分图类型有边界 | include、宏、主题、stereotype 和 skinparam | PlantUML |
| 混合架构视图 | 多种 Mermaid 图类型 | 广泛 UML 图族与 C4 库 | 统一表示法图集选 PlantUML |
Mermaid Architecture Diagram 和 PlantUML Deployment Diagram 不是同一套标准。它们在展示服务与基础设施时有交集，但承诺不同：Mermaid 提供简洁的资源地图，PlantUML 提供更丰富的 UML 导向建模语言。
这张架构图究竟要回答什么问题？
选择语法之前，先说清楚架构问题：
- 谁使用系统，哪些内容在边界之外？ 使用 Context 视图。
- 系统由哪些应用和数据存储组成？ 使用 Container 或服务视图。
- 哪些模块提供或消费接口？ 使用 Component 视图。
- 进程和构件运行在哪里？ 使用 Deployment 视图。
- 一次请求如何执行？ 应该使用时序图，而不是再画一张方框地图。
- 业务流程如何分支？ 使用活动图。
这样可以避免最常见的“万能架构图”问题：一页方框同时混入业务边界、源码模块、运行节点和请求顺序，却没有清楚回答任何一个问题。
Mermaid 什么时候适合服务与资源地图？
Mermaid Architecture Diagram 官方文档说明该图型从 11.1.0 起提供，并包含 group、service、edge 和 junction。官网最新版文档中，11.15.0 已提供 nodeSeparation、idealEdgeLengthMultiplier、edgeElasticity、numIter 与确定性 seed 等布局参数，11.16.0 再提供 align row、align column。这些是最新版能力；本项目锁定 Mermaid 11.6.0，不能把它们当作当前可用语法。
architecture-beta
group app(cloud)[Application]
service web(internet)[Web App] in app
service api(server)[API] in app
service db(database)[Database] in app
service queue(disk)[Job Queue] in app
web:R --> L:api
api:B --> T:db
api:R --> L:queue
这张图只回答一个问题：核心资源之间如何通信。服务或资源关系变化时，可以直接更新对应节点和连线，而不混入组件契约或部署语义。
以下架构任务尤其适合 Mermaid：
- 架构随代码频繁变化。
group、service、junction已足以表达所需资源关系。- 图的目标是展示当前服务地图，而不是定义组件接口或部署节点语义。
- 简单依赖关系比明确的 port 或 UML 部署表示法更重要。
不要把所有架构问题都塞进这张图。如果同时加入团队、源码 package、Kubernetes node、请求步骤、数据库、队列和安全区域，任何语法都会得到过载模型。
PlantUML 更适合组件契约
组件图不只是用箭头连接方框。它可能需要提供与依赖接口、dependency、package、boundary、stereotype 和稳定命名规则。
@startuml
skinparam componentStyle uml2
package "OnUML Platform" {
[Web App] as Web
[Diagram API] as API
[Render Service] as Renderer
database "Project Store" as DB
interface "Diagram Commands" as Commands
interface "Render Requests" as RenderRequests
Web - Commands
Commands - API
API - RenderRequests
RenderRequests - Renderer
API --> DB : reads and writes
}
@enduml
Mermaid 可以使用 Flowchart、Block Diagram、Architecture Diagram 或 C4 Component 近似表达这类结构，用于说明时可能已经够用。如果接口与依赖本身就是评审契约，而不只是线条标签，PlantUML 更合适。
如果重点是对象结构、继承、组合和方法级建模，请看专门的 Mermaid vs PlantUML 类图对比。类图不应该承担服务边界，组件图也不应该列出每一个类。
部署视图为什么是 PlantUML 明显拉开差距的地方？
部署视图回答软件运行在哪里。PlantUML 可以嵌套 node、execution environment、artifact、database、queue、storage 和其他运行元素。
@startuml
node "Edge Network" as Edge {
artifact "Next.js Web App" as Web
artifact "API Routes" as API
}
cloud "Managed Services" as Cloud {
database "PostgreSQL" as DB
queue "Render Queue" as Queue
node "Render Worker" as Worker
}
Web --> API : HTTPS
API --> DB : SQL
API --> Queue : enqueue
Queue --> Worker : deliver job
Worker --> DB : store result
@enduml
Mermaid Architecture Diagram 可以画出类似资源拓扑，Mermaid C4 也提供 Deployment 视图。需要明确的嵌套运行环境、artifact、节点类型、可复用基础设施样式，或者需要一整套相关 UML 图时，PlantUML 仍然更强。
更重要的是保持语义诚实：
- Mermaid Architecture Diagram 可以是一张很好的部署总览。
- 不能因此把它描述成完全等价的 UML Deployment Diagram。
- PlantUML Deployment Diagram 也可以只保留必要节点；UML 专用表示法不要求把所有运行细节塞进一张图。
C4 与时序图应该放在架构文档的哪里？
C4 把架构组织成 Context、Container、Component 和 Code 四个核心静态层级。它决定展示哪个抽象层级，Mermaid 或 PlantUML 决定如何描述和渲染；C4 Dynamic 说明静态模型元素在一个用例中的协作，时序图则用于消息级顺序与调用语义。
需要正式 C4 文档时，详细比较与语法边界请看 Mermaid C4 vs C4-PlantUML。需要解释一次请求的消息级交互，请改用 Mermaid vs PlantUML 时序图，不要在架构地图中塞入调用先后。
实用的混合策略
所有图统一一种语法可以简化工具链，但不一定是最低维护成本。一个实用分法是：
| 文档层级 | 建议格式 | 原因 |
|---|---|---|
| 服务依赖总览 | Mermaid Architecture 或 Flowchart | 直接表达服务、资源和连接关系 |
| API 交互 | Mermaid 或 PlantUML Sequence | 根据交互复杂度选择 |
| 架构基线 | PlantUML 或 C4-PlantUML | 共享规范和复用能力更强 |
| 组件契约 | PlantUML | 接口语义更完整 |
| 部署拓扑 | PlantUML | 运行环境和节点建模更丰富 |
同时使用两种语法的前提是每张图都有负责人和明确目的。否则同一架构会被重复维护，增加文档漂移风险。
应该怎么选软件架构图工具？
以下情况选择 Mermaid：
- 需要频繁跟随服务或资源关系变化。
- 主要用于说明服务、资源或较小的系统边界。
- 不要求组件接口、嵌套部署节点或跨图样式复用。
以下情况选择 PlantUML：
- 图属于长期维护的架构基线。
- 需要 UML 组件或部署语义。
- 共享 include、宏、stereotype、theme 或 icon 很重要。
- 多种架构视图需要统一渲染流程。
频繁变化的服务地图与治理型架构资产有不同负责人和更新节奏时，可以同时使用两者。
FAQ
Mermaid 足够画软件架构图吗？
如果图用于解释服务关系、系统边界或资源总览，通常足够。评审依赖明确的组件 port 和 interface、嵌套部署节点、高级复用或严格视觉规范时，PlantUML 更合适。
Mermaid 能画部署图吗？
Mermaid 可以用 Architecture Diagram，或者目前仍属于 experimental 的 C4 Deployment 语法表达部署导向视图。它们能够说明云资源和运行拓扑，但不等同于 PlantUML 的 UML 部署表示法；PlantUML 提供了更丰富的部署专用元素。
所有架构图都应该使用 C4 吗？
不需要。多个抽象层级能帮助读者理解系统时，C4 很有价值。小型服务可能只需要一张依赖图和一张时序图。只维护真正能回答问题的最小视图集合。
微服务架构应该选哪个？
频繁更新的服务地图通常更适合 Mermaid；治理型架构基线通常更适合 PlantUML 或 C4-PlantUML。要表达一次请求经过哪些微服务，时序图会比两种架构地图都更清楚。
最后总结：Mermaid 让服务地图贴近日常工程工作；PlantUML 为组件和部署文档提供更明确的表示法、复用和控制能力。为每一张图先确定问题，再决定语法，能减少文档漂移。