另一种将 Mermaid 转换为图片的方式：面向开发者的 Mermaid CLI 指南

开发者通常需要一种可重复、可脚本化的方式将 Mermaid 图表转换为标准图片格式。虽然网页工具适合快速转换，但命令行工具提供了自动化、CI/CD 集成和完全本地控制的能力。本文将展示如何使用 @mermaid-js/mermaid-cli 从 Mermaid 代码渲染出高质量的 PNG、JPG、SVG 和 PDF 图片。

什么是 Mermaid CLI？

Mermaid CLI 是一个命令行接口工具，它可以将 Mermaid 定义文件转换为图片（SVG/PNG/JPG/PDF），无需浏览器界面。它非常适合批量处理、构建流水线和可复现的文档生成。了解更多请访问官方仓库：https://github.com/mermaid-js/mermaid-cli

如何安装 Mermaid CLI？

你可以根据工作流选择全局安装、本地安装、通过 npx 运行、使用 Docker，或者通过 Node.js API 调用。

全局安装（简单方便，适合本地使用）：
```
npm install -g @mermaid-js/mermaid-cli
```
本地安装（避免全局依赖，适合项目内使用）：
```
npm install @mermaid-js/mermaid-cli
```
然后从 node_modules 调用二进制文件：
```
./node_modules/.bin/mmdc -h
```
通过 npx 运行（无需预先安装，适合一次性使用）：
```
npx -p @mermaid-js/mermaid-cli mmdc -h
```

Docker/Podman（隔离环境，易于 CI 集成）：

# Docker 方式
docker pull minlag/mermaid-cli
docker run --rm -u `id -u`:`id -g` -v /path/to/diagrams:/data minlag/mermaid-cli -i diagram.mmd

# Podman 方式
podman run --userns keep-id --user ${UID} --rm -v /path/to/diagrams:/data:z ghcr.io/mermaid-js/mermaid-cli/mermaid-cli -i diagram.mmd

Node.js API（在脚本中以编程方式调用）：

import { run } from "@mermaid-js/mermaid-cli"

await run(
  "input.mmd",
  "output.svg",
  // 可选的配置对象
)

如何将 Mermaid 转换为图片？

使用 mmdc 命令，指定输入文件（-i）和输出路径（-o）。

注意：以下命令假设 mmdc 已通过 PATH 可用（全局安装）或通过 npx 调用。如果是本地安装，请将 mmdc 替换为 ./node_modules/.bin/mmdc；如果是 Docker，请使用容器命令（如 docker run ... minlag/mermaid-cli -i ...）。

将 Mermaid 文件转换为 SVG：
```
mmdc -i input.mmd -o output.svg
```

转换为 PNG 或 PDF（修改扩展名即可）：

mmdc -i input.mmd -o output.png
mmdc -i input.mmd -o output.pdf

如何控制主题和背景？

使用 -t 参数指定主题，-b 参数指定背景。

暗色主题配合透明背景：

mmdc -i input.mmd -o output.png -t dark -b transparent

可以添加自定义 CSS 或覆盖样式吗？

可以。你可以通过 --cssFile 参数内联 CSS 文件，或者通过配置文件（--configFile）使用 themeCSS。

内联自定义 CSS：

mmdc --input flowchart.mmd --cssFile flowchart.css -o docs/flowchart-styled.svg

提示：如果你想全局覆盖 Mermaid 主题样式，建议在 --configFile 中添加 {"themeCSS": "..."}，以确保结果的一致性。

如何转换包含 Mermaid 图表的 Markdown 文件？

将 mmdc 指向一个 Markdown 模板文件和输出文件，它会自动渲染 Mermaid 代码块并生成引用的 SVG 图片。

转换包含多个 Mermaid 图表的 Markdown 文件：
```
mmdc -i readme.template.md -o readme.md
```
CLI 会查找 Markdown 中的 Mermaid 代码块，生成对应的 SVG 图片，并更新 Markdown 以引用这些生成的图片。

如何从标准输入（stdin）读取？

使用 --input - 从标准输入读取 Mermaid 代码。

使用 heredoc 的示例：

cat << 'EOF' | mmdc --input - -o diagram.svg
graph TD
  A[Client] --> B[Load Balancer]
EOF

开发者的最佳实践

整理输入/输出文件、标准化选项配置，并将其集成到脚本中。

整理文件：使用专门的 diagrams/ 目录存放源文件，artifacts/ 目录存放输出文件。
标准化选项：使用共享配置文件（如主题、背景等），确保 CI 和本地运行结果一致。

使用脚本自动化：在 package.json 中添加脚本，例如：

{
  "scripts": {
    "build:diagrams": "mmdc -i diagrams/arch.mmd -o artifacts/arch.svg -t dark -b transparent"
  }
}

在 CI/CD 中使用：在 GitHub Actions 或 GitLab 中，通过 Docker 或 npx 运行 mmdc，避免管理全局安装。

什么时候用 CLI，什么时候用网页工具？

CLI 适合自动化和可复现性；网页工具适合快速预览、交互式编辑和即时视觉反馈。

CLI 优势：可重复性、版本控制、脚本化、非交互式构建。
网页工具优势：即时预览、错误可见性、快速迭代和布局调整。

总结

如果你偏好自动化、可复现性以及与开发者工作流的集成，Mermaid CLI 是网页转换工具的完美补充。只需几个命令，你就能将任何 Mermaid 代码转换为生产级图片，并将其接入构建流水线、文档生成器和 CI 任务中。

延伸阅读：Mermaid CLI GitHub 仓库 — https://github.com/mermaid-js/mermaid-cli