Mermaid.js CLI工具：命令行图表生成与批量处理

痛点：手动图表生成的效率瓶颈

在日常开发文档编写过程中，你是否经常遇到这样的场景：需要为多个Markdown文件生成流程图、序列图或类图，但每次都要打开在线编辑器，复制粘贴代码，下载图片，再插入文档？这种重复性工作不仅耗时耗力，还容易出错。

Mermaid.js CLI工具正是为解决这一痛点而生！它让你能够在命令行中批量处理Mermaid图表，实现自动化图表生成，大幅提升文档编写效率。

CLI工具核心功能一览

Mermaid CLI提供了一套完整的命令行界面，支持多种图表格式输出和批量处理能力：

功能特性	描述	适用场景
多格式输出	SVG、PNG、PDF等多种格式	不同文档需求
批量处理	支持目录级图表生成	大型项目文档
配置定制	自定义主题、样式配置	品牌一致性
自动化集成	CI/CD流水线集成	自动化文档生成

安装与配置

环境要求

• Node.js 14.0.0 或更高版本
• npm 或 yarn 包管理器

安装步骤

# 全局安装mermaid-cli
npm install -g @mermaid-js/mermaid-cli

# 或者使用yarn
yarn global add @mermaid-js/mermaid-cli

# 验证安装
mmdc --version

基础配置

创建配置文件 .mmdc.json：

{
  "theme": "default",
  "backgroundColor": "#ffffff",
  "outputFormat": "svg",
  "width": 800,
  "height": 600
}

核心命令详解

基础图表生成

# 从文件生成图表
mmdc -i input.mmd -o output.svg

# 指定输出格式
mmdc -i diagram.mmd -o diagram.png

# 设置主题
mmdc -i flowchart.mmd -o flowchart.svg -t forest

# 自定义宽度高度
mmdc -i sequence.mmd -o sequence.png -w 1200 -H 800

批量处理示例

# 处理目录下所有.mmd文件
find ./docs -name "*.mmd" -exec mmdc -i {} -o {}.svg \;

# 使用并行处理提高效率
find ./docs -name "*.mmd" | xargs -P 4 -I {} mmdc -i {} -o {}.svg

实战案例：自动化文档流水线

项目结构规划

flowchart TD
    A[文档源码目录] --> B[Mermaid源文件]
    B --> C[CLI批量处理]
    C --> D[生成图表文件]
    D --> E[集成到文档]
    E --> F[最终文档输出]

自动化脚本示例

创建 generate-diagrams.sh 脚本：

#!/bin/bash

# 配置参数
INPUT_DIR="./docs/diagrams"
OUTPUT_DIR="./docs/assets/diagrams"
THEME="default"
FORMAT="svg"

echo "开始生成Mermaid图表..."

# 创建输出目录
mkdir -p $OUTPUT_DIR

# 遍历处理所有Mermaid文件
for file in $INPUT_DIR/*.mmd; do
    if [ -f "$file" ]; then
        filename=$(basename "$file" .mmd)
        echo "正在处理: $filename"
        
        mmdc -i "$file" -o "$OUTPUT_DIR/$filename.$FORMAT" -t $THEME
        
        if [ $? -eq 0 ]; then
            echo "✓ $filename 生成成功"
        else
            echo "✗ $filename 生成失败"
        fi
    fi
done

echo "图表生成完成！"

CI/CD集成示例

.github/workflows/generate-diagrams.yml:

name: Generate Mermaid Diagrams

on:
  push:
    paths:
      - 'docs/diagrams/**'
      - '.github/workflows/generate-diagrams.yml'

jobs:
  generate-diagrams:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        cache: 'npm'
    
    - name: Install mermaid-cli
      run: npm install -g @mermaid-js/mermaid-cli
    
    - name: Generate diagrams
      run: |
        mkdir -p docs/assets/diagrams
        for file in docs/diagrams/*.mmd; do
          if [ -f "$file" ]; then
            filename=$(basename "$file" .mmd)
            mmdc -i "$file" -o "docs/assets/diagrams/$filename.svg" -t default
          fi
        done
    
    - name: Commit generated diagrams
      run: |
        git config --local user.email "[e-mail]"
        git config --local user.name "GitHub Action"
        git add docs/assets/diagrams/
        git commit -m "Auto-generated diagrams [skip ci]" || echo "No changes to commit"
        git push

高级功能与技巧

自定义CSS样式

# 使用自定义CSS文件
mmdc -i diagram.mmd -o diagram.svg -C custom.css

# custom.css示例
.node rect {
  fill: #e1f5fe;
  stroke: #01579b;
}

.edgePath path {
  stroke: #546e7a;
  stroke-width: 2px;
}

配置文件管理

{
  "flowchart": {
    "htmlLabels": false,
    "curve": "basis"
  },
  "sequence": {
    "diagramMarginX": 50,
    "diagramMarginY": 10,
    "actorMargin": 50
  },
  "theme": "forest",
  "themeVariables": {
    "primaryColor": "#ff6f00",
    "primaryTextColor": "#fff",
    "primaryBorderColor": "#e65100"
  }
}

错误处理与日志

# 启用详细日志
mmdc -i input.mmd -o output.svg --verbose

# 输出到日志文件
mmdc -i diagram.mmd -o diagram.svg 2>&1 | tee generation.log

# 错误处理脚本
if ! mmdc -i "$file" -o "$output"; then
    echo "错误: $file 生成失败" >&2
    exit 1
fi

性能优化建议

批量处理优化

# 使用并行处理
parallel mmdc -i {} -o {.}.svg ::: *.mmd

# 限制并发数
find . -name "*.mmd" -print0 | xargs -0 -P 4 -I {} mmdc -i {} -o {}.svg

缓存策略

# 只处理修改过的文件
find ./diagrams -name "*.mmd" -newer timestamp.file -exec mmdc -i {} -o {}.svg \;

# 更新时间戳
touch timestamp.file

常见问题解决方案

中文显示问题

# 确保系统字体支持中文
mmdc -i chinese.mmd -o chinese.svg --cssFile chinese.css

# chinese.css
@font-face {
  font-family: 'Noto Sans SC';
  src: local('Noto Sans SC');
}

* {
  font-family: 'Noto Sans SC', sans-serif;
}

大型图表处理

# 增加内存限制
NODE_OPTIONS="--max-old-space-size=4096" mmdc -i large.mmd -o large.svg

# 分步处理复杂图表
split -l 50 large.mmd segment_
for segment in segment_*; do
    mmdc -i "$segment" -o "${segment}.svg"
done

最佳实践总结

1. 版本控制: 将Mermaid源文件与生成的图表一起纳入版本控制
2. 自动化流水线: 集成到CI/CD流程中实现自动生成
3. 样式统一: 使用统一的CSS样式确保品牌一致性
4. 错误处理: 实现完善的错误处理和日志记录
5. 性能监控: 监控图表生成时间和资源消耗

技术架构解析

sequenceDiagram
    participant User
    participant CLI as mmdc
    participant Core as Mermaid Core
    participant Renderer
    participant Output

    User->>CLI: 执行命令
    CLI->>Core: 解析Mermaid代码
    Core->>Renderer: 渲染图表
    Renderer->>Output: 生成输出文件
    Output-->>CLI: 返回结果
    CLI-->>User: 完成提示

通过Mermaid.js CLI工具，你可以将图表生成工作完全自动化，释放双手专注于内容创作。无论是个人项目还是大型团队协作，这套工具链都能显著提升文档编写效率和质量。

立即尝试将Mermaid CLI集成到你的工作流中，体验命令行图表生成的强大威力！