字数 2820，阅读大约需 15 分钟

如果你日常需要画架构图、ER图、部署图，大概率跟PlantUML或Mermaid打过交道。用过就知道，这两个工具在简单场景下够用，图一复杂就开始折磨人。

今天聊一个比较牛的开源项目——D2。这是一个声明式图表脚本语言，我用了半年，把团队文档里的图全从PlantUML迁到了它上面。

D2：用文本描述图表，缩进即层级

D2是一个声明式图表脚本语言。你写文本，它出图。缩进表示层级，箭头表示连线，就这么简单。

这是最基础的例子：

x -> y -> z

三字母，一张有向图：

用代码画图这事不新鲜，主流软件都有，D2跟它们比有个关键区别：它从一开始就没打算只做「能出图就行」。它瞄准的是「能出好看的图，而且在你不干预的情况下」，这在文本绘图领域几乎是个空白。

上面这张图就是D2的招牌demo。左边是文本，右边是渲染出来的SVG。注意看那个卫星图标的重复排列、storage的圆柱体、container的虚线边框。你用draw.io拖拽出这个效果，保守估计十分钟。D2写出来大概三十行，而且可复用。

现在这个项目24k+ star，Go写的，CLI一条命令安装：

curl -fsSL https://d2lang.com/install.sh | sh -s --

macOS用户也能直接 brew install d2。装完就能用，不用配环境变量，不用装Java运行时。这个后面会说为什么重要。

老牌文本绘图工具的问题：PlantUML、Mermaid、Graphviz

我说个真实的痛点。

PlantUML画时序图还行。画架构图？那就是在跟布局引擎打架。你定义了A包含B，B连线到C，出来的图里B跑到A外面去了，C被挤到了画布右下角。你想调，得加一堆skinparam、ortho、linetype，这些参数之间的交互关系跟玄学差不多。

Mermaid更让人血压高。GitHub原生支持Markdown里的mermaid代码块，这是它的大杀器。你写个README，贴段mermaid代码，GitHub自动渲染。爽吗？等你图里的节点超过十个就知道了。自动布局一塌糊涂，线条交叉成蜘蛛网，你想手动调？对不起，Mermaid的布局控制选项少得可怜。Mermaid v11集成了ELK布局引擎，有改善，但也就那样。

还有个被很多人忽略的问题：错误提示。

PlantUML报错经常就是一句 Syntax Error?，带个问号。你盯着300行代码找了二十分钟，发现少了个引号。Mermaid稍微好一点，但也就好那么一点。这俩工具在错误提示这件事上，都活在上个时代。

然后是环境问题。PlantUML依赖Java运行时。你在CI流水线里想自动生成架构图？先装JRE，配Graphviz依赖，然后祈祷版本兼容。我去年在一个Docker镜像里折腾PlantUML环境，耗掉了一个下午。

Graphviz的DOT语言更不用说了。1991年的设计，语法跟考古现场似的。画出来的图自带一股学术论文味，你把它放进产品文档里，设计师会跟你绝交。

我列个表直观对比一下当前主流文本绘图工具（数据来自text-to-diagram.com，Terrastruct官方维护的对比站）：

老工具的问题不是功能不够。是它们的设计理念停留在了「把图画出来就行」，没考虑过「画图这个过程本身」有多折磨人。

D2相比这些老工具，优势在哪

我不是要写一篇D2的feature list。GitHub README已经写得很全了。我挑几个我用下来真正觉得这个工具牛的点来说：

缩进语法决定层级关系，不用额外声明父子节点

D2的语法设计遵循一个原则：你在文本里看到的层级结构，就是图里的层级结构。

network: {
  cell tower: {
    satellites: {
      shape: stored_data
      style.multiple: true
    }
    transmitter
  }
}

network包含cell tower，cell tower包含satellites。你不需要额外声明父子关系，缩进就决定了容器嵌套。这在Mermaid和PlantUML里做不到这么自然。Mermaid的subgraph声明很啰嗦，PlantUML的package语法跟缩进无关，你得用花括号手动管理作用域。

写完保存，d2 --watch in.d2 out.svg，浏览器自动刷新。改一个字，图立刻更新。这个watch模式的体验跟前端开发里的hot reload一样顺滑。

三个布局引擎覆盖不同场景，默认效果就够用

文本绘图工具的核心能力是自动布局。再好用的语法，布局烂就是废物。

D2内置了三个布局引擎：Dagre（默认，适合层级图）、ELK（适合节点连线复杂的图）、TALA（Terrastruct自研，针对软件架构图优化）。你可以在文件头部切换：

    
vars: {
  d2-config: {
    layout-engine: elk
  }
}

我实测下来，Dagre处理大多数场景足够用。ELK在处理容器嵌套多、连线方向复杂的架构图时明显更好。TALA需要额外安装，但对大型架构图的效果是最接近「不用手动调」这个理想的。

对比Mermaid：Mermaid的自动布局在超过15个节点后基本不可控。对比PlantUML：PlantUML布局能力强但调参成本极高。D2的定位是「默认效果足够好，你可以不调」。

内置多套专业主题，导出的图可以直接放进文档

这是D2最让我舒服的地方。

D2内置了多套正式主题，从浅色到深色，从简洁到商务。切换主题一行配置：

theme-id: 1

你不需要像PlantUML那样写几十行skinparam调颜色、调字体、调边框圆角。D2的主题是专业设计师做的，不是程序员随手配的色板。

除了正经主题，D2还有个sketch模式，手绘风格。你写文档的时候用它画草稿图，看起来像是白板上拍的照片，这在早期方案讨论里比正式框图更有亲和力。

D2还支持响应式暗黑模式。你的文档切到暗色主题，图里的颜色自动跟着变。这在Mermaid里做不到。

错误信息具体到行，告诉你哪里错、怎么改

D2的parser会尽量收集所有错误，而不是遇到一个就罢工。错误信息告诉你第几行、什么问题、怎么改。

实际体验：我写D2的时候，报错说「第47行 x -> 后面缺目标节点」，我扫一眼就知道怎么改。PlantUML只会回你一个 Syntax Error?，Mermaid给你一堆调用栈。

这个差距就是「工具在帮你」和「工具在恶心你」的区别。

插件生态覆盖VSCode、Obsidian、Confluence等主流工具

D2有官方的VSCode插件、Vim插件、Obsidian插件、Slack App、Discord bot。社区贡献了Emacs mode、Confluence插件、Maven插件、Pandoc filter……列表太长，你去看GitHub README的Related部分。

对我来说最实用的是VSCode插件。语法高亮、自动补全、实时预览，体验跟写代码一样。Obsidian插件也很方便，我在笔记里画架构草图直接写d2代码块。

还几个大项目在用D2画架构图：ElasticSearch、Sourcegraph、Temporal、Tauri（78.5k star那个Rust GUI框架）、JetBrains IntelliJ、LocalStack。一个2022年才发布的项目被这些团队采用，多少说明了问题。

可以作为Go库调用，程序化批量生成图表

如果你用Go，可以直接把D2当library引入，程序化生成图表。这是Mermaid做不到的（它依赖浏览器渲染），PlantUML理论上可以但极其笨重。

import "oss.terrastruct.com/d2/d2compiler"
import "oss.terrastruct.com/d2/d2renderers/d2svg"

你在CI里跑测试，测试结果自动生成架构现状图，提交到文档仓库。或者写个脚本扫数据库schema，自动生成ER图。这种场景D2是原生支持的。

从文本生成动画图表，多步骤过渡一张SVG搞定

D2是目前唯一支持从文本生成动画图表的语言。你定义多个step，它生成带过渡效果的SVG。

这在做技术分享PPT的时候是个杀手锏。你不用画三张图来表示架构演进过程，一个D2文件定义三个layer，导出一个带动画的SVG。Mermaid做不到，PlantUML做不到，draw.io做不到。

D2目前的短板

GitHub不原生渲染、图标库不够全、TALA有付费版

夸完了，说说不爽的地方。

GitHub不原生渲染D2。 这是Mermaid的护城河，目前谁也跨不过去。你写README，贴mermaid代码块，GitHub自动出图。D2不行，你得在CI里生成SVG提交到仓库，或者用社区GitHub Action。Terrastruct官方的说法是他们一直在跟GitHub沟通，但这事主动权在GitHub手里。

图标库不够全。 D2的icons.terrastruct.com提供了一些常用图标，但跟draw.io内置的AWS/GCP/Azure图标库比差远了。你想画云架构图，图标得自己找URL引入。

TALA布局引擎的free版和pro版有差距。 TALA是Terrastruct的商业产品，开源用户可以用免费版binary，但功能有裁切。这我能理解，毕竟公司要赚钱。D2 Studio（他们的商业IDE）也是付费的。不过核心D2语言和CLI是完全开源的MPL 2.0协议，日常用足够了。

语法还在迭代，D2还没到1.0。不过从2022年到现在更新节奏很稳，changelog写得详细，没出现过大版本破坏性变更。

结尾

这是一款比较牛的画图工具，上手很简单，语法和yml有点接近，非常值得一试。

可能有很多小伙伴要说了，AI时代了，有必要用这些专业工具画图吗？笔者想说的是，AI 解决的是"从无到有"，而专业工具解决的是"从有到精、从精到准"，两者根本不是同一个赛道。

当然，如果日常简单用一下，画个草图，AI还是又快又准的，但是要形成沉淀，统一风格的公司团队流程图资产，这些专业工具短时间没有看到能被取代的。不过用AI辅助做前期工作还是很棒的，目前没有看到关于这个软件的Skill，有兴趣的同学赶紧整一个挂GitHub。

GitHub地址：

https://github.com/terrastruct/D2