d2-diagrams

D2 图表

擅长使用 D2（一种现代图表脚本语言）通过声明式文本定义生成图表。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 Mermaid……
需要丰富的样式、类和主题	在 GitHub Markdown 中嵌入图表
需要复杂的嵌套容器布局	只需样式简单的流程图
需要带图标的架构图	需要在文档平台中原生渲染的图表
需要带彩色边的决策树	需要时序图（Mermaid 的语法更丰富）
需要 SQL 表 / ERD 图	优先考虑广泛的工具支持

如需详细的功能对比，请参阅 REFERENCE.md。

核心专长

• 声明式语法：描述要绘制的图表，布局由 D2 处理
• 多种布局引擎：dagre（默认）、elk、tala（高级版）
• 丰富的主题：内置 100 多种主题，支持深色模式
• 多种输出格式：SVG、PNG、PDF、GIF（动画）
• 监视模式：文件更改时自动重新生成

安装

# mise (preferred)
mise install d2 && mise use -g d2

# macOS
brew install d2

# Linux/Windows (via curl)
curl -fsSL https://d2lang.com/install.sh | sh -s --

# Go install
go install oss.terrastruct.com/d2@latest

基本命令

基本渲染

# Convert to SVG (default)
d2 diagram.d2 diagram.svg

# Convert to PNG
d2 diagram.d2 diagram.png

# Convert to PDF
d2 diagram.d2 diagram.pdf

# Output to stdout
d2 diagram.d2 -

PNG 前提条件：首次渲染 PNG 时会下载捆绑的 Chromium（约 140 MB）。首次运行预计会延迟约 1 分钟；之后的渲染速度很快。

监视模式

# Watch and auto-regenerate
d2 --watch diagram.d2 diagram.svg

# Watch with browser preview
d2 --watch --browser diagram.d2

主题

# List available themes
d2 themes

# Use specific theme (by ID)
d2 -t 101 diagram.d2 output.svg

# Dark theme (respects system preference)
d2 --dark-theme 200 diagram.d2 output.svg

# Combine light and dark themes
d2 -t 1 --dark-theme 200 diagram.d2 output.svg

布局引擎

# List available layouts
d2 layout

# Use specific layout
d2 -l elk diagram.d2 output.svg
d2 -l dagre diagram.d2 output.svg

草图模式

# Hand-drawn style
d2 --sketch diagram.d2 output.svg

D2 语法

基本形状和连接

# Shapes (auto-created)
server
database
client

# Connections
client -> server: request
server -> database: query
database -> server: result
server -> client: response

# Bidirectional
a <-> b

# Undirected
a -- b

形状类型

# Explicit shapes
rect: {shape: rectangle}
oval: {shape: oval}
cyl: {shape: cylinder}
queue: {shape: queue}
pkg: {shape: package}
step: {shape: step}
page: {shape: page}
doc: {shape: document}
cloud: {shape: cloud}
diamond: {shape: diamond}
hex: {shape: hexagon}
para: {shape: parallelogram}
circle: {shape: circle}

容器（嵌套）

server: {
  app: Application
  db: Database
  app -> db
}

client -> server.app

标签和图标

# Labels
a: "My Label"
a -> b: "connection label"

# Icons (from icon packs)
server: {
  icon: https://icons.terrastruct.com/essentials/004-server.svg
}

# Tooltip
node: {
  tooltip: Additional information shown on hover
}

# Links
github: {
  link: https://github.com
}

样式

# Inline styles
styled: {
  style: {
    fill: "#ff6b6b"
    stroke: "#c92a2a"
    stroke-width: 2
    border-radius: 8
    shadow: true
    opacity: 0.9
    font-color: white
  }
}

# Connection styles
a -> b: {
  style: {
    stroke: red
    stroke-width: 3
    stroke-dash: 5
    animated: true
  }
}

Glob 模式

# Style all shapes
*: {
  style.fill: lightblue
}

# Style all connections
* -> *: {
  style.stroke: gray
}

类（可复用样式）

定义命名样式集，并将其应用于多个节点/边。

classes: {
  error: {
    style: {
      fill: "#ffebee"
      stroke: "#c62828"
      font-color: "#c62828"
      border-radius: 8
    }
  }
  success: {
    style: {
      fill: "#e8f5e9"
      stroke: "#2e7d32"
      font-color: "#2e7d32"
      border-radius: 8
    }
  }
  decision: {
    shape: diamond
    style: {
      fill: "#fff3e0"
      stroke: "#e65100"
      font-color: "#e65100"
    }
  }
}

# Apply a class
start: Start {class: success}
check: Valid? {class: decision}
fail: Error {class: error}

start -> check
check -> fail: No

变量

vars: {
  primary-color: "#4a90d9"
}

box: {
  style.fill: ${primary-color}
}

文件中的配置

vars: {
  d2-config: {
    layout: elk
    theme: 4
    dark-theme: 200
    pad: 20
    sketch: true
  }
}

# Diagram content
a -> b -> c

常见图表模式

系统架构

direction: right

client: Client {
  icon: https://icons.terrastruct.com/essentials/user.svg
}

lb: Load Balancer {
  icon: https://icons.terrastruct.com/aws/Networking%20&%20Content%20Delivery/Elastic%20Load%20Balancing.svg
}

services: Services {
  api: API Server
  auth: Auth Service
  api -> auth: validate
}

data: Data Layer {
  db: PostgreSQL {
    shape: cylinder
  }
  cache: Redis {
    shape: cylinder
  }
}

client -> lb -> services.api
services.api -> data.db
services.api -> data.cache

类时序流程

direction: right

user: User
frontend: Frontend
api: API
db: Database

user -> frontend: 1. Click button
frontend -> api: 2. POST /action
api -> db: 3. INSERT
db -> api: 4. OK
api -> frontend: 5. 200 OK
frontend -> user: 6. Show success

决策树 / 流程图

使用类确保样式一致，用菱形表示决策，并为“是/否”路径使用彩色边。

classes: {
  decision: {
    shape: diamond
    style: {
      fill: "#fff3e0"
      stroke: "#e65100"
      font-color: "#e65100"
    }
  }
  action: {
    shape: rectangle
    style: {
      fill: "#e3f2fd"
      stroke: "#1565c0"
      font-color: "#1565c0"
      border-radius: 8
    }
  }
  terminal: {
    shape: oval
    style: {
      fill: "#e8f5e9"
      stroke: "#2e7d32"
      font-color: "#2e7d32"
    }
  }
  warn: {
    shape: hexagon
    style: {
      fill: "#ffebee"
      stroke: "#c62828"
      font-color: "#c62828"
    }
  }
}

start: Start {class: terminal}
staged: Staged changes? {class: decision}
lint: Run linter {class: action}
pass: Lint pass? {class: decision}
commit: Create commit {class: action}
done: Done {class: terminal}
fix: Fix issues {class: warn}

start -> staged
staged -> lint: Yes {style.stroke: green}
staged -> done: No {style.stroke: red}
lint -> pass
pass -> commit: Yes {style.stroke: green}
pass -> fix: No {style.stroke: red}
fix -> lint
commit -> done

有关更多模式（数据库 ERD、Kubernetes 部署）、特殊形状（sql_table、class、代码块）、图层、主题类别，以及 D2 与 Mermaid 的完整对比，请参阅 REFERENCE.md。

面向 Agent 的优化

场景	命令
快速生成 SVG	d2 diagram.d2 diagram.svg
实时预览	d2 --watch --browser diagram.d2
深色主题	d2 --dark-theme 200 diagram.d2 output.svg
草图样式	d2 --sketch diagram.d2 output.svg
ELK 布局	d2 -l elk diagram.d2 output.svg
列出主题	d2 themes
导出 PNG	d2 --scale 2 diagram.d2 output.png

快速参考

标志	说明
-w, --watch	监视更改并重新生成
--browser	打开浏览器预览（配合 --watch 使用）
-t, --theme	主题 ID（运行 d2 themes 查看列表）
--dark-theme	深色模式主题 ID
-l, --layout	布局引擎：dagre、elk、tala
--sketch	手绘风格
--scale	输出缩放比例（例如，使用 2 可获得 2 倍分辨率）
--pad	图表内边距（像素）
--center	将图表居中
--animate-interval	动画帧间隔（毫秒）
-h, --help	显示帮助