当前位置：首页 > news >正文

告别 kroki.io：.mmd 与 PlantUML 本地离线渲染方案盘点

news 2026/5/8 20:02:17

https://github.com/BlackwaterTechnology/blogger-agent.git 这个工具自带的generate-diagram子命令，实现是core/diagrams.py里那五十行代码——把文本 POST 到https://kroki.io/<dsl>/png，把返回的 PNG 落盘。够用，但有三个绕不开的问题：一是必须联网，飞机上、内网机或者 kroki.io 偶尔抽风的时候直接趴窝；二是源码里写着ctx.check_hostname = False，已经为了 SSL 兼容把校验关了，从安全角度并不干净；三是公司内的图表内容有时候是不该往公网泼的。

写这篇文章过程中我顺手跑了一下blogger generate-diagram --type mermaid想给文章配张图，结果 kroki.io 连续返回504 Gateway Timeout，连最简单的A --> B都渲染不出来。换--type plantuml同样 504。这条注脚不是凑字数——它就是本文存在的理由。

PlantUML 老牌玩家都知道一个plantuml.jar就能本地全套渲染，那 Mermaid 呢？这就是这篇文章想理清楚的事。

1. PlantUML 一直是离线友好的

plantuml.jar本质上是个 Java 程序，下载下来就可以跑：

java-jarplantuml.jar diagram.puml# 生成 diagram.pngjava-jarplantuml.jar-tsvgdiagram.puml# 输出 SVG

历史上 PlantUML 的痛点是依赖 Graphviz 的dot二进制来排版（除了 sequence、activity beta 等少数图类型）。这件事在两个版本之后已经变得轻量很多：

1.2020.21+：Windows 版直接把一个精简版dot.exe打包进 JAR，运行时自动解压到临时目录，安装阶段连 Graphviz 都不用碰；
1.2021.5+：实验性的纯 Java 排版引擎Smetana上线，用法是在.puml文件里加一行!pragma layout smetana，从此可以彻底告别 Graphviz。

更隐藏的玩法是plantuml.jar内置了一个迷你 HTTP 服务器：

java-jarplantuml.jar-picoweb:8080

跑起来就有一个本机版的 plantuml.com，渲染敏感内容时尤其有用。这个能力很多人用了多年都不知道，但它解释了为什么 PlantUML 在企业内网生态里活得这么久。

2. Mermaid 的官方方案：mmdc，但它带着 Chromium

Mermaid 官方的 CLI 是@mermaid-js/mermaid-cli，安装后命令叫mmdc：

npminstall-g@mermaid-js/mermaid-cli mmdc-idiagram.mmd-odiagram.png

它在功能上几乎是无损的——Mermaid 本质是浏览器里的 JS 库，所以官方策略很务实：直接拉一个 headless Chromium 跑真实的渲染。Puppeteer 在 mermaid-cli 里被声明为 peer dependency，第一次安装会下一份匹配版本的 Chromium 落到本地。

代价同样务实：

安装包体积：单是 Chromium 就 200MB+；
启动慢：每次mmdc调用都重启一次浏览器，单图渲染普遍要 1–3 秒；
Node 版本要求：^18.19或>=20，老环境得先升级；
跑在 CI 容器或 Docker 里要小心 sandbox、缺字体、缺libnss3这类陷阱。

社区里反复吐槽 mmdc 慢，根因不是代码而是冷启浏览器的固定开销。如果你只渲染一两张图，没所谓；如果是文档批量构建，每张图都付一次浏览器启动税，时间会非常刺眼。

3. Rust 原生方案：mermaid-rs-renderer 把浏览器整个砍掉

2026 年初出来的mermaid-rs-renderer（命令名mmdr）选了另一条路：直接用 Rust 实现 Mermaid 语法的解析器，再把 AST 渲染成 SVG，没有 Node、没有浏览器、没有 Puppeteer。

brewinstallmermaid-rs-renderer# 或 cargo install / scoop / AURmmdr-idiagram.mmd-odiagram.svg

性能上的差距是数量级的：作者 2026 年 2 月放出的基准里，对小型/常见图表，mmdr比mmdc快 1600–2069 倍。这个数字看起来夸张，但解释合理——mmdc 慢的部分主要是浏览器冷启动，把浏览器整个拿掉之后量级自然就掉下来了。

需要诚实地讲它的代价：

覆盖度还不全：Mermaid 这几年扩出了很多图类型（mindmap、timeline、git graph、xychart 等），第三方实现想把所有 DSL 跟齐是个长期工作；
像素级一致性不保证：原生渲染器在排版细节、字体回退、emoji 上不可能 100% 像 Chromium；
PNG/PDF 输出：原生渲染只到 SVG，进一步要 PNG 还得借助resvg、rsvg-convert之类的工具链。

所以它的定位很清晰：CI 里批量渲染、对启动延迟敏感、且只用 Mermaid 中常见图类型的场景。生产文档站如果用了xychart-beta这种新语法，别贸然替换。

类似流派还有@rendermaid/core，纯 TypeScript 服务端渲染，但目前只支持 flowchart，sequence diagram 还没做完，比较适合非常窄的场景。

4. 折中派：自建 Kroki

如果你已经习惯了 blogger 现在 POST kroki.io 的这套接口，最小改动方案是把 kroki 自己跑起来：

dockerrun-d--namekroki-p8000:8000 yuzutech/krokidockerrun-d--namemermaid--networkkroki yuzutech/kroki-mermaid

yuzutech/kroki主容器自带 PlantUML 和 Graphviz，Mermaid、BPMN、Excalidraw 这些走 sidecar 容器。然后把core/diagrams.py:18那行https://kroki.io/...改成http://localhost:8000/...就完事，连协议都不用动。

这个方案最大的好处是复用了 blogger 现有的 HTTP 协议层，零代码重构换来完整的离线能力，并且支持的 DSL 列表（PlantUML / Mermaid / D2 / Excalidraw / Graphviz / DBML 等十几种）一次性全拿到。

代价是你得运维一个 Docker 服务、占内存、首次拉镜像走流量。对个人工作站来说稍重，对团队/公司部署很合适。

5. 选型建议

把上面四类方案放一起对比，结论是按场景选，不要找银弹：

个人写博客、偶尔画图：保留 kroki.io，零运维。这是 blogger 当前的默认，没必要换。
离线/敏感环境，必须本地：PlantUML 走plantuml.jar+!pragma layout smetana；Mermaid 走mmdc，吃下 Chromium 的体积换完整度。
CI 批量构建文档站：Mermaid 用mmdr（Rust），plantuml 直接 JAR，启动开销最低。
团队级、要支持多种 DSL：自建 Kroki，一个 Docker 网络解决全部问题。

回头看 blogger 这个项目本身，最有性价比的演进路径是给core/diagrams.py加一个--backend {kroki,mmdc,mmdr,plantuml-jar,kroki-local}参数：默认还是公网 kroki，但允许用户切到本地后端。代码改动小，但语义上从"必须联网"变成"可选离线"，对一个面向中文创作者、经常在内网/办公环境里跑的工具，这个能力是早晚要补的。

6. 一点判断

工具选择的原则常常不是哪个最强，而是哪个最匹配你的失败模式。kroki.io 的失败模式是公网抖动；mmdc 的失败模式是 Chromium 装不上；mmdr 的失败模式是新 Mermaid 语法不支持；plantuml.jar 的失败模式是没装 Java；自建 Kroki 的失败模式是 Docker 没跑起来。看清自己的失败面，比追新更重要。

后记：本文配图本来想用blogger generate-diagram走 kroki.io 生成，结果遇上 504 反复打脸。改用本地工具时又遇到第二个真实场景——最初我用mmdr渲染那张方案对比图，多分支树的边路由出现了肉眼可见的拐角错位和断线（mmdr 0.2.2 的已知短板，作者在 README 里也写了"layout edge routing is approximate"，是用纯 Rust 重实现 layered layout 的代价）。换条路：把同一份内容改写成 PlantUML mindmap，java -jar ~/bin/plantuml.jar -tsvg illustration_1.puml && rsvg-convert -w 1800 illustration_1.svg -o illustration_1.png，PlantUML 自家的 mindmap 布局引擎对树状数据稳定可靠，一次出图。封面同样走 SVG → rsvg-convert 路径，规避了 PlantUML mindmap-tpng -Sdpi不生效的另一个坑。整个写作过程没有再依赖任何在线服务，本文目录下保留了illustration_1.puml、cover.puml两份源码——这就是离线渲染加多工具备份的实战收益：单一工具总有它不擅长的图，但两个本地工具搭配几乎能覆盖所有场景。

Sources: