mermaid.cli 原理揭秘：Puppeteer+无头Chrome如何将一个.mmd文件变成SVG、PNG和PDF

mermaid.cli 原理揭秘Puppeteer无头Chrome如何将一个.mmd文件变成SVG、PNG和PDF【免费下载链接】mermaid.cliDevelopment has been moved to https://github.com/mermaid-js/mermaid-cli项目地址: https://gitcode.com/gh_mirrors/me/mermaid.climermaid.cli 是一个免费的命令行工具能把一个.mmd文件一键转换成 SVG、PNG 和 PDF 图表图片。它的核心套路很简单用 Puppeteer 启动一个无头 Chrome 浏览器让 Mermaid 引擎在网页里把图表文字渲染成真正的 SVG再通过取文本、截图、打印三种方式导出成图片。本文带你拆解全部 6 个步骤。 一句话看懂 mermaid.cli 是什么mermaid.cli 是 Mermaid 图表语言的命令行界面你只需把流程图、时序图等写成几行纯文本存进.mmd文件执行mmdc命令就能得到可嵌入文档和网页的图片文件。它的依赖非常精简见 package.json只有三个核心库依赖角色commander命令行参数解析与校验chalk彩色控制台输出puppeteer启动并操控无头 Chrome 快速上手30 秒跑通第一条命令git clone https://gitcode.com/gh_mirrors/me/mermaid.cli cd mermaid.cli yarn install source copy_modules.sh用项目自带的示例流程图试一下mmdc -i test/flowchart.mmd -o output.pngmmdc命令在 package.json 的bin字段中声明指向打包后的单文件 index.bundle.js。 整体原理从文本到图片的 6 步流水线核心逻辑全部集中在 index.js 中完整流程如下步骤执行者做了什么1commander解析-i/-o/-t/-b等参数校验输入文件存在、输出后缀为 svg/png/pdf2puppeteer.launch()在后台启动一个无头 Chrome无窗口、无界面3page.goto()加载随包自带的 index.html 空白画布页4page.$eval()把 .mmd 文本注入页面调用mermaid.init()渲染出 SVG5按输出后缀三选一分支SVG 取文本 / PNG 裁剪截图 / PDF 整页打印6fs/page.screenshot/page.pdf把最终文件写入磁盘第 1 步参数解析与校验commanderindex.js 前半部分用 commander 定义了全部选项输入文件-i、输出文件-o、主题-t、页面宽高-w/-H、背景色-b、mermaid 配置文件-c、自定义 CSS-C、Puppeteer 配置文件-p。同时做了三道新手常见的校验输入文件必须存在输出后缀只能是.svg/.png/.pdf输出目录必须已存在不满足时通过 chalk 打印红色错误信息并退出避免生成到错误位置。第 2 步启动无头浏览器Puppeteer无头headless指一个完整的 Chrome 浏览器在后台运行但没有窗口和界面。它能做真浏览器的一切事解析 HTML、执行 JS、渲染 SVG、截图、打印 PDF只是全程不可见。const browser await puppeteer.launch(puppeteerConfig) const page await browser.newPage() page.setViewport({ width, height })如果需要额外的 Chrome 启动参数比如后文 Linux 的--no-sandbox可以写进 JSON 文件用-p传入。第 3 步隐藏的画布——index.html浏览器启动后mmdc 不会直接渲染图表而是先加载随包自带的 index.html。这个页面极简div idcontainer/div script src./mermaid.min.js charsetutf-8/script只有一个空容器 div 和 Mermaid 渲染引擎脚本。注意mermaid.min.js不是提交在仓库里的而是构建时由 copy_modules.sh 从 node_modules 的 mermaid 包复制过来连同 FontAwesome 图标字体实现离线可用。第 4 步注入 .mmd 代码渲染出 SVG这是最关键的魔法时刻。mmdc 读取你的 .mmd 文件文本通过page.$eval()注入到页面里container.innerHTML definition // 把 .mmd 文本写进 div window.mermaid.initialize(mermaidConfig) // 应用主题与配置 window.mermaid.init(undefined, container) // 解析文本生成 SVG如果通过-C传了自定义 CSS它会被动态追加为一个style标签到页面 head 中。执行完mermaid.init()后容器 div 内就出现了一个真正渲染好的svg节点。第 5 步SVG / PNG / PDF 三种截然不同的导出方式index.js 最后的分支处理三种输出格式思路完全不同输出格式方法一句话原理SVGpage.$eval()取容器的innerHTMLSVG 本身就是 HTML 文本直接把文本写盘即是图片文件PNGgetBoundingClientRect()取 SVG 边界框再page.screenshot({ clip })精确裁剪到 SVG 区域截图不带多余白边PDFpage.pdf({ printBackground })交给 Chrome 内置打印能力把整页渲染为 PDF背景色选项-b也有对应细节背景设为transparent时PNG 截图会加omitBackground: true让背景透明PDF 则不打印背景色。 测试目录速览test/ 目录自带一组示例夹具README 建议修改代码后用它做手工验证test/flowchart.mmd —— 6 行流程图示例test/sequence.mmd —— 含 loop 块的时序图示例test/config.json —— mermaid 配置示例forest 主题、时序图行高等test/index.css —— 自定义样式示例⚠️ 新手必踩坑Linux 沙箱报错在 root 用户或较老内核上运行Chrome 常报No usable sandbox!或Running as root without --no-sandbox is not supported。最直接的绕过办法创建puppeteer-config.json{ args: [--no-sandbox] }然后在命令行指定它mmdc -p puppeteer-config.json -i test/flowchart.mmd -o out.svg 几个实用细节不写-o时默认输出为输入文件名加.svg-t主题支持 default、forest、dark、neutral 四种内置风格npm 上的 mermaid.cli 包已停止更新官方开发已迁移到 mermaid-js 组织下的 mermaid-cli 项目新项目建议使用更新版本的 mermaid-js/mermaid-cli 总结mermaid.cli 的本质是借浏览器画图Puppeteer 提供无头 Chromeindex.html 页面是画布Mermaid 引擎是画师取文本、截图、打印 PDF 三条路线分别对应 SVG、PNG、PDF 三种格式。理解这条 6 步流水线后你就能把同样的思路迁移到许多网页技术 无头浏览器的自动化场景中。【免费下载链接】mermaid.cliDevelopment has been moved to https://github.com/mermaid-js/mermaid-cli项目地址: https://gitcode.com/gh_mirrors/me/mermaid.cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考