blog.dopana

返回

你在技术博客文章中通过 ````mermaid` 语法嵌入了几张系统架构图。读者打开网页时,文章正文虽然立刻呈现,但图表区域却是一片空白或原始代码块。几秒钟后,随着浏览器下载完数兆大小的 JavaScript 代码包并完成运算,图表才突然弹出来,同时整个页面发生剧烈跳动(累积布局偏移,CLS)。

这是使用 astro-mermaid 等传统客户端渲染方案时的典型痛点。本文将介绍如何使用 Pele 彻底替代 astro-mermaid,在静态构建阶段(SSG)直接将 Mermaid 文本编译为静态 SVG,从而将客户端图表运行时 JavaScript 减少到 0KB。

问题:客户端渲染 Mermaid 的三大隐患#

传统 astro-mermaid 插件依赖浏览器的客户端运行时:

  1. 构建阶段:Astro 仅仅把 ````mermaid代码块转译为普通的
    ` HTML 标签。
  2. 页面加载:浏览器必须完整下载庞大的 mermaid.js(解压后体积高达 2MB 到 3MB)。
  3. 计算排版:浏览器 CPU 执行复杂的排版算法(Dagre、Elk、D3 等),在手机端易导致发热和卡顿。
  4. 明暗主题切换:每次切换深色/浅色模式,JavaScript 都必须清空 DOM 并重新解析和重绘所有图表。
现代方案: remark-pele传统方案: astro-mermaidMarkdown (.md)Astro 构建输出包含 pre.mermaid 的 HTML浏览器加载 HTML下载 mermaid.js 运行时(~2-3MB)客户端执行 JS 绘制 SVG(产生布局偏移、延迟卡顿)Markdown (.md)Astro 构建 + Pele直接输出包含 SVG 的 HTML浏览器即时渲染图表(0KB JS, 零布局跳动)

[!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 pele
bash

第二步:编写 Remark 插件 remark-pele.ts#

在 src/plugins/remark-pele.ts 创建插件。该插件遍历 Markdown 语法树(MDAST),匹配语言为 mermaid 的代码节点,并将其替换为由 Pele 生成的 SVG 容器:

[!TIP] 传入 idPrefix: pele-${diagramIndex}- 至关重要。当一篇文章存在多个图表时,可确保 SVG 内部的箭头标记(marker)、渐变和剪切路径(clip-path)的唯一性,防止不同图表之间的样式冲突。

第三步:更新 astro.config.ts#

在 astro.config.ts 配置文件中,移除 astroMermaid 集成,并将 remarkPele 注入到 markdown.processor:

第四步:配置 CSS 变量主题#

在全局样式表中将 Pele 的 CSS 主题变量与博客自身的设计令牌绑定:

同时设置容器在移动端的水平自适应滑动:

第五步:清理无用脚本与卸载旧包#

移除模板(如 BaseLayout.astro)中任何初始化 Mermaid 的客户端脚本(不再需要 import('mermaid') 和 mermaid.run())。

随后彻底卸载旧依赖:

bun remove astro-mermaid mermaid
bash

优化成效对比#

评估指标改造前 (astro-mermaid)改造后 (pele)提升效果
客户端 JS 体积约 2.5 MB (mermaid bundle)0 KB下降 100%
累积布局偏移 (CLS)明显跳动0 (完全稳定)体验极佳
无 JS 环境容灾显示失败或生硬代码完美正常显示极高可靠性
明暗主题切换延迟需等待 JS 重新排版纯 CSS 瞬时生效丝滑无感
构建性能开销N/A845 张图表耗时 ~1.5 秒极快

结语#

通过使用 Pele 将 Mermaid 从客户端动态执行转变为构建期静态编译,我们成功实现了极致的首屏加载速度,彻底消除了页面布局跳动,同时大幅减少了移动端网络与计算资源的浪费。

参考资料#