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

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.21Windows 版直接把一个精简版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但它带着 ChromiumMermaid 官方的 CLI 是mermaid-js/mermaid-cli安装后命令叫mmdcnpminstall-gmermaid-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% 像 ChromiumPNG/PDF 输出原生渲染只到 SVG进一步要 PNG 还得借助resvg、rsvg-convert之类的工具链。所以它的定位很清晰CI 里批量渲染、对启动延迟敏感、且只用 Mermaid 中常见图类型的场景。生产文档站如果用了xychart-beta这种新语法别贸然替换。类似流派还有rendermaid/core纯 TypeScript 服务端渲染但目前只支持 flowchartsequence diagram 还没做完比较适合非常窄的场景。4. 折中派自建 Kroki如果你已经习惯了 blogger 现在 POST kroki.io 的这套接口最小改动方案是把 kroki 自己跑起来dockerrun-d--namekroki-p8000:8000 yuzutech/krokidockerrun-d--namemermaid--networkkroki yuzutech/kroki-mermaidyuzutech/kroki主容器自带 PlantUML 和 GraphvizMermaid、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 smetanaMermaid 走mmdc吃下 Chromium 的体积换完整度。CI 批量构建文档站Mermaid 用mmdrRustplantuml 直接 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 mindmapjava -jar ~/bin/plantuml.jar -tsvg illustration_1.puml rsvg-convert -w 1800 illustration_1.svg -o illustration_1.pngPlantUML 自家的 mindmap 布局引擎对树状数据稳定可靠一次出图。封面同样走 SVG → rsvg-convert 路径规避了 PlantUML mindmap-tpng -Sdpi不生效的另一个坑。整个写作过程没有再依赖任何在线服务本文目录下保留了illustration_1.puml、cover.puml两份源码——这就是离线渲染加多工具备份的实战收益单一工具总有它不擅长的图但两个本地工具搭配几乎能覆盖所有场景。Sources:mermaid-js/mermaid-cli - DeepWiki Overviewmermaid-js/mermaid-cli Installation Methodsmermaid-rs-renderer (mmdr) - GitHubmmdr crates.io pagePlantUML local installation FAQPlantUML Quick Start GuidePlantUML Graphviz / Smetana docsKroki self-hosted setupyuzutech/kroki Docker Hubrendermaid/core server-side renderer