简介：基于 3Dmol.js 的分子可视化前端项目压缩包，为前端开发者、科研人员和化学教育工作者提供可直接运行的示例工程。项目利用 WebGL 硬件加速，在浏览器中实现原子、化学键及大分子结构的流畅渲染，支持 PDB、MOL、SDF 等常见格式的解析与显示；交互层面涵盖旋转、平移、缩放、高亮、视角切换及动画模拟，能够满足课程教学、数据演示和工具原型开发等多种场景。压缩包整体约 136MB，目录结构经过整理，便于查找源码与配置资源，部署后即可启动体验。目前已有 341 人学习使用。内容重点覆盖 WebGL 渲染原理、分子数据解析、3D 场景构建、用户交互定制、动画更新、性能优化与响应式设计等关键实践，读者可借此快速掌握 3Dmol.js 的核心用法，并以此为模板扩展出更复杂的分子展示应用。
1. 3Dmol前端项目：zip包解压后先别写代码，先搞懂它渲染什么
做化学模拟相关的前端展示时，最头疼的一步往往不是画界面，而是怎么把蛋白质或小分子的三维结构搬进浏览器。传统思路是调后端渲染引擎出图，再丢给前端显示，链路长且每换一个视角就要重新生成图片。这个名为"前端项目-3Dmol"的压缩包，走的是完全相反的路线：依赖3Dmol.js这个纯前端WebGL分子可视化库，让浏览器直接拿着原子坐标文件（PDB、SDF、MOL2等）在Canvas里绘制三维结构，旋转、缩放、选中残基全部在客户端完成，不需要后端参与渲染。
打开zip包后你会发现，这不是一套需要部署的服务，而是一个可以被任何静态页面托管的前端工程。适合谁？适合正在做结构生物信息学平台、化学课件、药物筛选工具的前端开发者，也适合有分子数据但不知道怎么在网页上呈现的研究人员。这一章先不急着碰代码，我们把它的结构和能力边界对齐，后面照着改就快得多。
2. 拆开这个前端工程：3Dmol.js的目录结构、数据流与两种集成方式
2.1 解压后先看这三个文件：入口、依赖与数据
一个典型的3Dmol前端项目解压后，核心文件很少。我拿到这类zip包，习惯先按"入口HTML、库文件、数据文件"三个维度清点，避免被无关的构建配置干扰。通常看到的布局是：
frontend-3dmol/ ├── index.html # 页面入口，加载库和初始化viewer ├── js/ │ ├── 3Dmol-min.js # 3Dmol.js压缩版，整个渲染引擎 │ └── main.js # 业务脚本，负责建viewer、加载分子 ├── data/ │ ├── protein.pdb # 蛋白质结构文件 │ └── ligand.sdf # 小分子结构文件 └── css/ └── style.css # 页面布局与画布尺寸控制先解释这个目录为什么这样设计。3Dmol-min.js是整个包的核心依赖，它把WebGL封装成了操作分子的高层API，不依赖任何后端服务；index.html负责建立页面骨架；main.js是你要改的代码，加载数据、设置样式、绑定交互都在这里。data目录放结构文件，也可以放远程URL。还有一种情况是zip里只有压缩后的JS和示例数据，没有main.js，这时你要自己写初始化脚本，我会在第3章给出可直接复用的模板。
2.2 3Dmol.js的渲染管线：从原子坐标到屏幕像素
搞明白3Dmol.js的渲染过程，后面调参才不会像碰运气。它的流程可以简化为四个阶段：解析分子文件、构建原子模型、应用样式着色、交给WebGL光栅化。解析阶段把PDB或SDF文本转成内部的原子和键对象；样式的核心是由setStyle方法决定每个原子和键长什么样子；最后WebGL着色器把球棍模型或卡通模型画到Canvas上。
这里有个关键认知：3Dmol.js渲染的是你给定的坐标数据，不会自动做能量最小化或构象搜索。这意味着你从PDB数据库下载的静态结构，展示的是实验测定时的构象，而不是分子在实际环境中的动态形态。做展示没问题，做对接模拟就得配合后端计算结果。我见过有开发者拿3Dmol.js显示对接后的构象，但发现坐标没更新，原因就是把静态PDB当成了最终结果，没意识到数据来源本身决定展示上限。
另一个容易被忽略的点是，3Dmol.js对分子文件的解析是"宽容但有限"的。它支持PDB、MOL/SDF、XYZ、MOL2等常见格式，但不是每种格式的全部字段都支持。比如PDB文件里的晶体学信息、REMARK记录这类非坐标内容会被忽略。如果发现某个原子的颜色或位置不对，优先怀疑文件格式是否有非标准字段，而不是急着改代码。
2.3 两种集成方式：本地静态引入与npm模块化
这个zip项目里如果只有静态资源，说明设计者希望你用传统script标签引入。这也是我推荐新手先采用的方式，因为不用处理打包配置，逻辑链条一目了然。3Dmol-min.js挂载一个全局对象$3Dmol，直接拿来用就是。
如果项目已有完善的npm构建链，可以考虑用npm上的3dmol包。两种方式的选型理由很简单：静态引入适合快速验证和纯展示型页面，npm集成适合需要和React/Vue组件状态联动的复杂应用。我在某个模拟项目X里先用静态引入跑通渲染，后面要加多视图联动时才迁到了npm方式。迁移成本主要在处理生命周期——npm模块里viewer实例要手动销毁，而静态页面刷新即重置。
// npm方式初始化一个viewer实例 import * as $3Dmol from '3dmol'; const viewer = $3Dmol.createViewer('elementId', { backgroundColor: 'white' });这段代码里的createViewer第一个参数是页面元素的ID，第二个是配置对象。配置对象里最常用的是背景色、宽高。注意，npm方式必须确保目标元素在DOM树中已经存在，否则viewer创建会静默失败。静态引入和npm方式本质上是同一套API，所以后续章节的代码对两种方式都适用，只是引入方式不同。
3. 本地跑通最小3Dmol项目：HTTP服务启动与第一个分子视图
3.1 用HTTP服务器启动项目，别直接双击HTML
这是3Dmol项目最大的坑，也是新手最容易卡住的一步。直接双击index.html在浏览器打开，页面可能一片空白，控制台报CORS错误或WebGL纹理加载失败。原因是WebGL在处理本地文件时有安全限制，而且浏览器默认禁止从file://协议下加载外部数据文件。解决方案是一律通过HTTP协议访问。
我一般会先在zip解压目录下起一个静态服务器。如果你装了Python，最常见的做法是：
cd frontend-3dmol python3 -m http.server 8000然后在浏览器里访问http://localhost:8000。这个命令的解释：python3 -m http.server会启动一个简单的静态文件服务，8000是端口，可以按需改成8080或3000。注意不要漏了cd这一步——服务器的工作目录决定你能访问哪些文件，如果把服务器开在上级目录，访问路径也要相应带上子目录名。另一种常见做法是用Node的npx serve，效果相同，选熟悉的一种即可。
3.2 最小HTML模板：加载PDB并设定视图
跑通HTTP服务后，写一个最小的展示页面。下面这个模板是我通常在main.js里起步用的，去掉所有花哨功能，只负责把分子画出来并支持鼠标旋转缩放：
<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>3Dmol最小示例</title> <style> #mol-container { width: 600px; height: 450px; position: relative; } </style> <script src="js/3Dmol-min.js"></script> </head> <body> <div id="mol-container"></div> <script> let viewer = $3Dmol.createViewer('mol-container', { backgroundColor: '#f0f0f0' }); fetch('data/protein.pdb') .then(res => res.text()) .then(data => { viewer.addModel(data, 'pdb'); viewer.setStyle({}, { cartoon: { color: 'spectrum' } }); viewer.zoomTo(); viewer.render(); }); </script> </body> </html>代码逻辑拆开讲。createViewer创建viewer实例，容器尺寸由CSS控制，config里的背景色直接作用于3D场景。fetch从HTTP服务器取PDB文件的文本内容，这一步必须在HTTP环境下工作，算是对3.1节的呼应。addModel(data, 'pdb')告诉解析器这段文本是PDB格式，数据会被解析成内部模型。setStyle({}, { cartoon: { color: 'spectrum' } })的空对象{}表示选中所有原子，使用卡通样式并让颜色按残基位置渐变。zoomTo()把相机自动缩放到包住整个分子的位置，render()手动触发一次绘制。
参数怎么调整？看你的展示目标。如果看重原子细节，把cartoon换成stick或sphere；如果希望分子整体带点科技感，背景色可以设为深灰色#222并把球的颜色改为白色。要提醒的是，不同的样式渲染成本差异大，球棍模型在原子多时性能压力明显，第5章会仔细讲。
3.3 参数调整：样式、背景色与视角
把样式当成一个树形配置来理解，能少走弯路。setStyle第一层是"选哪些原子"，第二层是"画成什么样子"，可以组合出很丰富的效果。比如让蛋白质骨架用卡通表示，让配体小分子用球棍表示：
viewer.setStyle({ model: 0 }, { cartoon: { color: 'spectrum' } }); viewer.setStyle({ resn: 'LIG' }, { stick: { radius: 0.25, color: '#cc0000' } });第一句的{ model: 0 }选中文档里的第一个模型，用卡通样式；第二句的{ resn: 'LIG' }选中所有残基名为LIG的原子，用球棍样式并把半径缩小到0.25。这里的resn是残基名过滤，如果你不知道配体的残基名，可以先跑一个查询API打印模型里所有残基名，再回填这个值。color参数支持颜色名和十六进制，用#cc0000能精确控制颜色。
视角控制同样藏在参数里。zoomTo之前可以先用viewer.setView([x, y, z, radius])直接指定相机朝向和缩放级别，也可以用viewer.rotate(90, 'x')来做旋转。更实用的做法是先让页面自动按分子大小取景，再由用户手动操作，也就是模板里zoomTo()的位置。如果希望打开页面就固定一个角度，我习惯在render()前调用：
viewer.setView([0, 0, -100, 0]);这个数组的前三个值是相机位置，第四个是朝向目标点与相机的距离。参数调起来靠视觉反馈，一次改一个变量观察画面变化即可。常见翻车点是把前三个值当成旋转角度，实际是空间坐标，改完画面飞走属于正常现象，慢慢回调就行。
4. 给3Dmol加交互：残基高亮、距离测量与多格式加载
4.1 点击选中残基并高亮
静态展示只是第一步，交互才真正有价值。最常见的交互是点击某个残基或原子，让它从整体中凸显出来。3Dmol.js原生支持点击事件，需要在创建viewer时打开clickable配置，然后注册回调函数：
let viewer = $3Dmol.createViewer('mol-container', { backgroundColor: '#f0f0f0', clickable: true, }); viewer.setClickHandler(function(atom, viewer) { if (!atom) return; // 高亮这个残基 viewer.setStyle({ resi: atom.resi, chain: atom.chain }, { stick: { radius: 0.3 } }); viewer.render(); console.log('点击残基:', atom.resi, atom.resn); });这里的关键逻辑：点击后从回调参数atom里拿到残基序号resi和链标识chain，再用这两个字段构造一个选区，单独赋予高亮样式。chain这个字段容易被忽略，如果分子有多个链且残基序号在链之间重复，不加链过滤会高亮所有同名残基，造成视觉干扰。所以我的习惯是点击回调里一定同时用resi和chain构造选区，而不是只筛resi。
点击高亮还要考虑"取消选中"。一个简单策略是再点一次同一个残基就恢复原始样式。做法是记录上一次的残基标识，比较后决定执行高亮还是还原。这个逻辑放在setClickHandler里实现，涉及状态管理，建议用一个全局变量存previousSelection，代码虽然多几行，但交互手感会舒服很多。
最后提醒一点：设置clickable: true后，viewer默认把鼠标左键的拖拽行为从旋转改成了点击选区。也就是说用户按住拖拽不再旋转分子，这会显著影响操作体验。我一般把点击和拖拽分开：clickable: true配合点击高亮，同时保留拖拽旋转。3Dmol.js的默认行为是单击触发点击、拖拽依然旋转，如果你发现拖拽也变成了画框选择，需要检查是不是手动绑定了mousedown事件干扰了默认逻辑。
4.2 测量两个原子间的距离
做药物化学或酶催化展示时，测量距离是刚需。3Dmol.js没有内置一把"尺子"，但你可以自己实现：先取到两个原子的坐标，再用三维空间距离公式计算。坐标从哪里来？在点击回调里，atom.x、atom.y、atom.z就是当前点击位置的原子坐标，可以直接读取：
let atomA = null; viewer.setClickHandler(function(atom) { if (!atom) return; if (!atomA) { atomA = atom; viewer.setStyle({ serial: atom.serial }, { sphere: { scale: 1.2, color: 'yellow' } }); viewer.render(); return; } // 拿到第二个原子后算距离 let dx = atom.x - atomA.x; let dy = atom.y - atomA.y; let dz = atom.z - atomA.z; let dist = Math.sqrt(dx*dx + dy*dy + dz*dz).toFixed(2); // 画一条线表示测量范围 viewer.addLine({ x: atom.x, y: atom.y, z: atom.z }, { x: atomA.x, y: atomA.y, z: atomA.z }, { color: 'red', linewidth: 2 }); viewer.render(); atomA = null; });这段代码的思路：第一次点击记录原子A并把它的球体放大标记；第二次点击拿到原子B，计算欧几里得距离，然后用addLine在两点之间画红线，视觉上直观对应距离。注意addLine需要两个坐标对象，格式是{x, y, z}，第三个参数是线样式。距离单位由PDB文件决定，PDB标准里坐标单位是埃（Å），所以算出来的数值直接就是埃。
一个容易被忽略的坑：atom.serial是原子在模型中的序号，点击事件里用它做唯一标识是安全的。但如果你在点击后重新设置了样式，serial不会改变，可以放心用来恢复原样式。计算距离前最好校验两个原子是否来自同一个模型，否则不同模型坐标可能处于不同参考系，算出的距离没有意义。严谨的做法是同时比对atom.model字段。
4.3 SDF/MOL2等小分子格式的加载与展示
蛋白质用PDB格式，小分子配体更多是SDF或MOL2格式。3Dmol.js对SDF的支持很成熟，加载方式几乎和PDB一样，但需要把格式字符串传给addModel的第二个参数。区别在于小分子通常没有链和残基的概念，所以样式筛选逻辑要改用原子名或分子名。
fetch('data/ligand.sdf') .then(res => res.text()) .then(data => { viewer.addModel(data, 'sdf'); viewer.setStyle({}, { stick: { radius: 0.2 } }); viewer.zoomTo(); viewer.render(); });格式参数'sdf'是关键，如果写成'pdb'会解析失败或元素错乱，画面里出现一堆乱线。加载MOL2时参数改为'mol2'，逻辑完全相同。小分子的展示样式建议用stick或ballAndStick，球棍结合能看清原子类型和键的连接方式，sphere会因原子过多显得拥挤。
多格式混搭时，最稳妥的做法是按模型索引区分样式。addModel会返回一个模型对象，也可以从viewer.getModel(0)获取。给蛋白质和小分子分别设样式，用模型索引作为选区：
viewer.addModel(proteinData, 'pdb'); viewer.addModel(ligandData, 'sdf'); viewer.setStyle({ model: 0 }, { cartoon: { color: 'spectrum' } }); viewer.setStyle({ model: 1 }, { stick: { radius: 0.2, color: '#ff6600' } }); viewer.zoomTo(); viewer.render();model: 0和model: 1把两套样式分别作用于两个模型。这里有个隐含规则：样式设置是按"任何匹配选区的模型"生效的，所以如果用resn: 'LIG'这种名字筛选，一定要确认配体里残基名的确叫LIG，否则样式不会作用在任何原子上。调试时先用viewer.getModel(1).atoms().length确认模型里有多少原子，能快速排除数据未加载的问题。
5. 3Dmol项目避坑指南：五个让画面空白或卡死的常见问题
5.1 现象：双击HTML文件打开后画面空白，控制台报错
这是3Dmol前端项目最高频的翻车现场。双击index.html，页面标题正常渲染，但分子区域一片空白，打开浏览器控制台会看到Access to fetch at 'file:///...' from origin 'null' has been blocked by CORS policy或类似的WebGL安全错误。
原因在于浏览器把file://协议下的页面当成一个隔离的"null"源，出于安全策略禁止它fetch本地文件。同时WebGL的纹理加载对本地文件也有额外限制，双重作用下分子根本进不来。解决方式就在3.1节：启动一个HTTP静态服务，通过http://localhost访问。这不是什么玄学，是浏览器安全模型在起作用，养成用HTTP服务预览页面的习惯后，这类报错基本可以杜绝。
5.2 现象：页面通过HTTP打开，但加载远程PDB一直转圈超时
有时数据文件不放在本地，而是从某个在线数据库拉取。页面能打开，但分子迟迟不出现，控制台提示Mixed Content或跨域拒绝。原因有两类：第一类是当前页面是HTTPS协议，却请求了HTTP协议的远程数据，浏览器默认阻止混合内容；第二类是远程服务器不返回Access-Control-Allow-Origin，跨域拿不到数据。
解决思路按顺序排查：先确认页面协议和数据协议一致，尽量都走HTTPS。再确认远程服务是否允许跨域，如果不允许，就改用后端代理——把数据请求转发到自己的服务器，由后端去远端取数据再返回给前端。我一般会在项目里加一个简单的代理接口，前端只请求同源路径，根除跨域问题。还有一种快速验证的方法：把远程PDB下载到本地data目录，确认内容一致后加载本地文件，至少能排除数据本身损坏的可能。
5.3 现象：代码没问题，但页面提示WebGL不支持或初始化失败
有些低配电脑或虚拟机浏览器里，createViewer直接抛异常，提示WebGL is not supported或Error creating WebGL context。原因不是代码问题，而是浏览器没有开启硬件加速，或系统显卡驱动不支持当前浏览器所需的WebGL版本。3Dmol.js依赖WebGL 1.0以上，大多数现代浏览器默认开启，但虚拟机、远程桌面环境里常常是软件渲染，兼容性差。
解决方法是先检查浏览器设置里"硬件加速"是否开启，再去https://get.webgl.org跑一下检测页。如果确实不支持，放弃在该环境展示3D，给页面加一个静态图片兜底。我通常在初始化viewer外面包一个try/catch，捕获异常后把容器换成一张预渲染的分子截图。这个退化策略在生产环境尤其重要，不然你永远不知道用户的浏览器能跑成什么样。
5.4 现象：大分子（比如整个病毒衣壳）渲染后卡成幻灯片
分子原子数上万以后，默认的球棍模型会让页面帧率暴跌。原因很直观：每个球和每根棍都是WebGL绘制的几何体，原子数越多，GPU需要处理的顶点数越多。蛋白质的PDB动辄几千原子，全部用sphere样式几乎等同于给GPU上刑。
解决方式分三个层次。第一，样式降级，把原子细节换成cartoon，卡通样式只画主链骨架，渲染开销只有球棍的几十分之一。第二，用viewer.setStyle只对需要看的部分应用高细节样式，其余部分保持低细节。第三，通过viewer.setQuality降低渲染质量，关闭抗锯齿或减少光照计算。我做过一个模拟项目X的展示页，处理一个约5万原子的复合物，最后采用的方案是整体卡通加上配体球棍，帧率稳定在操作流畅的范围内。
5.5 现象：卡通样式里螺旋和片层不显示，只有一条细线
用cartoon样式渲染蛋白质时，有时看到的不是漂亮的α螺旋和β折叠，而是一条光秃秃的主链。原因往往是这个PDB文件里没有记录二级结构信息。3Dmol.js的卡通渲染依赖解析器从文件里读取的二级结构分配，如果PDB缺少相关字段，它只能把主链画成连线。
解决办法分两步。先确认PDB文件里SEQRES和HELIX/SHEET记录是否完整，很多从某些工具导出的PDB会丢失这些字段。如果文件确实没有，可以先用外部工具重新计算二级结构再导出，或者接受线框表示，把展示重点放在侧链原子和配体上。另一个折中方案是改用tube样式，它不管二级结构信息，默认把主链画成光滑的管状，视觉上也美观。可配置的颜色方案spectrum也可以继续用，不影响效果。
6. 进阶：把3Dmol装进现代前端框架，并导出PNG截图
6.1 在Vue/React里挂载viewer实例
用框架时最核心的问题是生命周期。viewer实例绑定在具体DOM元素上，组件卸载时如果不销毁，WebGL上下文会泄漏。以Vue为例，在mounted里创建viewer，在beforeUnmount里调用viewer.clear()释放资源。React也类似，在useEffect的清理函数中做同样操作。
// Vue组件示例 import * as $3Dmol from '3dmol'; export default { mounted() { this.viewer = $3Dmol.createViewer(this.$refs.container, { backgroundColor: 'white' }); this.loadMolecule(); }, beforeUnmount() { if (this.viewer) { this.viewer.clear(); this.viewer = null; } } }关键点在于this.$refs.container必须已经渲染完成，所以不能在created里初始化。clear()会释放WebGL资源，防止切页面后浏览器标签页变卡。
6.2 导出当前视图为PNG图片
做报表或课件时，经常需要把分子视图存成图片。3Dmol.js提供了内置的截图方法，一行代码就能拿到当前Canvas的内容：
let canvas = viewer.png(); let link = document.createElement('a'); link.download = 'molecule.png'; link.href = canvas.toDataURL('image/png'); link.click();原理是viewer内部维护了一个Canvas画布，png()返回这个画布，再用toDataURL转成PNG数据URL并触发下载。如果你希望图片带透明背景，在创建viewer时把backgroundColor设为'transparent'，这样得到的就是透明底的图。但要注意，透明背景下某些颜色方案的可读性会下降，建议导出前确认最终使用场景。
6.3 一个技巧：自动旋转与结构对比
一个很出效果的加分项是让分子自动缓慢旋转，适合放在大屏或演示页面上。viewer.spin()即可启动，viewer.spin('y', 0.02)控制旋转轴和速度。结束旋转调用viewer.spin()不传参数也能停。
停顿一下，说个教训。我在某个展示页里加了自动旋转，结果用户反馈页面CPU占用居高不下。排查后发现是旋转回调里反复触发render()导致渲染循环满载。正确做法是只调用一次spin()，让内部渲染循环自己驱动，不要在外部再加定时器或动画帧。这类性能问题往往不是3Dmol本身慢，而是调用方式没对齐内部实现造成的。另外，自动旋转和截图搭配要小心，截图前先停转，否则导出的图可能是旋转中途的半透明状态。
这几年用3Dmol.js做前端分子可视化的经验，总结下来就一句话：先确认数据来源、再调样式、最后加交互。顺序反了会陷入反复改代码的泥潭。数据格式不对，样式再精细也是白搭。希望帮到你。
本文还有配套的精品资源，点击获取
