PlantUML 默认输出 SVG，但实际写文档 / 嵌入 README / 印 PDF / 进 LaTeX 都有不同要求。这篇整理所有输出格式的差异、最佳实践、陷阱。

输出格式速查

1

java -jar plantuml.jar -t<FORMAT> diagram.puml

SVG（默认）

1
2

java -jar plantuml.jar -tsvg diagram.puml
# -> diagram.svg

优点

• 矢量，浏览器缩放无锯齿
• 内嵌 font + CSS 主题
• 纯文本，可以 diff
• 文件小（几 KB 就能画大图）

缺点

• GitHub Markdown 直接渲染 SVG <img> 需要 SVG 文件嵌入或 URL 引用
• 渲染复杂图时浏览器吃内存
• 编辑器预览卡

用 SVG 不踩坑

1
2

# GitHub README 嵌入 SVG
![login](docs/sequence/login.svg)

或：

1

<img src="diagram.svg" alt="login flow" />

PNG

1

java -jar plantuml.jar -tpng diagram.puml

优点

• 几乎所有平台支持
• PPT / 微信文章嵌图
• 静态截图可读

缺点

• 分辨率固定，要 2x 给 retina 屏
• 文件大小比 SVG 大
• 没法 layout 动态调整

设置 DPI

1

java -jar plantuml.jar -tpng -DPI=200 diagram.puml

PDF

1

java -jar plantuml.jar -tpdf diagram.puml

优点

• 矢量打印高质量
• 适合学术论文、正式文档
• 默认 A4 / Letter 页面大小可调整

嵌入 LaTeX 论文

1

java -jar plantuml.jar -tpdf --latex-bibliography diagram.puml

LaTeX

1
2

java -jar plantuml.jar -tlatex diagram.puml
# -> diagram.tex

输出 TikZ 代码：

1
2
3
4
5

\begin{tikzpicture}
\node[rectangle, draw] (A) {A};
\node[rectangle, draw, right of=A] (B) {B};
\draw[->] (A) -- (B);
\end{tikzpicture}

嵌入现有 LaTeX 文档

1

java -jar plantuml.jar -tlatex_no_preamble diagram.puml

latex_no_preamble 输出的 TikZ 没有 \documentclass 等开头，直接 \input{diagram.tex} 就能嵌.

HTML

1
2

java -jar plantuml.jar -thtml diagram.puml
# -> diagram.html

输出 <div> 包裹 SVG 的 HTML 片段：

1
2
3

<div class="plantuml">
<svg>...</svg>
</div>

用于嵌入 Flask / Express / Django 模板。

Unicode 文本 / ASCII

1

java -jar plantuml.jar -tutxt diagram.puml

终端纯字符。最适合 Markdown 转写、邮件、Slack。

实际渲染：

1
2
3
4
5
6
7
8

+--------------------+
|     Hello          |
+--------------------+
         |
         v
+--------------------+
|     World          |
+--------------------+

ASCII 输出小技巧

• -taa 输出 ASCII art（普通 ASCII 字符）
• -taa_text 输出 ASCII 文本格式（保留更多字符）
• -tutxt 输出 Unicode 字符（带边框）

README 嵌入模式对比

模式 A：SVG 文件引用

1
2
3

docs/sequence/login.puml     <- 源码
docs/sequence/login.svg     <- 渲染产物
README.md                   <- ![](docs/sequence/login.svg)

模式 B：Mermaid 风格嵌入

1
2
3
4

```mermaid
sequenceDiagram
  Alice->>Bob: hello
  Bob-->>Alice: reply

1
2
3
4
5
6

```

### 模式 C：plantuml.com URL（无服务端）

```markdown
![alt](https://www.plantuml.com/plantuml/svg/<encoded>)

GitHub 会渲染。

模式 D：自己部署 PlantUML server

1

![alt](https://plantuml.puml.online/svg/<encoded>)

内网安全。

各种场景的格式选择

文档站 + GitHub + Notion

选 SVG（tsvg）。矢量、文件小、文本友好。

PDF 论文 / 印

选 PDF（tpdf）或 LaTeX（tlatex）。学术用 LaTeX 可嵌 TikZ。

PPT / 微信公众号

选 PNG（tpng）并 DPI=200。嵌入兼容性最好。

Slack / 邮件 / IM

选 Unicode 文本（tutxt）。终端纯文本兼容。

Web 模板

选 HTML（thtml）或 SVG（tsvg）。

暗色模式适配

PlantUML 的 SVG 默认浅色主题。在暗色网站里不太搭。

自带 dark theme

1
2
3
4
5

@startuml
!theme dark
class A
A --> B
@enduml

但 dark 主题太黑。

手调 skinparam

1
2
3
4
5
6
7
8
9
10
11

@startuml
skinparam {
  BackgroundColor #161B22
  FontColor #E6EDF3
  BorderColor #30363D
  ArrowColor #58A6FF
}

class A
A --> B
@enduml

或者：

1
2
3
4
5

@startuml
!theme cyborg
class A
A --> B
@enduml

!theme cyborg / !theme black-knight 等预设主题是暗色背景。

CSS @media 自适应

SVG 里内嵌媒体查询：

1

java -jar plantuml.jar -tsvg -DPLANTUML_DARK_MODE_DETECT=true diagram.puml

-DPLANTUML_DARK_MODE_DETECT=true 让 PlantUML 检测浏览器主题。输出的 SVG 会带 CSS media query，dark mode 浏览器里自动切换。

性能对比

复杂类图（>50 节点）：

• SVG: ~200ms 渲染
• PNG: ~300ms
• PDF: ~400ms
• LaTeX: ~300ms

实战：CI 输出多个格式

1
2
3
4
5
6
7
8
9

#!/bin/bash
# scripts/render-all.sh
DIR=docs/architecture

for puml in $(find $DIR -name '*.puml'); do
  java -jar plantuml.jar -tsvg  "$puml"
  java -jar plantuml.jar -tpng -DPI=200 "$puml"
  java -jar plantuml.jar -tpdf  "$puml"
done

但不要全部 commit，仓库里只放 SVG + 源 puml。PNG 和 PDF 在 release / artifact 上传。

实战：editor 嵌入

1
2
3
4
5
6
7
8
9
10
11

<!-- pages/edit.html -->
<style>
  .puml-preview img {
    max-width: 100%;
    height: auto;
  }
</style>

<div class="puml-preview">
  <img src="diagram.svg" alt="sequence diagram" />
</div>

1
2

<!-- 直接内嵌 SVG -->
<object data="diagram.svg" type="image/svg+xml"></object>

<object> 比 <img> 在响应 dark/light CSS 上更灵活。

反模式

1. 在 PR 加 PNG 而不是 SVG

PNG 文件大，不能 diff，渲染慢。改用 SVG。

2. 一图一格式

不要混。例如 blog 站点和论文都用 SVG，统一就是 SVG。要不同格式另存 copy。

3. 不用 dark mode

博客默认白主题，图也白主题。改成统一主题保持一致。

4. 字体不固定

PlantUML 默认用 C:/Windows/Fonts/arial.ttf（Windows）/ Liberation Sans（Linux）。结果：

• A 机器渲染图好，B 机器渲染图差
• 不同字体宽度导致箭头位置差

解决办法：固定字体：

1
2
3
4
5
6

@startuml
skinparam {
  DefaultFontName "Inter"
  DefaultFontSize 12
}
@enduml

CI 渲染也要装对应字体。

评测 checklist

• 输出 SVG 是默认？
• 不同场景选合适格式（PDF / PNG / utxt 等）？
• 字体一致？
• 暗色模式适配？

一句话总结

SVG 适合 95% 场景。论文要 PDF，PPT / 微信要 PNG，IM 要 utxt。所有格式都可一次源码生成，一图多版是文档站标准的做法。