界面交互这块，在三维项目里一直是个容易被低估的活儿。很多人把渲染、模型、光照调得漂漂亮亮，结果一到参数调节、场景切换、调试面板就抓瞎——要么自己手写一堆原生 DOM 控件浮在 canvas 上面，样式和三维场景割裂得厉害；要么干脆硬编码，改个参数就得重新跑一遍构建。我最早做三维可视化项目那会儿也是这么过来的，后来接触到 three.js 生态里的 gui.js 这一类轻量界面库，才算是把“调参”这件事从苦力活变成了顺手操作。这篇就围绕 three 场景下界面交互 gui.js 库的使用，把我这几年踩过的坑、总结的套路、能直接抄的代码，一次性讲透。
先说清楚它是什么、能干嘛。gui.js 本质上是一个跑在浏览器里的轻量级图形界面面板库，最常见的形态是右上角那一小块可折叠的参数控制面板：滑块调数值、颜色选择器换色调、下拉框切模式、按钮触发动作、文件夹分组收纳。它和 three.js 配合的核心价值在于——把场景里那些“需要反复试”的参数（相机位置、材质粗糙度、光照强度、粒子数量、后处理强度）暴露成可交互控件，改一下立刻在画面上看到反馈，不用改代码、不用刷新页面。适合谁看？三维方向的前端、做数据可视化的同学、搞创意编程的设计师、以及任何需要在网页里快速搭一个调试面板或配置面板的人。哪怕你 three 刚入门，只要会写基本的 JavaScript，这篇里的步骤都能照着跑起来。
1. 整体设计思路与选型考量
1.1 为什么三维项目特别需要一套界面库
三维场景和普通网页表单有个本质区别：它的参数是“连续且相互耦合”的。你调一个环境光强度，材质的观感会变；你改相机 fov，画面的透视关系会变；你动粒子系统的速度系数，整个动画的节奏都会跟着变。这种参数之间的联动，决定了三维调试天然需要“实时反馈 + 快速迭代”的交互方式。手写 DOM 表单不是不行，但你会陷入无穷无尽的样式适配、事件绑定、状态同步里，一个滑块要写 change 监听、要处理数值格式化、要防止拖拽时触发场景重渲染的性能抖动，写十个控件就够你喝一壶。
gui.js 这类库解决的正是这个“重复造轮子”的问题。它把常用控件封装好，你只需要声明“这个对象的这个属性，用滑块控制，范围 0 到 10，步长 0.1”，剩下的 UI 渲染、事件绑定、数值回写它全包了。更关键的是它的“对象绑定”设计——控件直接读写你传入对象的属性，你不需要手动做双向同步。这个设计看起来简单，实际用起来非常省心：场景里有个params对象存着所有可调参数，gui 面板绑上去，用户拖动滑块，params里的值自动变，你的渲染循环每帧读params就行，数据流是单向清晰的。
从选型角度讲，市面上做这类面板的库不止一个，但 gui.js 这一支的优势在于体积小（压缩后几十 KB 量级）、零依赖、API 极简、主题可定制。它不追求花哨的动画和复杂的布局系统，就是老老实实做“参数面板”这一件事，反而在三维调试这个场景里特别趁手。我对比过几种方案，下面这张表是我个人在实际项目里的取舍记录，供参考：
| 方案 | 体积 | 上手成本 | 与 three 配合 | 适合场景 |
|---|---|---|---|---|
| 原生 DOM 手写 | 最小但代码量大 | 高（样式事件全自己来） | 需手动同步 | 控件极少、样式要求极特殊 |
| gui.js 类轻量库 | 小 | 低 | 对象绑定天然契合 | 调试面板、参数配置 |
| 重型 UI 框架组件库 | 大 | 中 | 需桥接状态 | 完整业务后台、复杂表单 |
| 三维引擎自带调试工具 | 中 | 低 | 深度集成 | 引擎内快速调试 |
选 gui.js 的核心逻辑就一句话：调试面板要的是“快”和“轻”，不是“全”和“美”。你要是做的是一个面向终端用户的正式产品配置页，那确实该用成熟组件库保证可访问性和一致性；但如果是开发期的调参面板、内部工具、创意演示的交互层，gui.js 的性价比几乎无出其右。
1.2 对象绑定模式背后的数据流设计
理解 gui.js 的关键，是理解它的“对象绑定”到底绑的是什么。很多人第一次用会疑惑：我传进去一个对象，它怎么就能改我的值？原理不复杂——gui 内部持有你传入对象的引用，控件变化时直接对这个引用做属性赋值。也就是说，它改的是“同一个对象”，不是副本。这个机制带来一个非常重要的实践结论：你的参数对象应该是场景渲染逻辑的唯一数据源。
我见过不少新手这样写：gui 绑了一个config对象，但渲染循环里读的却是另一套散落的变量，结果拖滑块面板动了、画面没动，然后开始怀疑库有 bug。其实问题出在数据流断了。正确的做法是让渲染循环每帧（或在 change 回调里）去读config上的值，形成“面板改 config → 渲染读 config”的闭环。这个思路和现代前端的状态驱动渲染是一个道理，只不过这里的状态就是一个普通 JS 对象。
再往深一层，对象绑定还支持嵌套。你可以把参数按功能分组，比如config.light、config.material、config.camera，gui 添加文件夹后绑定子对象，面板上就呈现出层级结构。这个设计对三维项目特别友好，因为三维参数天然是按“光照/材质/相机/后处理”分块的。分组不仅让面板更清爽，也让代码组织更清晰——每个模块维护自己的参数子对象，最后汇总到一个根对象上。
1.3 面板与渲染循环的协作节奏
还有一个容易被忽略的设计点：面板交互和渲染循环的节奏配合。三维场景通常是requestAnimationFrame驱动的持续渲染，而面板交互是离散的事件（拖动、点击）。这两者如果处理不好，会出现两种极端：一是每次滑块 change 都触发一次重量级重建（比如重新生成几何体），拖一下卡三秒；二是面板改了值但渲染循环没感知，画面纹丝不动。
我的经验是把参数分成两类区别对待。第一类是“每帧读取型”，比如光照强度、材质颜色、相机参数，这类参数渲染循环每帧都读，面板一改下一帧就生效，无需额外处理，最省心。第二类是“重建触发型”，比如几何体细分段数、粒子总数、后处理开关，这类参数改了需要重建对象或重编译材质，开销大，不能每帧检查。对这类参数，我会在 gui 的onChange回调里做防抖，或者干脆提供一个“应用”按钮，用户调完再点一下统一重建。这个区分是我踩过性能坑之后才想明白的，后面实操章节会给出具体代码。
2. 核心细节解析与实操要点
2.1 参数对象的组织与命名规范
参数对象怎么组织，直接决定了面板好不好用、代码好不好维护。我的习惯是按“渲染管线顺序”来分层：相机 → 光照 → 材质 → 几何 → 后处理 → 全局开关。每一层一个子对象，命名上用语义化的英文短词，避免a、b、p1这种。举个我常用的结构：
const params = { camera: { fov: 50, near: 0.1, far: 1000, autoRotate: true, rotateSpeed: 0.5 }, light: { ambientIntensity: 0.6, directionalIntensity: 1.2, color: '#ffffff' }, material: { roughness: 0.4, metalness: 0.8, wireframe: false }, post: { enabled: true, bloomStrength: 0.8 } };这个结构的好处是，面板分组和代码分层一一对应，找参数不用翻半天。命名上有个小技巧：布尔开关用is/enabled/auto前缀，数值用带单位的语义词（如Intensity、Speed、Strength），颜色用color结尾。这样面板上扫一眼就知道每个控件是干嘛的，不用点开看范围。
注意：参数对象的初始值一定要和场景实际初始状态一致。我见过初始值写 0.5、场景实际用 0.8 的情况，结果面板一加载滑块就“跳”一下，画面跟着突变，很影响体验。初始化时直接从场景对象上读当前值回填到 params，是最稳妥的做法。
2.2 控件类型的选择与参数范围设定
gui.js 支持的控件类型基本覆盖了三维调试的所有需求：数值滑块、数值输入框、颜色选择器、下拉选择、布尔开关、按钮、文本输入。选哪种控件不是随便定的，背后有讲究。
数值参数优先用滑块，但范围和步长的设定直接决定手感。范围太宽，滑块拖一格数值跳一大截，精细调节做不到；范围太窄，稍微一拖就顶到头。我的经验是：范围取“实际可用区间的 1.5 到 2 倍”，步长取“你能感知到差异的最小粒度”。比如材质粗糙度实际用 0 到 1，范围就设 0 到 1、步长 0.01；光照强度实际用 0 到 3，范围设 0 到 5、步长 0.05。步长太小（比如 0.001）会导致滑块拖动时事件触发过于频繁，反而卡顿，这个后面性能章节细说。
颜色参数用颜色选择器控件，注意它返回的是十六进制字符串（如#ff8800），而 three 的Color构造器接受这种格式，直接new THREE.Color(params.light.color)即可，不用手动转换。下拉选择适合“模式切换”类参数，比如后处理模式、相机类型、材质预设，选项用对象形式传入，键是显示名、值是实际值，这样面板显示友好、代码取值准确。
布尔开关适合功能启停，比如线框模式、自动旋转、后处理开关。这里有个细节：布尔开关的onChange回调里如果要做重量级操作（比如切换后处理管线），记得加个防抖或者用“应用”按钮兜底，避免用户快速连点时反复重建。
2.3 文件夹分组与面板层级设计
参数一多，面板就会变成一长条，找东西费劲。gui.js 的文件夹（folder）功能就是解决这个的。按前面说的参数分层，每个子对象建一个文件夹，面板上就是可折叠的分组，清爽很多。文件夹还能嵌套，比如“光照”下面再分“环境光”“平行光”，不过我的建议是嵌套不要超过两层，再深就点得烦了，反而降低效率。
分组时有个实用技巧：把“高频调节”的参数放最上面的文件夹，“低频/一次性配置”的放下面或折叠起来。比如相机和光照是调场景时最常动的，放最前；后处理参数调好了基本不动，可以默认折叠。gui.js 的文件夹支持close()方法默认收起，这个在参数多的时候特别有用。
另外，面板本身的初始位置和宽度也值得调一下。默认位置在右上角，如果你的场景右上角有别的 UI（比如 logo、操作提示），就会重叠。可以通过面板容器的 CSS 或者库提供的定位选项调整。宽度默认偏窄，参数名长一点就显示不全，适当加宽能提升可读性。这些细节看着小，但直接影响你每天对着它调参的心情。
2.4 事件回调的合理使用与副作用控制
gui.js 的控件支持onChange、onFinishChange等回调，用好了能大幅提升体验，用不好就是性能灾难。核心区别在于：onChange是值每次变化都触发（拖动过程中连续触发），onFinishChange是用户松开滑块/结束操作时才触发一次。
这个区别决定了它们的适用场景。轻量操作（改个颜色、调个强度）用onChange，因为要的就是实时反馈；重量级操作（重建几何、重编译材质、请求数据）用onFinishChange，避免拖动过程中反复触发。我早期就犯过在onChange里重建几何体的错，拖一下滑块浏览器直接卡死，后来改成onFinishChange才顺畅。
还有一种情况是“多个参数联动”。比如你调了相机 fov，可能还需要同步更新某个投影矩阵或者 UI 提示。这种联动逻辑写在回调里没问题，但要注意不要在回调里做会再次触发回调的操作，否则容易形成循环。我的做法是把联动逻辑抽成一个独立的applyParams()函数，回调里只调它，函数内部只读不写面板绑定的对象，保证数据流单向。
3. 实操过程与核心环节实现
3.1 环境搭建与库的引入方式
动手之前先把环境理清楚。gui.js 这一支的引入方式有几种：npm 安装后模块化引入、CDN 直接 script 标签引入、或者下载单文件本地引用。做正式项目我推荐 npm 方式，版本可控、能配合打包工具做 tree-shaking；做快速 demo 或教学演示，CDN 或本地单文件更省事，不用配构建。
npm 方式的话，安装后在入口文件里引入并实例化：
import GUI from 'gui.js'; const gui = new GUI({ title: '场景调试面板', width: 300 });实例化时可以传配置项，常用的有title（面板标题）、width（面板宽度）、autoPlace（是否自动放置到页面）。如果你的页面布局特殊，可以把autoPlace设为 false，然后手动把面板的 DOM 挂到指定容器里，这样能精确控制位置。
CDN 方式就是在 HTML 里加一个 script 标签，全局会暴露一个构造器，用法一样。这里提醒一句：引入顺序要在 three 之后，因为面板初始化时往往要读场景对象的值，three 没加载完会报错。我一般把 three 和 gui 的引入都放在 body 末尾或者用模块化的 import，保证依赖顺序正确。
3.2 从零绑定第一个参数控件
环境好了，先绑一个最简单的参数建立信心。假设场景里有个平行光dirLight，我们想调它的强度。第一步在 params 里加light.directionalIntensity，初始值从dirLight.intensity读；第二步用gui.add()绑定：
gui.add(params.light, 'directionalIntensity', 0, 5, 0.05) .name('平行光强度') .onChange((val) => { dirLight.intensity = val; });这几行拆开看：add(对象, 属性名, 最小值, 最大值, 步长)是数值滑块的签名；.name()设置面板上显示的中文名（不设就显示属性名，英文看着累）；.onChange()里把新值写回真正的场景对象。注意这里 params 和 dirLight 是两个对象，回调负责把 params 的值同步到场景对象上——这就是前面说的“面板改 params，回调同步到场景”的闭环。
跑起来之后拖动滑块，应该能看到光照实时变化。如果没反应，先检查三件事：回调有没有写、场景对象引用对不对、渲染循环有没有在跑。这三个是新手最常见的“面板动了画面不动”的原因。
3.3 颜色、下拉、布尔与按钮控件的完整写法
单个滑块跑通后，把其他控件类型过一遍。颜色控件：
gui.addColor(params.light, 'color') .name('光源颜色') .onChange((val) => { dirLight.color.set(val); });注意set()方法接受十六进制字符串，直接传就行。下拉控件：
gui.add(params.post, 'mode', ['无', '泛光', '景深']) .name('后处理模式') .onChange((val) => { switchPostProcessing(val); });数组形式的选项，面板显示数组元素、取值也是元素本身，简单直接。如果显示名和实际值要分离，用对象形式{ '显示名': 实际值 }。布尔控件：
gui.add(params.material, 'wireframe') .name('线框模式') .onChange((val) => { mesh.material.wireframe = val; });按钮控件稍微特殊，它是“触发一次”而不是“绑定值”，写法是gui.add({ action: () => {...} }, 'action').name('重置视角')，把函数包在一个临时对象里绑上去。按钮适合放“重置”“截图”“导出配置”这类一次性动作。
把这些控件组合起来，一个功能完整的面板就成型了。我的习惯是先搭骨架（所有控件绑上、回调先留空或简单赋值），跑通后再逐个补回调逻辑，这样出问题容易定位是哪个控件的事。
3.4 文件夹分组与面板结构的落地
控件多了之后上文件夹。按参数分层建：
const cameraFolder = gui.addFolder('相机'); cameraFolder.add(params.camera, 'fov', 20, 100, 1).name('视野角度'); cameraFolder.add(params.camera, 'autoRotate').name('自动旋转'); const lightFolder = gui.addFolder('光照'); lightFolder.add(params.light, 'ambientIntensity', 0, 2, 0.05).name('环境光强度'); lightFolder.add(params.light, 'directionalIntensity', 0, 5, 0.05).name('平行光强度'); const postFolder = gui.addFolder('后处理'); postFolder.add(params.post, 'enabled').name('启用后处理'); postFolder.close(); // 默认折叠文件夹的add方法和根 gui 一样，只是绑定的对象换成子对象。close()让不常用的分组默认收起，面板首屏更干净。这里有个实操细节：文件夹的创建顺序就是面板上的显示顺序，所以按使用频率排，高频的放前面。
3.5 参数持久化：把调好的值存下来
调了半天参数，刷新页面全没了，这是最让人抓狂的事。解决办法是参数持久化——把 params 序列化存到本地存储，下次加载时读回来。实现不复杂：
function saveParams() { localStorage.setItem('sceneParams', JSON.stringify(params)); } function loadParams() { const saved = localStorage.getItem('sceneParams'); if (saved) { Object.assign(params, JSON.parse(saved)); } }在面板上加个“保存配置”按钮调saveParams，页面初始化时调loadParams再刷新面板显示。注意Object.assign是浅合并，如果 params 有嵌套子对象，需要递归合并或者逐层 assign，否则子对象会被整体替换掉、丢失未保存的字段。这个坑我踩过，存了一次之后发现某些参数变 undefined，就是浅合并惹的祸。
更稳妥的做法是给每个子对象单独存取，或者用深合并工具函数。如果参数结构稳定，也可以只存“变化过的值”，加载时和默认值合并，这样默认值调整后老配置也能兼容。
4. 常见问题与排查技巧实录
4.1 面板动了但画面没反应的排查路径
这是最高频的问题，我整理了一个排查顺序，按这个走基本能定位：
| 排查项 | 检查方法 | 常见原因 |
|---|---|---|
| 回调是否执行 | 回调里加 console.log | 忘了写 onChange 或拼错属性名 |
| 场景对象引用 | 打印回调里的对象 | 引用的是副本或已销毁对象 |
| 渲染循环是否运行 | 看帧率或加计数器 | 循环停了或没触发重渲染 |
| 参数是否被覆盖 | 检查别处是否重置了值 | 初始化逻辑每帧重置参数 |
| 材质是否需要更新 | 检查 material.needsUpdate | 某些材质属性改动需手动标记 |
按这个表走，九成问题能自己解决。特别提一下最后一项：three 里有些材质属性（比如某些贴图相关、着色器相关）改了之后不会自动生效，需要设material.needsUpdate = true触发重编译。这个不是 gui 的问题，是 three 的机制，但新手容易误以为是面板没生效。
4.2 拖动滑块卡顿的性能优化
滑块拖动卡顿，根源通常是onChange里做了重活。优化思路分三层：第一层，把重量级操作从onChange挪到onFinishChange；第二层，如果必须实时，就在回调里做节流，比如用requestAnimationFrame包一层，保证一帧最多处理一次；第三层，检查步长是不是太小导致事件过密，适当放大步长。
还有一种卡顿是“渲染本身太重”，面板只是背锅。判断方法是：不拖滑块、场景静止时帧率如何？如果静止也卡，那是渲染性能问题，跟面板无关，得去优化几何体、减少 draw call、降分辨率。我遇到过有人把锅甩给 gui，结果一查是场景里几万个粒子每帧都在重建，跟面板半毛钱关系没有。
4.3 面板样式与场景 UI 冲突的处理
面板默认样式是深色半透明，如果你的场景整体是浅色或者有大量 UI 元素，面板可能显得突兀或者遮挡内容。处理方式有几种：改主题色（库一般支持主题配置或 CSS 变量覆盖）、调面板位置（避开关键区域）、调透明度、或者干脆做成可折叠的抽屉。
我的习惯是把面板放在右上角、默认半透明、鼠标悬停时加深，这样既不抢戏又随时可用。如果场景有全屏操作（比如第一人称漫游），面板要支持一键隐藏，绑个快捷键（比如 H 键切换显示）会很方便。这些是体验层面的打磨，不影响功能，但决定了工具好不好用。
4.4 参数初始值与场景状态不同步的坑
前面提过这个，这里展开说。不同步的表现是：页面一加载，面板滑块位置和场景实际状态对不上，一动滑块画面就突变。根因是 params 的初始值是硬编码的，而场景对象的初始值可能是另一套逻辑算出来的。
解决办法是初始化时从场景对象反向读取。比如相机 fov，不要写死fov: 50，而是fov: camera.fov；光照强度同理。这样面板初始显示的就是场景真实状态，滑块不会跳。如果场景状态是异步加载的（比如模型加载完才确定某些参数），那就在加载完成的回调里再初始化面板，或者提供一个“同步当前状态到面板”的按钮。这个细节虽小，但对调试体验影响很大，值得花几分钟处理好。
4.5 多面板与面板生命周期的管理
复杂项目里可能不止一个面板——场景调试一个、材质编辑一个、动画控制一个。多面板要注意两点：一是位置别重叠，二是销毁要及时。gui.js 的实例一般有destroy()方法，页面切换或组件卸载时调用，避免残留的 DOM 和事件监听造成内存泄漏。
在单页应用里尤其要注意这个。我见过路由切换后旧面板还挂在那儿、事件还在触发的情况，就是因为没销毁。养成“谁创建谁销毁”的习惯，在组件卸载的生命周期里清理面板，能省掉很多诡异 bug。另外，多个面板如果绑定同一个 params 对象，改一个另一个不会自动刷新显示（因为 gui 不监听外部变化），这种场景要么合并成一个面板，要么手动调updateDisplay()同步，别指望它自动联动。
5. 进阶玩法与工程化建议
5.1 把面板配置抽成独立模块
项目一大，面板代码容易散落在主逻辑里，越写越乱。我的做法是抽一个独立的debugPanel.js模块，导出一个createPanel(params, sceneRefs)函数，内部负责建面板、绑控件、写回调。主逻辑只调一次这个函数，传进去参数对象和场景对象引用。这样面板代码和业务代码解耦，上线时把整个模块的条件引入去掉就行，不会污染生产包。
更进一步，可以把“控件描述”做成配置数组，用一个循环批量生成控件，而不是一个个手写gui.add。比如：
const controls = [ { folder: '相机', key: 'fov', min: 20, max: 100, step: 1, label: '视野角度' }, { folder: '光照', key: 'ambientIntensity', min: 0, max: 2, step: 0.05, label: '环境光强度' } ];然后遍历生成。这样加参数只改配置、不改逻辑，维护成本低很多。当然，回调逻辑复杂的控件还是单独写更清晰，配置化适合那些“改值即生效”的简单参数。
5.2 生产环境的面板开关策略
调试面板不该出现在正式用户面前。常见的开关策略有三种：按环境变量控制（开发环境显示、生产隐藏）、按 URL 参数控制（加个?debug=1才显示）、按快捷键控制（默认隐藏，按特定组合键呼出）。我一般用环境变量 + 快捷键双保险：开发环境默认显示方便调试，生产环境默认隐藏但保留快捷键，方便线上排查问题时临时呼出。
实现上就是在创建面板前判断一下条件，不满足就不实例化。注意如果面板模块被静态引入，即使不实例化，代码也会打进包里，所以更彻底的做法是用动态 import 或者构建工具的按需加载，把面板代码完全排除出生产包。这个对包体积敏感的项目值得做。
5.3 面板与配置文件的联动
调好的参数除了存本地，还可以导出成 JSON 文件，方便团队共享或者作为预设。实现就是JSON.stringify(params)后触发下载，导入则是读文件解析后合并到 params 再刷新面板。这套“导出/导入预设”的机制在团队协作里特别有用——一个人调好了光照氛围，导出给其他人直接用，不用口头描述参数。
如果参数要作为正式配置进入生产，那面板调好后导出的 JSON 就可以作为默认配置的参考。我的习惯是调参阶段用面板快速试，试出满意的值后手动整理进配置文件，而不是直接把面板导出的原始 JSON 塞进生产配置——因为面板参数往往包含很多调试专用的开关，需要筛选。
5.4 移动端与触屏的适配注意
gui.js 这类面板最初是为桌面鼠标操作设计的，触屏上滑块拖动、颜色选择的手感会打折扣。如果项目要在移动端用，注意几点：控件尺寸要够大（手指点得中）、滑块步长适当放大（精细拖动在触屏上很难）、面板宽度适配窄屏（太宽会超出屏幕）。有些库对触屏有专门优化，选型时可以留意。
不过说实话，移动端做三维调试面板的场景不多，更多是桌面开发、移动端展示。如果确实需要在移动端调参，我倾向于简化面板——只保留最核心的几个参数，或者做成全屏的参数页而不是浮层，操作空间更大。
6. 我踩过的几个典型坑与经验总结
第一个坑是回调里改了 params 又触发回调。有次我在 onChange 里做了个“数值归一化”，把超出范围的值 clamp 回 params，结果 clamp 又触发了一次 onChange，形成循环，浏览器直接卡死。教训是：回调里只读 params、只写场景对象，不要反向写 params。如果确实需要修正值，用onFinishChange或者加个标志位防重入。
第二个坑是颜色格式不匹配。面板颜色控件返回十六进制字符串，但我有一处代码期望的是 RGB 对象，直接传进去导致颜色全黑。排查了半天才发现是格式问题。后来养成习惯：所有颜色相关的赋值统一走new THREE.Color(val)包一层，不管来源是什么格式，Color 构造器都能处理，省心。
第三个坑是面板初始值跳变。前面提过，根因是硬编码初始值和场景实际值不一致。自从改成从场景对象反向读取初始值后，这个问题再没出现过。这个习惯值得所有用面板的人养成——面板是场景状态的镜子，不是独立的数据源。
第四个坑是忘了销毁面板导致内存泄漏。单页应用里切来切去，旧面板的事件监听一直挂着，时间长了页面越来越卡。后来在组件卸载钩子里统一调 destroy，问题消失。这个坑不显眼，但排查起来很费劲，因为表现是“越用越卡”而不是报错。
第五个坑是步长设太小导致事件风暴。有个参数范围 0 到 1，我设了 0.001 的步长，结果拖动时一秒触发几百次回调，每次回调里还有计算，直接卡成幻灯片。后来把步长调到 0.01，手感没差多少，性能好了十倍。这个经验是：步长要匹配人眼/人手的感知精度，不是越小越好。
这些坑说起来都是小事，但每一个都实打实花了我半天到一天去排查。写出来是希望后来的人少走弯路。gui.js 这类库本身不复杂，难的是把它和三维场景的数据流、渲染节奏、性能边界配合好。把数据流理顺（面板改 params、渲染读 params、回调只做单向同步）、把重量级操作挪到合适的时机（onFinishChange 或按钮触发）、把初始值对齐场景真实状态，这三点做到了，面板用起来就非常顺手。
最后分享一个我最近常用的组合：面板 + 快捷键 + 本地存储三件套。面板负责调，快捷键负责快速显隐和重置，本地存储负责记住上次调好的状态。这三样加起来，调试效率比纯手改代码高一个数量级。至于面板里具体放哪些参数，我的原则是“凡是你会改第二次的，都值得放上去”——第一次改可能是试，第二次改就说明它是常用参数，值得一个控件的位置。
