简介：KPV（KEGG PATHWAY VIEWER）是一套面向生物信息学与系统生物学学习者的KEGG代谢通路可视化工具源码，适合希望把通路数据搬到浏览器中交互分析的高校师生与科研人员使用。项目依据AP检测算法对网络中的蛋白质进行分类，可直观标出连通度最高的关键节点；同时以动态HTML方式呈现KEGG路径，支持节点删除、边添加等基本操作，便于模拟和观察网络结构变化。压缩包共956个文件，约62.01MB，包含211个js脚本、167个html页面、61个css与42个less样式文件，以及177个png、29个gif等图表素材，另有131个md说明文档和若干php、sql、sqlite等后端与数据文件，构成前端展示、样式布局、数据存储与文档说明相对完整的结构。该资源已有1086人学习下载，读者可据此了解通路可视化的实现思路，参考蛋白质节点分类与网络交互逻辑，并在本地复现页面效果或二次开发。

1. 差异基因列表跑完富集，评审会上被问一句「这几个基因在细胞周期通路里到底怎么连的」，表格答不了这个问题

我一般直接打开 kegg-network-viewer：把通路编号或者手里的 KGML 文件拖进去，浏览器里就长出一张能缩放、能拖动、点一下节点就能高亮邻居的网络图，产物是一个纯静态 HTML 页面，不用装客户端、不用连数据库、也不用配后端。它适合拿来做通路汇报、给富集结果做二次确认，也适合当练手项目——从 XML 解析到布局、交互、导出，四块拆得很干净，想加什么字段都能找到落点。下面按「结构长什么样、数据怎么进来、图画到哪、哪里会翻车、怎么改成自己的」的顺序拆一遍。

2. 架构与目录：一个 KGML 文件怎么变成浏览器里的一张图

2.1 三层结构：抓取、规范化、渲染

这个工具的骨架很朴素，三件事分得很开。第一层是抓取，把公开通路数据里的 KGML（一种描述通路内基因、化合物、酶以及它们相互关系的 XML）拉到本地存成文件，这一步是可选的，你手上已经有.kgml就跳过。第二层是规范化，在浏览器里用DOMParser把 XML 拆成两个扁平数组nodes和edges，把「XML 树」变成「图数据结构」。第三层是渲染，用 D3 把这两个数组画成 SVG，挂上缩放、拖拽、高亮。

为什么不干脆在后端出图？因为通路图的交互密度太高——鼠标移到某个基因上要看它的邻居，点一下子通路要能下钻，改配色要立刻生效。后端每次出 PNG，等于每点一下都回源一次，而且发给合作方还得连服务。静态 HTML 的代价是首次解析稍微慢一点（几百个 entry 的通路大概几十毫秒到一百多毫秒），换来的是双击就能打开。

这也是我建议先读parse-kgml.js再读render.js的原因：数据层一旦对齐，渲染层出问题基本都能一眼定位。

2.2 目录结构：每个文件夹各管一摊

解压后按职责捋一遍，大致是下面这样（具体文件名可能略有出入，顺着import关系对得上就行）：

kegg-network-viewer/ ├── index.html # 唯一入口：挂载点 + 顶部工具栏（选文件、选布局、导出） ├── src/ │ ├── main.js # 启动流程：读参数 → parse → normalize → render │ ├── parse-kgml.js # KGML(XML) → { nodes, edges } │ ├── normalize.js # 补 degree、合并重复 entry、算包围盒 │ ├── render.js # D3 布局、缩放拖拽、tick 更新 │ ├── interactions.js # 邻居高亮、搜索框、图例 │ └── export.js # SVG / PNG 导出 ├── styles/ │ └── viewer.css # 节点配色、字体、工具栏样式 ├── data/ │ ├── raw/ # 原始 .kgml 文件 │ └── build/ # 预转换好的 .json，省掉每次解析 ├── scripts/ │ └── fetch-kgml.mjs # 批量下载 + 转 JSON 的 Node 脚本 └── samples/ # 两三张现成通路，用来验证环境

值得单独说的是data/build/。很多人第一次跑会忽略它，结果每次都从 XML 重新解析。预转换这一步在批量看几十条通路时收益很明显——JSON 直接fetch回来就能画，省掉DOMParser的开销，也方便你在外面用脚本先做过滤（比如只保留有差异基因的 entry）。

2.3 跑起来：一条命令起服务，三种方式喂数据

不需要npm install，也不需要打包工具，它就是一个静态站点。但有一点必须注意：不能双击index.html。在file://协议下，浏览器会把fetch('./data/raw/hsa04110.kgml')当成跨域请求拦掉，页面直接空白。

# 1) 进目录 cd kegg-network-viewer # 2) 起一个静态服务，任选其一 python3 -m http.server 8080 # 或者：npx serve . # 3) 浏览器打开 http://localhost:8080

起好服务之后有三种喂数据的方式，按方便程度排：

第一，直接把samples/里的 kgml 文件拖到页面中间的上传区，走FileReader读文本再解析，完全不经过网络。第二，在地址栏带参数，比如http://localhost:8080/?pathway=hsa04110，main.js会拼出./data/build/hsa04110.json去拉。第三，改main.js里的默认路径常量，让它一进来就加载你关心的那条通路。

提示：跑之前先确认浏览器的开发者工具 Console 是干净的。这项目用的是原生 ES Module（<script type="module">），如果你的服务把.js的 MIME 类型返回成text/plain，模块加载会被拒绝，报错信息是Failed to load module script，看着像代码问题，其实是服务配置问题。

3. 数据层：KGML 里的 entry、relation、reaction 怎么读成 nodes 和 edges

3.1 先认清四种 entry，不然字段全对不上

KGML 里的entry是节点的主要来源，type属性决定它是什么：gene是基因（name形如hsa:7157），compound是化合物（cpd:C00002），enzyme是酶，map是子通路引用（path:hsa04110），点进去应该是另一张图。

这里有两个特别容易踩的点。一是同一个entry可以挂多个graphics子节点，表示这个基因在图上画了好几个框（常见于跨膜蛋白或者被拆开摆放的复合物）；二是name属性可能是空格分隔的多个基因，表示这一组基因共用一个框。如果你只读第一个graphics、只取name的第一段，图画出来是对的，但悬停看不到完整信息，做下游分析时也会丢基因。

<!-- 一个 entry 挂两个 graphics、name 里带两个基因的典型形态 --> <entry id="12" name="hsa:7157 hsa:7158" type="gene"> <graphics name="TP53, p53" fgcolor="#000000" bgcolor="#BFFFBF" type="rectangle" x="120" y="340" width="46" height="17"/> <graphics name="TP53, p53" fgcolor="#000000" bgcolor="#BFFFBF" type="rectangle" x="120" y="300" width="46" height="17"/> </entry>

graphics上的x、y是矩形左上角坐标，width、height是框的尺寸。很多通路图的坐标能到 1500 以上，viewBox直接写死0 0 800 600就会把右下角裁掉。

3.2 解析函数：把 XML 压成两个扁平数组

核心就是一个函数，输入 XML 文本，输出{ nodes, edges }。下面这段是我在这个项目里用得最顺的写法：

// parse-kgml.js —— KGML 文本 → { nodes, edges } const TYPE_COLOR = { gene: '#BFFFBF', enzyme: '#B3B3FF', compound: '#FFD9B3', map: '#FFFFFF', ortholog: '#CCCCCC', }; export function parseKgml(xmlText) { const doc = new DOMParser().parseFromString(xmlText, 'application/xml'); // XML 不合法时 DOMParser 不抛异常，而是塞一个 <parsererror> 节点 const err = doc.querySelector('parsererror'); if (err) throw new Error('KGML 不是合法 XML：' + err.textContent.slice(0, 120)); const nodes = []; for (const entry of doc.querySelectorAll('pathway > entry')) { const id = entry.getAttribute('id'); const type = entry.getAttribute('type'); const name = entry.getAttribute('name') || ''; const boxes = [...entry.querySelectorAll('graphics')].map(g => ({ x: +g.getAttribute('x'), y: +g.getAttribute('y'), w: +g.getAttribute('width'), h: +g.getAttribute('height'), })); const first = boxes[0] || { x: 0, y: 0, w: 46, h: 17 }; nodes.push({ id, // entry id 是唯一主键，边也用它对齐 type, genes: name.split(' ').filter(Boolean), // 一个 entry 多基因时全部保留 label: (entry.querySelector('graphics')?.getAttribute('name') || name) .split(',')[0].trim(), // 只放第一个别名，避免标签溢出 // 坐标统一存「中心点」，渲染时才好直接用 translate 摆位 x: first.x + first.w / 2, y: first.y + first.h / 2, w: first.w, h: first.h, boxes, // 多框 entry 靠它把每个框都画出来 color: TYPE_COLOR[type] ?? '#DDDDDD', }); } return { nodes, edges: parseEdges(doc, nodes) }; }

几个参数的取舍值得说明白。id用entry的id而不是基因名——同一个基因在一条通路里可能出现多次，用基因名做主键会互相覆盖。x、y存中心点而非左上角，是因为 D3 里给<g>打transform: translate(x, y)时，子元素的矩形必须用-w/2、-h/2反向偏移，中心点对齐比左上角对齐少写一堆补偿。boxes保留完整数组，是为了后面能把多框 entry 的每个框都画出来，否则跨膜蛋白看起来会缺一半。

TYPE_COLOR这张表就是配色入口，想改成自己的色系，只动这一个对象即可，别去viewer.css里逐类选择器改。

3.3 relation 和 reaction：两种边，别混着画

边的来源有两处，语义完全不同。relation描述调控关系（激活、抑制、磷酸化），reaction描述酶催化的底物到产物。前者一条记录就是一条边，后者要从substrate和product做笛卡尔积——一个反应可能有多个底物、多个产物。

// parse-kgml.js —— 边解析 + 去重 function parseEdges(doc, nodes) { const valid = new Set(nodes.map(n => n.id)); // 先建 id 白名单，挡掉悬空边 const seen = new Set(); const edges = []; const push = (source, target, type, subtype) => { if (!source || !target || source === target) return; if (!valid.has(source) || !valid.has(target)) return; const key = `${type}|${source}|${target}|${subtype}`; if (seen.has(key)) return; // 同一对节点同一类型只留一条 seen.add(key); edges.push({ id: `e${edges.length}`, source, target, type, subtype }); }; // relation：基因 / 化合物之间的调控 for (const rel of doc.querySelectorAll('pathway > relation')) { const sub = rel.querySelector('subtype'); push(rel.getAttribute('entry1'), rel.getAttribute('entry2'), rel.getAttribute('type'), sub?.getAttribute('name') ?? 'unknown'); } // reaction：酶催化，substrate × product 展开成多条边 for (const rxn of doc.querySelectorAll('pathway > reaction')) { const subs = [...rxn.querySelectorAll('substrate')].map(s => s.getAttribute('id')); const prods = [...rxn.querySelectorAll('product')].map(p => p.getAttribute('id')); for (const s of subs) for (const p of prods) { push(s, p, 'reaction', rxn.getAttribute('type')); } } return edges; }

去重键里带上subtype是关键。同两个基因之间既可能是activation又可能是phosphorylation，只按source|target去重会把其中一条吞掉，画出来就少一个箭头。valid白名单用来挡悬空边——KGML 里偶尔会引用当前文件没有定义的 entry（比如它属于另一条子通路），不挡掉的话 D3 的forceLink会直接报missing: xxx然后整张图不动。

push里我特意排掉了自环（source === target）。反应里确实存在底物就是产物的情况，但画在图上是一个绕过节点的圈，视觉噪音很大，我的做法是先过滤，需要时再单独列一张表。

4. 渲染层：在 HTML 里把网络画出来，并让它可以被操作

4.1 布局二选一：预置坐标还是力导向

这是整个项目里第一个要你做决定的开关。preset模式用 KGML 自带的坐标，节点基本落在原图的位置上，细胞膜、细胞核、线粒体的相对关系还在，做通路汇报时生物学含义不会丢。force模式纯用力导向，适合你把自己拼的多条通路合并成一张图——这时候原始坐标来自不同画布，叠在一起必然打架。

两种模式共用同一套渲染代码，差别只在于有没有给模拟加forceX/forceY约束。这里有个反直觉的细节：约束的目标值不能直接用d.x。forceX在每帧都会修改d.x，如果目标也读d.x，等于节点拽着自己的鞋带往上提，跑一会儿就被力导向推得面目全非。所以要在启动模拟之前把原始坐标拷一份只读的ox、oy。

// render.js —— 骨架部分：初始化、数据绑定、模拟 export function renderNetwork(container, graph, opts = {}) { const { mode = 'preset', width = 1200, height = 900 } = opts; // 原坐标备份：forceX/forceY 只能指向 ox/oy，不能指向会被模拟改写的 x/y graph.nodes.forEach(d => { d.ox = d.x; d.oy = d.y; }); const svg = d3.select(container).append('svg') .attr('width', '100%') .attr('height', '100%') .attr('viewBox', `0 0 ${width} ${height}`) // 用通路包围盒算出来的尺寸 .attr('preserveAspectRatio', 'xMidYMid meet'); const root = svg.append('g'); // 缩放只作用于这一层 const linkLayer = root.append('g').attr('class', 'links'); const nodeLayer = root.append('g').attr('class', 'nodes'); const link = linkLayer.selectAll('line') .data(graph.edges, d => d.id) .join('line') .attr('stroke', '#8a8a8a') .attr('stroke-width', 1.2) .attr('marker-end', 'url(#arrow)'); const node = nodeLayer.selectAll('g.node') .data(graph.nodes, d => d.id) // 用 entry id 做 key，重绘才不会错位 .join('g') .attr('class', 'node'); node.append('rect') .attr('x', d => -d.w / 2) // 坐标是中心点，矩形反向偏移半个宽高 .attr('y', d => -d.h / 2) .attr('width', d => d.w) .attr('height', d => d.h) .attr('rx', 3) .attr('fill', d => d.color) .attr('stroke', '#333') .attr('stroke-width', 0.8); node.append('title').text(d => d.genes.join('\n')); // 悬停看全部基因，标签只放第一个 const sim = d3.forceSimulation(graph.nodes) .force('link', d3.forceLink(graph.edges).id(d => d.id).distance(70).strength(0.4)) .force('charge', d3.forceManyBody().strength(-150)) .force('collide', d3.forceCollide().radius(d => Math.max(d.w, d.h) / 2 + 3)) .on('tick', () => { link.attr('x1', d => d.source.x).attr('y1', d => d.source.y) .attr('x2', d => d.target.x).attr('y2', d => d.target.y); node.attr('transform', d => `translate(${d.x},${d.y})`); }); if (mode === 'preset') { sim.force('x', d3.forceX(d => d.ox).strength(0.9)) .force('y', d3.forceY(d => d.oy).strength(0.9)) .alpha(0.6); // 初始扰动别太大，避免开局乱飞 } return { svg, root, node, link, sim }; }

参数上，distance(70)决定连线的最短长度，通路里节点密的时候调到 40～50 会更好看；strength(-150)是斥力，负数越大越散，超过 -400 小通路会散成一盘沙；collide的半径用节点尺寸算，不要写死常量，基因框和化合物框的宽度差很多。alpha(0.6)让预置模式不用从高温开始降温，省掉开局那两三秒的抖动。

viewBox的两个参数不要写死，正确做法是遍历所有boxes求minX/minY/maxX/maxY，再各留 40 像素边距。

4.2 缩放、拖拽与邻居高亮

交互部分的代码量不大，但顺序有讲究：先挂zoom再挂drag，否则拖节点的时候画布跟着一起平移。

// render.js —— 交互：缩放 + 拖拽 + 点击高亮 export function bindInteractions({ svg, root, node, link, sim }, graph) { // 1) 画布缩放 const zoom = d3.zoom() .scaleExtent([0.15, 8]) // 下限别低于 0.1，再小就只剩噪点 .on('zoom', ev => root.attr('transform', ev.transform)); svg.call(zoom); // 2) 节点拖拽：拖的时候临时固定 fx/fy，松手后放开 node.call(d3.drag() .on('start', (ev, d) => { if (!ev.active) sim.alphaTarget(0.3).restart(); d.fx = d.x; d.fy = d.y; }) .on('drag', (ev, d) => { d.fx = ev.x; d.fy = ev.y; }) .on('end', (ev, d) => { if (!ev.active) sim.alphaTarget(0); d.fx = null; d.fy = null; })); // 3) 点击高亮：只算一跳邻居，够用且快 function highlight(id) { const near = new Set([id]); graph.edges.forEach(e => { // 模拟跑起来后 source/target 会从字符串变成节点对象，两种都要兼容 const s = e.source.id ?? e.source; const t = e.target.id ?? e.target; if (s === id) near.add(t); if (t === id) near.add(s); }); node.attr('opacity', d => near.has(d.id) ? 1 : 0.12); link.attr('opacity', e => { const s = e.source.id ?? e.source, t = e.target.id ?? e.target; return (s === id || t === id) ? 1 : 0.05; }); } node.on('click', (ev, d) => { ev.stopPropagation(); highlight(d.id); }); svg.on('click', () => { node.attr('opacity', 1); link.attr('opacity', 1); }); // 点空白复位 return { highlight }; }

e.source.id ?? e.source这个写法看着别扭，但省不掉。D3 的forceLink在第一次 tick 之后会把edges里的source/target从字符串 id 替换成节点对象的引用，所以同一个字段在模拟前后是两种类型。判断邻居时如果只按字符串比，高亮永远点不亮。

scaleExtent的下限设 0.15 是给大型通路留的余量，上限 8 已经够看清单个基因框里的别名了。真要进一步放大，改的是viewBox而不是scaleExtent。

4.3 导出：SVG 与 PNG 的两套打法

导出这块是我觉得这项目最实用的地方——汇报材料里的图，一放大就糊是常事，SVG 矢量图能救回来。

// export.js —— 导出 SVG；注意样式必须内联 export function exportSvg(svgEl, filename = 'pathway.svg', w = 1200, h = 900) { const clone = svgEl.cloneNode(true); clone.setAttribute('width', w); // 把 100% 换成像素，否则部分查看器里尺寸为 0 clone.setAttribute('height', h); clone.setAttribute('xmlns', 'http://www.w3.org/2000/svg'); // 外部 CSS 不会被一起序列化，关键样式必须先写进 style 属性 clone.querySelectorAll('.node rect').forEach(r => { r.setAttribute('style', 'stroke:#333;stroke-width:0.8'); }); const blob = new Blob([new XMLSerializer().serializeToString(clone)], { type: 'image/svg+xml;charset=utf-8' }); const a = document.createElement('a'); a.href = URL.createObjectURL(blob); a.download = filename; a.click(); URL.revokeObjectURL(a.href); // 不释放会一直占着内存 }

导出 PNG 走的是另一条路：把上面的 SVG 序列化成 data URL，塞进Image对象，等onload之后画到<canvas>上，再canvas.toBlob()。两个参数必须给对——canvas.width要按scale倍放大（想 2 倍图就乘 2），drawImage的宽高也要同步放大，否则出来是一张放大的马赛克。还有一个坑：Image加载 SVG 时如果里面引用了外部字体，字会变成默认字体，中文甚至可能整段缺失，所以导出前把字体名写进style属性最保险。

5. 避坑与排查：五个把我卡住的现场

5.1 打开是白屏，Console 一行红字

现象：双击index.html，页面框架出来了，图画布空的，Console 报Access to fetch ... has been blocked by CORS policy。

原因：file://协议下没有源，任何fetch本地文件的操作都会被浏览器按跨域处理。这不是代码写错，是协议限制。

解决：起静态服务，python3 -m http.server 8080就行。实在不方便起服务，就改用文件选择框喂数据，走FileReader.readAsText读文本，这条路不经过网络请求，file://下也能跑。我把这个当成默认入口，就是因为踩过一次现场演示时忘了起服务的坑。

5.2 框都画出来了，就是一根线都没有

现象：节点铺满画布，边的图层是空的，Console 里Error: missing: 37。

原因：edges里某条边的source或target在当前nodes里找不到对应 id。最常见的是reaction的substrate引用了一个当前 KGML 文件没定义的 entry，其次是解析时把entry的 id 转成了数字而边上还是字符串，===判断永远为假。

解决：解析阶段就建 id 白名单过滤，像 3.3 里那样。另外全流程统一用字符串 id，getAttribute拿到的本来就是字符串，别手贱parseInt。

5.3 图被压扁或者右下角被裁掉

现象：整张图挤在左上角一小块，或者右下角的节点看不见。

原因：viewBox写死了。不同通路的坐标范围差别很大，有的x只到 600，有的能到 2400，固定0 0 1200 900必然有一部分出界。

解决：跑一遍所有boxes求包围盒，viewBox用minX-40 minY-40 (maxX-minX+80) (maxY-minY+80)。另外preserveAspectRatio保持xMidYMid meet，容器比例和 viewBox 比例不一致时不会拉伸变形。

5.4 导出的图打开是空白，或者中文全变方块

现象：pathway.svg用浏览器打开一片白；导出的 PNG 里节点文字变成豆腐块。

原因：一是样式写在外部 CSS 里，XMLSerializer只序列化 DOM 结构，不带样式表；二是width/height还是100%，部分查看器解析不出来；三是Image加载 SVG 时拿不到页面里声明的字体。

解决：导出前把关键样式内联到元素的style属性上，width/height换成具体像素，xmlns手动补上，字体名直接写进style="font-family: ..."。这三步做完基本就不会翻车了。

5.5 几百个节点的通路，拖起来像幻灯片

现象：小通路很流畅，一换到大通路，缩放卡顿，拖节点掉帧。

原因：每个节点都单独挂了mousemove监听，几百个元素就是几百个回调；再加上每次zoom事件都重新selectAll算一遍，主线程直接被占满。

解决：事件委托到svg一层，用ev.target.closest('g.node')拿节点；zoom回调里只改root的transform，别碰子元素；模拟的alphaMin调到 0.02 让它早点停下来，preset模式下甚至可以跑 300 帧后直接sim.stop()。

6. 二次开发：把这张图改成你自己项目里的一个视图

这个项目最舒服的地方是数据层和渲染层切得干净，改造基本不用动骨架。常见的几个方向我列在下面，按改动成本排：

颜色映射是最容易见效的一个。默认配色是按type走的，把它换成按表达量走：先给每个节点挂一个value字段（从富集结果表里按基因名 join 进来），再换一个连续色标。

// render.js —— 把节点填充色从「按类型」改成「按 logFC」 const color = d3.scaleDiverging() .domain([-2, 0, 2]) // 下限、中性点、上限，超出范围会夹住 .interpolator(d3.interpolateRdBu); // 红-白-蓝，蓝低红高 // 在解析之后、渲染之前，把表达量 join 到节点上 const expr = new Map([['7157', 2.31], ['7158', -1.02]]); // 来自你的差异分析结果 graph.nodes.forEach(d => { const hit = d.genes.map(g => g.split(':')[1]).find(g => expr.has(g)); d.value = hit ? expr.get(hit) : null; }); // 替换掉原来的 .attr('fill', d => d.color) .attr('fill', d => d.value == null ? '#E8E8E8' : color(d.value))

domain的三个值建议按你数据的实际分位数定，写死 ±2 只是习惯做法；color对null必须单独兜底，不然scaleDiverging(null)返回的是中性色，图上会分不清「没测到」和「没变化」——这个区别在汇报时经常被追问，别偷懒。

想验证改得对不对，我的习惯是拿一条已知结论的通路做回归测试：比如细胞周期通路里那几个核心调控基因应该在图上互相连着，改完配色之后点一下它，高亮出来的邻居数量和改之前对得上，就说明数据层没被改坏。

血泪经验是：每次动parse-kgml.js都先跑一遍samples/里的三条通路，看一眼节点数和边数有没有突变，再做别的。数据层的错不会立刻报异常，它只会安静地让图少几条边，等你拿着图去汇报的时候才发现不对。从那以后我每次改解析逻辑，都强制走一遍这三条样本的节点数、边数、孤立节点数对比，再往下写渲染。希望帮到你。

本文还有配套的精品资源，点击获取