Line9 是一个自带布局算法的 Mermaid 渲染引擎它的核心定位直接写在项目标题里a Mermaid rendering engine with its own layout。用 Mermaid 画流程图的开发者很多但大多数只熟悉 mermaid 代码怎么写对文本到 SVG 之间发生了什么并不清楚。这篇文章围绕 Line9 的技术主线展开Mermaid 渲染链路是什么、布局层解决什么问题、自研布局引擎需要哪些模块、输出结果怎么验证以及节点重叠、连线穿越这类问题如何排查。理解这条链路之后你不仅能看懂 Line9 这类项目的价值也能在自己的项目中判断到底应该继续依赖通用布局库还是自己实现一版可控的布局算法。1. 先理解 Mermaid 渲染链路文本到 SVG 之间发生了什么1.1 Mermaid 文本为什么不能直接渲染成 SVGMermaid 的输入是一段类似流程描述的文字比如A - B这样的关系表达。很多人的直觉是这段文字应该能直接套模板生成 SVG。实际上不行原因在于文本描述的是图的逻辑结构而 SVG 描述的是图形的几何结果。从逻辑结构到几何结果中间缺了很大一段计算工作。具体来说一段 Mermaid 文本进入渲染器之后至少需要经过这几步mermaid 文本 - 词法分析、语法分析 - 图结构节点列表、边列表、子图信息 - 节点尺寸测量根据文字内容和样式计算宽度与高度 - 布局计算分配层级、排序、计算节点坐标 - 边线路由把边画成直线、折线或正交线并绕过节点 - SVG 元素生成 - 页面渲染其中最关键的一点是节点坐标不是文本里写出来的而是渲染器算出来的。文本里只写了“A 指向 B”但没写 A 画在页面左上角还是右下角没写 A 和 B 之间间隔多少像素也没写这条边是全直线还是带折点。所有这些几何信息都需要布局引擎在拿到图结构之后计算。1.2 布局引擎在整个链路中的位置布局引擎可以理解成一个纯函数输入是节点和边输出是每个节点的坐标以及每条边的路径点。它是整个渲染链路里最核心、也最容易被替换的一层。如果你的渲染器把布局层设计成独立模块那么换一种布局算法只需要替换一个函数不需要改动解析和 SVG 生成。从接口角度看布局层的输入输出大致是interface LayoutInput { nodes: Array{ id: string; width: number; height: number; }; edges: Array{ id: string; source: string; target: string; label?: string; }; rankdir: TB | LR | BT | RL; } interface LayoutOutput { nodePositions: Recordstring, { x: number; y: number }; edgeRoutes: Array{ id: string; points: Array{ x: number; y: number }; }; }这个接口设计的价值在于解耦。解析层负责把文本变成LayoutInput布局层负责把LayoutInput变成LayoutOutput渲染层再根据LayoutOutput生成 SVG。每一层都可以单独测试单独替换。常见的 Mermaid 流程图渲染在过去依赖 dagre 这类通用布局库而像 Line9 这样“自带 layout”的渲染引擎就是把这一层换成自己的实现。1.3 “自带 layout”和默认布局有什么区别默认布局和自研布局的差别表面上是依赖替换实际上是控制权的转移。使用 dagre 或 elk 这类通用布局库时你得到的是经过大量场景验证的算法但代价是布局行为被库的抽象封住想调整某个细节往往需要翻源码甚至要改库的源码。自研布局则把控制权完全拿回来你可以针对自己的图类型实现最合适的算法也可以严格约定输出结果必须稳定。对比维度默认依赖布局dagre/elk自研 layout依赖体积引入完整通用算法库只保留自己需要的算法行为可控性通过参数和配置调整可以直接修改坐标分配逻辑输出确定性依赖库内部排序策略可以严格按节点 id 排序保证稳定特殊需求扩展成本高可按业务定制边界情况维护上游负责修复需要自己处理环、自环、多边等场景需要注意的是自研布局并不天然比默认布局好。dagre 这类库经过多年沉淀对各种边界情况有成熟处理自研布局在获得灵活性的同时必须把所有边界情况接住否则项目越大坑越多。2. 为什么流程图布局是渲染引擎中最难的部分2.1 一个好的布局要同时满足四个目标布局之所以难是因为它同时承担了四个目标而且这些目标之间经常互相冲突。第一个目标是可读性。流程图最重要的价值是让人一眼看懂依赖关系所以边的交叉越少越好。交叉过多时读者很难追踪一条边从哪来、到哪去。第二个目标是连通性边不能穿过节点也不能贴着节点边缘造成歧义。第三个目标是空间效率不能为了避开交叉而把整张图拉得特别松散白白浪费画布。第四个目标是确定性相同输入应该产生相同输出否则做快照测试、对比回归都无从谈起。这四个目标经常无法同时满足。比如减少边的交叉可能需要调整节点顺序而调整顺序后空间利用率可能变差。所以布局算法本质上是一套启发式策略它不追求数学上的最优解而是追求在常见输入下表现稳定、结果可接受。自研布局引擎时必须承认这一点不能幻想写一个算法就能在所有图上完美。2.2 常见布局算法层级布局、力导向布局、正交布线流程图布局场景里最常用的是层级布局也叫 Sugiyama 风格布局。它把图画成若干层然后做四件事先处理环把环中的某些边临时反转成反馈边再分层让每条有向边尽量从高层指向低层然后对每一层内的节点排序目的是减少边交叉最后分配坐标确定每个节点的 x 和 y。力导向布局则是模拟物理系统把节点当成质点边当成弹簧通过迭代让系统趋于稳定。它适合无向图、网络关系图生成的布局往往表现出自然的簇结构但对流程图这种强调方向和层级关系的图力导向布局的方向感偏弱结果也不一定稳定。正交布线不是完整的布局算法而是边路由策略。它把边画成水平和垂直交替的折线风格接近电路图和电路板走线。对于强调整齐感的图正交布线比直线更专业但算法复杂度更高折点也更难优化。算法类型基本思想适合场景主要缺点层级布局Sugiyama分层、排序、减交叉流程图、依赖图环处理复杂细节调优繁琐力导向布局模拟质点与弹簧网络图、无向图方向感弱结果不稳定正交布线水平垂直折线电路图、结构图折点计算复杂2.3 自研布局的收益与风险自研布局最直接的收益是去掉通用依赖减少打包体积同时让布局行为完全可控。如果业务里只有一种图例如树形流程图那么针对树实现一版简单布局可能比引入 dagre 更轻、更快、更稳定。风险同样明显。第一环处理非常容易出错A - B和B - A同时存在时分层算法需要先识别反馈边否则分层结果会乱。第二交叉最小化本身是启发式算法自研版本在复杂图上的表现可能不如成熟库。第三边界情况极多自环、多边、孤立节点、子图嵌套、节点宽度差异巨大这些都需要逐一处理。第四性能优化要靠自己dagre 在大图上做过大量优化自研算法很容易在百节点级别出现明显卡顿。所以自研布局的合理策略不是“完全从零写”而是先实现一个能覆盖核心场景的最简布局再用测试用例把边界情况逐步补上。这也是建议所有学习这类项目的人采用的方式。3. 自研布局渲染引擎的核心模块设计3.1 解析层把文本变成图结构自研渲染引擎的第一步是把 Mermaid 文本解析成结构化的图数据。Mermaid 语法本身包含节点定义、节点样式、边、子图、方向和注释等元素解析层至少要能提取节点 id、节点标签、边关系和方向。解析后的结构可以设计成下面这样的 JSON方便后续布局层消费{ nodes: [ { id: A, label: A, width: 40, height: 30 }, { id: B, label: B, width: 40, height: 30 }, { id: C, label: C, width: 40, height: 30 }, { id: D, label: D, width: 40, height: 30 } ], edges: [ { from: A, to: B, label: }, { from: A, to: C, label: }, { from: B, to: D, label: }, { from: C, to: D, label: } ], rankdir: TB }这里需要注意的是节点尺寸。文本解析出来时节点只有 label没有宽高。宽高需要根据字体大小、padding、是否带图标等样式信息测量得到。测量时机应该在布局之前否则布局算法拿不到节点占用面积。常见做法是先把节点渲染到隐藏的测量容器里读取尺寸再进入布局计算。3.2 布局层计算每个节点的坐标布局层负责把图结构变成坐标。下面用一个最简层级布局来说明思路它包含三步分层、层内排序、坐标分配。第一步是分层。最常用的策略是“最长路径分层”源节点在第 0 层每经过一条边目标节点至少往后推一层。使用拓扑序遍历可以实现function assignLayers(nodes: L9Node[], edges: L9Edge[]): Mapstring, number { const inDegree new Mapstring, number(); const layer new Mapstring, number(); nodes.forEach((node) { inDegree.set(node.id, 0); layer.set(node.id, 0); }); edges.forEach((edge) { inDegree.set(edge.to, (inDegree.get(edge.to) || 0) 1); }); const queue nodes .filter((node) (inDegree.get(node.id) || 0) 0) .map((node) node.id); while (queue.length 0) { const current queue.shift()!; const base layer.get(current) || 0; edges .filter((edge) edge.from current) .forEach((edge) { layer.set(edge.to, Math.max(layer.get(edge.to) || 0, base 1)); inDegree.set(edge.to, (inDegree.get(edge.to) || 0) - 1); if (inDegree.get(edge.to) 0) { queue.push(edge.to); } }); } return layer; }这段代码的关键点是只有当节点的所有前驱都处理完节点才能进入队列。这样可以保证A - D和B - D同时存在时D 的层级一定取所有前驱中最大的那个加一。第二步是层内排序目的是减少边交叉。最简单的实现是计算每个节点在其层中的“重心值”即所有邻居图层位置的平均值然后按重心值排序。这个步骤在真正生产环境中会迭代多轮这里先不展开。第三步是坐标分配。每一层节点的 y 坐标由层号决定x 坐标则根据节点宽度和间距依次累加function assignCoordinates( graph: L9Graph, layers: Mapstring, number, opts: { rankSep: number; nodeSep: number } ): Mapstring, { x: number; y: number } { const positions new Mapstring, { x: number; y: number }(); const groupByLayer new Mapnumber, L9Node[](); graph.nodes.forEach((node) { const layer layers.get(node.id) || 0; if (!groupByLayer.has(layer)) { groupByLayer.set(layer, []); } groupByLayer.get(layer)!.push(node); }); const sortedLayers [...groupByLayer.keys()].sort((a, b) a - b); sortedLayers.forEach((layerIndex, index) { const nodesInLayer groupByLayer.get(layerIndex)!; let cursorX 0; nodesInLayer.forEach((node) { positions.set(node.id, { x: cursorX node.width / 2, y: index * opts.rankSep, }); cursorX node.width opts.nodeSep; }); }); return positions; }这里把节点中心点作为坐标存储是因为 SVG 里定位节点通常用transform或x/y属性渲染层可以很方便地从中心点推出左上角。3.3 渲染层把坐标变成 SVG布局层输出坐标后渲染层要做的事情相对机械把节点变成rect加text把边变成path再加上箭头和主题样式。一个最小渲染函数可以这样写function renderSvg( graph: L9Graph, positions: Mapstring, { x: number; y: number } ): string { const parts: string[] []; graph.edges.forEach((edge) { const from positions.get(edge.from)!; const to positions.get(edge.to)!; parts.push( path dM ${from.x} ${from.y} L ${to.x} ${to.y} stroke#999 fillnone / ); }); graph.nodes.forEach((node) { const p positions.get(node.id)!; const left p.x - node.width / 2; const top p.y - node.height / 2; parts.push( g transformtranslate(${left}, ${top}) rect width${node.width} height${node.height} rx4 fill#fff stroke#333 / text x${node.width / 2} y${node.height / 2} text-anchormiddle dominant-baselinecentral${node.label}/text /g ); }); return svg xmlnshttp://www.w3.org/2000/svg${parts.join()}/svg; }真实渲染层比这个复杂的地方在于箭头 marker、边的 label、节点圆角与边框样式、颜色主题、异常样式以及可访问性属性。但核心机制是一样的渲染层只消费坐标不参与任何布局计算。这个分离对排查问题很有帮助图乱了先判断是坐标问题还是 SVG 生成问题。3.4 一个最小可运行示例把上面三层串起来就是一个最小可运行的渲染引擎入口function renderFromText(text: string): string { const graph parseGraph(text); const layers assignLayers(graph); const ordered reduceCrossings(graph, layers); const positions assignCoordinates(graph, ordered, { rankSep: 80, nodeSep: 30, }); return renderSvg(graph, positions); }这个函数需要你为parseGraph、reduceCrossings补齐实现。parseGraph负责把 Mermaid 文本变成L9GraphreduceCrossings是层内排序的启发式优化。整个链路的顺序是固定的先解析再布局最后渲染。每一步只要输出结构符合预期就可以独立调试。如果你打算兼容 Mermaid 生态另一条路是把 Mermaid 的解析结果转成自己的L9Graph相当于复用 Mermaid 的语法解析能力只替换布局和渲染。这样做工作量更小也是很多自研渲染器的实际选择。4. 运行验证如何确认布局结果正确4.1 用最小流程图验证节点坐标验证布局引擎最简单的办法是用一个可预期的小图先手算出期望坐标再对比引擎输出。下面这个输入是最典型的测试用例A - B A - C B - D C - D这是一个标准 DAG没有环没有自环。分层结果应该是A 在第 0 层B、C 在第 1 层D 在第 2 层坐标分配之后可以打印成表格人工核对节点层级XYA0按节点宽度和层内排序计算0B1层内按重心排序后计算80C1层内按重心排序后计算80D2按节点宽度和层内排序计算160这里的 Y 值由rankSep决定X 值由节点宽度和nodeSep决定。开发阶段可以把positions用console.table打印出来或者直接输出成 JSON 在测试中断言。注意验证时不能只看图“长什么样”还要核对具体坐标是否符合算法定义否则算法被悄悄改坏时很难发现。4.2 检查边是否交叉、节点是否重叠布局结果正确性检查除了坐标符合预期还要做几何层面的自检。三个基础检查分别是节点重叠、边交叉、边穿过节点。节点重叠检查最直接对任意两个节点判断两个矩形是否相交。一个简单的矩形相交判断函数如下function rectsOverlap( a: { x: number; y: number; width: number; height: number }, b: { x: number; y: number; width: number; height: number } ): boolean { return ( a.x b.x b.width a.x a.width b.x a.y b.y b.height a.y a.height b.y ); }边交叉检查需要两两比较线段是否相交。边穿过节点检查需要计算每条边与每个节点矩形的关系。这些检查放在单元测试里非常合适因为布局算法改一次这些断言能立刻暴露几何回归。对于本文的最小示例期望结果是任意两个节点矩形都不相交四条边的交点数为 0没有边穿过节点矩形。如果这三个条件不满足说明布局层或排序层有问题。4.3 与默认渲染器输出做对比自研布局引擎还有一个重要的验证手段拿同一份 Mermaid 文本在 mermaid live editor 或 VSCode 的 mermaid preview 插件里渲染一份然后与自己的渲染结果对比。对比时遵循这个顺序先比节点数量和边数量是否一致不一致说明解析层丢了元素。再比节点之间的连接关系是否一致不一致说明建图逻辑有误。然后比方向和层级是否一致例如源节点是否被画在上方或左侧。最后才比较间距、折线、箭头等视觉细节。只要前两步一致布局差异就是算法选择问题而不是功能 bug。如果你想验证解析层对常见语法的覆盖度可以找一些 drawio 转换出的 Mermaid 文本作为输入样本这些文件往往包含更复杂的节点样式和连线方式比手写的简单案例更能暴露解析器缺陷。5. 常见问题与排查路径5.1 节点重叠在一起现象同一层里多个节点叠在一起或者不同层节点因为坐标分配不合理产生交叉。常见原因有三个。第一坐标分配时没有按节点实际宽度累加而是简单用index * (width nodeSep)导致宽度不一的节点错位。第二nodeSep设置过小或者干脆没有设置间距。第三分层算法在遇到环时退化成大量节点处于同一层这一层的节点数量爆炸间距被压缩到 0。排查方式先打印每个节点的layer值和坐标确认分层结果是否符合预期再检查同一层内节点 x 区间是否连续且不重叠。处理建议坐标分配时严格使用“当前 x 游标 节点宽度 nodeSep”的方式累加而不是用索引乘固定宽度。如果层内节点过多导致空间不足考虑调大画布宽度或调小节点字号而不是压缩间距。5.2 连线穿过节点现象一条边从某个节点上方或者中间直接穿过没有绕开节点。常见原因是渲染层直接用两个节点中心点连直线没有做边路由。这在边跨多层时尤其明显因为跨层边通常需要经过中间节点的空隙直线很容易与矩形相交。排查方式在浏览器里把 SVG 的path和节点rect叠加检查或者写一个几何检测函数统计“边与节点相交”的数量。如果相交数量为 0则问题不在路由如果大于 0说明渲染层缺少绕障逻辑。处理建议先给边加上“两端点锚点”让边从节点边框边缘出发而不是从中心点出发然后对跨层边做正交折线路由中间折点放在两层之间的空隙区域。自研渲染器在最早期可以直接要求入口文本都写“相邻层边”规避复杂的跨层路由后续再逐步补齐。5.3 同一张图每次渲染结果不同现象连续渲染两次同一份文本两张图坐标不一样导致用户截图、对比、测试结果不稳定。常见原因是布局算法里使用了不稳定的遍历顺序。JavaScript 对象的字符串键有遍历顺序规则但数字键会被提前排序Map 的遍历顺序是插入顺序如果代码不小心依赖了这些顺序或者排序过程使用了随机数做 tie-break输出就会抖动。排查方式连续渲染 10 次把坐标序列做 diff找到第一次出现差异的位置。检查该位置是否在排序环节或者是否依赖某个未固定顺序的集合。处理建议在进入排序算法前先把每一层内部的节点按 id 排序保证初始顺序稳定。不要在 tie-break 时使用Math.random()改用 id 或 label 的字典序。最后在 CI 里加一个快照测试渲染固定输入并断言坐标完全一致。5.4 大图渲染卡顿现象节点数量达到上百个时布局计算耗时明显上升页面渲染卡顿。常见原因是交叉最小化算法复杂度过高需要对大量边做两两比较另一种原因是布局结果生成了大量 SVG 节点浏览器布局和绘制压力过大。排查方式使用浏览器 Performance 面板记录耗时分别统计解析、布局、渲染三个阶段的时间。如果布局阶段占比最高问题在算法如果渲染阶段占比最高问题在 SVG 元素数量或样式复杂度。处理建议给布局计算设置节点数量上限超过上限时回退到简化算法把布局计算放到 Web Worker 里避免阻塞主线程对于特别大的图考虑分层渲染或虚拟滚动只渲染可视区域内的节点。这些优化需要在业务真正遇到大图场景后再投入否则容易陷入过度设计。问题现象常见原因检查方式处理建议节点重叠坐标未按实际宽度累加或 nodeSep 过小打印 position比较同层节点 x 区间按实际宽度累加调大 nodeSep连线穿过节点边画直线且没有绕障路由检测 path 与 rect 相交数量增加锚点计算和正交折线路由多次渲染结果不同遍历顺序不稳定或排序使用随机数连续渲染并 diff 坐标序列按 id 固定初始顺序去掉随机 tie-break大图渲染卡顿交叉最小化复杂度过高SVG 元素过多Performance 面板分段计时限制规模Web Worker 计算可视区域渲染6. 最佳实践与扩展方向6.1 学习环境如何快速跑通如果是学习目的建议不要一上来就啃完整 Mermaid 语法而是搭建一个最小复现环境跑通本文介绍的四层链路解析、分层、排序、渲染。具体步骤可以这样安排先准备一组固定输入从线性链开始比如A - B - C - D。再加入分支比如A - B、A - C观察分层是否正确。再加入环比如A - B、B - A观察环处理逻辑是否兜住。最后加入孤立节点确认没有前后继的节点也能正常分配到某一层。每一步都用坐标断言来验证。如果解析出来的图结构正确坐标符合预期渲染出的 SVG 能在浏览器打开核心链路就算跑通了。对照工具可以选择 mermaid live editor 或 VSCode 里的 mermaid preview 插件它们能帮你快速确认输入文本本身是否合法避免把语法问题误判成布局问题。6.2 生产环境还需要补哪些能力从学习项目到生产可用中间还隔着不少工程化工作。最基本的几项包括配置外置化。层级间距、同一层节点间距、布局方向、主题颜色都不应该写死在代码里而应该通过配置对象传入。这样不同业务场景可以复用同一套渲染引擎。错误处理。解析失败时要有清晰的错误提示标明是哪一段文本、哪个位置出了问题避免用户看到空白画布。布局失败时要有降级方案比如回退到默认布局渲染器至少保证图能显示出来。日志和监控。生产环境需要记录布局耗时、渲染失败率、图体量分布这些指标。布局算法改动后这些数据能快速反映是否出现性能回归。快照回归测试。固定一批覆盖正常、环、孤立节点、多边、大图的输入样本每次改动后跑一遍坐标快照断言。这个测试比人工看图可靠得多。可访问性。生成的 SVG 需要补充 title 和必要的语义文本让屏幕阅读器能读出节点内容而不是只看到一堆图形。6.3 可复用的布局引擎检查清单下面这份清单可以直接用于自研渲染引擎的发布前检查也可以作为评审别人布局引擎时的提问列表[ ] 图结构解析是否支持环、自环、多边、孤立节点[ ] 布局算法遇到非 DAG 输入时是否有稳定的环处理策略[ ] 同一输入多次渲染坐标是否完全一致[ ] 节点间距和层级间距是否通过参数控制而不是硬编码[ ] 边的路径是否经过节点矩形是否做了绕障[ ] 箭头方向是否随布局方向TB、LR、BT、RL正确变化[ ] 节点 label 较长时节点宽高是否正确测量[ ] 大图是否有节点数量上限和性能降级策略[ ] 输出 SVG 是否包含节点语义信息是否支持可访问性[ ] 是否有固定输入样本的坐标快照测试自研布局引擎是一个很好的学习项目因为它把解析、算法、几何、渲染四类问题压缩在一个小范围内。Line9 给出的方向是与其依赖通用布局库不如针对自己的图类型实现可控的算法。对想深入学习 Mermaid 源码或图形算法的开发者建议从最小 DAG 布局开始先跑通分层、排序、定坐标、出 SVG 四条链路再加入环处理、正交路由和子图支持。真正进入生产前至少把确定性、节点重叠、连线穿越这三个问题用自动化测试固定下来否则后续每一次算法调整都可能引入隐藏回归。
深入Mermaid渲染引擎：从文本到SVG的布局算法解析
Line9 是一个自带布局算法的 Mermaid 渲染引擎它的核心定位直接写在项目标题里a Mermaid rendering engine with its own layout。用 Mermaid 画流程图的开发者很多但大多数只熟悉 mermaid 代码怎么写对文本到 SVG 之间发生了什么并不清楚。这篇文章围绕 Line9 的技术主线展开Mermaid 渲染链路是什么、布局层解决什么问题、自研布局引擎需要哪些模块、输出结果怎么验证以及节点重叠、连线穿越这类问题如何排查。理解这条链路之后你不仅能看懂 Line9 这类项目的价值也能在自己的项目中判断到底应该继续依赖通用布局库还是自己实现一版可控的布局算法。1. 先理解 Mermaid 渲染链路文本到 SVG 之间发生了什么1.1 Mermaid 文本为什么不能直接渲染成 SVGMermaid 的输入是一段类似流程描述的文字比如A - B这样的关系表达。很多人的直觉是这段文字应该能直接套模板生成 SVG。实际上不行原因在于文本描述的是图的逻辑结构而 SVG 描述的是图形的几何结果。从逻辑结构到几何结果中间缺了很大一段计算工作。具体来说一段 Mermaid 文本进入渲染器之后至少需要经过这几步mermaid 文本 - 词法分析、语法分析 - 图结构节点列表、边列表、子图信息 - 节点尺寸测量根据文字内容和样式计算宽度与高度 - 布局计算分配层级、排序、计算节点坐标 - 边线路由把边画成直线、折线或正交线并绕过节点 - SVG 元素生成 - 页面渲染其中最关键的一点是节点坐标不是文本里写出来的而是渲染器算出来的。文本里只写了“A 指向 B”但没写 A 画在页面左上角还是右下角没写 A 和 B 之间间隔多少像素也没写这条边是全直线还是带折点。所有这些几何信息都需要布局引擎在拿到图结构之后计算。1.2 布局引擎在整个链路中的位置布局引擎可以理解成一个纯函数输入是节点和边输出是每个节点的坐标以及每条边的路径点。它是整个渲染链路里最核心、也最容易被替换的一层。如果你的渲染器把布局层设计成独立模块那么换一种布局算法只需要替换一个函数不需要改动解析和 SVG 生成。从接口角度看布局层的输入输出大致是interface LayoutInput { nodes: Array{ id: string; width: number; height: number; }; edges: Array{ id: string; source: string; target: string; label?: string; }; rankdir: TB | LR | BT | RL; } interface LayoutOutput { nodePositions: Recordstring, { x: number; y: number }; edgeRoutes: Array{ id: string; points: Array{ x: number; y: number }; }; }这个接口设计的价值在于解耦。解析层负责把文本变成LayoutInput布局层负责把LayoutInput变成LayoutOutput渲染层再根据LayoutOutput生成 SVG。每一层都可以单独测试单独替换。常见的 Mermaid 流程图渲染在过去依赖 dagre 这类通用布局库而像 Line9 这样“自带 layout”的渲染引擎就是把这一层换成自己的实现。1.3 “自带 layout”和默认布局有什么区别默认布局和自研布局的差别表面上是依赖替换实际上是控制权的转移。使用 dagre 或 elk 这类通用布局库时你得到的是经过大量场景验证的算法但代价是布局行为被库的抽象封住想调整某个细节往往需要翻源码甚至要改库的源码。自研布局则把控制权完全拿回来你可以针对自己的图类型实现最合适的算法也可以严格约定输出结果必须稳定。对比维度默认依赖布局dagre/elk自研 layout依赖体积引入完整通用算法库只保留自己需要的算法行为可控性通过参数和配置调整可以直接修改坐标分配逻辑输出确定性依赖库内部排序策略可以严格按节点 id 排序保证稳定特殊需求扩展成本高可按业务定制边界情况维护上游负责修复需要自己处理环、自环、多边等场景需要注意的是自研布局并不天然比默认布局好。dagre 这类库经过多年沉淀对各种边界情况有成熟处理自研布局在获得灵活性的同时必须把所有边界情况接住否则项目越大坑越多。2. 为什么流程图布局是渲染引擎中最难的部分2.1 一个好的布局要同时满足四个目标布局之所以难是因为它同时承担了四个目标而且这些目标之间经常互相冲突。第一个目标是可读性。流程图最重要的价值是让人一眼看懂依赖关系所以边的交叉越少越好。交叉过多时读者很难追踪一条边从哪来、到哪去。第二个目标是连通性边不能穿过节点也不能贴着节点边缘造成歧义。第三个目标是空间效率不能为了避开交叉而把整张图拉得特别松散白白浪费画布。第四个目标是确定性相同输入应该产生相同输出否则做快照测试、对比回归都无从谈起。这四个目标经常无法同时满足。比如减少边的交叉可能需要调整节点顺序而调整顺序后空间利用率可能变差。所以布局算法本质上是一套启发式策略它不追求数学上的最优解而是追求在常见输入下表现稳定、结果可接受。自研布局引擎时必须承认这一点不能幻想写一个算法就能在所有图上完美。2.2 常见布局算法层级布局、力导向布局、正交布线流程图布局场景里最常用的是层级布局也叫 Sugiyama 风格布局。它把图画成若干层然后做四件事先处理环把环中的某些边临时反转成反馈边再分层让每条有向边尽量从高层指向低层然后对每一层内的节点排序目的是减少边交叉最后分配坐标确定每个节点的 x 和 y。力导向布局则是模拟物理系统把节点当成质点边当成弹簧通过迭代让系统趋于稳定。它适合无向图、网络关系图生成的布局往往表现出自然的簇结构但对流程图这种强调方向和层级关系的图力导向布局的方向感偏弱结果也不一定稳定。正交布线不是完整的布局算法而是边路由策略。它把边画成水平和垂直交替的折线风格接近电路图和电路板走线。对于强调整齐感的图正交布线比直线更专业但算法复杂度更高折点也更难优化。算法类型基本思想适合场景主要缺点层级布局Sugiyama分层、排序、减交叉流程图、依赖图环处理复杂细节调优繁琐力导向布局模拟质点与弹簧网络图、无向图方向感弱结果不稳定正交布线水平垂直折线电路图、结构图折点计算复杂2.3 自研布局的收益与风险自研布局最直接的收益是去掉通用依赖减少打包体积同时让布局行为完全可控。如果业务里只有一种图例如树形流程图那么针对树实现一版简单布局可能比引入 dagre 更轻、更快、更稳定。风险同样明显。第一环处理非常容易出错A - B和B - A同时存在时分层算法需要先识别反馈边否则分层结果会乱。第二交叉最小化本身是启发式算法自研版本在复杂图上的表现可能不如成熟库。第三边界情况极多自环、多边、孤立节点、子图嵌套、节点宽度差异巨大这些都需要逐一处理。第四性能优化要靠自己dagre 在大图上做过大量优化自研算法很容易在百节点级别出现明显卡顿。所以自研布局的合理策略不是“完全从零写”而是先实现一个能覆盖核心场景的最简布局再用测试用例把边界情况逐步补上。这也是建议所有学习这类项目的人采用的方式。3. 自研布局渲染引擎的核心模块设计3.1 解析层把文本变成图结构自研渲染引擎的第一步是把 Mermaid 文本解析成结构化的图数据。Mermaid 语法本身包含节点定义、节点样式、边、子图、方向和注释等元素解析层至少要能提取节点 id、节点标签、边关系和方向。解析后的结构可以设计成下面这样的 JSON方便后续布局层消费{ nodes: [ { id: A, label: A, width: 40, height: 30 }, { id: B, label: B, width: 40, height: 30 }, { id: C, label: C, width: 40, height: 30 }, { id: D, label: D, width: 40, height: 30 } ], edges: [ { from: A, to: B, label: }, { from: A, to: C, label: }, { from: B, to: D, label: }, { from: C, to: D, label: } ], rankdir: TB }这里需要注意的是节点尺寸。文本解析出来时节点只有 label没有宽高。宽高需要根据字体大小、padding、是否带图标等样式信息测量得到。测量时机应该在布局之前否则布局算法拿不到节点占用面积。常见做法是先把节点渲染到隐藏的测量容器里读取尺寸再进入布局计算。3.2 布局层计算每个节点的坐标布局层负责把图结构变成坐标。下面用一个最简层级布局来说明思路它包含三步分层、层内排序、坐标分配。第一步是分层。最常用的策略是“最长路径分层”源节点在第 0 层每经过一条边目标节点至少往后推一层。使用拓扑序遍历可以实现function assignLayers(nodes: L9Node[], edges: L9Edge[]): Mapstring, number { const inDegree new Mapstring, number(); const layer new Mapstring, number(); nodes.forEach((node) { inDegree.set(node.id, 0); layer.set(node.id, 0); }); edges.forEach((edge) { inDegree.set(edge.to, (inDegree.get(edge.to) || 0) 1); }); const queue nodes .filter((node) (inDegree.get(node.id) || 0) 0) .map((node) node.id); while (queue.length 0) { const current queue.shift()!; const base layer.get(current) || 0; edges .filter((edge) edge.from current) .forEach((edge) { layer.set(edge.to, Math.max(layer.get(edge.to) || 0, base 1)); inDegree.set(edge.to, (inDegree.get(edge.to) || 0) - 1); if (inDegree.get(edge.to) 0) { queue.push(edge.to); } }); } return layer; }这段代码的关键点是只有当节点的所有前驱都处理完节点才能进入队列。这样可以保证A - D和B - D同时存在时D 的层级一定取所有前驱中最大的那个加一。第二步是层内排序目的是减少边交叉。最简单的实现是计算每个节点在其层中的“重心值”即所有邻居图层位置的平均值然后按重心值排序。这个步骤在真正生产环境中会迭代多轮这里先不展开。第三步是坐标分配。每一层节点的 y 坐标由层号决定x 坐标则根据节点宽度和间距依次累加function assignCoordinates( graph: L9Graph, layers: Mapstring, number, opts: { rankSep: number; nodeSep: number } ): Mapstring, { x: number; y: number } { const positions new Mapstring, { x: number; y: number }(); const groupByLayer new Mapnumber, L9Node[](); graph.nodes.forEach((node) { const layer layers.get(node.id) || 0; if (!groupByLayer.has(layer)) { groupByLayer.set(layer, []); } groupByLayer.get(layer)!.push(node); }); const sortedLayers [...groupByLayer.keys()].sort((a, b) a - b); sortedLayers.forEach((layerIndex, index) { const nodesInLayer groupByLayer.get(layerIndex)!; let cursorX 0; nodesInLayer.forEach((node) { positions.set(node.id, { x: cursorX node.width / 2, y: index * opts.rankSep, }); cursorX node.width opts.nodeSep; }); }); return positions; }这里把节点中心点作为坐标存储是因为 SVG 里定位节点通常用transform或x/y属性渲染层可以很方便地从中心点推出左上角。3.3 渲染层把坐标变成 SVG布局层输出坐标后渲染层要做的事情相对机械把节点变成rect加text把边变成path再加上箭头和主题样式。一个最小渲染函数可以这样写function renderSvg( graph: L9Graph, positions: Mapstring, { x: number; y: number } ): string { const parts: string[] []; graph.edges.forEach((edge) { const from positions.get(edge.from)!; const to positions.get(edge.to)!; parts.push( path dM ${from.x} ${from.y} L ${to.x} ${to.y} stroke#999 fillnone / ); }); graph.nodes.forEach((node) { const p positions.get(node.id)!; const left p.x - node.width / 2; const top p.y - node.height / 2; parts.push( g transformtranslate(${left}, ${top}) rect width${node.width} height${node.height} rx4 fill#fff stroke#333 / text x${node.width / 2} y${node.height / 2} text-anchormiddle dominant-baselinecentral${node.label}/text /g ); }); return svg xmlnshttp://www.w3.org/2000/svg${parts.join()}/svg; }真实渲染层比这个复杂的地方在于箭头 marker、边的 label、节点圆角与边框样式、颜色主题、异常样式以及可访问性属性。但核心机制是一样的渲染层只消费坐标不参与任何布局计算。这个分离对排查问题很有帮助图乱了先判断是坐标问题还是 SVG 生成问题。3.4 一个最小可运行示例把上面三层串起来就是一个最小可运行的渲染引擎入口function renderFromText(text: string): string { const graph parseGraph(text); const layers assignLayers(graph); const ordered reduceCrossings(graph, layers); const positions assignCoordinates(graph, ordered, { rankSep: 80, nodeSep: 30, }); return renderSvg(graph, positions); }这个函数需要你为parseGraph、reduceCrossings补齐实现。parseGraph负责把 Mermaid 文本变成L9GraphreduceCrossings是层内排序的启发式优化。整个链路的顺序是固定的先解析再布局最后渲染。每一步只要输出结构符合预期就可以独立调试。如果你打算兼容 Mermaid 生态另一条路是把 Mermaid 的解析结果转成自己的L9Graph相当于复用 Mermaid 的语法解析能力只替换布局和渲染。这样做工作量更小也是很多自研渲染器的实际选择。4. 运行验证如何确认布局结果正确4.1 用最小流程图验证节点坐标验证布局引擎最简单的办法是用一个可预期的小图先手算出期望坐标再对比引擎输出。下面这个输入是最典型的测试用例A - B A - C B - D C - D这是一个标准 DAG没有环没有自环。分层结果应该是A 在第 0 层B、C 在第 1 层D 在第 2 层坐标分配之后可以打印成表格人工核对节点层级XYA0按节点宽度和层内排序计算0B1层内按重心排序后计算80C1层内按重心排序后计算80D2按节点宽度和层内排序计算160这里的 Y 值由rankSep决定X 值由节点宽度和nodeSep决定。开发阶段可以把positions用console.table打印出来或者直接输出成 JSON 在测试中断言。注意验证时不能只看图“长什么样”还要核对具体坐标是否符合算法定义否则算法被悄悄改坏时很难发现。4.2 检查边是否交叉、节点是否重叠布局结果正确性检查除了坐标符合预期还要做几何层面的自检。三个基础检查分别是节点重叠、边交叉、边穿过节点。节点重叠检查最直接对任意两个节点判断两个矩形是否相交。一个简单的矩形相交判断函数如下function rectsOverlap( a: { x: number; y: number; width: number; height: number }, b: { x: number; y: number; width: number; height: number } ): boolean { return ( a.x b.x b.width a.x a.width b.x a.y b.y b.height a.y a.height b.y ); }边交叉检查需要两两比较线段是否相交。边穿过节点检查需要计算每条边与每个节点矩形的关系。这些检查放在单元测试里非常合适因为布局算法改一次这些断言能立刻暴露几何回归。对于本文的最小示例期望结果是任意两个节点矩形都不相交四条边的交点数为 0没有边穿过节点矩形。如果这三个条件不满足说明布局层或排序层有问题。4.3 与默认渲染器输出做对比自研布局引擎还有一个重要的验证手段拿同一份 Mermaid 文本在 mermaid live editor 或 VSCode 的 mermaid preview 插件里渲染一份然后与自己的渲染结果对比。对比时遵循这个顺序先比节点数量和边数量是否一致不一致说明解析层丢了元素。再比节点之间的连接关系是否一致不一致说明建图逻辑有误。然后比方向和层级是否一致例如源节点是否被画在上方或左侧。最后才比较间距、折线、箭头等视觉细节。只要前两步一致布局差异就是算法选择问题而不是功能 bug。如果你想验证解析层对常见语法的覆盖度可以找一些 drawio 转换出的 Mermaid 文本作为输入样本这些文件往往包含更复杂的节点样式和连线方式比手写的简单案例更能暴露解析器缺陷。5. 常见问题与排查路径5.1 节点重叠在一起现象同一层里多个节点叠在一起或者不同层节点因为坐标分配不合理产生交叉。常见原因有三个。第一坐标分配时没有按节点实际宽度累加而是简单用index * (width nodeSep)导致宽度不一的节点错位。第二nodeSep设置过小或者干脆没有设置间距。第三分层算法在遇到环时退化成大量节点处于同一层这一层的节点数量爆炸间距被压缩到 0。排查方式先打印每个节点的layer值和坐标确认分层结果是否符合预期再检查同一层内节点 x 区间是否连续且不重叠。处理建议坐标分配时严格使用“当前 x 游标 节点宽度 nodeSep”的方式累加而不是用索引乘固定宽度。如果层内节点过多导致空间不足考虑调大画布宽度或调小节点字号而不是压缩间距。5.2 连线穿过节点现象一条边从某个节点上方或者中间直接穿过没有绕开节点。常见原因是渲染层直接用两个节点中心点连直线没有做边路由。这在边跨多层时尤其明显因为跨层边通常需要经过中间节点的空隙直线很容易与矩形相交。排查方式在浏览器里把 SVG 的path和节点rect叠加检查或者写一个几何检测函数统计“边与节点相交”的数量。如果相交数量为 0则问题不在路由如果大于 0说明渲染层缺少绕障逻辑。处理建议先给边加上“两端点锚点”让边从节点边框边缘出发而不是从中心点出发然后对跨层边做正交折线路由中间折点放在两层之间的空隙区域。自研渲染器在最早期可以直接要求入口文本都写“相邻层边”规避复杂的跨层路由后续再逐步补齐。5.3 同一张图每次渲染结果不同现象连续渲染两次同一份文本两张图坐标不一样导致用户截图、对比、测试结果不稳定。常见原因是布局算法里使用了不稳定的遍历顺序。JavaScript 对象的字符串键有遍历顺序规则但数字键会被提前排序Map 的遍历顺序是插入顺序如果代码不小心依赖了这些顺序或者排序过程使用了随机数做 tie-break输出就会抖动。排查方式连续渲染 10 次把坐标序列做 diff找到第一次出现差异的位置。检查该位置是否在排序环节或者是否依赖某个未固定顺序的集合。处理建议在进入排序算法前先把每一层内部的节点按 id 排序保证初始顺序稳定。不要在 tie-break 时使用Math.random()改用 id 或 label 的字典序。最后在 CI 里加一个快照测试渲染固定输入并断言坐标完全一致。5.4 大图渲染卡顿现象节点数量达到上百个时布局计算耗时明显上升页面渲染卡顿。常见原因是交叉最小化算法复杂度过高需要对大量边做两两比较另一种原因是布局结果生成了大量 SVG 节点浏览器布局和绘制压力过大。排查方式使用浏览器 Performance 面板记录耗时分别统计解析、布局、渲染三个阶段的时间。如果布局阶段占比最高问题在算法如果渲染阶段占比最高问题在 SVG 元素数量或样式复杂度。处理建议给布局计算设置节点数量上限超过上限时回退到简化算法把布局计算放到 Web Worker 里避免阻塞主线程对于特别大的图考虑分层渲染或虚拟滚动只渲染可视区域内的节点。这些优化需要在业务真正遇到大图场景后再投入否则容易陷入过度设计。问题现象常见原因检查方式处理建议节点重叠坐标未按实际宽度累加或 nodeSep 过小打印 position比较同层节点 x 区间按实际宽度累加调大 nodeSep连线穿过节点边画直线且没有绕障路由检测 path 与 rect 相交数量增加锚点计算和正交折线路由多次渲染结果不同遍历顺序不稳定或排序使用随机数连续渲染并 diff 坐标序列按 id 固定初始顺序去掉随机 tie-break大图渲染卡顿交叉最小化复杂度过高SVG 元素过多Performance 面板分段计时限制规模Web Worker 计算可视区域渲染6. 最佳实践与扩展方向6.1 学习环境如何快速跑通如果是学习目的建议不要一上来就啃完整 Mermaid 语法而是搭建一个最小复现环境跑通本文介绍的四层链路解析、分层、排序、渲染。具体步骤可以这样安排先准备一组固定输入从线性链开始比如A - B - C - D。再加入分支比如A - B、A - C观察分层是否正确。再加入环比如A - B、B - A观察环处理逻辑是否兜住。最后加入孤立节点确认没有前后继的节点也能正常分配到某一层。每一步都用坐标断言来验证。如果解析出来的图结构正确坐标符合预期渲染出的 SVG 能在浏览器打开核心链路就算跑通了。对照工具可以选择 mermaid live editor 或 VSCode 里的 mermaid preview 插件它们能帮你快速确认输入文本本身是否合法避免把语法问题误判成布局问题。6.2 生产环境还需要补哪些能力从学习项目到生产可用中间还隔着不少工程化工作。最基本的几项包括配置外置化。层级间距、同一层节点间距、布局方向、主题颜色都不应该写死在代码里而应该通过配置对象传入。这样不同业务场景可以复用同一套渲染引擎。错误处理。解析失败时要有清晰的错误提示标明是哪一段文本、哪个位置出了问题避免用户看到空白画布。布局失败时要有降级方案比如回退到默认布局渲染器至少保证图能显示出来。日志和监控。生产环境需要记录布局耗时、渲染失败率、图体量分布这些指标。布局算法改动后这些数据能快速反映是否出现性能回归。快照回归测试。固定一批覆盖正常、环、孤立节点、多边、大图的输入样本每次改动后跑一遍坐标快照断言。这个测试比人工看图可靠得多。可访问性。生成的 SVG 需要补充 title 和必要的语义文本让屏幕阅读器能读出节点内容而不是只看到一堆图形。6.3 可复用的布局引擎检查清单下面这份清单可以直接用于自研渲染引擎的发布前检查也可以作为评审别人布局引擎时的提问列表[ ] 图结构解析是否支持环、自环、多边、孤立节点[ ] 布局算法遇到非 DAG 输入时是否有稳定的环处理策略[ ] 同一输入多次渲染坐标是否完全一致[ ] 节点间距和层级间距是否通过参数控制而不是硬编码[ ] 边的路径是否经过节点矩形是否做了绕障[ ] 箭头方向是否随布局方向TB、LR、BT、RL正确变化[ ] 节点 label 较长时节点宽高是否正确测量[ ] 大图是否有节点数量上限和性能降级策略[ ] 输出 SVG 是否包含节点语义信息是否支持可访问性[ ] 是否有固定输入样本的坐标快照测试自研布局引擎是一个很好的学习项目因为它把解析、算法、几何、渲染四类问题压缩在一个小范围内。Line9 给出的方向是与其依赖通用布局库不如针对自己的图类型实现可控的算法。对想深入学习 Mermaid 源码或图形算法的开发者建议从最小 DAG 布局开始先跑通分层、排序、定坐标、出 SVG 四条链路再加入环处理、正交路由和子图支持。真正进入生产前至少把确定性、节点重叠、连线穿越这三个问题用自动化测试固定下来否则后续每一次算法调整都可能引入隐藏回归。