merman：把 Mermaid 变成可嵌入 CLI、服务端和原生应用的无头 Rust 渲染器

很多团队都在写 Mermaid。

在 README 里画流程图；
在设计文档里画架构图；
在 CI 里生成静态文档；
在内部平台里把图表嵌进预览页；
有时还希望把图导出成 PNG、PDF，或者直接在终端里看文本版。

问题是，一旦你想把 Mermaid 从浏览器和 Node 工具链里拿出来，事情就会立刻变复杂。

你需要的不再只是“能不能渲染”，而是：

能不能在无头环境里稳定跑；
能不能嵌进 Rust、C、Python、Flutter 这样的宿主；
能不能在 CI 或服务端批量生成；
能不能尽量贴近上游 Mermaid，而不是渲染出一个“差不多像”的兼容版本。

今天想记下的 Latias94/merman，就在做这件事。它把自己定义成 “Mermaid.js, but headless, in Rust.”，目标不是再包一层浏览器，而是直接做一套可嵌入、可批处理、可跨语言接入的 Mermaid 渲染栈。

按 GitHub 仓库页面和 README 在 2026-06-22 的公开信息，这个仓库当前大约有 382 stars、14 forks，主要语言是 Rust，仓库创建于 2026-02-10，最近公开更新时间是 2026-06-22。仓库采用 MIT / Apache-2.0 双许可证；GitHub Releases 页面显示当前最新正式版本是 0.7.0，发布日期为 2026-06-09。

项目概览

属性	详情
仓库	Latias94/merman
定位	面向 CLI、服务端和原生宿主的 headless Mermaid Rust 渲染器
Stars	382
Forks	14
主要语言	Rust
创建时间	2026-02-10
最近更新时间	2026-06-22
License	MIT / Apache-2.0
最新正式版本	0.7.0
版本日期	2026-06-09

它解决的不是“怎么画图”，而是“怎么脱离浏览器后还画得稳”

merman 最值得注意的一点，是它一开始就不把自己当成前端小组件。

README 里给出的入口非常明确，它既可以当：

merman-cli 命令行工具；
Rust crate；
提供稳定 C ABI 的 merman-ffi；
浏览器/TypeScript 包；
Python、Flutter、Android、Apple 侧的绑定基础。

这说明它的目标不是“在本地预览 Mermaid”，而是把 Mermaid 变成一个可以被不同运行时消费的底层能力。

这和很多只服务单一场景的 Mermaid 工具有明显区别。对后者来说，浏览器能出图就差不多了；但对 merman 来说，更难的问题是：

在没有 DOM 的地方怎么渲染；
在不同宿主里怎样暴露稳定接口；
输出 SVG 之外，怎样继续导出 PNG、JPG、PDF 或终端文本；
如何尽量维持和上游 Mermaid 的行为一致。

输出面很完整，不只是一张 SVG

merman README 列出的输出能力相当全面。

它不只是“把 Mermaid 字符串转成 SVG”，还可以输出：

semantic JSON；
layout JSON；
Mermaid 风格 SVG；
ASCII / Unicode 终端图；
通过 SVG 后处理和光栅化导出的 PNG、JPG、PDF。

这里面我觉得最实用的是两层。

第一层是 semantic / layout JSON。这意味着它不只是一个黑盒渲染器，也能把解析和布局结果作为中间产物交出来，适合给别的工具继续消费。

第二层是 ASCII / Unicode 输出。这会让它从“文档渲染工具”变成“终端工作流工具”。如果你想在日志、CLI、TUI 或纯文本文档里展示流程图，这条路径就非常顺手。

很多项目会做其中一层，但 merman 看起来是试图把这些输出收拢成一个统一栈。

真正拉开差距的，是它在认真追 Mermaid 上游行为

如果只是做“能渲染一部分 Mermaid”的实验项目，其实不稀缺。

merman 更有意思的地方，是它明确把 Mermaid 当成规范本身，而不是只拿 Mermaid 当灵感来源。README 里写得很直白：它希望匹配那些上游“看起来有点奇怪”的实际行为，而不是擅自改写成 Rust 世界里更顺手的解释。

为此它做了几件很重但很有价值的事：

用 fixtures/**/*.golden.json 锁语义快照；
用 fixtures/**/*.layout.golden.json 锁布局结果；
用上游 Mermaid 生成的 SVG 作为端到端基线；
做 DOM parity 检查，而不是只比肉眼看起来像不像；
在 README 中直接写出当前语料规模是 23 类图表、3500+ upstream SVG baselines。

这套思路很工程化。

因为图形渲染类项目最容易陷入“我这里看着差不多”的陷阱。真正一旦进 CI、批量导出、跨平台嵌入，就会发现边角差异会不停累积。merman 的做法是在一开始就把这些差异变成可回归验证的资产。

对服务端和原生嵌入来说，FFI 和宿主测量接口很关键

如果你只是本地跑命令行，Mermaid 渲染器并不罕见。

但 merman 还有一条更偏平台能力的线：它通过 merman-ffi 暴露稳定 C ABI，并且为 Python、Flutter、Android、Apple/Swift 等宿主准备了绑定路径。

这个设计很重要，因为 Mermaid 真正难嵌的地方，经常不是语法解析，而是：

文本测量；
字体回退；
原生宿主自己的布局系统；
不同平台对 SVG 或 <foreignObject> 的支持差异。

README 对这一层写得很细。它允许宿主提供自己的 text measurement callback；如果宿主无法处理，再退回 vendored 的兼容测量。这种分层非常务实。

原因很简单：一个 headless 渲染器可以负责“尽量稳定地产生结果”，但真正的几何精度往往还是和宿主字体环境有关。merman 没有假装这个问题不存在，而是把接口提前设计出来。

它不只想做库，还想做能进工作流的文档工具

从 README 结构看，merman 已经明显不只是一个底层 crate。

它在仓库里拆出了多层工作面：

merman-cli 负责 detect / parse / layout / render 工作流；
merman-rustdoc 处理 rustdoc 里的 Mermaid fence；
@mermanjs/web 处理浏览器包；
merman-typst-plugin 还在试探 Typst 类插件宿主。

这意味着它开始覆盖的不是单一 API，而是一整条“从源码、到文档、到导出、到嵌入”的链路。

对于维护技术文档或开发者平台的人来说，这很有吸引力。因为很多时候你并不想自己拼：

Mermaid 解析器；
SVG 渲染器；
PNG 导出器；
不同语言绑定；
质量门禁和回归样例。

如果一个项目愿意把这些表面都整理出来，它就更像可以长期依赖的基础件，而不是一次性的 demo。

也正因为追求兼容，它会诚实地写出边界

merman README 里还有一点我比较喜欢：它没有把自己写成“已经完美替代 Mermaid”。

公开文档直接列出了几个现实限制：

SVG 的 <foreignObject> 在某些光栅化器里兼容性一般；
文本测量天然受宿主字体环境影响；
PNG / JPG 导出有默认像素预算，防止无头环境里超大图吃爆内存；
某些复杂布局仍然会以 geometry-normalized 的方式和上游对齐。

这类说明其实很加分。

因为这表明作者知道图渲染栈里哪些问题可以工程化解决，哪些问题只能通过接口、预算和回退策略来控制。一个渲染工具如果敢把这些边界写清楚，通常比“全部都支持”更可信。

为什么我觉得它值得关注

我会记下 merman，不是因为 Mermaid 本身有多新，而是因为它抓住了一个越来越常见的需求：

开发者想在更多非浏览器环境里使用 Mermaid，而且希望结果能进入正式工作流。

这个需求背后其实是几种场景同时在增长：

文档站点和静态生成；
服务端批量导图；
原生桌面和移动端嵌入；
CLI / TUI 的文本图形输出；
对上游行为足够敏感的自动化测试和回归验证。

如果你只是偶尔在 Markdown 里插图，官方 Mermaid CLI 可能就够了。但如果你开始在 Rust 服务、原生应用、跨语言插件或 CI 文档流水线里长期用 Mermaid，那么 merman 这种“headless + 可嵌入 + 强对齐”的路线，就会比浏览器包一层更有吸引力。

小结

Latias94/merman 最值得看的地方，不只是它用 Rust 重写了 Mermaid 渲染，而是它把 Mermaid 当成一项可以进入 CLI、服务端、原生宿主和文档流水线的底层能力来做。

它提供的不只是 SVG，还有 semantic/layout JSON、ASCII/Unicode 输出、PNG/JPG/PDF 导出和 FFI 接口；更重要的是，它愿意为“和上游保持对齐”付出大量质量门禁成本。

如果你正在找的不是一个前端图表玩具，而是一套能稳定进入工程工作流的 headless Mermaid 栈，merman 很值得继续跟。