最近项目里要做一批网络拓扑图和设备关系图我选了 AntV 的 G6 作为主力渲染引擎。这个选择背后其实折腾了不少轮子从 D3 到 Echarts 再到 vis.js 都试过最后才在 G6 上定下来。这篇文章就把我在实际开发里摸出来的经验完整写出来包括为什么选它、G6 的核心概念怎么理解、一个网络拓扑图具体怎么写出来以及踩过的坑和排查思路。写这篇东西的初衷很实在G6 官方文档虽然全但信息密度太高新手照着文档写经常会卡在“文档里都有但不知道先看哪个”的状态。我尽量用做业务的思路来讲而不是按 API 顺序罗列。适合正在做或者准备做前端拓扑图、关系图、流程图、ER 图、组织结构图这类场景的开发者包括被领导突然丢一个“把这个设备拓扑画出来”需求的同学。1. 先搞清楚G6 到底解决什么问题1.1 为什么是 G6而不是 D3 / Echarts / vis.js先说结论图可视化场景里G6 是“开箱自带关系分析思维”的库D3 是“什么都能画但都得自己搭”Echarts 是“统计图表很强但图布局和交互偏弱”vis.js 则是“轻量快速但复杂场景自定义吃力”。我拿四个维度对比过对比项G6D3Echartsvis.js内置关系图布局非常多force/dagre/circular/radial/er 等需要配合 d3-force 自己实现只有力导向图可用有但可选不多自定义节点/边图形系统灵活支持注册自定义节点灵活但代码量大有限主要靠 series 配置样式可调但深度自定义费劲交互体系内置拖拽画布、缩放、框选、拖节点全部手写有图例和部分交互复杂交互吃力基础交互齐全性能策略大数据量有 compact、L3 渲染等优化手动控制 diff中等数据量还行大了也会卡中等数据量尚可我当时的场景是要在监控大屏上呈现几十台设备、上百条链路节点要有状态色、链路要能显示带宽和告警还要支持缩放拖拽、点击设备弹出详情。用 Echarts 的 force 布局画了两版节点一多就乱成蜘蛛网关键链路高亮这种需求也要绕很多弯。换到 G6 之后最明显的感觉是它把“图分析”这个层面的事替你考虑好了而不是让你从零去拼凑。1.2 “图”和“图表”是两回事很多前端接触过 Echarts潜意识里会把拓扑图当成一种“图表的变体”这是最大的认知偏差。Echarts 里你给的是 x/y 轴数据或者是一组关系对它自动帮你排布。而 G6 这种图可视化引擎面对的是真正意义上的“图数据结构”节点和边是平级的核心对象布局算法负责决定节点坐标你还可以手动指定坐标。理解这一点之后很多问题就豁然开朗了。比如为什么 G6 的 data 里一定要有 nodes 和 edges 两个数组为什么布局参数会影响节点之间的相对位置为什么想让人工拖完的位置固定下来要额外处理。本质上是因为它在做图布局和图形渲染两层事情而不只是“把 SVG/Canvas 画出来”。1.3 用 G6 能覆盖哪些关系图场景G6 能做的事比“拓扑图”这三个字宽得多。以我自己接触过的场景为例网络拓扑图机房设备、链路、子网关系这是最典型的场景微前端应用依赖关系图子应用之间互相引用、共享依赖画出来非常直观ER 图把 MySQL 的表结构导出成关系图在做数据血缘、数据中台可视化时很常用知识图谱/思维导图只要数据结构是节点 关系G6 基本都能承载树形结构组织架构、权限树、菜单树用 TreeGraph 或者 dagre 布局都能处理所以不要因为它叫“拓扑图引擎”就觉得自己用不上凡是表达“谁和谁怎么样”这种关系的都可以考虑用 G6。2. 动手前的概念准备G6 的核心四件套2.1 数据模型nodes 和 edges 是全部基础G6 的数据结构简单到有点朴实const data { nodes: [ { id: node-1, label: 核心路由器 }, { id: node-2, label: 接入交换机 } ], edges: [ { source: node-1, target: node-2, label: GE链路 } ] };nodes 里每个节点必须有唯一 idedges 里 source 和 target 分别指向节点的 id。就这么简单。所有复杂功能——自定义样式、交互事件、状态切换——都是在这个基础数据上做扩展。这里有个容易忽略的点G6 的节点坐标有两种来源方式。一种是不写 x/y交给布局算法算另一种是手动指定 x/y布局算法就不会覆盖在 force 布局里要注意某些场景下 force 会继续推挤。如果你做的是那种需要精确排版的场景比如网络拓扑图里把边界路由器固定在两侧建议手动指定坐标并使用layout: { type: }或者选择不强制重新布局的配置。2.2 布局算法决定“图长什么样”的幕后推手布局是关系图里最影响观感的环节。G6 内置的布局很多我实际用得最多的几个布局类型适合场景实际体验force关系比较杂没有明显层级节点自动聚散适合探索式分析但参数调起来费时间dagre有向无环流程、组织层级自动分层适合工单流转、流程图radial有明确中心点比如核心设备以根节点为中心往外扩散适合展示“以某设备为核心的拓扑”circular环形结构或者想突出环网节点围成一圈好看但关系展示可能比较乱grid节点数量大且关系不是重点规整排列适合展示大量设备资产我当时做网络拓扑图第一版用的 force结果节点总是在不停抖动稳定性差。后来发现很多网络运维类产品用的是自定义布局或者分层布局因为运维人员脑子里对网络拓扑有固定的空间认知。最后我们采用手动计算分组坐标 子图内部用小规模 force 的方式既保留了自动排布的省力又保证了整体逻辑清晰。布局这个东西一定要在动手前想清楚你这个图是给谁看的他想从图里获取什么。如果用户关心的是链路通断那节点摆得整齐比“布局算法看起来很聪明”更重要。2.3 交互模式与事件体系G6 的交互是通过 mode 机制管理的。常用的内置交互有drag-canvas拖动画布zoom-canvas缩放画布drag-node拖动节点click-select点击选中brush-select框选节点tooltip悬浮提示配置方式是在 Graph 初始化时指定 modesmodes: { default: [drag-canvas, zoom-canvas, drag-node, click-select] }事件监听上G6 提供了很细粒度的事件比如node:click、canvas:dblclick、edge:mouseenter、node:dragend等。这些事件名格式很规律元素类型:事件类型。我在做设备详情弹窗时就是监听node:click然后根据事件对象的 item 取到节点 model再发起数据请求。使用模式这里有个坑如果你在初始化之后再调用graph.addBehaviors(tooltip, default)默认 tooltip 的配置是全局的没法针对不同节点定制内容。后来我用的是在 render 之后统一给节点绑定事件再用自定义浮层做 tooltip效果完全可控。3. 实操从零写一个可交互的网络拓扑图3.1 第 1 步准备好拓扑数据以一套简化的企业网络为例设备类型有核心路由器、接入交换机、服务器、防火墙。链路分核心链路和普通链路还有一条链路处于告警状态。const data { nodes: [ { id: router-core, label: 核心路由, type: router }, { id: switch-a, label: 交换机A, type: switch }, { id: switch-b, label: 交换机B, type: switch }, { id: server-a, label: 数据库服务器, type: server }, { id: server-b, label: 应用服务器, type: server }, { id: firewall-1, label: 防火墙, type: firewall } ], edges: [ { source: router-core, target: switch-a, label: GE, status: normal }, { source: router-core, target: switch-b, label: GE, status: normal }, { source: switch-a, target: server-a, label: FE, status: warning }, { source: switch-a, target: server-b, label: FE, status: normal }, { source: switch-a, target: firewall-1, label: FE, status: normal }, { source: router-core, target: firewall-1, label: GE, status: normal } ] };这里节点上挂了 type 字段边上挂了 status 字段这些自定义字段在后面的自定义节点、自定义边和状态样式里都会用到。数据结构在设计阶段就要想清楚否则后面改字段名会牵连很多代码。3.2 第 2 步初始化 Graph 并完成首次渲染import G6 from antv/g6; const container document.getElementById(topo-container); const graph new G6.Graph({ container, width: container.clientWidth, height: container.clientHeight, fitView: true, fitViewPadding: [30, 30, 30, 30], modes: { default: [drag-canvas, zoom-canvas, drag-node, click-select] }, layout: { type: force, preventOverlap: true, linkDistance: 120, nodeStrength: -50, edgeStrength: 0.8 }, defaultNode: { type: rect, size: [80, 40], labelCfg: { style: { fill: #333, fontSize: 12 } } }, defaultEdge: { type: line, labelCfg: { autoRotate: true, style: { fill: #666 } } } }); graph.data(data); graph.render();这段代码跑起来你已经能看到一个能拖拽、能缩放、节点可以移动的拓扑图了。几个注意点fitView: true会在首次渲染时自动缩放画布让所有节点都显示在可视区域内开发阶段强烈建议开否则节点可能画到视野外面让人怀疑代码写错了。container的宽高最好显式设置G6 虽然能从 DOM 上读取但如果容器是动态宽高比如响应式布局你得在 resize 时手动graph.changeSize()。force 布局的参数不是随便填的。linkDistance控制边的目标长度nodeStrength为负值表示节点互相排斥值越小绝对值越大节点散得越开。一般从 120 和 -50 起步再根据实际效果微调。3.3 第 3 步注册自定义节点和边让拓扑图更像“拓扑图”默认的 rect 节点太素了真实网络拓扑图里设备通常有不同的形状和颜色。G6 的registerNode可以让你自定义节点的绘制方式。G6.registerNode(router, { draw(cfg, group) { const keyShape group.addShape(rect, { attrs: { x: -35, y: -20, width: 70, height: 40, radius: 6, fill: #0d47a1, stroke: #0a3d8f, lineWidth: 2 } }); group.addShape(text, { attrs: { text: cfg.label || cfg.id, x: 0, y: 0, textAlign: center, textBaseline: middle, fill: #fff, fontSize: 12 } }); return keyShape; } }, single-node);注册之后数据里 type 为router的节点就会用这个自定义节点渲染。如果你的设备类型很多一定要提炼公共逻辑。我当时是把设备类型映射到一个配置表里配置表包含形状、颜色、图标、尺寸然后写一个通用 draw 函数去执行而不是每种类型单独写一个 registerNode。边的自定义也类似G6.registerEdge(link-line, { draw(cfg, group) { const { startPoint, endPoint, status } cfg; const color status warning ? #fa8c16 : #2f54eb; const keyShape group.addShape(line, { attrs: { x1: startPoint.x, y1: startPoint.y, x2: endPoint.x, y2: endPoint.y, stroke: color, lineWidth: status warning ? 3 : 2 } }); return keyShape; } }, line);注意自定义边的 draw 函数里你能拿到的startPoint和endPoint是经过锚点计算后的实际连接点不是原始数据里的坐标。刚开始写的时候我拿cfg.source和cfg.target去取节点坐标发现边的起点终点会莫名其妙偏到别的地方后来才意识到应该用startPoint/endPoint。3.4 第 4 步加上状态高亮、Tooltip 和点击事件拓扑图最关键的交互是联路状态高亮和节点详情展示。我用setItemState配合 G6 的状态样式机制来做G6.registerNode(router, { // ... draw 函数 getStateStyle(name, value, item) { const style {}; if (name selected value) { style.stroke #ffc53d; style.lineWidth 4; } if (name highlight value) { style.opacity 1; } return style; } }, single-node);这个机制的思路很清晰节点的绘制样式和状态样式分开管理状态切换时 G6 会自动合并样式。比手动去改图形属性要靠谱得多因为手动改完后一刷新或者一移动就可能丢样式。点击事件和高亮联动graph.on(node:click, (ev) { const node ev.item; const model node.getModel(); const connectedEdges node.getEdges(); graph.setItemState(node, selected, true); // 让非相邻节点变透明突出当前设备链路 graph.getNodes().forEach(item { const isConnected connectedEdges.some(edge { const edgeModel edge.getModel(); return edgeModel.source model.id || edgeModel.target model.id; }); graph.setItemState(item, dim, !isConnected item ! node); }); });Tooltip 我建议别用内置的尤其当你要展示的内容很复杂时。内置 tooltip 只能配置文本不能渲染复杂的 HTML 结构。我的做法是监听node:mouseenter和node:mouseleave事件自己生成一个绝对定位的浮层。这样文案、样式、甚至里面放一个迷你表格都可以自己控制。3.5 第 5 步动态更新、定时刷新和导出图片真实业务里拓扑图的数据是动态的。设备状态变了链路告警了都需要更新界面。G6 提供了几种更新方式区别很大// 1. 更新单个节点属性 graph.updateItem(nodeId, { style: { fill: #ff4d4f } }); // 2. 切换整个数据源 graph.changeData(newData); graph.render(); // 3. 只更新布局重排 graph.layout();我当时做监控大屏设备状态每 30 秒刷新一次。一开始图省事用changeData全量替换结果每次刷新节点都会跳一下用户看着很难受。后来改成先用接口返回的数据做 diff然后只updateItem有变化的节点平滑度好了很多。导图这个功能 G6 直接内置了可以用graph.downloadFullImage(拓扑图)导出当前画布也可以graph.toFullDataURL()拿到底图 URL 再传服务器。实测下来在节点较多时导出比截图工具效果更好适合做周报、月报里的拓扑截图。4. 开发中高频踩坑与排查实录4.1 常见问题速查表问题现象可能原因解决方法页面一片空白没看到任何节点container 宽高为 0检查容器 CSS初始化时打印 container.clientWidth数据正常但节点全是默认样式数据里没写 type或 registerNode 注册名不一致核对 type 字段和注册名严格一致自定义节点不更新修改了 draw 函数但浏览器缓存了旧 bundle强制刷新或升级构建版本号布局一直抖动force 布局参数不合理增大 linkDistance降低 edgeStrength边连到了节点中心而不是边缘使用默认锚点连接配置 anchorPoints 或使用自动锚点计算缩放后文字模糊使用了低分辨率图片做节点图标使用矢量图形或 SVG icon大量节点渲染卡顿默认 SVG 渲染性能瓶颈切换 renderer 为 canvas并合理分组4.2 最经典的坑节点数据没渲染出来这个坑我见很多同事踩过。G6 的graph.data()之后必须调用graph.render()而且 render 之前如果改了数据要重新调用graph.data()覆盖否则数据不会更新。写 React 或者 Vue 时如果生命周期没处理好容易在组件还没挂载完成时就实例化 Graph容器宽高为 0导致整个图画不出来。排查方法很简单初始化之后立刻 console.log 一下容器尺寸再在 render 之后 console.log 一下graph.getNodes().length。这两个日志能帮你排除 90% 的“白屏”类问题。4.3 自定义节点的更新问题G6 里自定义节点的缓存机制容易让人困惑。你改完 registerNode 的 draw 实现如果实例还是同一个 graph重新graph.render()未必会生效。因为节点的 keyShape 已经是之前生成的图形实例了draw 函数不会再次执行。解决方式有几个使用graph.refreshItem(item)强制刷新某个节点使用graph.changeData()换一批新数据重新渲染页面级强制重建 graph 实例简单粗暴但要小心事件重复绑定我实际项目里最常用的是重新构建 graph 实例。因为每次自定义节点改动往往伴随着数据结构的调整直接 new 一个新的 Graph 比费劲维护缓存状态要省心。只要把初始化封装成一个函数重建成本并不高。4.4 大数据量下的性能优化思路如果你的拓扑图要渲染上千个节点需要注意渲染器换成 canvas。G6 默认是 SVG节点在几百以内问题不大上千之后明显卡。初始化时配置renderer: canvas会好很多。关闭不必要的动画。animate: true在节点多的时候会让缩放、布局重排卡顿。合理使用collapse-expand和 Combo分组能力。把低层设备折叠进一个分组需要时再展开交互体验和渲染性能都会有很大提升。分帧渲染概念在这里也很重要G6 有相关机制但业务侧最好先做数据裁剪不要一口气把全量数据灌进图里。4.5 和 Vue / React 集成时的注意点G6 本身是框架无关的但和前端框架集成时需要处理生命周期问题。在 React 里我习惯在 useEffect 里初始化和销毁在 Vue 里放在 mounted 和 beforeUnmount。关键点G6 实例一定要在组件卸载时调用graph.destroy()否则会有内存泄漏刷新页面时还会报“container is not a DOM element”之类的错。另外响应式数据更新时不要直接改 props 里的数据然后期望画布自动变化G6 的数据流是单向的你得显式调用 changeData、updateItem 等方法。如果把 G6 封装成组件建议把配置项设计成 props比如data、layoutConfig、modeConfig内部只在数据变化时做 diff 更新。组件化的顶层封装做成后业务方引入拓扑图就和用普通组件一样简单。5. 从网络拓扑图延伸到更多关系图场景5.1 把 MySQL 表结构导出成 ER 关系图前端界面上直接展示数据库表关系在很多后台系统里是刚需。把 information_schema 里的外键关系查出来组装成 nodes 和 edges 数据G6 直接用 er 布局就能画出一张清晰的 ER 图。我试过用 G6 渲染几百张表的 ER 图效果比某些数据库客户端自带的 ER 图还好上不少因为可以定制表节点的样式表名、字段列表、主键用特殊字体颜色标出来。字段列表中文字过多时可以用自定义节点里的group.addShape(text, { ... })逐行绘制。5.2 画类图和微前端依赖图UML 类图、微前端子应用依赖关系图本质上也属于关系图。类图需要表达继承、组合、聚合等不同关系微前端依赖图需要表达运行时依赖还是构建时依赖这些区别都可以通过注册不同类型的边来实现。G6 的边可以自定义箭头的形状、线的虚实甚至可以根据关系类型动态渲染。我之前给一个微前端项目画过子应用依赖图20 多个子应用依赖关系特别乱。用 G6 的 dagre 布局加上边颜色区分依赖类型之后业务方很快就找到了几个循环依赖的隐患点。这种从“看代码”到“看图”的转变是图可视化工具最值钱的地方。5.3 把 G6 封装成公司内部组件库如果你所在团队有前端组件库非常建议把 G6 的常用场景封装成通用组件。比如 TopoGraph、ERGraph、FlowGraph。封装之后业务方只需要传数据就能出图相关配置比如布局类型、交互行为、节点映射规则都收敛到组件内部。封装时要注意把 G6 的graph实例暴露出去因为后续做联动、事件订阅、数据更新都离不开这个实例。我一直用的方式是 defineExpose 或者在 React 里 forwardRef 把 graph 实例传给父组件父组件可以做高度定制。6. 最后想说的几句实在话做图可视化这类需求十有八九不是视觉问题而是数据结构和业务逻辑的问题。G6 已经把渲染和交互做得很完善了真正的分水岭在于你能不能把业务语义转换成图数据结构以及能不能设计出让人一眼就懂的空间布局。数据关系理不清换什么库都白搭。另外网上很多教程停留在展示 G6 的 API 用法你照抄可能能跑通一个小 demo但一到真实场景就会遇到布局混乱、交互不符合预期、自定义节点失效这些事。遇到问题多去读 G6 的源码和官方 issue效率比盲改配置高很多。官方文档的搜索功能其实很好用直接搜英文关键词加项目名基本都能搜到答案。如果你刚接触 G6建议从一个小型但真实的需求开始练手不要一上来就想做那种很炫的大屏。先做一个 20 个节点以内的拓扑图把自定义节点、边样式、事件交互、数据更新跑通再逐步加复杂度。这样踩坑的代价最小收获也最扎实。