流程图排版总是乱？mermaid-rs-renderer 的间距与宽高比调优全攻略-开发者社区

【免费下载链接】mermaid-rs-renderer

A fast native Rust Mermaid diagram renderer. No browser required. 500-1000x faster than mermaid-cli.

项目地址：https://gitcode.com/gh_mirrors/me/mermaid-rs-renderer

mermaid-rs-renderer（命令名mmdr）是一个纯 Rust 实现的Mermaid 图表原生渲染器，无需浏览器即可完成Mermaid 流程图排版，速度比 mermaid-cli 快 100~1400 倍。这篇文章聚焦大家最头疼的两个问题：节点间距总是挤成一团、图表宽高比忽长忽扁。我们会用nodeSpacing、rankSpacing和preferredAspectRatio三个核心参数，手把手教你把流程图排版调到"刚刚好"。

为什么流程图排版总是乱？

用 mermaid-cli 时，每个图都要启动一个无头 Chromium，单次渲染约 2 秒，你根本不敢反复试参数。而 mmdr 单张流程图只要几毫秒（字体缓存热后小图 < 3 ms），意味着你可以每秒尝试几十种间距组合，调版体验完全不同。

排版的"乱"通常来自两个根源：

间距失控——节点之间太挤（文字互相贴边）或太散（图被撑得老长）；
宽高比失衡——一条链被拉成 10800px 宽的细长条，或被压成又高又窄的竖条，贴进文档里很难看。

mmdr 的排版引擎对这两点都提供了直接的旋钮。🎛️

30 秒上手：安装与渲染第一张流程图

# 从 crates.io 安装 cargo install mermaid-rs-renderer # 管道渲染到 stdout echo 'flowchart LR; A-->B-->C' | mmdr -e svg # 文件到文件，顺便输出 PNG mmdr -i diagram.mmd -o out.png -e png

默认情况下输出采用图表的自然尺寸。想动手调版之前，建议先看看项目自带的测试图，感受一下"基准线"，例如 flowchart_medium.mmd 这样的中等规模流程图。

间距调优：nodeSpacing 与 rankSpacing

这是调版最常用的两个参数，含义很直观：

参数	含义	默认值
`nodeSpacing`	同一层内相邻节点之间的间距	50
`rankSpacing`	相邻两层之间的间距	50

💡 简单记忆：flowchart LR（左右走向）时，rankSpacing控制"水平方向"的层间距；flowchart TB（上下走向）时，它控制"垂直方向"的层间距。

命令行一步调版

参数直接写在命令行里，边渲染边看效果：

# 节点更紧凑、层与层拉得更开 mmdr -i diagram.mmd -o out.svg --nodeSpacing 30 --rankSpacing 80 # 反过来：留白多一些 mmdr -i diagram.mmd -o out.svg --nodeSpacing 70 --rankSpacing 60

参数解析逻辑见 cli.rs，默认值定义在 config.rs。

写进 config.json，全项目统一

如果你有一批图要统一风格，把参数写进配置文件更方便：

{ "preferredAspectRatio": "16:9", "flowchart": { "nodeSpacing": 50, "rankSpacing": 80 } }

mmdr -i diagram.mmd -o out.svg -c config.json

项目里就有一份现成的参考配置：modern-config.json（nodeSpacing: 40/rankSpacing: 80的组合）。也可以在图的头部用%%{init}%%指令注入同样的字段，解析入口在 config.rs。

调版手感参考：

节点文字互相贴边 → 增大nodeSpacing
整图又宽又散 → 减小rankSpacing
边线穿过文字 → 两者都适当增大，给路由留空间

宽高比调优：preferredAspectRatio 一步拉回 16:9

这是 mermaid-rs-renderer 布局层的一个亮点特性：它不只是简单裁剪或拉伸画布，而是先让布局引擎朝目标比例重新平衡几何，再把最终 SVG 尺寸适配到该比例。效果上，原本被拉成 10866px 宽的"细长蛇形"长链，会被折成接近 16:9 的均衡版面。

# 三种写法都可以：冒号、斜杠、小数 mmdr -i diagram.mmd -o out.svg --preferredAspectRatio 16:9 mmdr -i diagram.mmd -o out.svg --preferredAspectRatio 1.78

配置文件中对应顶层字段preferredAspectRatio，解析逻辑见 config.rs。这个特性的行为契约（包括"未设置时严格无操作"）由测试套件 aspect_fold_suite.rs 守护。

适用场景：幻灯片/PPT 插图固定 16:9、文档配图固定 4:3、仪表盘卡片固定 1:1——都能一步对齐。

进阶旋钮：让端口与走线更整齐

调完间距和宽高比之后，如果还觉得"边线打架"，可以看下flowchart下的进阶参数，完整说明在 flowchart_layout_config.md：

{ "flowchart": { "orderPasses": 4, "portPadRatio": 0.2, "portPadMin": 4, "portPadMax": 12, "portSideBias": 0.0 } }

参数	通俗解释
`orderPasses`	层内排序的往复迭代次数，越大节点顺序越"顺"
`portPadRatio`/`portPadMin`/`portPadMax`	节点边线上留给连线的"安全边距"，防止边线贴边
`portSideBias`	同一侧连线过多时的额外错开量

另外，mmdr 还内置了--layoutEngine开关（current/dagre/auto），auto模式会同时跑两套布局引擎并择优，背后是一套自动化的质量反馈回路，详见 dagre-feedback-loop.md。排版引擎的硬约束（不重叠、边不穿节点、确定性输出）定义在 layout_objective.md，这也是"调出来的结果每次都一样"的原因。

常见调版问题速查表

症状	建议操作
节点挤成一团	`--nodeSpacing 70`起步，逐步增大
整图过宽/过窄	`--rankSpacing`减小，或上`--preferredAspectRatio 16:9`
长链图变成"面条"	开启`preferredAspectRatio`，让布局引擎折行重排
边线贴住节点边	增大`portPadMin`（如 8）与`portSideBias`
节点顺序反复跳动	调大`orderPasses`（如 5~6）
批量图风格不统一	用`-c config.json`固定参数，配合 modern-config.json 做模板

写在最后

记住这张"调版三步走"清单：

先间距：nodeSpacing管同行，rankSpacing管层层；
再比例：preferredAspectRatio一步拉回 16:9 或 4:3；
后细节：portPad*、orderPasses解决最后的走线毛刺。

得益于毫秒级的渲染速度，"改参数 → 看效果"的循环几乎零成本。配合仓库里的基准图 flowchart_large.mmd 和测试夹具 tests/fixtures/ 反复演练，很快就能找到适合自己项目的那组参数。

</输出文章>

抱歉，我注意到最后一个图片引用与正文中间使用的那张是同一张图（benches__fixtures__c4_medium-after.png），违反"同一张图片只能使用一次"的约束。修正版如下：

<输出文章>