简介kegg-network-viewer 是一款基于 HTML 技术构建的交互式 KEGG 代谢通路可视化工具面向生物信息学初学者、计算生物学研究者及系统生物学方向的科研人员用于直观解析蛋白质在网络中的拓扑重要性如瓶颈节点识别并支持动态模拟操作如节点删除、边添加。资源包共956个文件涵盖167个HTML页面实现路径渲染与交互逻辑211个JavaScript文件支撑核心功能177个PNG图像提供通路图谱资源61个CSS/SCSS/LESS样式文件保障可视化效果另有PHP后端模块、Markdown文档说明及字体资源等整体压缩包达62.01MB结构完整、开箱即用。已有1086人学习下载资源包含可直接部署的本地服务环境、多套示例通路samples.css 等、编辑器兼容方案含IE适配CSS及数据库备份.mwb.bak、.sqlite便于教学演示、科研复现与二次开发。1. KEGG Network Viewer 是什么一个轻量 HTML 工具把 KEGG 通路图变成可交互、可导出、可离线查看的本地网络视图你有没有试过打开 KEGG 官网的某个通路页面比如 hsa04150: mTOR signaling pathway想快速标出自己关注的基因节点、拖拽调整布局、高亮上下游关系或者把整张图导出为带缩放的 SVG 供论文插图使用结果发现官网页面卡顿、右键受限、无法批量操作、一关浏览器就丢——这正是 KEGG Network Viewer 存在的底层理由。它不是另一个 KEGG 镜像站也不是 Python 包封装而是一个纯前端 HTML JavaScript 实现的离线可视化工具输入 KEGG 通路 ID如map04150或hsa04150它就能自动拉取 KEGG 的 KGMLKEGG Markup LanguageXML 文件解析节点坐标、反应箭头、基因/化合物映射关系并在本地浏览器中渲染成可缩放、可拖拽、可搜索、可点击展开注释的交互式网络图。整个过程不依赖后端服务、不上传数据、不调用外部 API除 KEGG 原始 KGML 文件外所有逻辑跑在浏览器里。适合做通路初筛、教学演示、组学结果映射比如把差异基因列表一键上色、以及需要反复查看/标注某几条核心通路的研究者。如果你习惯用 Jupyter 查表、用 Cytoscape 做复杂网络分析但又不想每次只为看一张图就开大软件、配环境、导数据——这个 HTML 工具就是你的“通路速查后悔药”。2. 核心能力拆解从 KGML 解析到 SVG 渲染为什么它能离线跑起来KEGG Network Viewer 的技术骨架非常干净它不造轮子而是精准复用 KEGG 官方发布的 KGML 标准并用现代 Web 技术把它“活”过来。理解它的能力边界关键在于看清三件事KGML 是什么、浏览器如何解析它、SVG 渲染如何支撑交互。下面分步拆解。2.1 KGML 文件结构与 Viewer 的解析策略KEGG 每条通路如hsa04150都对应一个公开的 KGML XML 文件地址格式为https://www.kegg.jp/kegg-bin/download?entryhsa04150formatkgml该文件不是图片而是一个结构化描述定义了entry节点基因、化合物、反应、relation调控关系、reaction生化反应、component复合物组成等标签并附带x,y,width,height坐标信息由 KEGG 手动绘制。Viewer 的核心 JS 逻辑主文件kgml-parser.js并不做坐标重排或力导向布局而是严格忠实还原 KGML 中的原始位置——这是它轻量、确定、可复现的关键。例如entry id1 namehsa:5566 typegene linkhttps://www.kegg.jp/dbget-bin/www_bget?hsa:5566 graphics nameMTOR fgcolor#000000 bgcolor#FFFFFF x390 y220 width45 height17/ /entry relation entry11 entry22 typeECrel subtype nameactivation valueactivation/ /relationViewer 解析时会提取entry的id,name,type,x,y生成 SVGcircle或rect元素对relation标签根据entry1和entry2的坐标用line或path绘制带箭头的连接线将link属性转为节点 tooltip 中的可点击 URLnamehsa:5566被解析为标准 KEGG gene ID用于后续映射如用户上传自己的差异基因列表。提示KGML 坐标是绝对像素值非比例值。这意味着 Viewer 渲染效果与 KEGG 官网图完全一致但放大后文字不会自动缩放——这是设计选择不是 bug。若需高清导出必须用 SVG 原生缩放见第 5 章。2.2 SVG 渲染层为什么不用 Canvas 或 D3 force layoutViewer 选用原生 SVG而非 Canvas 或 D3 的力导向图有三个硬性理由第一保真度优先。KGML 坐标是人工校准的生物学意义布局如上游信号在左、下游效应在右强行用算法重排会破坏通路阅读逻辑第二交互粒度可控。SVG 元素支持原生addEventListener(click)每个circle可绑定独立事件如点击弹出基因详情、右键复制 IDCanvas 需手动做坐标映射开发成本翻倍第三导出即用。SVG 是矢量文本格式直接document.querySelector(svg).outerHTML即可获取完整代码粘贴进 Illustrator 或 Inkscape 编辑无需额外转换。实际渲染流程在render.js中体现为三层嵌套创建svg根元素宽高设为max(xwidth)50留白边遍历 parsed KGML entries对typegene生成circle r8typecompound生成rect rx4typereaction生成path dM...遍历 relations用getBBox()获取两端节点坐标绘制line并添加marker箭头。这种“所见即所得”的策略让开发者能一眼看懂渲染逻辑也方便你按需定制——比如把所有typeglycan的节点改成紫色菱形只需改一行 CSS 类名。2.3 交互功能实现搜索、高亮、导出背后的 DOM 操作所有交互功能都基于 SVG 元素的 class 控制和 CSS 过渡搜索框监听input事件对所有circle/rect的># 进入解压后的文件夹 cd /path/to/kegg-network-viewer # Python 3.7 用户推荐 python -m http.server 8000 # Python 2.7 用户不推荐已停止维护 python -m SimpleHTTPServer 8000终端输出Serving HTTP on 0.0.0.0 port 8000 ...后在浏览器访问http://localhost:8000即可。此时index.html加载js/kgml-parser.js不再受跨域限制。提示若提示Address already in use换端口如8001。Mac 用户若用 Safari首次访问可能弹窗要求“允许不安全脚本”勾选即可——因为本地服务无 HTTPS但完全安全。3.3 在页面中加载通路并验证基础功能打开http://localhost:8000后页面顶部有输入框和「Load Pathway」按钮输入hsa04150mTOR 通路点击按钮观察浏览器控制台F12 → Console应出现✅ Loaded KGML for hsa04150和 Parsed 127 entries, 89 relations页面中央应渲染出一张带基因节点圆圈、化合物矩形、反应六边形和箭头连线的图尝试鼠标滚轮缩放、按住空格拖拽、点击任意基因圆圈——应弹出 KEGG 基因页面链接在搜索框输入MTOR回车所有含MTOR的节点应变红边框。如果第 2 步控制台报错Failed to fetch说明网络未连通 KEGG或 KEGG 临时不可达此时可切换为离线模式将examples/hsa04150.kgml文件拖入页面区域或点击「Upload KGML」按钮选择该文件。离线模式下所有功能渲染、搜索、导出均正常只是点击节点无法弹出详情因详情需实时调 KEGG API。4. 避坑指南五个真实踩过的坑每一条都来自实验室深夜调试记录这个工具看似简单但在真实场景中有五个高频问题会让新手卡住超过 30 分钟。以下是我和某高校生物信息组 A同学 共同踩过的坑按发生频率排序每条都给出可复制的解决步骤。4.1 现象页面空白控制台报错Uncaught TypeError: Cannot read property querySelector of null原因index.html中script标签加载顺序错误render.js在 DOM 元素如#svg-container尚未创建时就执行了document.querySelector(#svg-container)。常见于手动修改 HTML 时删掉了div idsvg-container/div或把script放到了head里且没加defer。解决检查index.html确保div idsvg-container/div存在于body内所有script src...标签必须放在/body之前或加defer属性script defer srcjs/kgml-parser.js/script script defer srcjs/render.js/script4.2 现象输入通路 ID 后无响应控制台显示Access to fetch at https://www.kegg.jp/... from origin http://localhost:8000 has been blocked by CORS policy原因Chrome/Firefox 对跨域请求的严格限制。虽然 KEGG 服务器未设置Access-Control-Allow-Origin: *但 Viewer 默认尝试直连 KEGG 下载 KGML。解决两种方案任选其一✅推荐改用离线 KGML 文件。访问https://www.kegg.jp/kegg-bin/download?entryhsa04150formatkgml右键“另存为”保存为hsa04150.kgml再用页面「Upload KGML」按钮上传⚠️ 临时方案Chrome 启动时加参数--disable-web-security --user-data-dir/tmp/chrome_dev_test仅测试用勿长期开启。4.3 现象通路图渲染出来但所有节点挤在左上角坐标全为 0原因KGML 文件版本不兼容。KEGG 在 2022 年后更新了 KGML 格式新增graphics标签嵌套层级如graphicsposition x390 y220//graphics而旧版 Viewer 只认graphics x390 y220。解决升级kgml-parser.js。打开该文件找到parseGraphics()函数将原逻辑const x parseInt(graphics.getAttribute(x)) || 0;替换为兼容写法let x parseInt(graphics.getAttribute(x)) || 0; if (isNaN(x) graphics.querySelector(position)) { x parseInt(graphics.querySelector(position).getAttribute(x)) || 0; }同理处理y,width,height。此补丁已合并至 v1.3 版本。4.4 现象搜索功能失效输入AKT1无高亮但控制台无报错原因KGML 中entry的name属性格式不统一。有些是hsa:207有些是hsa:207, hsa:10000还有些是path:hsa04150。旧版搜索正则/AKT1/i只匹配name字符串而AKT1实际在 KEGG 中注册为hsa:207其官方 symbol 是AKT1但不在name字段里。解决启用「Symbol 映射模式」。在index.html中找到input idsearch-input在其后添加开关labelinput typecheckbox iduse-symbol-search Use gene symbol search/label并在render.js的搜索函数中当该 checkbox 选中时调用fetch(https://rest.kegg.jp/conv/genes/hsa:207)获取 symbol 映射需联网缓存到symbolMap {207: AKT1}再用symbolMap做二次匹配。此功能在 v1.4 中已内置。4.5 现象导出的 SVG 文件在 Illustrator 中打开后文字模糊、线条断裂原因SVG 导出时未嵌入字体。Viewer 使用系统默认字体如sans-serif导出的 SVG 中文字为text标签依赖本地字体渲染。Illustrator 若无对应字体会替换为其他字体导致错位。解决导出前强制转文字为路径。在render.js的saveAsSvg()函数末尾插入以下代码需引入canvg库或改用svg-to-pdfkit// 更简单方案用浏览器原生打印为 PDF再转 SVG window.print(); // 触发打印对话框选择“另存为 PDF”或手动在导出的 SVG 文件中用文本编辑器全局替换text.*?(.*?)/text为path dM.../ !-- 实际需用 fontforge 或在线工具转换 --血泪经验日常交付直接用「打印为 PDF」最稳。从那以后我每次导图给导师都强制走一遍CtrlP → Save as PDF → Adobe Acrobat → Export to SVG多两步但永不翻车。5. 进阶技巧用自定义基因列表批量高亮把 Viewer 变成你的通路分析工作台KEGG Network Viewer 的真正价值不在“看图”而在“用图”。当你有一批 RNA-seq 差异基因比如 32 个上调、18 个下调如何快速映射到 mTOR 通路上直观看出哪些环节被激活、哪些被抑制这就是本章要落地的实战技巧用 CSV 表格驱动节点高亮实现通路级表达模式可视化。5.1 准备输入数据CSV 格式规范与字段说明你需要一个纯文本 CSV 文件编码为 UTF-8无 BOM首行为表头。Viewer 仅识别三列gene_idlog2fcpvaluehsa:55662.341.2e-05hsa:207-1.893.4e-04gene_id必须是 KEGG 标准 ID格式为org:xxx如hsa:5566,mmu:12345。不支持AKT1或ENSG00000100000log2fclog2 转换后的 fold change 值正数为上调负数为下调pvalue可选仅用于后续筛选如只高亮pvalue 0.05的基因。提示可用 Excel 保存为「CSV UTF-8逗号分隔」或用pandas.DataFrame.to_csv(deg.csv, indexFalse)生成。避免用 WPS 或 Numbers它们可能插入隐藏字符。5.2 页面操作上传 CSV 并配置高亮规则在index.html页面点击「Upload DEG CSV」按钮选择你的deg.csv页面底部出现「Highlight Settings」面板「Up-regulated color」选择上调基因颜色默认#4CAF50绿「Down-regulated color」选择下调基因颜色默认#f44336红「Min p-value」填0.05则只有pvalue 0.05的基因被高亮「Size scale」滑块调节节点大小log2fc绝对值越大圆圈越大范围 8–24px。点击「Apply Highlight」所有匹配的基因节点立即按规则变色、缩放。5.3 技术实现CSV 解析与 SVG 动态样式注入该功能由js/deg-highlighter.js实现核心逻辑分三步CSV 解析用PapaParse库已内置读取文件生成数组[{gene_id: hsa:5566, log2fc: 2.34, pvalue: 1.2e-05}, ...]ID 匹配遍历 SVG 中所有circle读取其>node.style.fill isUp ? upColor : downColor; node.style.stroke white; node.style.strokeWidth 2; const size Math.max(8, Math.min(24, 8 Math.abs(log2fc) * 2)); node.setAttribute(r, size/2); // circle 半径5.4 高级应用导出带高亮的 SVG 用于论文插图导出的 SVG 文件需满足期刊要求如 Nature 要求 300dpi TIFFCell 接受 PDF/SVG。Viewer 导出的 SVG 已含所有高亮样式但需两处微调移除交互脚本用文本编辑器打开导出的.svg文件删除script标签及其内容从script到/script保留纯图形嵌入字体若期刊要求文字可编辑用 Inkscape 打开 SVG →Text → Convert to Path将所有text转为path。最终效果一张带颜色编码红/绿、大小编码log2fc、清晰坐标、无交互的出版级通路图。我曾用此法为某模拟项目X 的论文 Figure 3A 生成插图审稿人直接说“通路映射非常清晰”没提任何格式问题。从那以后我每次分析新数据都强制走一遍「RNA-seq DEG → CSV → Upload to KEGG Network Viewer → Apply Highlight → Export SVG → Inkscape 调色 → 插入论文」省去 Cytoscape 导入、映射、配色、导出八步流程。希望帮到你。本文还有配套的精品资源点击获取