D2 声明式图表语言入门指南
一、概述
1. 简介
A. 是什么
D2（Declarative Diagramming）是一种声明式图表脚本语言，能够将文本描述转换为可视化图表。用户只需用简洁的语法描述想要展示的内容，D2 会自动处理布局和渲染，生成专业的架构图、流程图等图表。
B. 为什么学
- 解决传统绘图工具操作繁琐、版本管理困难的问题
- 代码即图表，便于版本控制和协作
- 内置智能布局引擎，自动优化图表结构
- 支持多种主题和样式，快速生成美观图表
C. 学完能做什么
- 使用 D2 语法编写架构图、流程图、序列图等
- 通过 CLI 工具将文本转换为 SVG、PNG 等格式
- 利用 Playground 实时预览和调试图表
- 在文档、博客中嵌入可维护的图表代码
2. 前置知识
A. 必备技能
- 基本文本编辑器操作
- 命令行基础操作
B. 推荐知识
- 了解软件架构图、流程图等图表概念
- 熟悉 YAML 或 JSON 等配置格式
二、环境准备
1. 系统要求
D2 是跨平台工具，支持：
- Linux
- macOS
- Windows
2. 安装步骤
使用包管理器安装：
macOS（Homebrew）：
brew install d2Linux：
curl -fsSL https://d2lang.com/install.sh | sh或从 GitHub Releases 页面下载二进制文件：
https://github.com/terrastruct/d2/releases
3. 验证安装
d2 version三、核心概念
1. 基本术语
- 声明式（Declarative）：描述想要什么，而不是如何实现
- 节点（Node）：图表中的元素，如实体、组件、角色等
- 边（Edge）：节点之间的关系或连接
- 形状（Shape）：节点的视觉表现形式，如矩形、圆形、数据库图标等
- 布局引擎（Layout Engine）：负责自动排列节点和边的算法
2. 工作原理
graph LR
A[D2 源码] --> B[D2 CLI]
B --> C[布局引擎]
C --> D[渲染器]
D --> E[输出图片]
F[配置文件] --> B
G[主题文件] --> D
D2 解析用户编写的声明式代码，通过布局引擎计算节点位置，最后渲染成可视化图表。
四、快速上手
1. Hello World 示例
创建文件 input.d2：
# 创建两个节点和一条连接
A -> B: Hello运行命令：
d2 input.d2 output.svg2. 核心功能演示
A. 定义节点
user: 用户
server: 服务器
database: 数据库B. 创建连接
user -> server: 请求
server -> database: 查询C. 设置样式
user: {
shape: person
style: {
fill: #e1f5fe
}
}3. 代码讲解
D2 语法简洁直观：
- 节点名称直接书写，冒号后可添加标签
- 箭头 -> 表示连接关系
- 花括号 {} 用于定义属性和子元素
- 注释使用 # 符号
五、进阶内容
1. 常用功能
A. 嵌套结构
network: {
cell tower: 基站
satellites: 卫星
transmitter: 发射器
satellites -> transmitter: send
}B. 多种形状
D2 支持丰富的形状类型：
- rectangle：矩形（默认）
- circle：圆形
- diamond：菱形
- cylinder：圆柱体（数据库）
- hexagon：六边形
- person：人物图标
- stored_data：存储图标
- page：页面图标
C. 样式定制
connection -> database: {
style.stroke-dash: 3
label: 访问
}2. 最佳实践
- 使用有意义的节点命名
- 合理组织嵌套结构
- 利用主题保持视觉一致性
- 使用注释说明复杂逻辑
- 配合版本管理追踪变更
3. 性能优化
- 大型图表使用 ELK 布局引擎（--layout elk）
- 启用 watch 模式实时预览（-w 参数）
- 使用变量复用配置（vars 块）
六、实战案例
1. 场景描述
绘制一个完整的软件系统架构图，包含用户界面、API 服务、数据处理和存储等组件。
2. 实现步骤
编写完整的 D2 代码：
vars: {
d2-config: {
layout-engine: elk
theme-id: 300
}
}
network: {
cell tower: {
satellites: {
shape: stored_data
style.multiple: true
}
transmitter
satellites -> transmitter: send
}
online portal: {
ui: {shape: hexagon}
}
data processor: {
storage: {
shape: cylinder
style.multiple: true
}
}
cell tower.transmitter -> data processor.storage: phone logs
}
user: {
shape: person
width: 130
}
user -> network.cell tower: make call
user -> network.online portal.ui: access {
style.stroke-dash: 3
}
api server -> network.online portal.ui: display
api server -> logs: persist
logs: {shape: page; style.multiple: true}
network.data processor -> api server生成图表：
d2 --theme=300 --dark-theme=200 -l elk --pad 0 ./input.d2 ./output.svg使用 watch 模式：
d2 -w input.d2这样在编辑 input.d2 时，图表会自动更新。
七、常见问题
1. 安装问题
Q: macOS 安装后找不到 d2 命令
A: 确保将 Homebrew 安装路径添加到 PATH：
export PATH="/opt/homebrew/bin:$PATH"2. 配置问题
Q: 如何自定义主题
A: 在代码中使用 vars 块配置：
vars: {
d2-config: {
theme-id: 自定义主题ID
}
}3. 运行问题
Q: 生成的图表布局不理想
A: 尝试不同的布局引擎：
- dagre：层次化布局（默认）
- elk：层级布局，适合复杂图
- tala：力导向布局
八、学习资源
1. 官方资源
- D2 官方文档：https://d2lang.com/tour/intro
- 在线 Playground：https://play.d2lang.com
- GitHub 仓库：https://github.com/terrastruct/d2
2. 社区资源
3. 快速参考
文档末尾提供速查表（Cheat Sheet），涵盖常用语法和示例。