Pele：重新实现 Mermaid 的高性能图表渲染引擎

想用几行文本画出流程图、Git 分支、时序图或思维导图，Mermaid 已经是技术文档里近乎标准的选择。然而，熟悉的语法不代表只有一种绘制方式：解析文本、计算布局、生成图形，本来就可以由不同的引擎完成。

2026 年 10 月，Obsidian 团队推出了 Pele。打开它的 Examples，从 Flowchart、Mindmap、Git Graph 到 Sankey、Architecture，都有视觉风格统一的图表。更令人惊讶的是，它宣称可以明显减小体积、缩短渲染时间，还能根据可用宽度重新布局。¹

不过这里最重要的区别不是“Pele 新增了几十种图表”——这些图表类型许多早就存在于 Mermaid 中；Pele 重做的是支持它们的渲染引擎。 这篇文章想回答三个问题：它究竟改变了什么？漂亮与快速从何而来？我们应该把它接入已有文档网站吗？

一、Mermaid 不等于 Mermaid.js 渲染器

Mermaid 最吸引人的设计，是把图表描述成可以纳入版本控制的文本：

flowchart LR
    A["Mermaid 文本"] --> B["语法解析"]
    B --> C["图结构与布局"]
    C --> D["SVG"]
    D --> E["浏览器显示"]

在这一流程中，Mermaid 是一套语法与图表约定，Mermaid.js 是最具代表性的官方实现。许多 Markdown 编辑器、文档框架和代码托管网站支持 Mermaid，不代表它们一定采用相同版本、相同主题或相同的 SVG 生成方式。

Pele 选择兼容 Mermaid 的常见语法，却重新实现从文本到 SVG 的关键过程。对文章作者而言，最理想的结果是不必重写图表源码，只更换负责绘制的实现；但这只能算迁移目标，不能假设所有边缘语法、样式指令和交互特性都能无损保留。³

1.1它到底可以绘制什么？

官方 Examples 展示了 33 种图表类型。按表达目的，可以大致分成几组：

这里的“支持”以相应版本的示例和兼容性声明为依据；支持某个图种不代表支持 Mermaid.js 中该图种的全部语法和行为。尤其当你在原图中加入自定义样式、点击事件、HTML 标签或实验语法时，更应该核对输出。³

1.2几种特别适合技术文档的图

Flowchart：描述一个系统为何这样执行。 比如一个游戏世界的更新调度：

flowchart TD
    A["固定时间步 Tick"] --> B["收集待更新任务"]
    B --> C["更新实体与物理"]
    C --> D["处理方块与信号变化"]
    D --> E["同步状态给客户端"]
    E --> F["等待下一次 Tick"]

Sequence：表达参与者之间的时间关系。 它能把“客户端请求、服务器验证、结果同步”展开为一段可追踪的交互：

sequenceDiagram
    participant C as Client
    participant S as Server
    participant W as World
    C->>S: Request action
    S->>S: Validate
    S->>W: Apply change
    W-->>S: Updated state
    S-->>C: Replicate result

Git Graph：说明分支与合并，而不是罗列 Git 命令。

gitGraph
    commit
    branch feature
    checkout feature
    commit
    commit
    checkout main
    commit
    merge feature

Mindmap 适合知识框架，Sankey 适合“某种量如何从多个来源流入不同去处”。它们不仅更好看，还能让作者不用反复画形状、拉箭头和对齐文字。但必须警惕另一面：适合表达逻辑的图，不一定适合表达真实测量数据。统计图的比例、单位和尺度仍需严谨定义。

二、Pele、Mermaid.js 与 Beautiful Mermaid

现在出现了三个值得一起看的选择：

• Mermaid.js：官方渲染实现，图种和高级语法覆盖更全面，积累了成熟生态。
• Pele：以高性能、轻量、主题与响应式为主要卖点，目标兼容大量 Mermaid 语法。
• Beautiful Mermaid：刻意保持小范围的图表支持，偏重简洁视觉，同时可以输出终端文本图。⁴

Pele 官方在相应版本的比较中称，其压缩体积约为 230 KB（Gzip），而 Mermaid.js 为 1.6 MB。两者相差约七倍；官方还称部分基准的渲染耗时相差数十至数百倍。⁵

Pele 的官方基准提供了可参考的复测入口，例如仓库中的 npm run bench:mermaid。但这不等于本文已经跑完一轮对照实验。若要把“快多少”写成独立结论，应该固定版本、机器、浏览器与测试样本，附上可复现脚本与原始数据。⁵

2.1如何做一组可信的 Benchmark？

建议至少准备四组图：十几个节点的普通流程图、数百节点的复杂流程图、长时序图以及含大量中文标签的图表。记录以下指标：

同一组输入应由同一页面逐个切换引擎渲染，避免字体、缩放比例、缓存状态和浏览器版本成为混杂变量。渲染很快但结果不对，不能算“性能胜利”。

三、好看的背后：不只是换一套 CSS

图表的最终观感，至少由三层决定：

flowchart LR
    A["输入语法"] --> B["解析后的语义与关系"]
    B --> C["节点位置、分组与连线布局"]
    C --> D["形状、间距、字体、主题"]
    D --> E["最终 SVG"]

语义决定有哪些节点和关系；布局决定它们如何排列；样式决定形状、色彩、描边和文字的呈现。换主题只能改变第三层中的一部分。如果节点太挤、箭头绕行混乱、文字溢出，即使配色再漂亮也很难读。

Pele 值得关注的设计，就在于它并非仅仅给 Mermaid.js 的 SVG 套上视觉皮肤，而是可以自己决定布局和输出。具体到某类图用了什么算法、是否增量更新、在哪一步优化了内存，必须以对应版本源码为依据，不能从漂亮的结果推断它一定使用某个著名算法。⁶

3.1CSS 变量：让图表属于页面本身

传统的嵌入式图表常见问题，是它像贴在文章里的一张截图：正文的主题、文字颜色和背景变了，图表却保持另一套视觉。

Pele 使用如 --pele-bg、--pele-fg、--pele-accent 的 CSS 变量定义主题，让 SVG 可以继承页面设计语言。理想情况下，深浅色切换不必重新解析整幅图，页面主题与图表主题可以同步变化。⁷

然而，还需要测试具体生成 SVG 是否引用动态变量，以及自定义字体、特殊节点与背景填充有没有固定颜色；“支持 CSS 变量”不等于每一处细节都自动正确。

3.2响应式：重新布局，而不是把大图缩小

这是我认为比纯速度更重要的功能。传统宽图在手机上容易成为一串几乎看不清的字符。Pele 的响应式方案允许根据容器最大宽度调整部分图表布局；官方展示了流程图方向变化、看板折叠和思维导图显示方式调整等行为。⁸

这和简单的 svg { max-width: 100% } 不一样：后者通常只改变整幅图的缩放比例，前者可以改变信息的空间组织。但复杂图仍应提供放大和横向滚动作为后备，而不是承诺所有图表都能自动变得适合手机。

3.3生成 SVG，与把 SVG 安全地插入网页，是两件事

SVG 是文本形式的图形描述，可以便于缩放、拷贝和样式化；但当输入来源不可信时，必须考虑 URL、内嵌内容和潜在的脚本注入等风险。Pele 对自由 HTML 和 JavaScript 回调等 Mermaid 高风险功能作出了限制，这同时影响了安全边界和兼容性。³

把引擎输出直接交给 dangerouslySetInnerHTML 时，应先弄清楚可信输入范围、渲染器的净化策略和运行环境。对允许读者提交图表的在线服务，不能只因为“渲染器输出 SVG”就跳过安全评估。

四、它是怎样工作的？

不妨把 Mermaid 渲染理解为一台小型编译器。它的输入是一门针对图表设计的领域特定语言（DSL），输出不是机器码，而是一幅矢量图：

flowchart TD
    S["源代码 / DSL"] --> P["词法与语法解析"]
    P --> M["图表模型"]
    M --> L["布局计算"]
    L --> G["SVG 生成"]
    G --> V["渲染与交互"]
    T["字体、间距和主题"] --> L
    T --> G

这个图是为了理解系统而做的概念性分层，不是对 Pele 源码模块名称的逐项复制。不同图种可能采用不同解析器与布局策略；字体测量也可能和布局发生多次往返。

4.1为什么重新实现可能更轻、更快？

首先，通用大型图表库要兼顾很多历史语法、布局分支、交互行为以及兼容路径。一个新的实现可以重新选择依赖与数据结构，专注高频路径，减少中间层。

其次，SVG 可以由字符串或轻量对象生成，而不一定需要一个庞大的浏览器依赖链。在适合的情况下，解析与布局结果可以直接映射成 SVG 元素，减轻运行时开销。

最后，主动限制旧 API 和高风险特性有助于收敛问题规模。但这也是取舍：减少特性覆盖，本来就可能换来更小的程序与更明确的执行路径。

这三点是理解此类渲染器的工程解释，并不是已经通过剖析 Pele 1.8.0 的 profiler 证明的具体加速来源。要给出因果结论，还需要 profiling 火焰图、热点函数和复杂输入的回归测试。⁶

4.2真正难的是自动布局

读入 A --> B 并不困难。困难在于一个复杂图包含子图、跨层依赖、交叉边、长文字与尺寸不同的节点时，怎样安排位置才能既紧凑又能读懂。

典型自动布局问题可以拆成：决定节点相对层级、减少连线交叉、调整节点与边的几何路径、为标签预留空间、生成可视元素。布局目标往往彼此冲突：减少交叉可能增大图宽，让图更紧凑又可能降低可读性。

所以比较 Pele 与 Mermaid.js 时，最好除了跑秒表，再把同样的图放在一起，检查交叉边、标签溢出、子图边界、阅读顺序和移动端表现。

五、实际接入：在 Fumadocs 中使用 Pele

对于新项目，可以从 Pele 的安装与 API 入手；对于已有数百张图的文档网站，我更建议先维持 Mermaid 源码与渲染器解耦。

本站目前基于 Next.js、Fumadocs 和 MDX。MDX 写作层通过 remarkMdxMermaid 识别 Mermaid 代码块，随后交给自定义的 Mermaid React 组件。这个组件当前实际动态导入的是 Beautiful Mermaid，而不是 Mermaid.js 官方运行库。 它还负责主题参数、SVG 尺寸检查、加载状态以及独立的图表查看器。⁹

因此本站的升级方案，不是从 Mermaid.js 直接替换为 Pele，而是：

flowchart TD
    A["MDX Mermaid code block"] --> B["Fumadocs MDX plugin"]
    B --> C["Diagram Renderer Adapter"]
    C --> D{"Pele 渲染成功且兼容？"}
    D -->|Yes| E["Pele SVG"]
    D -->|No| F["Beautiful Mermaid 或源码回退"]
    E --> G["现有 MermaidViewer"]
    F --> G

这里需要特别指出：Beautiful Mermaid 并不能作为所有 Pele 图种的通用回退，因为它只支持 Mermaid 的一个子集。对于两个引擎都不支持的图，应保留源码显示、报错信息，或专门增加官方 Mermaid.js 的懒加载后备路径。

5.1最小调用方式

Pele 的公开接口提供将 Mermaid 文本转换为 SVG 的同步渲染路径，还提供针对 DOM 容器的挂载方式；实际参数、返回类型和容器生命周期应以安装版本的类型声明为准。以下是展示调用边界的概念示例，集成前需要根据锁定版本校验签名，而不是直接粘贴到本站生产组件中：

// 概念示例：把引擎封装在可替换的适配层
type DiagramEngine = {
  render: (source: string) => string;
};

function renderDiagram(engine: DiagramEngine, source: string) {
  try {
    return { ok: true as const, svg: engine.render(source) };
  } catch (error) {
    return { ok: false as const, error };
  }
}

不建议为了一篇文章把 Pele 引入全部客户端页面，也不建议每渲染一次就重新创建浏览器测量环境。更好的做法是先做一个独立试验页面，检查 TypeScript API、生成的 SVG、主题切换与实际耗时，再决定采用客户端渲染还是静态预渲染。

5.2验收清单

• 语法：复杂子图、时序、Git Graph、思维导图、中文换行、自定义标签。
• 视觉：节点是否丢失、箭头是否指错、连线是否遮字、字体是否一致。
• 响应式：窄屏、横竖布局转换、缩放与横向滚动。
• 主题：暗色模式、透明背景、SSR 与 Hydration 的一致性。
• 可靠性：输入错误、空图、超大图、切换页面取消异步任务。
• 安全：用户可控内容、链接和 SVG 注入边界。
• 性能：浏览器首次显示时间与构建产物大小，而非只看库内计时。

六、何时迁移？何时等待？

Pele 发布后更新很快。10 月中旬的版本已经出现过公开 API 变动，而截至本文写作时 npm 版本又推进到了 1.8.0。两周可以作为观察窗口，但时间过去本身不能证明稳定。¹⁰

我会采取渐进策略：

1. 现在试验：锁定 Pele 版本，抽样整理本站现有 Mermaid 图，构建兼容性用例与可视化快照；先不修改公开文章渲染结果。
2. 未来两周观察：检查发布日志、API 变动、错误修复，以及包含中文和复杂布局的测试。
3. 通过验收后灰度：在一个独立路由或少数文章中启用 Pele，保留现有 Beautiful Mermaid 与源码回退。
4. 积累真实数据再替换默认值：如果它在手机阅读、性能与图表正确性方面持续胜出，再让 Pele 成为默认渲染器。

需要注意，静态 SVG 预渲染可以改善首屏，但会失去客户端按容器宽度重新布局的即时能力；动态挂载则更灵活，但增加客户端逻辑。对于绝大多数文章，静态、可放大、可滚动的图也许已足够；只有对响应式真正有价值的图才需要更复杂的客户端行为。

7结语：图表语言与绘制引擎的分离

Pele 最让我感兴趣的，不是宣传页上漂亮的图，也不只是几百倍的性能数字，而是它揭示了一种可以复用的软件设计：内容的表达格式，未必需要绑定原始实现。

Mermaid 让开发者把结构和关系保存在文本中；Pele 尝试用一套更轻、更统一、更适合现代页面的渲染过程来解释这些文本。Beautiful Mermaid 则证明，缩小图种范围、同时提供 SVG 和终端字符图，也是一条合理路线。三者的目标不完全相同，不必只选出一个普适赢家。

对于技术写作者来说，图表首先要准确表达关系，其次才是漂亮、速度和丰富动画。对已有博客而言，保留原始 Mermaid 源码、抽象渲染层，并以实际图表而不是宣传数字决定是否切换，可能比第一时间追上最新版本更有价值。

Pele 很值得尝试。但优秀的新引擎，与可放心替换的成熟基础设施，是两个不同的判断。