PlantUML 导出后处理:从 SVG 到 PDF/PPT/Markdown 嵌入

PlantUML 默认只输出 SVG/PNG,但实际项目里要嵌进 PDF、PPT、Word、Notion、企业 wiki。这篇是各种导出格式的转换脚本、踩坑、性能取舍。

三种核心输出格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 默认 SVG
plantuml -tsvg diagram.puml
# 输出:diagram.svg — 矢量,适合网页

# PNG(位图)
plantuml -tpng diagram.puml
# 输出:diagram.png — 适合不支持 SVG 的环境

# PDF
plantuml -tpdf diagram.puml
# 输出:diagram.pdf — 适合论文/报告

# LaTeX(嵌入论文)
plantuml -tlatex diagram.puml
# 输出:diagram.tex — TikZ 源码,可被 pdflatex 编译

# EPS(老旧 LaTeX)
plantuml -teps diagram.puml

SVG 是默认且最佳——矢量,文字可选中,色深自由。PNG/PDF 是兼容性 fallback。

SVG 嵌入 Markdown

GitHub / GitLab

1

![架构图](docs/diagrams/architecture.svg)

GitHub 直接渲染 SVG,矢量,放大不模糊。GitLab 同。

Hexo / Hugo(本地静态博客)

看 [plantuml-render-from-hexo] 那篇,推荐 hexo-renderer-plantuml 在 build 阶段预渲染。

Notion

Notion 不支持 SVG 直接上传,先转 PNG:

1

plantuml -tpng -Sresolution=300 diagram.puml

Sresolution=300 让 PNG 是 300 DPI,放大不糊。Notion 接受 PNG 后会再压缩一次,300 DPI 输出刚好。

Confluence

Confluence 接受 SVG 直接上传,但有时会强制转 PNG 显示。要在 macro 里嵌入原始 SVG:

1
2
3
4
5

<ac:structured-macro ac:name="html">
  <ac:plain-text-body><![CDATA[
    <object data="diagram.svg" type="image/svg+xml"></object>
  ]]></ac:plain-text-body>
</ac:structured-macro>

SVG → PNG 高清导出

默认 -tpng 输出 96 DPI,放大模糊。提高分辨率:

1
2
3
4
5

# 200 DPI
plantuml -tpng -Sresolution=200 diagram.puml

# 输出 PNG 格式:PNG-32(透明背景)
plantuml -tpng -SbackgroundColor=transparent diagram.puml

批量脚本:

1
2
3
4
5
6
7
8
9
10

#!/bin/bash
# render-hi-dpi.sh
RES=300
mkdir -p out/hi-dpi
for puml in docs/diagrams/*.puml; do
  base=$(basename "$puml" .puml)
  docker run --rm -v $(pwd):/data plantuml/plantuml \
    -tpng -Sresolution=$RES \
    "/data/$puml" -o "/data/out/hi-dpi/${base}.png"
done

SVG → PDF 嵌入 LaTeX 论文

PlantUML 的 -tpdf 直接出 PDF,质量好。但:

• LaTeX \includegraphics 默认会裁剪 → 用 width=\textwidth 显式指定
• 字体可能跟论文正文不一致 → 用 -SdefaultFontName=Times 强制衬线

1
2
3
4
5
6

\begin{figure}[htbp]
  \centering
  \includegraphics[width=0.8\textwidth]{diagrams/sequence.pdf}
  \caption{用户登录时序图}
  \label{fig:login-sequence}
\end{figure}

-tlatex 输出 TikZ 源码,可被论文直接 include,文字用论文字体。但 -tlatex 不支持所有 PlantUML 特性(复杂组件/部署图有时报错)。

SVG → PPT 演示文稿

PowerPoint 不支持 SVG,必须转 PNG:

1

plantuml -tpng -Sresolution=300 diagram.puml

自动 PPT 嵌入脚本(用 python-pptx):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

from pptx import Presentation
from pathlib import Path

prs = Presentation()
for puml in Path("diagrams").glob("*.puml"):
    # 渲染
    subprocess.run([
        "docker", "run", "--rm", "-v", f"{Path.cwd()}:/data",
        "plantuml/plantuml", f"/data/{puml}", "-tpng", "-Sresolution=300"
    ], check=True)
    # 加进 PPT
    slide = prs.slides.add_slide(prs.slide_layouts[5])
    slide.shapes.add_picture(
        f"diagrams/{puml.stem}.png",
        left=Inches(0.5), top=Inches(0.5),
        width=Inches(9), height=Inches(6))
prs.save("diagrams.pptx")

字体一致性——PPT 用宋体/Calibri,PlantUML 默认 DejaVu Sans。导出后 PPT 里文字跟图里文字字体不一样。修法:

1

plantuml -tpng -SdefaultFontName="Calibri" -SdefaultFontSize=14 diagram.puml

嵌入 Word / Office 文档

Word 2016+ 支持 SVG 粘贴:复制 SVG 文件 → 在 Word 里 Ctrl+V → 自动粘贴为可缩放矢量图。

但 Word 默认渲染 SVG 用 IE 兼容模式,PlantUML 的某些 CSS3 特性可能不显示。保险做法:Word 里用 PNG,300 DPI:

1

plantuml -tpng -Sresolution=300 diagram.puml

SVG 优化(减小体积)

PlantUML 默认输出的 SVG 有大量元数据、注释、空元素。生产环境用 SVGO 压缩:

1
2

npm install -g svgo
svgo -i input.svg -o output.min.svg

压缩后体积减少 40-60%,但所有注释文字都被删——如果图里有 note left of Alice: remember 这种,压缩后渲染时不会显示。

保留注释的 svgo 配置(svgo.config.js):

1
2
3
4
5
6
7

module.exports = {
  plugins: [
    { name: 'removeComments', active: false },  // 保留注释
    { name: 'removeMetadata', active: true },
    { name: 'removeXMLNS', active: false },     // 保留命名空间
  ]
};

暗色模式适配

PlantUML 默认白色背景 + 黑色文字。博客有暗色模式时,SVG 不会自动适配。

修法:渲染两次,JS 根据 theme 切换:

1
2

plantuml -tsvg -SbackgroundColor=transparent -Scolor=white diagram.puml    # dark
plantuml -tsvg -SbackgroundColor=transparent -Scolor=black diagram.puml    # light

1
2
3
4

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="diagram-dark.svg">
  <img src="diagram-light.svg" alt="diagram">
</picture>

prefers-color-scheme: dark 自动切换。比 CSS filter:invert 质量好得多(后者把蓝色翻转成橙色,很难看)。

性能:大批量导出

100+ 个 .puml,逐个起 Docker 容器很慢。并行:

1
2
3
4

# GNU parallel
ls docs/diagrams/*.puml | parallel -j 8 \
  "docker run --rm -v $(pwd):/data plantuml/plantuml \
   -tsvg /data/{} -o /data/out/"

xargs -P:

1
2

ls docs/diagrams/*.puml | xargs -P 8 -I {} \
  sh -c 'docker run --rm -v $(pwd):/data plantuml/plantuml -tsvg /data/{} -o /data/out/'

或者 用 plantuml-server 一波全发过去:

1
2

PUML=$(cat diagram.puml | base64 -w0 | sed 's/+/-/g;s/\//_/g/')
curl "http://localhost:8080/svg/~1${PUML}" -o diagram.svg

~1 是 plantuml.com 当前默认的 HUFFMAN 编码前缀(2025 之后改的)。

失败案例

• SVG 在 Outlook 邮件里不显示:Outlook Word 渲染引擎不识别 SVG。只能用 PNG,300 DPI。
• LaTeX \includegraphics 报 “File not found”:PlantUML PDF 输出需要字体嵌入,LaTeX 端要 pdflatex 才能吃 PDF。xelatex 也可以。lualatex 经常报字体错。
• Notion SVG 模糊:Notion 会把 SVG 缩放到固定尺寸,导出时加 width=100% 让 SVG 自身响应式,别用固定 width。
• PPT 里图变形:python-pptx 默认按图片原始像素比缩放,可能跟 PPT 16:9 不匹配。手动设 width=Inches(9) height=Inches(6)。
• CI 渲染中文乱码:PlantUML 默认字体 DejaVu Sans 不含 CJK。服务器装 fonts-noto-cjk,plantuml 用 -SdefaultFontName=Noto Sans CJK SC。