使用 Pele 替代 astro-mermaid:构建期生成 SVG 图表
使用 Pele 替代 astro-mermaid,在 Astro 构建期将 Mermaid 语法直接渲染为静态 SVG,实现客户端 0KB JS 与纯 CSS 主题无缝切换。
你在技术博客文章中通过 ````mermaid` 语法嵌入了几张系统架构图。读者打开网页时,文章正文虽然立刻呈现,但图表区域却是一片空白或原始代码块。几秒钟后,随着浏览器下载完数兆大小的 JavaScript 代码包并完成运算,图表才突然弹出来,同时整个页面发生剧烈跳动(累积布局偏移,CLS)。
这是使用 astro-mermaid 等传统客户端渲染方案时的典型痛点。本文将介绍如何使用 Pele 彻底替代 astro-mermaid,在静态构建阶段(SSG)直接将 Mermaid 文本编译为静态 SVG,从而将客户端图表运行时 JavaScript 减少到 0KB。
问题:客户端渲染 Mermaid 的三大隐患#
传统 astro-mermaid 插件依赖浏览器的客户端运行时:
- 构建阶段:Astro 仅仅把 ````mermaid
代码块转译为普通的` HTML 标签。
- 页面加载:浏览器必须完整下载庞大的
mermaid.js(解压后体积高达 2MB 到 3MB)。 - 计算排版:浏览器 CPU 执行复杂的排版算法(Dagre、Elk、D3 等),在手机端易导致发热和卡顿。
- 明暗主题切换:每次切换深色/浅色模式,JavaScript 都必须清空 DOM 并重新解析和重绘所有图表。
[!WARNING] 一旦读者禁用 JavaScript、或者使用阻止重脚本的网络环境,客户端图表将彻底无法显示,只留下一堆难以阅读的原始代码。
什么是 Pele?通俗解释(ELI5)#
不妨把图表想象成一张餐桌:
- 客户端渲染 Mermaid 好比买了一套平板包装家具,里面装着 100 颗螺丝和安装手册:读者的浏览器(客人)在坐下来吃饭前,得先满头大汗地把桌子组装好。
- Pele 则好比木匠在工厂里就已经把整张桌子组装打磨完成并送货上门:拆开包装即可立刻使用,客人不需要消耗任何体力。
Pele ↗ 是由 Obsidian 首席执行官 kepano 开发的高性能 Mermaid 渲染引擎。它具备以下显著特点:
- 同步静态生成(Synchronous):无需无头浏览器(如 Puppeteer),在 Node.js 或 Bun 进程中即可瞬间将 Mermaid 源码编译为 SVG。
- CSS 变量动态主题:生成的 SVG 使用标准的 CSS 自定义属性(
--pele-bg、--pele-fg、--pele-surface、--pele-border等)。深色/浅色模式切换完全交由原生 CSS 处理,毫秒级即时响应且无需重新执行 JS。 - 广泛兼容主流图表:完美支持流程图、时序图、类图、状态图、实体关系图(ER)、Git分支图、脑图(Mindmap)及时间线等。
实践指南:在 Astro 中集成 Pele#
第一步:安装 Pele#
在项目中安装 pele 依赖:
bun add pele
# 或者 npm: npm install pele
# 或者 pnpm: pnpm add pelebash第二步:编写 Remark 插件 remark-pele.ts#
在 src/plugins/remark-pele.ts 创建插件。该插件遍历 Markdown 语法树(MDAST),匹配语言为 mermaid 的代码节点,并将其替换为由 Pele 生成的 SVG 容器:
import type { Code, Root } from 'mdast';
import { render, type RenderOptions } from 'pele';
import { visit } from 'unist-util-visit';
export interface RemarkPeleOptions {
fontSize?: number;
fontFamily?: string;
renderOptions?: RenderOptions;
}
function escapeHtml(str: string): string {
return str
.replace(/&/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/"/g, '"')
.replace(/'/g, ''');
}
export default function remarkPele(options: RemarkPeleOptions = {}) {
const defaultFontSize = options.fontSize ?? 14;
const defaultFontFamily = options.fontFamily ?? 'Inter, system-ui, sans-serif';
return (tree: Root) => {
let diagramIndex = 0;
visit(tree, 'code', (node: Code, index, parent) => {
if (
node.lang &&
node.lang.trim().toLowerCase() === 'mermaid' &&
parent &&
typeof index === 'number'
) {
try {
diagramIndex++;
const idPrefix = `pele-${diagramIndex}-`;
const { svg } = render(node.value, {
idPrefix,
responsive: true,
fontSize: defaultFontSize,
fontFamily: defaultFontFamily,
...options.renderOptions,
});
// 将代码节点替换为包含 SVG 的 HTML 容器
parent.children[index] = {
type: 'html',
value: `<div class="pele-diagram my-6 flex justify-center overflow-x-auto">${svg}</div>`,
};
} catch (err: unknown) {
const error = err as Error;
console.warn(`[remark-pele] 图表渲染失败:`, error?.message);
parent.children[index] = {
type: 'html',
value: `<div class="pele-error my-4 rounded-lg border border-red-500/50 bg-red-500/10 p-4"><p class="mb-2 font-mono text-xs text-red-500">Mermaid Render Error: ${escapeHtml(error?.message || String(err))}</p><pre class="overflow-x-auto text-xs"><code>${escapeHtml(node.value)}</code></pre></div>`,
};
}
}
});
};
}ts[!TIP] 传入
idPrefix: pele-${diagramIndex}-至关重要。当一篇文章存在多个图表时,可确保 SVG 内部的箭头标记(marker)、渐变和剪切路径(clip-path)的唯一性,防止不同图表之间的样式冲突。
第三步:更新 astro.config.ts#
在 astro.config.ts 配置文件中,移除 astroMermaid 集成,并将 remarkPele 注入到 markdown.processor:
import { defineConfig } from 'astro/config';
import { unified } from '@astrojs/markdown-remark';
import remarkPele from './src/plugins/remark-pele.ts';
import astroMermaid from 'astro-mermaid';
export default defineConfig({
markdown: {
processor: unified({
remarkPlugins: [
remarkMath,
remarkPele,
],
rehypePlugins: [ /* ... */ ],
}),
},
integrations: [
astroMermaid({ /* ... */ }),
AstroPureIntegration(config),
],
});ts第四步:配置 CSS 变量主题#
在全局样式表中将 Pele 的 CSS 主题变量与博客自身的设计令牌绑定:
:root {
/* Pele Mermaid theme tokens (Light mode) */
--pele-font: Inter, system-ui, -apple-system, sans-serif;
--pele-font-mono: monospace;
--pele-radius: var(--radius);
--pele-bg: transparent;
--pele-fg: hsl(var(--foreground));
--pele-muted: hsl(var(--muted-foreground));
--pele-line: hsl(var(--muted-foreground));
--pele-surface: hsl(var(--muted));
--pele-surface-alt: hsl(var(--card));
--pele-border: hsl(var(--border));
--pele-accent: hsl(var(--primary));
}
.dark,
[data-theme="dark"] {
/* Pele Mermaid theme tokens (Dark mode) */
--pele-bg: transparent;
--pele-fg: hsl(var(--foreground));
--pele-muted: hsl(var(--muted-foreground));
--pele-line: hsl(var(--muted-foreground));
--pele-surface: hsl(var(--muted));
--pele-surface-alt: hsl(var(--card));
--pele-border: hsl(var(--border));
--pele-accent: hsl(var(--primary));
}css同时设置容器在移动端的水平自适应滑动:
.pele-diagram {
margin-block: 1.75rem;
display: flex;
justify-content: center;
align-items: center;
overflow-x: auto;
-webkit-overflow-scrolling: touch;
border-radius: var(--radius, 0.5rem);
padding: 0.5rem;
}
.pele-diagram svg.pele {
max-width: 100%;
height: auto;
display: block;
}css第五步:清理无用脚本与卸载旧包#
移除模板(如 BaseLayout.astro)中任何初始化 Mermaid 的客户端脚本(不再需要 import('mermaid') 和 mermaid.run())。
随后彻底卸载旧依赖:
bun remove astro-mermaid mermaidbash优化成效对比#
| 评估指标 | 改造前 (astro-mermaid) | 改造后 (pele) | 提升效果 |
|---|---|---|---|
| 客户端 JS 体积 | 约 2.5 MB (mermaid bundle) | 0 KB | 下降 100% |
| 累积布局偏移 (CLS) | 明显跳动 | 0 (完全稳定) | 体验极佳 |
| 无 JS 环境容灾 | 显示失败或生硬代码 | 完美正常显示 | 极高可靠性 |
| 明暗主题切换延迟 | 需等待 JS 重新排版 | 纯 CSS 瞬时生效 | 丝滑无感 |
| 构建性能开销 | N/A | 845 张图表耗时 ~1.5 秒 | 极快 |
结语#
通过使用 Pele 将 Mermaid 从客户端动态执行转变为构建期静态编译,我们成功实现了极致的首屏加载速度,彻底消除了页面布局跳动,同时大幅减少了移动端网络与计算资源的浪费。