发布 @xingwangzhe/satteri-mermaid：剔除mermaid.js，用Rust原生渲染流程图，构建时产出纯静态SVG

• @xingwangzhe/satteri-mermaid

本文核心代码是Vibe Rust写的

在前文 Astro: 优化katex,mermaid和灯箱使用中，我已经通过构建时检测实现了 mermaid 的按需加载——只有包含流程图的页面才会 import mermaid.js。

但问题恰恰出在这里。

mermaid.js 有多重？

来，我们先看看客户端 mermaid.js 的体量：

用 1.2MB 的 JavaScript 渲染一张“Hello World”流程图——这是用火箭炮打蚊子。

说实话，对于一个纯静态博客而言，让客户端 JavaScript 来渲染流程图，本身就有点荒谬。这些图表在构建时就完全可以确定了——它们就是写死在 Markdown 里的 Mermaid 代码，变都不变的。我构建一次，生成静态 SVG，后面就永远不需要再碰 JS 了。

但当时我并没有合适的工具。直到我发现了 mermaid-rs-renderer——一个用 Rust 写的 Mermaid 渲染器，并决定把它包装成 Astro 插件。

这一路，跌跌撞撞走了三代。

出土文物清单：satteri-mermaid 的演化史

在最终方案落地之前，我的 @xingwangzhe/satteri-mermaid 插件经历了三个大版本的更迭。说实话，每一代都是在上一代的坑里爬出来的。

从 JavaScript 到 WASM 再到 napi-rs 原生绑定，这一路在优化。

核心架构：MDAST + HAST 双插件

在 v0.2 版本之前，我只有一个简单的 MDAST 插件：检测到 ```mermaid 代码块，直接把它原样输出到 HTML。然后让客户端 mermaid.js 来接手。

问题很快暴露了——Sätteri 处理器（本博客使用的 Markdown 处理器）在进行文本变换（smart punctuation 等）时，会破坏 Mermaid 代码。最典型的是 {" 这种花括号加引号的序列，会被 Sätteri 当成字符实体处理。结果就是渲染出来的流程图要么缺胳膊少腿，要么直接报错。

这个问题的根源在于：Mermaid 代码在 Markdown 的 AST（抽象语法树）层面还是一段“普通文本”，会被后续的各种 Rehype/Hast 插件随意蹂躏。唯一的解决方案是——在 MDAST 阶段把 Mermaid 代码隐藏起来，等所有文本处理都结束了，再在 HAST 阶段还原并渲染。

这就是双插件架构的核心思路：

这个过程的设计巧妙之处在于：

三代渲染引擎的技术细节

第一代：客户端 mermaid.js（v0.1 - v0.2）

1
// MDAST 插件：检测 mermaid 代码块，输出占位符
2
visit(tree, (node: any) => {
3
    if (node.type === "code" && node.lang === "mermaid") {
4
        node.type = "html";
5
        node.value = `<pre class="mermaid">${node.value}</pre>`;
6
    }
7
});

然后在 Layout 里条件加载：

1
{hasMermaid && (
2
    <script>
3
        import mermaid from "mermaid";
4
        mermaid.initialize({ startOnLoad: true });
5
    </script>
6
)}

这倒也不是一无是处——至少比全局加载 mermaid.js 好。但问题在于，mermaid 依然是客户端的。搜索引擎爬虫看不到你的流程图内容，RSS 阅读器里是一片空白，关掉 JS 的用户看到的是 <pre class="mermaid">graph TD\n A-->B</pre> 这样的原始代码。

第二代：@mermanjs/web WASM（v0.3 - v0.5）

第一次尝试“构建时渲染”用的是 beautiful-mermaid（一个 JS 渲染器），很快换成了 @mermanjs/web——一个用 Rust 编译成的 WASM 模块。这比纯 JS 强了不少：

但 WASM 方案有个很蛋疼的问题——初始化特别重：

1
import { initMerman, renderSvg } from "@mermanjs/web";
2
import { existsSync, readFileSync } from "node:fs";
3

4
// 在 node_modules 里找 WASM 文件...这操作真的优雅吗？
5
function findWasm(): string {
6
  let dir = process.cwd();
7
  for (let i = 0; i < 20; i++) {
8
    const p = dir + "/node_modules/@mermanjs/web/pkg/merman_wasm_bg.wasm";
9
    if (existsSync(p)) return p;
10
    const sep = dir.lastIndexOf("/");
11
    if (sep <= 0) break;
12
    dir = dir.slice(0, sep);
13
  }
14
  throw new Error("Cannot find @mermanjs/web WASM");
15
}
16

17
async function doInit(): Promise<void> {
18
  const wasmPath = findWasm();
19
  const wasmBytes = readFileSync(wasmPath);
20
  const wasmModule = await WebAssembly.compile(wasmBytes);
21
  await initMerman({ loader: ..., wasm: wasmModule });
22
}

在 node_modules 里逐级往上找 8.8MB 的 WASM 文件，然后 readFileSync 读进来，再 WebAssembly.compile 编译……这一套下来，构建启动时间直接多了几百毫秒。

而且最让人抓狂的是，merman 的边框宽度是硬编码 1px，没法自定义——在深色主题下，边框几乎看不见。

第三代：napi-rs 原生绑定（v0.7.0）——终局之战

WASM 方案还有一个更深层的问题——它是一个“中间人”。Rust 代码 → 编译成 WASM → Node.js 加载 WASM → WebAssembly 运行时执行。每一步都是开销。

最优解是什么？Rust 代码 → 编译成原生 .node 二进制 → Node.js 直接调用。中间的 WASM 层，砍掉。

这就是 v0.7.0 做的事——用 napi-rs 把 mermaid-rs-renderer 包装成一个 Node.js 原生模块：

1
use mermaid_rs_renderer::{render_with_options, RenderOptions as MrRenderOptions, Theme};
2
use napi_derive::napi;
3

4
#[napi(object)]
5
pub struct RenderOptions {
6
    pub theme: Option<String>,
7
    pub primary_color: Option<String>,
8
    pub primary_border_color: Option<String>,
9
    // ... 60+ 参数全覆盖
10
}
11

12
#[napi]
13
pub fn render(code: String, opts: Option<RenderOptions>) -> napi::Result<String> {
14
    let mr_opts = build_render_options(&opts);
15
    render_with_options(&code, mr_opts)
16
        .map_err(|e| napi::Error::from_reason(e.to_string()))
17
}

JS 端直接调用，不再需要什么 WASM 文件查找的骚操作：

1
import { createRequire } from "node:module";
2

3
function getBinding(): NativeBinding {
4
    const require = createRequire(import.meta.url);
5
    return require("../index.cjs") as NativeBinding;
6
}
7

8
export function renderMermaidSVG(code: string, opts: Record<string, unknown>): string {
9
    const { render } = getBinding();
10
    return render(code.trim(), opts);
11
}

就这。不需要 readFileSync，不需要 WebAssembly.compile，不需要在 node_modules 里大海捞针。Node.js 的 require 直接加载 .node 二进制，Rust 函数像 JS 函数一样调用。

效果对比

表格最后一行需要说明一下——napi-rs 需要预编译平台二进制，目前我们覆盖了 Linux x64、Linux arm64、macOS arm64、Windows x64。对于小众平台（如 FreeBSD），可以回退到客户端 mermaid.js 模式（ssg: false），或者……自己编译（开源的好处）。

在 Astro 中的使用

整个配置出奇地简单。在 astro.config.mjs 中：

1
import { satteri } from "@astrojs/markdown-satteri";
2
import { mermaidMdast, mermaidHast } from "@xingwangzhe/satteri-mermaid";
3

4
export default defineConfig({
5
    markdown: {
6
        processor: satteri({
7
            mdastPlugins: [mermaidMdast()],
8
            hastPlugins: [
9
                mermaidHast({
10
                    theme: "dark",
11
                    responsive: true,
12
                    themeOverrides: {
13
                        clusterBorder: "#cccccc",
14
                        primaryBorderColor: "#ff6600",
15
                    },
16
                }),
17
            ],
18
        }),
19
    },
20
});

然后你该写什么写什么：

1
```mermaid
2
flowchart TD
3
    A["开始"] --> B["处理"]
4
    B --> C["结束"]
5
```

构建后自动变成：

1
<div class="mermaid" data-mermaid-ssg="true" style="max-width:100%;overflow:hidden">
2
    <svg viewBox="..." style="width:100%;display:block">...</svg>
3
</div>

零 JS，零依赖，纯静态。搜索引擎能直接索引 SVG 内的文字，RSS 阅读器能正常显示，手机端也不需要加载 1.2MB 的脚本来渲染一张图。

ssg 开关：构建时 vs 客户端，由你决定

说实话，我也不想把话说死——并不是所有人都适合纯静态 SVG。有些场景下，你可能就是想用客户端 mermaid.js 自己渲染：

为此，插件提供了一个 ssg 开关：

1
mermaidHast({
2
    ssg: true, // 构建时产出内联 SVG，零客户端 JS
3
    theme: "dark",
4
});

1
mermaidHast({
2
    ssg: false, // 输出 <pre class="mermaid"> 代码块，交给客户端 mermaid.js 渲染
3
});

当 ssg: false 时，插件不会调用 napi-rs 渲染器，而是输出干净的 <pre class="mermaid">code</pre> 标签。你只需要在页面中引入 mermaid.js：

1
<script type="module">
2
    import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
3
    mermaid.initialize({ startOnLoad: true });
4
</script>

这个开关的设计理念很明确：你不需要在“全有”和“全无”之间二选一。一台 x64 Linux 构建服务器上开 ssg: true 享受 3ms/图的速度；改天换到 ARM 开发板上照样能跑 ssg: false 不掉链子。进可攻，退可守。

这一路踩过的坑

坑 1：Sätteri 破坏 Mermaid 代码

这是最早的坑，也是逼出双插件架构的根本原因。Sätteri 的 smart punctuation 会把 Mermaid 代码中的特殊字符序列（比如 {"）当成文本进行处理变换，导致图渲染失败。

解决方案前面已经说了：MDAST 阶段把代码藏起来，HAST 阶段再取出来渲染。

坑 2：WASM 文件查找

@mermanjs/web 的 WASM 文件位置在不同环境下可能不同（npm link、workspace、monorepo 都会影响路径）。写了一个逐级向上查找的函数，最多找 20 层目录。说实话，这种代码写出来我就知道这方案活不长。

用 napi-rs 之后，.node 文件跟着 npm 包走，Node.js 的 require 机制自动解析路径。天经地义的事，不需要任何骚操作。

坑 3：Expressve Code 语法高亮器干扰

Astro 的 expressive-code 会把 ```mermaid 代码块当成普通代码块处理，输出时加了一堆 <span> 和 class。导致 HAST 插件找不到 mermaid 代码。

解决方案是在 HAST 插件中同时监听两种节点：raw 节点（原生的 HTML 输出）和 element 节点（被语法高亮器处理后的结构化输出）。双路径兜底，确保万无一失。

总结

现在回头看，这个问题的解决路径其实非常清晰：

最终，我们用 150 行 Rust + 450 行 TypeScript 的代码量，换来了：

说实话，这种“在构建时就把所有事情做完”的理念，才是一个静态博客该有的样子。你的内容是什么，就生成什么——不需要用户在浏览器里再去编译、渲染、计算。

流程图不应该是一个运行时概念——它应该是一张图片。在你按下 Ctrl+S 的那一刻，它就应该是图片了。

安装使用

1
npm install @xingwangzhe/satteri-mermaid

依赖 satteri >= 0.8.0。无需其他运行时依赖——napi-rs 渲染器已内置在各平台的 .node 二进制中。开箱即用。

相关链接：

• @xingwangzhe/satteri-mermaid — npm 包源码
• mermaid-rs-renderer — 底层 Rust 渲染器
• Astro: 优化katex,mermaid和灯箱使用 — 上一阶段的优化记录