企业官网建设流程全解析

简介：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 的 KGML（KEGG Markup Language）XML 文件，解析节点坐标、反应箭头、基因/化合物映射关系，并在本地浏览器中渲染成可缩放、可拖拽、可搜索、可点击展开注释的交互式网络图。整个过程不依赖后端服务、不上传数据、不调用外部 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?entry=hsa04150&format=kgml
该文件不是图片，而是一个结构化描述：定义了<entry>（节点：基因、化合物、反应）、<relation>（调控关系）、<reaction>（生化反应）、<component>（复合物组成）等标签，并附带x,y,width,height坐标信息（由 KEGG 手动绘制）。Viewer 的核心 JS 逻辑（主文件kgml-parser.js）并不做坐标重排或力导向布局，而是严格忠实还原 KGML 中的原始位置——这是它轻量、确定、可复现的关键。例如：

<entry id="1" name="hsa:5566" type="gene" link="https://www.kegg.jp/dbget-bin/www_bget?hsa:5566"> <graphics name="MTOR" fgcolor="#000000" bgcolor="#FFFFFF" x="390" y="220" width="45" height="17"/> </entry> <relation entry1="1" entry2="2" type="ECrel"> <subtype name="activation" value="activation"/> </relation>

Viewer 解析时会：

• 提取entry的id,name,type,x,y，生成 SVG<circle>或<rect>元素；
• 对relation标签，根据entry1和entry2的坐标，用<line>或<path>绘制带箭头的连接线；
• 将link属性转为节点 tooltip 中的可点击 URL；
• name="hsa:5566"被解析为标准 KEGG gene ID，用于后续映射（如用户上传自己的差异基因列表）。

提示：KGML 坐标是绝对像素值，非比例值。这意味着 Viewer 渲染效果与 KEGG 官网图完全一致，但放大后文字不会自动缩放——这是设计选择，不是 bug。若需高清导出，必须用 SVG 原生缩放（见第 5 章）。

2.2 SVG 渲染层：为什么不用 Canvas 或 D3 force layout？

Viewer 选用原生 SVG（而非 Canvas 或 D3 的力导向图）有三个硬性理由：
第一，保真度优先。KGML 坐标是人工校准的生物学意义布局（如上游信号在左、下游效应在右），强行用算法重排会破坏通路阅读逻辑；
第二，交互粒度可控。SVG 元素支持原生addEventListener('click')，每个<circle>可绑定独立事件（如点击弹出基因详情、右键复制 ID），Canvas 需手动做坐标映射，开发成本翻倍；
第三，导出即用。SVG 是矢量文本格式，直接document.querySelector('svg').outerHTML即可获取完整代码，粘贴进 Illustrator 或 Inkscape 编辑，无需额外转换。

实际渲染流程在render.js中体现为三层嵌套：

1. 创建<svg>根元素，宽高设为max(x+width)+50（留白边）；
2. 遍历 parsed KGML entries，对type="gene"生成<circle r="8">，type="compound"生成<rect rx="4">，type="reaction"生成<path d="M...">；
3. 遍历 relations，用getBBox()获取两端节点坐标，绘制<line>并添加<marker>箭头。

这种“所见即所得”的策略，让开发者能一眼看懂渲染逻辑，也方便你按需定制——比如把所有type="glycan"的节点改成紫色菱形，只需改一行 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」按钮：

  1. 输入hsa04150（mTOR 通路），点击按钮；
  2. 观察浏览器控制台（F12 → Console）：应出现✅ Loaded KGML for hsa04150和📊 Parsed 127 entries, 89 relations；
  3. 页面中央应渲染出一张带基因节点（圆圈）、化合物（矩形）、反应（六边形）和箭头连线的图；
  4. 尝试鼠标滚轮缩放、按住空格拖拽、点击任意基因圆圈——应弹出 KEGG 基因页面链接；
  5. 在搜索框输入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 id="svg-container"></div>，或把<script>放到了<head>里且没加defer。
  解决：检查index.html，确保<div id="svg-container"></div>存在于<body>内；所有<script src="...">标签必须放在</body>之前，或加defer属性：

  <script defer src="js/kgml-parser.js"></script> <script defer src="js/render.js"></script>

  4.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?entry=hsa04150&format=kgml，右键“另存为”保存为hsa04150.kgml，再用页面「Upload KGML」按钮上传；
  • ⚠️ 临时方案：Chrome 启动时加参数--disable-web-security --user-data-dir=/tmp/chrome_dev_test（仅测试用，勿长期开启）。

  4.3 现象：通路图渲染出来，但所有节点挤在左上角（坐标全为 0）

  原因：KGML 文件版本不兼容。KEGG 在 2022 年后更新了 KGML 格式，新增<graphics>标签嵌套层级（如<graphics><position x="390" y="220"/></graphics>），而旧版 Viewer 只认<graphics x="390" y="220">。
  解决：升级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 id="search-input">，在其后添加开关：

  <label><input type="checkbox" id="use-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 d="M..."/> <!-- 实际需用 fontforge 或在线工具转换 -->

  血泪经验：日常交付直接用「打印为 PDF」最稳。从那以后我每次导图给导师，都强制走一遍Ctrl+P → 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_id	log2fc	pvalue
  hsa:5566	2.34	1.2e-05
  hsa:207	-1.89	3.4e-04

  • gene_id：必须是 KEGG 标准 ID，格式为org:xxx（如hsa:5566,mmu:12345）。不支持AKT1或ENSG00000100000；
  • log2fc：log2 转换后的 fold change 值，正数为上调，负数为下调；
  • pvalue：可选，仅用于后续筛选（如只高亮pvalue < 0.05的基因）。

  提示：可用 Excel 保存为「CSV UTF-8（逗号分隔）」，或用pandas.DataFrame.to_csv('deg.csv', index=False)生成。避免用 WPS 或 Numbers，它们可能插入隐藏字符。

  5.2 页面操作：上传 CSV 并配置高亮规则

  1. 在index.html页面，点击「Upload DEG CSV」按钮，选择你的deg.csv；
  2. 页面底部出现「Highlight Settings」面板：
     • 「Up-regulated color」：选择上调基因颜色（默认#4CAF50绿）；
     • 「Down-regulated color」：选择下调基因颜色（默认#f44336红）；
     • 「Min p-value」：填0.05，则只有pvalue < 0.05的基因被高亮；
     • 「Size scale」：滑块调节节点大小，log2fc绝对值越大，圆圈越大（范围 8–24px）。
  3. 点击「Apply Highlight」，所有匹配的基因节点立即按规则变色、缩放。

  5.3 技术实现：CSV 解析与 SVG 动态样式注入

  该功能由js/deg-highlighter.js实现，核心逻辑分三步：

  1. CSV 解析：用PapaParse库（已内置）读取文件，生成数组[{gene_id: 'hsa:5566', log2fc: 2.34, pvalue: 1.2e-05}, ...]；
  2. 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 TIFF，Cell 接受 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 导入、映射、配色、导出八步流程。希望帮到你。

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