猫头虎 分享 京东开源 JoyAgent-JDGenie 多智能体：GAIA 准确率 75.15%，用 TaoToken 统一 Key 跑通端到端配置
2026/9/26 19:36:34
简介：neovis.js 是一套基于 vis.js 构建、可直接对接 Neo4j 数据库的浏览器端图形可视化方案，面向需要在 Web 页面中呈现图数据的前端开发者与图数据库使用者。它支持连接 Neo4j 实例获取实时数据，允许自定义节点标签与展示属性、Cypher 查询语句、节点图片 URL、边粗细、社区/集群归属及节点大小，并可配置弹出窗口，适合知识图谱展示、社交关系分析等场景。资源包共 34 个文件，以 12 个 js 源码与 5 个 html 示例为主，另含 md 说明文档、json 配置、map 映射文件、png 示意图及 yml 工作流配置等，压缩包约 3.01MB，目录涵盖 src 源码、dist 构建产物、examples 示例与测试用例。目前已有 2602 人学习下载，读者可借助示例页面与源码快速理解图数据渲染流程，掌握从查询到可视化呈现的完整实现思路。
1. neovis.js 把 Neo4j 数据搬到浏览器：为什么值得做，谁该上手
很多团队在 Neo4j 里跑完 Cypher，拿到一张关系表，却卡在“怎么让业务方一眼看懂”这一步。把结果导出 CSV 再丢进前端图表库，节点一多就散架，关系一深就画成毛线球。neovis.js 解决的正是这个断层：它把 Neo4j 的查询结果直接映射成浏览器里的力导向图，不用自己写节点去重、边合并、坐标计算那一整套脏活。你只要在页面里声明一个容器、配好连接信息和 Cypher，剩下的渲染交给它。适合谁？做知识图谱前端展示、风控关系排查、企业内部数据血缘可视化的工程师，尤其是已经用上 Neo4j 社区版、想快速出原型又不想被 D3 的 enter/update/exit 折磨的人。它不替代后端查询优化，但能把“数据到图形”这段路缩短到几十行配置。
2. neovis.js 的渲染链路：从 Neo4j 驱动到画布上的节点
2.1 它到底封装了哪几层
neovis.js 本质上是三件事的粘合：Neo4j 官方 JavaScript 驱动负责连库和跑 Cypher，vis-network 负责力导向布局和交互，中间一层配置映射把查询结果里的字段翻译成节点和边的视觉属性。你写labels、relationshipTypes这些配置，它内部会拼成 Cypher 的MATCH模式，或者你直接给完整语句也行。理解这一点很关键：它不是魔法，节点颜色、大小、标题都来自你查询里返回的属性名，名字对不上就渲染成默认灰点。常见做法是让 Cypher 返回id、label、title这类约定字段，再在配置里一一对应。
2.2 最小可跑通页面：一个 HTML 加两段配置
先别急着上框架，用最朴素的 HTML 验证链路。下面这段可以直接存成index.html，用本地静态服务器打开。
<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <title>neovis 最小示例</title> <!-- 引入 neovis.js，它内部会带上 vis-network 依赖 --> <script src="https://unpkg.com/neovis.js@2.1.0/dist/neovis.js"></script> </head> <body> <div id="viz" style="width:100%;height:600px;"></div> <script> // 1. 初始化配置对象 var config = { containerId: "viz", // 2. 连接信息，社区版默认 bolt 端口 7687 serverUrl: "bolt://localhost:7687", serverUser: "neo4j", serverPassword: "你的密码", // 3. 初始 Cypher，限制条数避免一上来就卡死 initialCypher: "MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 100", // 4. 视觉映射：把返回字段绑到节点属性 labels: { Person: { label: "name", // 节点显示名取 name 属性 [Neovis.NEOVIS_ADVANCED_CONFIG]: { function: { title: (node) => node.properties.name } } } }, relationships: { KNOWS: { thickness: 2 } } }; // 5. 实例化并渲染 var viz = new Neovis.default(config); viz.render(); </script> </body> </html>逻辑说明：containerId必须和页面里 div 的 id 一致，否则画布挂载失败且控制台不一定报错。serverUrl用bolt://而不是http://，这是 Neo4j 驱动的协议。initialCypher里的LIMIT是保命参数，不加的话大库直接让浏览器标签页崩溃。labels的键是 Neo4j 里的节点标签名，大小写敏感，写错就落到默认样式。Neovis.NEOVIS_ADVANCED_CONFIG是进阶入口，用来写回调函数控制 tooltip、颜色等。
参数说明：serverUser和serverPassword在社区版默认是neo4j加你首次启动时设的密码。如果 Neo4j 跑在 Docker 里，注意端口映射，7687是 bolt，7474是浏览器控制台，别搞混。initialCypher返回的变量名n、r、m会被 neovis 自动识别为节点和关系，不需要额外声明。
2.3 用 labels 和 relationships 控制视觉映射
当你的图里不止一种标签时，配置要按标签分别写。下面这段演示如何给不同标签不同颜色和大小，以及给关系加箭头。
var config = { containerId: "viz", serverUrl: "bolt://localhost:7687", serverUser: "neo4j", serverPassword: "你的密码", initialCypher: "MATCH (p:Person)-[r:WORKS_AT]->(c:Company) RETURN p, r, c LIMIT 50", labels: { Person: { label: "name", [Neovis.NEOVIS_ADVANCED_CONFIG]: { static: { color: "#4A90D9", // 固定颜色 size: 25 // 固定大小 } } }, Company: { label: "companyName", [Neovis.NEOVIS_ADVANCED_CONFIG]: { static: { color: "#E67E22", shape: "box" // 公司用方块区分 } } } }, relationships: { WORKS_AT: { [Neovis.NEOVIS_ADVANCED_CONFIG]: { static: { arrows: "to", // 箭头指向目标节点 color: "#999" } } } } };逻辑说明：static表示不随数据变化的固定样式，适合区分实体类型。label字段指定用哪个属性作为节点显示文字，如果属性不存在会显示空。shape支持dot、box、diamond等 vis-network 内置形状。关系配置里的arrows设成to能明确方向，避免业务方把上下游看反。
参数说明：颜色用十六进制字符串，大小是像素值。如果想让节点大小随某个属性变化，把static换成function，在回调里读node.properties返回数值。注意回调里不要做重计算，否则每帧都跑会拖慢布局。
3. 把 neovis.js 接进真实项目：查询、事件与数据更新
3.1 用 Cypher 控制返回结构而不是在前端过滤
新手容易犯的错是查一大堆再在前端筛，正确做法是让 Cypher 只返回要画的子图。比如从某个节点出发查多层关系，用变长路径但要限制深度。
// 从指定节点出发，查 2 跳内的关系，限制返回条数 MATCH path = (start:Person {name: "张三"})-[*1..2]-(other) RETURN path LIMIT 200逻辑说明：[*1..2]表示 1 到 2 跳，深度越大结果爆炸越快，生产环境建议不超过 3。LIMIT放在最后，但 Neo4j 仍会先展开再截断，所以配合apoc或先查 id 再展开更稳。返回path时 neovis 能自动解析路径里的节点和关系，比手动RETURN n, r, m更省事。
参数说明：如果查询慢，先在 Neo4j 浏览器里跑EXPLAIN看执行计划，确认标签和关系类型上有索引。neovis 不负责优化查询，它只是把结果画出来。
3.2 监听点击事件做下钻查询
静态图只能看，能点才有分析价值。neovis 暴露了registerOnEvent和updateWithCypher，可以在点击节点后重新查询。
var viz = new Neovis.default(config); viz.render(); // 节点点击回调 viz.registerOnEvent("click", function(event) { // event.nodes 是点击的节点 id 数组 if (event.nodes && event.nodes.length > 0) { var nodeId = event.nodes[0]; // 用节点 id 做下钻，注意这里用参数化查询防注入 var cypher = "MATCH (n)-[r]-(m) WHERE id(n) = " + nodeId + " RETURN n, r, m LIMIT 50"; viz.updateWithCypher(cypher); } });逻辑说明：event.nodes里是 vis-network 内部的节点 id，不是 Neo4j 的 id，但 neovis 在渲染时会把 Neo4j 的 id 映射过去，所以直接用通常没问题。updateWithCypher会清空当前图并重新渲染，适合下钻场景。如果只想高亮不重绘，得走 vis-network 原生 API，那就脱离 neovis 的封装了。
参数说明：LIMIT 50是防止下钻后节点过多。生产环境建议把拼接的 cypher 改成参数化，neovis 的updateWithCypher目前不直接支持参数对象，稳妥做法是在后端包一层接口，前端只传节点 id。
3.3 大数据量下的分批加载与布局冻结
超过 500 个节点后，力导向布局会持续抖动，CPU 飙升。常见做法是分批加载并冻结布局。
var config = { containerId: "viz", serverUrl: "bolt://localhost:7687", serverUser: "neo4j", serverPassword: "你的密码", initialCypher: "MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 300", // 关闭物理布局的持续运行 visOptions: { physics: { stabilization: { enabled: true, iterations: 200, // 稳定迭代次数，跑完就停 updateInterval: 25 } } } };逻辑说明：stabilization让布局在指定迭代次数后停止，避免无限抖动。iterations太小图会挤成一团，太大初始化慢，200 到 500 之间按节点数调。如果还是卡，把physics.enabled设成false，手动给节点坐标，但那就失去力导向的意义了。
参数说明：updateInterval控制渲染刷新频率，调大能降 CPU 但动画变卡。节点超过 1000 时建议改用服务端预计算布局或换 WebGL 方案，neovis 基于 SVG 的 vis-network 在超大图上力不从心。
4. 避坑与排查：neovis.js 连不上、画不出、点不动的真实原因
4.1 页面空白，控制台报 WebSocket 连接失败
现象：打开页面后容器区域一片白，F12 看到WebSocket connection to 'ws://localhost:7687' failed。原因：Neo4j 的 bolt 端口没开，或者serverUrl写成了http://。解决：确认 Neo4j 服务在跑，serverUrl用bolt://开头；如果是远程服务器，检查防火墙是否放行 7687，Neo4j 配置里dbms.connector.bolt.listen_address是否绑到0.0.0.0而不是仅localhost。
4.2 节点全是灰色默认样式，配置没生效
现象：图能出来，但所有节点一个颜色，labels里写的颜色没起作用。原因：Cypher 返回的节点标签名和配置里的键不一致，比如数据库里是person小写，配置写Person。解决：在 Neo4j 浏览器里跑MATCH (n) RETURN labels(n) LIMIT 10确认实际标签名，配置里严格照抄。另外检查initialCypher返回的变量是否被 neovis 识别为节点，如果返回的是collect(n)这种聚合结果，neovis 解析不了。
4.3 点击节点没反应，事件回调不触发
现象：绑定了registerOnEvent("click", ...)但点击无输出。原因：registerOnEvent必须在render()之后调用，且如果页面里有其他层覆盖了画布，点击事件被拦截。解决：把注册代码放到render()后面；检查容器 div 的z-index和是否有透明遮罩；如果用了updateWithCypher重绘，事件监听会保留，但节点 id 变了，回调里要重新取。
4.4 查询一多浏览器就崩，内存暴涨
现象：连续下钻几次后标签页无响应。原因：每次updateWithCypher都新建 vis-network 数据集，旧的没释放，加上力导向布局的物理引擎持续计算。解决：限制单次返回节点数在 300 以内；在visOptions里开stabilization并设iterations；下钻时如果只是换子图，考虑复用 viz 实例而不是反复 new。另外 Neo4j 驱动连接池也要设上限，避免连接泄漏。
4.5 中文节点显示成方块或乱码
现象：节点标题里的中文变成问号或方块。原因：HTML 页面没声明 UTF-8，或者 Neo4j 里存的属性编码不对。解决：页面<meta charset="utf-8">必须有；Neo4j 属性本身是 Unicode 存储，一般没问题，但导入 CSV 时要注意源文件编码。如果用的是 vis-network 的默认字体，某些环境缺中文字体，在visOptions里指定font: { face: "Microsoft YaHei" }。
5. 进阶技巧：用 neovis.js 做可交互的知识图谱下钻面板
把 neovis.js 用出生产价值，关键不在渲染本身，而在“查询编排”。我一般会做一个左侧筛选面板加右侧画布的结构：筛选条件拼成 Cypher 的WHERE子句，画布只负责展示。下面这个模式我反复用过，能避免大部分交互混乱。
// 根据筛选条件动态生成 Cypher，而不是写死 function buildCypher(filters) { var where = []; if (filters.label) { where.push("n:" + filters.label); } if (filters.keyword) { // 注意转义，生产环境走后端参数化 where.push("n.name CONTAINS '" + filters.keyword + "'"); } var whereClause = where.length > 0 ? "WHERE " + where.join(" AND ") : ""; return "MATCH (n) " + whereClause + " OPTIONAL MATCH (n)-[r]-(m) RETURN n, r, m LIMIT 200"; } // 筛选按钮触发重绘 document.getElementById("applyFilter").addEventListener("click", function() { var cypher = buildCypher({ label: document.getElementById("labelSelect").value, keyword: document.getElementById("keywordInput").value }); viz.updateWithCypher(cypher); });逻辑说明：OPTIONAL MATCH保证孤立节点也能显示，否则只查有关系的节点会漏掉单点。CONTAINS是模糊匹配，数据量大时慢，生产环境建议换成全文索引。LIMIT始终保留，这是前端可视化的底线。
参数说明：filters.label对应 Neo4j 标签，filters.keyword对应属性值。如果要做多标签联合查询，把n:Label改成n:Label1|Label2。注意 Cypher 注入风险，前端拼接只适合内部工具，对外服务必须后端参数化。
验证方法上，我习惯先用 Neo4j 浏览器把 Cypher 跑通，确认返回列名和 neovis 配置对得上，再贴到前端。这样能把“查询错”和“渲染错”分开排查，省掉大量来回。另一个习惯是给画布加一个节点计数显示，超过阈值就提示用户缩小范围，而不是等浏览器卡死。这些细节不写进配置文档，但决定了这个方案能不能真的交到业务方手里。希望帮到你。
本文还有配套的精品资源，点击获取