Mermaid-CLI 中 Puppeteer 连接配置的实践与优化

背景介绍

Mermaid-CLI 是基于 Node.js 的命令行工具，用于将 Mermaid 图表转换为各种输出格式。它底层使用 Puppeteer 库来控制 Chromium 浏览器进行渲染。在实际使用中，用户可能会遇到性能优化需求，特别是希望复用浏览器实例以减少启动时间。

核心问题分析

在使用 Mermaid-CLI 时，用户尝试通过 Puppeteer 的 browserUrl 或 browserWSEndpoint 配置参数来连接到一个已经运行的 Chromium 实例，但发现这些配置未被正确识别。这导致每次运行命令时都会启动新的浏览器实例，增加了处理时间。

技术原理

Puppeteer 提供了两种连接现有浏览器实例的方式：

1. browserWSEndpoint：通过 WebSocket 端点连接
2. browserUrl：通过 HTTP 调试端口连接

这两种方式理论上都可以实现浏览器实例的复用，但需要注意版本兼容性和配置格式。

解决方案探索

方案一：自定义 Node.js 脚本

通过编写自定义脚本，可以完全控制 Puppeteer 的生命周期：

import {writeFile} from 'node:fs/promise';
import puppeteer from 'puppeteer'
import { renderMermaid } from '@mermaid-js/mermaid-cli';

// 创建单个浏览器实例
const browser = await puppeteer.launch();

async function main() {
  // 可重复使用同一浏览器实例
  const { data } = await renderMermaid(browser, mermaidCode, 'png');
  await writeFile(data, 'output.png');
}

main();

这种方案的优势在于完全掌控浏览器实例，适合需要批量处理多个图表的场景。

方案二：升级 Mermaid-CLI 版本

较新版本的 Mermaid-CLI 使用了更新的 Puppeteer 版本，可能对连接配置有更好的支持。可以通过安装开发中的 v11 版本尝试解决兼容性问题。

实践建议

1. 性能权衡：对于单次转换，2秒左右的启动时间是可以接受的
2. 批量处理：如需处理多个图表，建议采用自定义脚本方案
3. 替代方案：可以考虑使用专门的 Go 语言实现等轻量级方案

总结

虽然 Mermaid-CLI 默认配置下不支持直接复用浏览器实例，但通过自定义脚本或版本升级可以解决这一问题。在实际项目中，应根据具体需求选择最适合的优化方案，平衡开发便利性和性能要求。