mermaid.cli是什么：Mermaid命令行图表渲染工具完全指南（从认识工具到画出第一张SVG）

mermaid.cli是什么：Mermaid命令行图表渲染工具完全指南（从认识工具到画出第一张SVG）

【免费下载链接】mermaid.cliDevelopment has been moved to https://github.com/mermaid-js/mermaid-cli项目地址: https://gitcode.com/gh_mirrors/me/mermaid.cli

🎯mermaid.cli是一款开源的Mermaid 命令行图表渲染工具（CLI 工具）：只需一个.mmd文本文件作为输入，就能一键生成SVG、PNG、PDF三种格式的图表文件。它把 Mermaid 的"文字画图"能力从浏览器搬到了终端，非常适合新手快速上手，也适合自动化文档生产。

---

一、mermaid.cli 能做什么？

Mermaid 是一种用纯文本描述图表的开源工具：流程图、时序图、甘特图等，都可以用几行文字写出来，无需手动拖拽节点。

而 mermaid.cli 的核心使命只有一个：

输入一个 Mermaid 定义文件 → 输出一张可使用的图片文件

它的命令行入口叫mmdc，最基础的用法就是：

mmdc -i input.mmd -o output.svg

三个输出格式全覆盖，各有所长：

格式	命令示例	适用场景
🖼️ SVG	mmdc -i input.mmd -o out.svg	网页嵌入、无限放大不失真
📷 PNG	mmdc -i input.mmd -o out.png	邮件、PPT、社交平台
📄 PDF	mmdc -i input.mmd -o out.pdf	打印、正式文档归档

工具本体由三个核心文件构成：

• index.js—— 命令行参数解析与渲染主流程（入口脚本）
• index.html—— 内置的渲染页面，供无头浏览器加载
• package.json—— 依赖声明，核心依赖为puppeteer（无头 Chrome）

二、如何安装 mermaid.cli？

1. 本地安装（官方推荐 ✅）

全局安装可能因权限问题失败，官方在 README 中明确建议优先本地安装：

yarn add mermaid.cli ./node_modules/.bin/mmdc -h

或使用 npm：

npm install mermaid.cli ./node_modules/.bin/mmdc -h

2. 全局安装（❗️官方不推荐）

npm install -g mermaid.cli

💡 安装完成后运行mmdc -h即可查看全部可用参数。

三、画出第一张 SVG：完整实战步骤

项目自带了现成的示例文件，跟着做 3 步即可。

第 1 步：准备输入文件

打开仓库中的 test/flowchart.mmd，内容是一段简洁的流程图定义（圣诞节购物流程）：

graph TD A[Christmas] -->|Get money| B(Go shopping) B --> C{Let me think} C -->|One| D[Laptop] C -->|Two| E[iPhone] C -->|Three| F[Car]

第 2 步：执行渲染命令

mmdc -i test/flowchart.mmd -o output.svg

第 3 步：打开output.svg—— 恭喜，你的第一张 Mermaid 流程图已经画好了！🎉

小技巧：-o参数可省略，默认会在输入文件名后追加.svg后缀（见 index.js 中的默认值逻辑）。

时序图同理，仓库里的test/sequence.mmd就是一个完整的业务时序示例，同样一条命令即可渲染。

四、mermaid.cli 常用参数速查表

这些参数在 index.js 中通过commander库注册，是日常使用频率最高的"长尾工具"：

参数	说明	默认值
-i, --input	输入文件（必填）	—
-o, --output	输出文件，须为 svg/png/pdf	输入文件名 +.svg
-t, --theme	主题：default / forest / dark / neutral	default
-w, --width	页面宽度	800
-H, --height	页面高度	600
-b, --backgroundColor	背景色，支持transparent、颜色名或色值	white
-c, --configFile	Mermaid 的 JSON 配置文件	—
-C, --cssFile	自定义 CSS 文件	—
-p, --puppeteerConfigFile	Puppeteer 的 JSON 配置文件	—

高频命令示例

# 指定尺寸 + 森林主题 mmdc -i input.mmd -o output.svg -w 1024 -H 768 -t forest # 透明背景 PNG（适合叠在其他设计稿上） mmdc -i input.mmd -o output.png -b transparent

五、进阶技巧：配置文件与样式定制

1. 用 JSON 配置文件统一控制图表风格

仓库中附带了一份现成的配置样例test/config.json，包含主题、流程图宽宽策略、自定义 CSS 等：

{ "startOnLoad": true, "flowchart": { "useMaxWidth": false, "htmlLabels": true }, "sequence": { "height": 40, "actorMargin": 80 }, "theme": "forest", "themeCSS": ".node rect { fill: red; }" }

配合-c参数即可整体换肤，不必每次手写参数。

2. 用 CSS 文件深度定制外观

test/index.css是项目内置的样式文件示例，通过-C test/index.css传入后，会在渲染时动态注入页面（index.js 中的myCSS逻辑），让你像写网页一样精修图表样式。

六、Linux 下常见问题：Chrome 沙箱报错怎么办？

这是新手最常踩的坑。当看到Failed to launch chrome!或No usable sandbox!报错时，官方给出的标准解法：

1. 创建puppeteer-config.json：

{ "args": ["--no-sandbox"] }

2. 渲染时加上-p参数引用它：

mmdc -p puppeteer-config.json -i input.mmd -o out.svg

⚠️ 官方更建议：升级 Linux 内核、避免以 root 身份运行。--no-sandbox属于临时应急方案。

七、项目结构与工作原理一图看懂

mermaid.cli/ ├── index.js # 主程序：解析参数 → 启动无头浏览器 → 截图/导出 ├── index.html # 渲染页面：加载 mermaid.min.js 与字体图标 ├── copy_modules.sh # 构建脚本：复制 mermaid 与 FontAwesome 资源 ├── test/ # 示例与手工测试素材 │ ├── flowchart.mmd # 流程图示例（4 个版本） │ ├── sequence.mmd # 时序图示例 │ ├── config.json # Mermaid 配置示例 │ └── index.css # 自定义样式示例 └── package.json # 依赖：commander / chalk / puppeteer

工作原理（通俗版）：mmdc启动一个无头 Chrome 浏览器 → 打开内置的index.html页面 → 把.mmd文本注入页面交给 Mermaid 渲染成 SVG → 根据输出格式"收割"结果（SVG 直接抓取标签、PNG 截图裁剪、PDF 走打印管线），最后关闭浏览器。整个过程无需手动打开任何网页，全自动完成。

八、重要提醒：项目迁移说明 📢

请注意：本仓库已停止活跃开发，README.md 顶部明确标注了迁移公告——官方开发已转移到 mermaid-js 组织下的新仓库。对应的 npm 包mermaid.cli不再更新且版本较旧，新项目建议直接使用@mermaid-js/mermaid-cli包。

理解本文的工具原理后，迁移到新包几乎零成本：命令名、参数、用法一脉相承，你只需把包名替换即可。

---

总结：3 步上手 mermaid.cli

步骤	动作	一句话
①	安装	npm install mermaid.cli
②	写图	用文字描述图表，保存为.mmd文件
③	渲染	mmdc -i 输入.mmd -o 输出.svg

掌握这 3 步，你就能在终端里快速生成流程图、时序图等各类图表，把"文字"变成"图"，让文档从此自带图解 🚀

【免费下载链接】mermaid.cliDevelopment has been moved to https://github.com/mermaid-js/mermaid-cli项目地址: https://gitcode.com/gh_mirrors/me/mermaid.cli