简介Three.js 3D可视化机房是一套面向Web前端与WebGL开发者的实战型3D应用源码以第一人称视角在浏览器中构建可漫游的虚拟机房适合从页面开发进阶到3D交互可视化的中级学习者参考。压缩包共176个文件、约8.54MB以60个js脚本、15个ts声明、数十张png/jpg贴图为主另含html入口页、gltf/fbx/3ds模型与7份md文档代码、素材、说明齐备可直接运行并二次修改。目前已有6031人次学习参考价值明确。工程重点演示EffectComposer后期合成与辉光、WebGLRenderer抗锯齿、MaskPass遮罩控制使亮点物体泛出光晕、模型边缘更平滑、局部区域按需显隐目录中v1-js与v2-jsm两个版本可对比传统脚本与ES6模块化的组织差异doc含API与教程文档便于对照修改、理解渲染管线与交互逻辑。1. 凌晨告警找不到机柜3D 机房值不值得做凌晨两点机房温度告警值班同事在 2D 拓扑图上翻了五分钟才定位到第三排第七个机柜——这种场景我见过太多次。ThreeJS 3D 可视化机房这套源码要解决的就是这件事把机柜、服务器 U 位、告警状态和巡检入口放进一个可旋转、可缩放、可点选的三维场景里让“第几排第几列”变成一眼能认出的空间位置。它是一套 Web 开发源代码前端用 ThreeJS 渲染数据层用 JS/AJAX 拉取机房布局适合做运维可视化、机房资产管理、教学演示的前端同学也适合想从 2D 组态切到 3D 的开发者。拿到源码后别急着改模型先按下面的顺序把场景跑通再替换成自己的机房数据。2. 搭起可运行的 3D 机房骨架场景、相机、渲染器与坐标单位一套 3D 机房源码能不能改得动第一眼不看模型多漂亮而看场景骨架是否干净相机初始位置是否合理、渲染器像素比有没有上限、坐标单位是否统一、数据是不是从接口进来。很多 Demo 在作者机器上跑得流畅换一台 2K 屏笔记本就开始掉帧问题往往出在setPixelRatio没限制、阴影贴图开得太大、每台服务器一个独立材质。先把最小渲染循环跑通再谈机柜和服务器。2.1 从源码目录到第一帧最小渲染循环这套 Web 开发源代码的前端入口通常是一个main.js或room.js里面做四件事创建场景、创建透视相机、创建 WebGL 渲染器、启动requestAnimationFrame循环。下面这段是骨架代码直接决定后续所有模型的坐标基准和交互手感。import * as THREE from three; import { OrbitControls } from three/addons/controls/OrbitControls.js; const container document.getElementById(room-canvas); const scene new THREE.Scene(); scene.background new THREE.Color(0x0b1220); scene.fog new THREE.Fog(0x0b1220, 30, 90); // 远处机柜淡出减少视觉噪音 const camera new THREE.PerspectiveCamera( 45, // 机房场景别用超广角45° 更接近人眼机柜不易变形 container.clientWidth / container.clientHeight, 0.1, 200 ); camera.position.set(12, 9, 16); const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); // 高 DPI 手机限到 2避免像素爆炸 renderer.setSize(container.clientWidth, container.clientHeight); renderer.shadowMap.enabled true; renderer.shadowMap.type THREE.PCFSoftShadowMap; container.appendChild(renderer.domElement); const controls new OrbitControls(camera, renderer.domElement); controls.target.set(0, 1.2, 0); // 视线落在机柜中部不是地面 controls.enableDamping true; controls.dampingFactor 0.08; controls.maxPolarAngle Math.PI / 2 - 0.05; // 禁止钻到地面以下 controls.minDistance 3; controls.maxDistance 40; const clock new THREE.Clock(); function tick() { const dt clock.getDelta(); controls.update(dt); // 开了 damping 就必须每帧 update renderer.render(scene, camera); requestAnimationFrame(tick); } tick();逻辑说明PerspectiveCamera的视场角用 45°机房这种以长方体为主的场景如果开到 75°边缘机柜会被拉斜点击拾取时手感也会飘。camera.position和controls.target要一起调只改相机位置会让轨道中心偏到墙外。renderer.setPixelRatio是移动端发热的第一道闸限制到 2 比默认跟随设备像素比稳得多。controls.update(dt)不能省否则阻尼失效松手就硬停。参数说明near0.1、far200按机房 30 米以内的尺度够用fog的近远距离要跟机房尺寸匹配写死 30/90 只适合十几米长的房间机房更大就要按包围盒计算。响应式部分别只监听resize改渲染器尺寸还要同步相机宽高比和 CSS2D 标签层否则窗口一拉标签和模型会错位。function onResize() { const w container.clientWidth; const h container.clientHeight; camera.aspect w / h; camera.updateProjectionMatrix(); renderer.setSize(w, h); labelRenderer.setSize(w, h); // 标签层和 WebGL 层必须同尺寸 } window.addEventListener(resize, onResize);这段代码看着简单却是后面所有坑的源头标签层没同步、容器宽高取到 0、resize事件触发太频繁导致卡顿都会在这里埋雷。容器宽高建议用ResizeObserver监听父元素不要只监听window后台管理系统的侧边栏一收起来canvas 宽度就变了。2.2 机房坐标系统与单位换算1U44.45mm 怎么落进 ThreeJS3D 机房最常见的翻车不是模型丑而是比例乱机柜高 2 米、服务器厚 4 厘米、U 位间距却按 1 个单位摆最后服务器像飘在半空。ThreeJS 本身没有单位但团队必须约定一个我一般用“米”作为场景单位地面y0机柜底部贴地服务器按1U 0.04445m换算。这样相机距离、雾效、阴影范围都能用真实尺度描述换机房时只改数据不改代码。对象真实尺寸ThreeJS 单位米坐标基准标准机柜宽 600mm、深 1200mm、高 2000mm0.6 × 1.2 × 2.0底部中心为原点1U 服务器高 44.45mm0.04445所在 U 位底部机房通道宽 1200mm1.2两排机柜之间相机初始高度约 1.6m 人眼1.62.0看向机柜中部机柜位置不要直接在代码里写mesh.position.set(3.2, 0, -1.8)而是从布局数据里读row、col、x、z、rotation。常见的做法是把机房画成网格每排机柜沿 X 轴排布排与排之间沿 Z 轴留 1.2 米通道。下面这个工具函数把“第几排第几列”换算成世界坐标后面所有机柜都走它避免一处偏移处处偏移。const CABINET_W 0.6; const AISLE_W 1.2; function cabinetWorldPosition(row, col, rowGap 1.6) { return { x: col * (CABINET_W 0.05), // 机柜之间留 5cm 缝避免视觉粘连 z: row * (1.2 AISLE_W), // 机柜深 1.2m 通道 1.2m rotationY: 0 }; }逻辑说明col * (CABINET_W 0.05)让同一排机柜等距排开缝隙太小阴影会糊成一片太大又不像真实机房。rowGap参数留给“背靠背”布局有些机房两排机柜共用一条冷通道行距就不是 2.4 米。旋转角rotationY不要省机房经常有 L 形布局机柜朝外和朝内是两套朝向。参数说明如果后端给的坐标单位是毫米进场景前统一除以 1000别在建模函数里临时乘系数。我见过一个项目一半模型用米、一半用厘米最后相机拉远看还行拉近点服务器直接穿出机柜。U 位换算也一样uStart从 1 开始还是从 0 开始要在数据层定死前端只做uStart * U不要每个模型自己猜。2.3 用 AJAX 拉取机房布局数据并驱动场景机房可视化不是手工摆模型而是数据驱动。这套 JS/AJAX 源代码的数据层一般用fetch拉一个room-layout.json里面包含机房尺寸、机柜数组、每个机柜的服务器列表。先别接真实接口用静态 JSON 把场景跑通再接后端。这样模型问题和数据问题能分开排查。async function loadRoomLayout(url) { const res await fetch(url, { headers: { Accept: application/json }, cache: no-store // 机房状态变化快调试期别让浏览器缓存旧布局 }); if (!res.ok) { throw new Error(机房布局加载失败: ${res.status} ${res.statusText}); } const data await res.json(); if (!Array.isArray(data.cabinets)) { throw new Error(布局数据缺少 cabinets 数组); } return data; } loadRoomLayout(/api/room/layout) .then((layout) buildRoom(layout)) .catch((err) { console.error(err); showRoomError(机房布局加载失败请检查接口或 JSON 格式); });逻辑说明cache: no-store只在调试期建议加生产环境按接口缓存策略来。res.ok判断不能省很多“场景空白”不是 ThreeJS 的问题而是接口返回 404 后res.json()抛错被吞了。cabinets数组校验是防止后端改字段名前端静默渲染出一个空房间。参数说明布局 JSON 里建议至少包含room.width、room.depth、cabinets[].id、cabinets[].row、cabinets[].col、cabinets[].servers[].uStart、servers[].uCount、servers[].state。state用normal / warning / critical / offline四档就够别把后端所有状态码直接塞进颜色映射否则前端会变成状态字典维护现场。接口返回慢时先渲染地面和机柜壳服务器数据后到再补不要让用户盯着黑屏等 AJAX。3. 机柜与服务器建模用 BoxGeometry 拼出可维护的 U 位结构机房 3D 场景里 90% 的物体是长方体不需要上来就 glTF 精模。机柜用BoxGeometry拼壳、前门、立柱服务器用薄盒子按 U 位叠放既能保证帧率也方便后面按userData做拾取。关键是参数化宽、深、高、U 数、颜色都从配置进不要把 0.6、1.2、2.0 写死在十几个地方。3.1 机柜参数化宽深高、前后门与立柱一个能看的机柜至少三层外壳、前门内凹框、顶部标识。外壳用深灰金属材质前门用半透明深色玻璃或网格材质这样里面的服务器能透出来。别把前门做成完全不透明否则点开机柜只能看到一块铁皮。下面这个函数返回一个Group原点在机柜底部中心后续摆放只改group.position。function createCabinet(cfg {}) { const { width 0.6, depth 1.2, height 2.0, bodyColor 0x252b33, doorColor 0x11161d } cfg; const group new THREE.Group(); group.name cabinet; // 外壳略小于真实尺寸给门和缝隙留空间 const body new THREE.Mesh( new THREE.BoxGeometry(width, height, depth), new THREE.MeshStandardMaterial({ color: bodyColor, metalness: 0.55, roughness: 0.45 }) ); body.position.y height / 2; body.castShadow true; body.receiveShadow true; group.add(body); // 前门半透明能看见内部服务器状态灯 const door new THREE.Mesh( new THREE.BoxGeometry(width * 0.92, height * 0.94, 0.02), new THREE.MeshStandardMaterial({ color: doorColor, metalness: 0.2, roughness: 0.75, transparent: true, opacity: 0.72 }) ); door.position.set(0, height / 2, depth / 2 0.012); group.add(door); // 顶部横梁方便视觉上区分机柜朝向 const topBar new THREE.Mesh( new THREE.BoxGeometry(width * 0.96, 0.04, depth * 0.96), new THREE.MeshStandardMaterial({ color: 0x3a4450, metalness: 0.6, roughness: 0.4 }) ); topBar.position.y height - 0.02; group.add(topBar); group.userData { type: cabinet, id: cfg.id || }; return group; }逻辑说明外壳body的position.y height / 2是把“底部中心”原点抬到几何中心因为BoxGeometry默认以自身中心为原点。前门往外偏移depth / 2 0.012避免和外壳共面产生 Z-fighting那个 0.012 是血泪经验贴太近会出现闪烁条纹。castShadow和receiveShadow按需开机柜数量多的时候阴影开销很大可以只让外壳投影门和横梁不投影。参数说明metalness不要给到 1没有环境贴图时金属度越高越黑0.40.6 配一盏方向光就够了。opacity0.72 是能看见内部又不至于完全透明低于 0.5 机柜会显得像塑料壳。group.userData.id必须写后面射线拾取到子网格时要向上找祖先拿机柜 ID没有这个字段就只能靠name字符串匹配改一次名全崩。3.2 服务器 U 位排布与状态色映射服务器不是按“第几台”摆而是按“从第几 U 开始、占几 U”摆。1U 服务器厚 0.04445 米2U 就是 0.0889 米但模型不能严丝合缝顶满否则相邻服务器会 Z-fighting。我一般让实际高度乘 0.92留一点缝。颜色按状态映射正常绿、告警黄、严重红、离线灰材质尽量复用别每台服务器 new 一个MeshStandardMaterial。const U 0.04445; const STATE_COLOR { normal: 0x2ecc71, warning: 0xf1c40f, critical: 0xe74c3c, offline: 0x7f8c8d }; const serverMaterialCache new Map(); function getServerMaterial(state) { if (!serverMaterialCache.has(state)) { serverMaterialCache.set( state, new THREE.MeshStandardMaterial({ color: STATE_COLOR[state] || STATE_COLOR.offline, metalness: 0.1, roughness: 0.6, emissive: STATE_COLOR[state] || STATE_COLOR.offline, emissiveIntensity: state critical ? 0.55 : 0.15 }) ); } return serverMaterialCache.get(state); } function addServerToCabinet(cabinet, server, cabinetDepth 1.2) { const { id, uStart, uCount 1, state offline } server; const h uCount * U * 0.92; const mesh new THREE.Mesh( new THREE.BoxGeometry(0.54, h, cabinetDepth * 0.78), getServerMaterial(state) ); // uStart 从 1 开始机柜底部留 0.08m 底座 mesh.position.set(0, 0.08 (uStart - 1) * U h / 2, 0.06); mesh.castShadow false; // 服务器在柜内阴影收益低关掉省性能 mesh.userData { type: server, id, uStart, uCount, state, cabinetId: cabinet.userData.id }; cabinet.add(mesh); return mesh; }逻辑说明h uCount * U * 0.92留缝position.y先加底座 0.08 米再加(uStart - 1) * U最后加半个自身高度这样服务器底部正好落在 U 位起点。cabinetDepth * 0.78让服务器比机柜浅一点前门关上时不会穿模。材质缓存按状态复用几百台服务器只产生四个材质GPU 上传和 draw call 都会少很多。参数说明uStart从 1 开始还是从 0 开始必须跟后端对齐我一般强制从 1 开始0 留给“未知”。emissiveIntensity严重状态给 0.55正常给 0.15太高会让红色糊成一片太低又看不出告警。服务器castShadowfalse是性能取舍如果机房只有十几台服务器可以打开超过两百台就关掉用发光色表达状态更划算。3.3 数据驱动建机房一份 JSON 铺满整个场景机柜和服务器函数写好之后建场景就变成循环先铺地面和墙再按cabinets数组摆机柜每个机柜里按servers数组摆服务器。下面这段是buildRoom的核心重点看错误隔离单个机柜数据坏了不能让整个机房空白。function buildRoom(layout) { const room new THREE.Group(); room.name room-root; const floor new THREE.Mesh( new THREE.PlaneGeometry(layout.room.width, layout.room.depth), new THREE.MeshStandardMaterial({ color: 0x1a2029, roughness: 0.9, metalness: 0.05 }) ); floor.rotation.x -Math.PI / 2; floor.receiveShadow true; room.add(floor); layout.cabinets.forEach((cabinetData) { try { const cabinet createCabinet({ id: cabinetData.id, width: cabinetData.width || 0.6, depth: cabinetData.depth || 1.2, height: cabinetData.height || 2.0 }); cabinet.position.set(cabinetData.x, 0, cabinetData.z); cabinet.rotation.y cabinetData.rotationY || 0; cabinet.userData.row cabinetData.row; cabinet.userData.col cabinetData.col; (cabinetData.servers || []).forEach((server) { addServerToCabinet(cabinet, server, cabinetData.depth || 1.2); }); room.add(cabinet); } catch (err) { console.warn(机柜 ${cabinetData.id} 构建失败, err); } }); scene.add(room); return room; }逻辑说明地面单独铺不要每个机柜带一块地板否则重叠面会闪烁。cabinet.position.set(x, 0, z)的y固定 0因为机柜组原点已经在底部如果模型原点在中心这里就要加height / 2原点约定必须在建模函数里写死。try/catch包住单个机柜某个servers字段不是数组时只跳过这个柜不影响整排。参数说明layout.room.width/depth用来定地面大小也建议用来算相机maxDistance和雾效距离别让用户能缩到墙外。rotationY传给cabinet.rotation.yL 形机房靠它转向。cabinetData.x/z如果是毫米在这里统一除以 1000不要留到服务器层级再换越晚换越乱。4. 交互与信息呈现Raycaster 拾取、CSS2D 标签与侧边详情面板3D 机房如果只能转不能点价值少一半。运维人员要的是“点一下机柜右侧弹出这台柜的 U 位占用和告警”“鼠标移上去机柜高亮标签显示名称”。ThreeJS 做这件事靠Raycaster拾取 CSS2DRenderer标签 普通 HTML 侧栏。三者分工要清楚射线负责选中对象CSS2D 负责空间锚定文字侧栏负责复杂表单和列表别把所有信息都塞进 3D 纹理里。4.1 射线拾取与悬停高亮别改共享材质射线拾取最常见的错误是拿鼠标坐标直接当 NDC 坐标用。Raycaster.setFromCamera要的是-11的归一化设备坐标必须用 canvas 的getBoundingClientRect()换算而且要考虑 canvas 在页面中的偏移。另一个坑是intersectObjects默认不递归机柜是Group直接传机柜组进去点不到里面的服务器。const raycaster new THREE.Raycaster(); const pointer new THREE.Vector2(); let hovered null; let originalEmissive null; function updatePointer(event) { const rect renderer.domElement.getBoundingClientRect(); pointer.x ((event.clientX - rect.left) / rect.width) * 2 - 1; pointer.y -((event.clientY - rect.top) / rect.height) * 2 1; } function pickAtPointer() { raycaster.setFromCamera(pointer, camera); const roots scene.getObjectByName(room-root); const hits raycaster.intersectObjects(roots.children, true); // 必须递归 for (const hit of hits) { let node hit.object; while (node !node.userData?.type) node node.parent; if (node?.userData?.type cabinet || node?.userData?.type server) { return node; } } return null; } function onPointerMove(event) { updatePointer(event); const target pickAtPointer(); if (target hovered) return; if (hovered) { hovered.traverse((child) { if (child.isMesh child.material?.emissive) { child.material.emissiveIntensity child.userData._oldEmissive ?? 0.15; } }); hovered null; } if (target) { hovered target; target.traverse((child) { if (child.isMesh child.material?.emissive) { child.userData._oldEmissive child.material.emissiveIntensity; child.material.emissiveIntensity 0.8; } }); renderer.domElement.style.cursor pointer; } else { renderer.domElement.style.cursor grab; } }逻辑说明pointer.y前面有负号因为浏览器 Y 轴向下、NDC Y 轴向上漏掉负号会出现“鼠标在上、选中在下”。while (node !node.userData?.type)向上找带业务类型的祖先点到服务器子网格也能归到服务器或机柜。高亮时保存原emissiveIntensity不要直接改material.color否则材质是共享的所有同状态服务器一起变色。参数说明roots.children只传机房根节点不要传整个scene场景里还有灯光、地面、辅助线全量递归会拖慢每次pointermove。悬停事件建议加 50ms 节流高频pointermove加射线检测在低端设备上会卡。intersectObjects第二个参数true不能省这是新手最常见的“点了没反应”。4.2 CSS2DRenderer 标签文字别烘进纹理机柜名称、IP 段、温度这些信息如果烘成纹理贴到模型上远处会糊、近处锯齿、改一个字要重新生成贴图。用CSS2DRenderer把 HTML 标签锚在 3D 坐标上字体清晰、可选中、可加 CSS 动画。代价是 DOM 数量几百个标签同时开着会拖慢页面所以标签要按距离和视角做显隐。import { CSS2DRenderer, CSS2DObject } from three/addons/renderers/CSS2DRenderer.js; const labelRenderer new CSS2DRenderer(); labelRenderer.setSize(container.clientWidth, container.clientHeight); labelRenderer.domElement.style.position absolute; labelRenderer.domElement.style.top 0; labelRenderer.domElement.style.left 0; labelRenderer.domElement.style.pointerEvents none; // 关键别挡住 canvas 的鼠标事件 container.appendChild(labelRenderer.domElement); function createCabinetLabel(cabinet, text) { const div document.createElement(div); div.className cabinet-label; div.textContent text; const label new CSS2DObject(div); label.position.set(0, 2.15, 0); // 机柜顶部上方 label.center.set(0.5, 1); cabinet.add(label); return label; } // 每帧渲染标签层 function tick() { controls.update(); renderer.render(scene, camera); labelRenderer.render(scene, camera); requestAnimationFrame(tick); }逻辑说明pointerEvents none必须加否则标签层是一整张透明 DOM鼠标事件全被它截走射线拾取永远点不到模型。标签挂在机柜Group下机柜移动标签跟着走不用每帧手算屏幕坐标。label.center.set(0.5, 1)让标签底部对齐锚点文字在机柜正上方而不是中心穿模。参数说明标签位置y2.15是按 2 米机柜留 15cm机柜加高就要改。标签显隐我一般按相机距离做阈值超过 25 米隐藏只留选中机柜的标签同屏标签超过 80 个就按视野裁剪。labelRenderer.domElement的z-index要低于侧栏、高于 canvas否则标签会盖住弹窗。4.3 点击弹窗与 AJAX 详情接口把重信息放回 HTML点击机柜后不建议在 3D 里画详情直接用右侧固定面板。射线拾取拿到cabinetId或serverId发一个 AJAX 请求拉详情渲染成表格。这样详情字段增删不用动 ThreeJS 代码前端和后端都好维护。下面这段带加载态和请求取消避免快速连点导致旧响应覆盖新面板。let detailController null; async function openDetailPanel(type, id) { const panel document.getElementById(detail-panel); panel.classList.add(is-open); panel.innerHTML div classloading加载中.../div; if (detailController) detailController.abort(); detailController new AbortController(); try { const res await fetch(/api/room/${type}/${encodeURIComponent(id)}, { signal: detailController.signal, headers: { Accept: application/json } }); if (!res.ok) throw new Error(详情接口 ${res.status}); const detail await res.json(); renderDetail(panel, detail); } catch (err) { if (err.name ! AbortError) { panel.innerHTML div classerror详情加载失败请重试/div; console.error(err); } } } renderer.domElement.addEventListener(click, () { const target pickAtPointer(); if (!target) return; const { type, id } target.userData; if (type id) openDetailPanel(type, id); });逻辑说明AbortController用来取消上一次请求快速点三个机柜时只保留最后一个响应否则面板会来回跳。encodeURIComponent防止 ID 里带斜杠或中文导致路径错。点击事件绑在renderer.domElement上不要绑在window否则点侧栏也会触发拾取。参数说明详情接口返回什么就渲染什么前端不要写死字段顺序。侧栏宽度建议 360420px太窄表格挤太宽挡场景。加载态和错误态必须有机房接口偶尔超时用户点了没反应会以为 3D 卡死。如果详情里还要嵌实时温度曲线建议单独用轻量图表库不要把图表也画进 ThreeJS。5. 避坑与排查3D 机房项目里最容易翻车的五件事3D 机房源码能跑起来只是开始真正耗时间的是“看起来差不多、点起来不对”的问题。下面五条是我在类似项目里反复遇到的每条按“现象 → 原因 → 解决”拆开。排查顺序建议从渲染器、坐标、交互、资源释放、移动端性能依次走别一上来就怀疑 ThreeJS 版本。5.1 现象场景全黑机柜像剪影现象页面打开后 canvas 一片黑只能看到机柜轮廓服务器颜色全灰调高颜色值也没用。原因最常见是灯光没加或强度太低。MeshStandardMaterial不是自发光材质没有环境光和方向光时metalness越高越黑机房源码里如果只加了一盏AmbientLight金属外壳会把环境光“吃”掉。第二个原因是渲染器色彩空间没设老代码默认线性输出深色材质会发闷。第三个原因是相机在机柜内部或near/far设错整个场景被裁掉。解决先加HemisphereLight提供基础环境光再加一盏DirectionalLight打阴影强度按场景尺度调。机柜金属度降到 0.5 左右没有环境贴图时不要给 0.9。渲染器颜色空间按当前 ThreeJS 版本设置别抄旧教程的outputEncoding。排查时临时把背景设成亮灰色、材质换成MeshBasicMaterial如果能看到模型说明几何没问题问题在光照和材质。const hemi new THREE.HemisphereLight(0xbfd4ff, 0x1a2029, 0.9); scene.add(hemi); const dir new THREE.DirectionalLight(0xffffff, 1.6); dir.position.set(8, 14, 10); dir.castShadow true; dir.shadow.mapSize.set(1024, 1024); dir.shadow.camera.left -15; dir.shadow.camera.right 15; dir.shadow.camera.top 15; dir.shadow.camera.bottom -15; scene.add(dir);shadow.mapSize不要一上来 4096机房这种大平面 1024 配 PCFSoft 够用阴影相机范围要包住机房否则边缘机柜没影子。5.2 现象机柜整体偏移半米服务器飘在半空现象机柜看起来贴地了但点击高亮框偏到旁边或者服务器底部和 U 位刻度对不上越往上偏得越多。原因模型原点不统一。BoxGeometry默认中心在几何中心有人建机柜时把position.y设成 0结果机柜一半埋地下有人又额外加了height / 2导致整体抬高。服务器 U 位换算时uStart从 0 开始还是从 1 开始没对齐每台差 1U叠到 40U 就偏出机柜。解决定死一条约定——所有机柜组原点在底部中心所有服务器position.y从机柜底部往上算uStart从 1 开始。建一个debugAxis辅助线在机柜底部画一个十字肉眼确认原点。U 位换算只允许在一个函数里出现别在建模、拾取、标签三处各写一遍。5.3 现象鼠标点机柜没反应或者点 A 弹 B现象鼠标移到机柜上不变手型点击不弹面板或者点第一排机柜弹出第三排的详情。原因三个高频问题。第一CSS2D 标签层没设pointer-events: none整层 DOM 把 canvas 事件挡住了。第二intersectObjects没传递归参数true机柜是Group射线只打组不打子网格。第三鼠标坐标没按 canvas 的getBoundingClientRect()换算页面有侧边栏或滚动时NDC 坐标整体偏移点 A 命中 B。解决先检查标签层 CSS再确认射线递归最后打印pointer.x/y看范围是否在-11。点击事件里加一个临时console.log(hit.object.name)看命中的是不是预期网格。如果用了OrbitControls拖拽结束也会触发 click建议记录pointerdown和pointerup的位移超过 5px 就不当点击处理。5.4 现象切换楼层几次后越来越卡最后浏览器崩现象第一次进机房很流畅切换到第二层、第三层再切回来帧率明显下降任务管理器里 GPU 内存持续上涨。原因ThreeJS 的几何体、材质、纹理不会自动释放。每次buildRoom都 new 一批BoxGeometry和MeshStandardMaterial旧场景只是从scene里removeGPU 资源还在。requestAnimationFrame如果开了多个循环每切一次多一个帧率直接腰斩。resize、pointermove事件重复绑定也会累积。解决封装disposeObject3D(root)递归调用geometry.dispose()、material.dispose()、texture.dispose()再从场景移除。全局只保留一个requestAnimationFrame循环切换楼层只换数据不换循环。事件绑定用AbortController或具名函数卸载时removeEventListener。function disposeObject3D(root) { root.traverse((obj) { if (obj.isMesh) { obj.geometry?.dispose(); const materials Array.isArray(obj.material) ? obj.material : [obj.material]; materials.forEach((mat) { Object.values(mat).forEach((v) { if (v v.isTexture) v.dispose(); }); mat.dispose(); }); } }); root.parent?.remove(root); }材质如果放在缓存Map里释放时要清缓存否则下一次建场景又拿到已销毁的材质表现为模型变黑或直接报错。5.5 现象移动端发烫、拖拽卡顿帧率掉到 20现象桌面浏览器 60 帧同一页面在平板或手机上拖拽明显拖影机身发热标签越多越卡。原因setPixelRatio跟随设备像素比高分屏手机上实际渲染像素是 CSS 像素的 3 倍阴影贴图 2048 起步每台服务器独立材质、独立几何体draw call 上千CSS2D 标签几百个同时渲染DOM 重排拖垮主线程。解决像素比限到 2 甚至 1.5阴影贴图降到 1024服务器材质按状态缓存同规格服务器用InstancedMesh合批。标签按相机距离和视野裁剪超过阈值直接visible false。移动端默认关阴影只保留环境光和方向光用发光色表达状态视觉差异不大帧率能回来一截。6. 把帧率稳住InstancedMesh 合批、LOD 与上线前的性能验收机房场景一旦超过两百台服务器逐台Mesh的 draw call 就会成为瓶颈。我的做法是把同规格、同状态的服务器合成InstancedMesh用矩阵写位置用setColorAt写状态色材质只保留一份。机柜本身数量通常几十到一百多可以保留独立Group方便拾取远处再用THREE.LOD换低模。验收时别只看“感觉流畅”打开renderer.info.render.calls和triangles记录切换楼层前后的数值再拿performance.now()统计连续 120 帧的平均帧时间超过 16.7ms 就说明没到 60 帧。const MAX_SERVERS 2000; const geo new THREE.BoxGeometry(0.54, 0.04, 0.9); const mat new THREE.MeshStandardMaterial({ metalness: 0.1, roughness: 0.6 }); const instanced new THREE.InstancedMesh(geo, mat, MAX_SERVERS); instanced.instanceMatrix.setUsage(THREE.DynamicDrawUsage); const dummy new THREE.Object3D(); const color new THREE.Color(); let index 0; function pushServerInstance(x, y, z, stateColor) { dummy.position.set(x, y, z); dummy.updateMatrix(); instanced.setMatrixAt(index, dummy.matrix); instanced.setColorAt(index, color.setHex(stateColor)); index; } instanced.count index; instanced.instanceMatrix.needsUpdate true; instanced.instanceColor.needsUpdate true; scene.add(instanced);这段代码的关键参数是MAX_SERVERS要按机房最大容量预留count按实际写入数量设置不然会渲染一堆零矩阵实例在原点。instanceColor需要材质支持顶点颜色状态色才能生效。拾取时InstancedMesh的hit.instanceId能拿到实例索引再映射回服务器 ID不要再用逐台Mesh的userData。验收项目标值查看方式draw calls小于 200renderer.info.render.calls三角面数小于 50 万renderer.info.render.triangles平均帧时间小于 16.7ms连续 120 帧performance.now()GPU 内存切换楼层后不持续上涨浏览器性能面板对比上线前我固定跑三遍空场景、单机柜、全量数据每遍都切一次楼层再切回来看renderer.info是否回到基线。从那以后我每次改完机房模型都强制走一遍这个流程不再靠“看起来不卡”判断。这套源码拿到后建议先跑最小场景再把机柜数据替换成自己的最后才动材质和光照。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/26 13:04:45 · 阅读 1.2k ThreeJS 3D机房可视化源码：建模、拾取与性能优化
简介Three.js 3D可视化机房是一套面向Web前端与WebGL开发者的实战型3D应用源码以第一人称视角在浏览器中构建可漫游的虚拟机房适合从页面开发进阶到3D交互可视化的中级学习者参考。压缩包共176个文件、约8.54MB以60个js脚本、15个ts声明、数十张png/jpg贴图为主另含html入口页、gltf/fbx/3ds模型与7份md文档代码、素材、说明齐备可直接运行并二次修改。目前已有6031人次学习参考价值明确。工程重点演示EffectComposer后期合成与辉光、WebGLRenderer抗锯齿、MaskPass遮罩控制使亮点物体泛出光晕、模型边缘更平滑、局部区域按需显隐目录中v1-js与v2-jsm两个版本可对比传统脚本与ES6模块化的组织差异doc含API与教程文档便于对照修改、理解渲染管线与交互逻辑。1. 凌晨告警找不到机柜3D 机房值不值得做凌晨两点机房温度告警值班同事在 2D 拓扑图上翻了五分钟才定位到第三排第七个机柜——这种场景我见过太多次。ThreeJS 3D 可视化机房这套源码要解决的就是这件事把机柜、服务器 U 位、告警状态和巡检入口放进一个可旋转、可缩放、可点选的三维场景里让“第几排第几列”变成一眼能认出的空间位置。它是一套 Web 开发源代码前端用 ThreeJS 渲染数据层用 JS/AJAX 拉取机房布局适合做运维可视化、机房资产管理、教学演示的前端同学也适合想从 2D 组态切到 3D 的开发者。拿到源码后别急着改模型先按下面的顺序把场景跑通再替换成自己的机房数据。2. 搭起可运行的 3D 机房骨架场景、相机、渲染器与坐标单位一套 3D 机房源码能不能改得动第一眼不看模型多漂亮而看场景骨架是否干净相机初始位置是否合理、渲染器像素比有没有上限、坐标单位是否统一、数据是不是从接口进来。很多 Demo 在作者机器上跑得流畅换一台 2K 屏笔记本就开始掉帧问题往往出在setPixelRatio没限制、阴影贴图开得太大、每台服务器一个独立材质。先把最小渲染循环跑通再谈机柜和服务器。2.1 从源码目录到第一帧最小渲染循环这套 Web 开发源代码的前端入口通常是一个main.js或room.js里面做四件事创建场景、创建透视相机、创建 WebGL 渲染器、启动requestAnimationFrame循环。下面这段是骨架代码直接决定后续所有模型的坐标基准和交互手感。import * as THREE from three; import { OrbitControls } from three/addons/controls/OrbitControls.js; const container document.getElementById(room-canvas); const scene new THREE.Scene(); scene.background new THREE.Color(0x0b1220); scene.fog new THREE.Fog(0x0b1220, 30, 90); // 远处机柜淡出减少视觉噪音 const camera new THREE.PerspectiveCamera( 45, // 机房场景别用超广角45° 更接近人眼机柜不易变形 container.clientWidth / container.clientHeight, 0.1, 200 ); camera.position.set(12, 9, 16); const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); // 高 DPI 手机限到 2避免像素爆炸 renderer.setSize(container.clientWidth, container.clientHeight); renderer.shadowMap.enabled true; renderer.shadowMap.type THREE.PCFSoftShadowMap; container.appendChild(renderer.domElement); const controls new OrbitControls(camera, renderer.domElement); controls.target.set(0, 1.2, 0); // 视线落在机柜中部不是地面 controls.enableDamping true; controls.dampingFactor 0.08; controls.maxPolarAngle Math.PI / 2 - 0.05; // 禁止钻到地面以下 controls.minDistance 3; controls.maxDistance 40; const clock new THREE.Clock(); function tick() { const dt clock.getDelta(); controls.update(dt); // 开了 damping 就必须每帧 update renderer.render(scene, camera); requestAnimationFrame(tick); } tick();逻辑说明PerspectiveCamera的视场角用 45°机房这种以长方体为主的场景如果开到 75°边缘机柜会被拉斜点击拾取时手感也会飘。camera.position和controls.target要一起调只改相机位置会让轨道中心偏到墙外。renderer.setPixelRatio是移动端发热的第一道闸限制到 2 比默认跟随设备像素比稳得多。controls.update(dt)不能省否则阻尼失效松手就硬停。参数说明near0.1、far200按机房 30 米以内的尺度够用fog的近远距离要跟机房尺寸匹配写死 30/90 只适合十几米长的房间机房更大就要按包围盒计算。响应式部分别只监听resize改渲染器尺寸还要同步相机宽高比和 CSS2D 标签层否则窗口一拉标签和模型会错位。function onResize() { const w container.clientWidth; const h container.clientHeight; camera.aspect w / h; camera.updateProjectionMatrix(); renderer.setSize(w, h); labelRenderer.setSize(w, h); // 标签层和 WebGL 层必须同尺寸 } window.addEventListener(resize, onResize);这段代码看着简单却是后面所有坑的源头标签层没同步、容器宽高取到 0、resize事件触发太频繁导致卡顿都会在这里埋雷。容器宽高建议用ResizeObserver监听父元素不要只监听window后台管理系统的侧边栏一收起来canvas 宽度就变了。2.2 机房坐标系统与单位换算1U44.45mm 怎么落进 ThreeJS3D 机房最常见的翻车不是模型丑而是比例乱机柜高 2 米、服务器厚 4 厘米、U 位间距却按 1 个单位摆最后服务器像飘在半空。ThreeJS 本身没有单位但团队必须约定一个我一般用“米”作为场景单位地面y0机柜底部贴地服务器按1U 0.04445m换算。这样相机距离、雾效、阴影范围都能用真实尺度描述换机房时只改数据不改代码。对象真实尺寸ThreeJS 单位米坐标基准标准机柜宽 600mm、深 1200mm、高 2000mm0.6 × 1.2 × 2.0底部中心为原点1U 服务器高 44.45mm0.04445所在 U 位底部机房通道宽 1200mm1.2两排机柜之间相机初始高度约 1.6m 人眼1.62.0看向机柜中部机柜位置不要直接在代码里写mesh.position.set(3.2, 0, -1.8)而是从布局数据里读row、col、x、z、rotation。常见的做法是把机房画成网格每排机柜沿 X 轴排布排与排之间沿 Z 轴留 1.2 米通道。下面这个工具函数把“第几排第几列”换算成世界坐标后面所有机柜都走它避免一处偏移处处偏移。const CABINET_W 0.6; const AISLE_W 1.2; function cabinetWorldPosition(row, col, rowGap 1.6) { return { x: col * (CABINET_W 0.05), // 机柜之间留 5cm 缝避免视觉粘连 z: row * (1.2 AISLE_W), // 机柜深 1.2m 通道 1.2m rotationY: 0 }; }逻辑说明col * (CABINET_W 0.05)让同一排机柜等距排开缝隙太小阴影会糊成一片太大又不像真实机房。rowGap参数留给“背靠背”布局有些机房两排机柜共用一条冷通道行距就不是 2.4 米。旋转角rotationY不要省机房经常有 L 形布局机柜朝外和朝内是两套朝向。参数说明如果后端给的坐标单位是毫米进场景前统一除以 1000别在建模函数里临时乘系数。我见过一个项目一半模型用米、一半用厘米最后相机拉远看还行拉近点服务器直接穿出机柜。U 位换算也一样uStart从 1 开始还是从 0 开始要在数据层定死前端只做uStart * U不要每个模型自己猜。2.3 用 AJAX 拉取机房布局数据并驱动场景机房可视化不是手工摆模型而是数据驱动。这套 JS/AJAX 源代码的数据层一般用fetch拉一个room-layout.json里面包含机房尺寸、机柜数组、每个机柜的服务器列表。先别接真实接口用静态 JSON 把场景跑通再接后端。这样模型问题和数据问题能分开排查。async function loadRoomLayout(url) { const res await fetch(url, { headers: { Accept: application/json }, cache: no-store // 机房状态变化快调试期别让浏览器缓存旧布局 }); if (!res.ok) { throw new Error(机房布局加载失败: ${res.status} ${res.statusText}); } const data await res.json(); if (!Array.isArray(data.cabinets)) { throw new Error(布局数据缺少 cabinets 数组); } return data; } loadRoomLayout(/api/room/layout) .then((layout) buildRoom(layout)) .catch((err) { console.error(err); showRoomError(机房布局加载失败请检查接口或 JSON 格式); });逻辑说明cache: no-store只在调试期建议加生产环境按接口缓存策略来。res.ok判断不能省很多“场景空白”不是 ThreeJS 的问题而是接口返回 404 后res.json()抛错被吞了。cabinets数组校验是防止后端改字段名前端静默渲染出一个空房间。参数说明布局 JSON 里建议至少包含room.width、room.depth、cabinets[].id、cabinets[].row、cabinets[].col、cabinets[].servers[].uStart、servers[].uCount、servers[].state。state用normal / warning / critical / offline四档就够别把后端所有状态码直接塞进颜色映射否则前端会变成状态字典维护现场。接口返回慢时先渲染地面和机柜壳服务器数据后到再补不要让用户盯着黑屏等 AJAX。3. 机柜与服务器建模用 BoxGeometry 拼出可维护的 U 位结构机房 3D 场景里 90% 的物体是长方体不需要上来就 glTF 精模。机柜用BoxGeometry拼壳、前门、立柱服务器用薄盒子按 U 位叠放既能保证帧率也方便后面按userData做拾取。关键是参数化宽、深、高、U 数、颜色都从配置进不要把 0.6、1.2、2.0 写死在十几个地方。3.1 机柜参数化宽深高、前后门与立柱一个能看的机柜至少三层外壳、前门内凹框、顶部标识。外壳用深灰金属材质前门用半透明深色玻璃或网格材质这样里面的服务器能透出来。别把前门做成完全不透明否则点开机柜只能看到一块铁皮。下面这个函数返回一个Group原点在机柜底部中心后续摆放只改group.position。function createCabinet(cfg {}) { const { width 0.6, depth 1.2, height 2.0, bodyColor 0x252b33, doorColor 0x11161d } cfg; const group new THREE.Group(); group.name cabinet; // 外壳略小于真实尺寸给门和缝隙留空间 const body new THREE.Mesh( new THREE.BoxGeometry(width, height, depth), new THREE.MeshStandardMaterial({ color: bodyColor, metalness: 0.55, roughness: 0.45 }) ); body.position.y height / 2; body.castShadow true; body.receiveShadow true; group.add(body); // 前门半透明能看见内部服务器状态灯 const door new THREE.Mesh( new THREE.BoxGeometry(width * 0.92, height * 0.94, 0.02), new THREE.MeshStandardMaterial({ color: doorColor, metalness: 0.2, roughness: 0.75, transparent: true, opacity: 0.72 }) ); door.position.set(0, height / 2, depth / 2 0.012); group.add(door); // 顶部横梁方便视觉上区分机柜朝向 const topBar new THREE.Mesh( new THREE.BoxGeometry(width * 0.96, 0.04, depth * 0.96), new THREE.MeshStandardMaterial({ color: 0x3a4450, metalness: 0.6, roughness: 0.4 }) ); topBar.position.y height - 0.02; group.add(topBar); group.userData { type: cabinet, id: cfg.id || }; return group; }逻辑说明外壳body的position.y height / 2是把“底部中心”原点抬到几何中心因为BoxGeometry默认以自身中心为原点。前门往外偏移depth / 2 0.012避免和外壳共面产生 Z-fighting那个 0.012 是血泪经验贴太近会出现闪烁条纹。castShadow和receiveShadow按需开机柜数量多的时候阴影开销很大可以只让外壳投影门和横梁不投影。参数说明metalness不要给到 1没有环境贴图时金属度越高越黑0.40.6 配一盏方向光就够了。opacity0.72 是能看见内部又不至于完全透明低于 0.5 机柜会显得像塑料壳。group.userData.id必须写后面射线拾取到子网格时要向上找祖先拿机柜 ID没有这个字段就只能靠name字符串匹配改一次名全崩。3.2 服务器 U 位排布与状态色映射服务器不是按“第几台”摆而是按“从第几 U 开始、占几 U”摆。1U 服务器厚 0.04445 米2U 就是 0.0889 米但模型不能严丝合缝顶满否则相邻服务器会 Z-fighting。我一般让实际高度乘 0.92留一点缝。颜色按状态映射正常绿、告警黄、严重红、离线灰材质尽量复用别每台服务器 new 一个MeshStandardMaterial。const U 0.04445; const STATE_COLOR { normal: 0x2ecc71, warning: 0xf1c40f, critical: 0xe74c3c, offline: 0x7f8c8d }; const serverMaterialCache new Map(); function getServerMaterial(state) { if (!serverMaterialCache.has(state)) { serverMaterialCache.set( state, new THREE.MeshStandardMaterial({ color: STATE_COLOR[state] || STATE_COLOR.offline, metalness: 0.1, roughness: 0.6, emissive: STATE_COLOR[state] || STATE_COLOR.offline, emissiveIntensity: state critical ? 0.55 : 0.15 }) ); } return serverMaterialCache.get(state); } function addServerToCabinet(cabinet, server, cabinetDepth 1.2) { const { id, uStart, uCount 1, state offline } server; const h uCount * U * 0.92; const mesh new THREE.Mesh( new THREE.BoxGeometry(0.54, h, cabinetDepth * 0.78), getServerMaterial(state) ); // uStart 从 1 开始机柜底部留 0.08m 底座 mesh.position.set(0, 0.08 (uStart - 1) * U h / 2, 0.06); mesh.castShadow false; // 服务器在柜内阴影收益低关掉省性能 mesh.userData { type: server, id, uStart, uCount, state, cabinetId: cabinet.userData.id }; cabinet.add(mesh); return mesh; }逻辑说明h uCount * U * 0.92留缝position.y先加底座 0.08 米再加(uStart - 1) * U最后加半个自身高度这样服务器底部正好落在 U 位起点。cabinetDepth * 0.78让服务器比机柜浅一点前门关上时不会穿模。材质缓存按状态复用几百台服务器只产生四个材质GPU 上传和 draw call 都会少很多。参数说明uStart从 1 开始还是从 0 开始必须跟后端对齐我一般强制从 1 开始0 留给“未知”。emissiveIntensity严重状态给 0.55正常给 0.15太高会让红色糊成一片太低又看不出告警。服务器castShadowfalse是性能取舍如果机房只有十几台服务器可以打开超过两百台就关掉用发光色表达状态更划算。3.3 数据驱动建机房一份 JSON 铺满整个场景机柜和服务器函数写好之后建场景就变成循环先铺地面和墙再按cabinets数组摆机柜每个机柜里按servers数组摆服务器。下面这段是buildRoom的核心重点看错误隔离单个机柜数据坏了不能让整个机房空白。function buildRoom(layout) { const room new THREE.Group(); room.name room-root; const floor new THREE.Mesh( new THREE.PlaneGeometry(layout.room.width, layout.room.depth), new THREE.MeshStandardMaterial({ color: 0x1a2029, roughness: 0.9, metalness: 0.05 }) ); floor.rotation.x -Math.PI / 2; floor.receiveShadow true; room.add(floor); layout.cabinets.forEach((cabinetData) { try { const cabinet createCabinet({ id: cabinetData.id, width: cabinetData.width || 0.6, depth: cabinetData.depth || 1.2, height: cabinetData.height || 2.0 }); cabinet.position.set(cabinetData.x, 0, cabinetData.z); cabinet.rotation.y cabinetData.rotationY || 0; cabinet.userData.row cabinetData.row; cabinet.userData.col cabinetData.col; (cabinetData.servers || []).forEach((server) { addServerToCabinet(cabinet, server, cabinetData.depth || 1.2); }); room.add(cabinet); } catch (err) { console.warn(机柜 ${cabinetData.id} 构建失败, err); } }); scene.add(room); return room; }逻辑说明地面单独铺不要每个机柜带一块地板否则重叠面会闪烁。cabinet.position.set(x, 0, z)的y固定 0因为机柜组原点已经在底部如果模型原点在中心这里就要加height / 2原点约定必须在建模函数里写死。try/catch包住单个机柜某个servers字段不是数组时只跳过这个柜不影响整排。参数说明layout.room.width/depth用来定地面大小也建议用来算相机maxDistance和雾效距离别让用户能缩到墙外。rotationY传给cabinet.rotation.yL 形机房靠它转向。cabinetData.x/z如果是毫米在这里统一除以 1000不要留到服务器层级再换越晚换越乱。4. 交互与信息呈现Raycaster 拾取、CSS2D 标签与侧边详情面板3D 机房如果只能转不能点价值少一半。运维人员要的是“点一下机柜右侧弹出这台柜的 U 位占用和告警”“鼠标移上去机柜高亮标签显示名称”。ThreeJS 做这件事靠Raycaster拾取 CSS2DRenderer标签 普通 HTML 侧栏。三者分工要清楚射线负责选中对象CSS2D 负责空间锚定文字侧栏负责复杂表单和列表别把所有信息都塞进 3D 纹理里。4.1 射线拾取与悬停高亮别改共享材质射线拾取最常见的错误是拿鼠标坐标直接当 NDC 坐标用。Raycaster.setFromCamera要的是-11的归一化设备坐标必须用 canvas 的getBoundingClientRect()换算而且要考虑 canvas 在页面中的偏移。另一个坑是intersectObjects默认不递归机柜是Group直接传机柜组进去点不到里面的服务器。const raycaster new THREE.Raycaster(); const pointer new THREE.Vector2(); let hovered null; let originalEmissive null; function updatePointer(event) { const rect renderer.domElement.getBoundingClientRect(); pointer.x ((event.clientX - rect.left) / rect.width) * 2 - 1; pointer.y -((event.clientY - rect.top) / rect.height) * 2 1; } function pickAtPointer() { raycaster.setFromCamera(pointer, camera); const roots scene.getObjectByName(room-root); const hits raycaster.intersectObjects(roots.children, true); // 必须递归 for (const hit of hits) { let node hit.object; while (node !node.userData?.type) node node.parent; if (node?.userData?.type cabinet || node?.userData?.type server) { return node; } } return null; } function onPointerMove(event) { updatePointer(event); const target pickAtPointer(); if (target hovered) return; if (hovered) { hovered.traverse((child) { if (child.isMesh child.material?.emissive) { child.material.emissiveIntensity child.userData._oldEmissive ?? 0.15; } }); hovered null; } if (target) { hovered target; target.traverse((child) { if (child.isMesh child.material?.emissive) { child.userData._oldEmissive child.material.emissiveIntensity; child.material.emissiveIntensity 0.8; } }); renderer.domElement.style.cursor pointer; } else { renderer.domElement.style.cursor grab; } }逻辑说明pointer.y前面有负号因为浏览器 Y 轴向下、NDC Y 轴向上漏掉负号会出现“鼠标在上、选中在下”。while (node !node.userData?.type)向上找带业务类型的祖先点到服务器子网格也能归到服务器或机柜。高亮时保存原emissiveIntensity不要直接改material.color否则材质是共享的所有同状态服务器一起变色。参数说明roots.children只传机房根节点不要传整个scene场景里还有灯光、地面、辅助线全量递归会拖慢每次pointermove。悬停事件建议加 50ms 节流高频pointermove加射线检测在低端设备上会卡。intersectObjects第二个参数true不能省这是新手最常见的“点了没反应”。4.2 CSS2DRenderer 标签文字别烘进纹理机柜名称、IP 段、温度这些信息如果烘成纹理贴到模型上远处会糊、近处锯齿、改一个字要重新生成贴图。用CSS2DRenderer把 HTML 标签锚在 3D 坐标上字体清晰、可选中、可加 CSS 动画。代价是 DOM 数量几百个标签同时开着会拖慢页面所以标签要按距离和视角做显隐。import { CSS2DRenderer, CSS2DObject } from three/addons/renderers/CSS2DRenderer.js; const labelRenderer new CSS2DRenderer(); labelRenderer.setSize(container.clientWidth, container.clientHeight); labelRenderer.domElement.style.position absolute; labelRenderer.domElement.style.top 0; labelRenderer.domElement.style.left 0; labelRenderer.domElement.style.pointerEvents none; // 关键别挡住 canvas 的鼠标事件 container.appendChild(labelRenderer.domElement); function createCabinetLabel(cabinet, text) { const div document.createElement(div); div.className cabinet-label; div.textContent text; const label new CSS2DObject(div); label.position.set(0, 2.15, 0); // 机柜顶部上方 label.center.set(0.5, 1); cabinet.add(label); return label; } // 每帧渲染标签层 function tick() { controls.update(); renderer.render(scene, camera); labelRenderer.render(scene, camera); requestAnimationFrame(tick); }逻辑说明pointerEvents none必须加否则标签层是一整张透明 DOM鼠标事件全被它截走射线拾取永远点不到模型。标签挂在机柜Group下机柜移动标签跟着走不用每帧手算屏幕坐标。label.center.set(0.5, 1)让标签底部对齐锚点文字在机柜正上方而不是中心穿模。参数说明标签位置y2.15是按 2 米机柜留 15cm机柜加高就要改。标签显隐我一般按相机距离做阈值超过 25 米隐藏只留选中机柜的标签同屏标签超过 80 个就按视野裁剪。labelRenderer.domElement的z-index要低于侧栏、高于 canvas否则标签会盖住弹窗。4.3 点击弹窗与 AJAX 详情接口把重信息放回 HTML点击机柜后不建议在 3D 里画详情直接用右侧固定面板。射线拾取拿到cabinetId或serverId发一个 AJAX 请求拉详情渲染成表格。这样详情字段增删不用动 ThreeJS 代码前端和后端都好维护。下面这段带加载态和请求取消避免快速连点导致旧响应覆盖新面板。let detailController null; async function openDetailPanel(type, id) { const panel document.getElementById(detail-panel); panel.classList.add(is-open); panel.innerHTML div classloading加载中.../div; if (detailController) detailController.abort(); detailController new AbortController(); try { const res await fetch(/api/room/${type}/${encodeURIComponent(id)}, { signal: detailController.signal, headers: { Accept: application/json } }); if (!res.ok) throw new Error(详情接口 ${res.status}); const detail await res.json(); renderDetail(panel, detail); } catch (err) { if (err.name ! AbortError) { panel.innerHTML div classerror详情加载失败请重试/div; console.error(err); } } } renderer.domElement.addEventListener(click, () { const target pickAtPointer(); if (!target) return; const { type, id } target.userData; if (type id) openDetailPanel(type, id); });逻辑说明AbortController用来取消上一次请求快速点三个机柜时只保留最后一个响应否则面板会来回跳。encodeURIComponent防止 ID 里带斜杠或中文导致路径错。点击事件绑在renderer.domElement上不要绑在window否则点侧栏也会触发拾取。参数说明详情接口返回什么就渲染什么前端不要写死字段顺序。侧栏宽度建议 360420px太窄表格挤太宽挡场景。加载态和错误态必须有机房接口偶尔超时用户点了没反应会以为 3D 卡死。如果详情里还要嵌实时温度曲线建议单独用轻量图表库不要把图表也画进 ThreeJS。5. 避坑与排查3D 机房项目里最容易翻车的五件事3D 机房源码能跑起来只是开始真正耗时间的是“看起来差不多、点起来不对”的问题。下面五条是我在类似项目里反复遇到的每条按“现象 → 原因 → 解决”拆开。排查顺序建议从渲染器、坐标、交互、资源释放、移动端性能依次走别一上来就怀疑 ThreeJS 版本。5.1 现象场景全黑机柜像剪影现象页面打开后 canvas 一片黑只能看到机柜轮廓服务器颜色全灰调高颜色值也没用。原因最常见是灯光没加或强度太低。MeshStandardMaterial不是自发光材质没有环境光和方向光时metalness越高越黑机房源码里如果只加了一盏AmbientLight金属外壳会把环境光“吃”掉。第二个原因是渲染器色彩空间没设老代码默认线性输出深色材质会发闷。第三个原因是相机在机柜内部或near/far设错整个场景被裁掉。解决先加HemisphereLight提供基础环境光再加一盏DirectionalLight打阴影强度按场景尺度调。机柜金属度降到 0.5 左右没有环境贴图时不要给 0.9。渲染器颜色空间按当前 ThreeJS 版本设置别抄旧教程的outputEncoding。排查时临时把背景设成亮灰色、材质换成MeshBasicMaterial如果能看到模型说明几何没问题问题在光照和材质。const hemi new THREE.HemisphereLight(0xbfd4ff, 0x1a2029, 0.9); scene.add(hemi); const dir new THREE.DirectionalLight(0xffffff, 1.6); dir.position.set(8, 14, 10); dir.castShadow true; dir.shadow.mapSize.set(1024, 1024); dir.shadow.camera.left -15; dir.shadow.camera.right 15; dir.shadow.camera.top 15; dir.shadow.camera.bottom -15; scene.add(dir);shadow.mapSize不要一上来 4096机房这种大平面 1024 配 PCFSoft 够用阴影相机范围要包住机房否则边缘机柜没影子。5.2 现象机柜整体偏移半米服务器飘在半空现象机柜看起来贴地了但点击高亮框偏到旁边或者服务器底部和 U 位刻度对不上越往上偏得越多。原因模型原点不统一。BoxGeometry默认中心在几何中心有人建机柜时把position.y设成 0结果机柜一半埋地下有人又额外加了height / 2导致整体抬高。服务器 U 位换算时uStart从 0 开始还是从 1 开始没对齐每台差 1U叠到 40U 就偏出机柜。解决定死一条约定——所有机柜组原点在底部中心所有服务器position.y从机柜底部往上算uStart从 1 开始。建一个debugAxis辅助线在机柜底部画一个十字肉眼确认原点。U 位换算只允许在一个函数里出现别在建模、拾取、标签三处各写一遍。5.3 现象鼠标点机柜没反应或者点 A 弹 B现象鼠标移到机柜上不变手型点击不弹面板或者点第一排机柜弹出第三排的详情。原因三个高频问题。第一CSS2D 标签层没设pointer-events: none整层 DOM 把 canvas 事件挡住了。第二intersectObjects没传递归参数true机柜是Group射线只打组不打子网格。第三鼠标坐标没按 canvas 的getBoundingClientRect()换算页面有侧边栏或滚动时NDC 坐标整体偏移点 A 命中 B。解决先检查标签层 CSS再确认射线递归最后打印pointer.x/y看范围是否在-11。点击事件里加一个临时console.log(hit.object.name)看命中的是不是预期网格。如果用了OrbitControls拖拽结束也会触发 click建议记录pointerdown和pointerup的位移超过 5px 就不当点击处理。5.4 现象切换楼层几次后越来越卡最后浏览器崩现象第一次进机房很流畅切换到第二层、第三层再切回来帧率明显下降任务管理器里 GPU 内存持续上涨。原因ThreeJS 的几何体、材质、纹理不会自动释放。每次buildRoom都 new 一批BoxGeometry和MeshStandardMaterial旧场景只是从scene里removeGPU 资源还在。requestAnimationFrame如果开了多个循环每切一次多一个帧率直接腰斩。resize、pointermove事件重复绑定也会累积。解决封装disposeObject3D(root)递归调用geometry.dispose()、material.dispose()、texture.dispose()再从场景移除。全局只保留一个requestAnimationFrame循环切换楼层只换数据不换循环。事件绑定用AbortController或具名函数卸载时removeEventListener。function disposeObject3D(root) { root.traverse((obj) { if (obj.isMesh) { obj.geometry?.dispose(); const materials Array.isArray(obj.material) ? obj.material : [obj.material]; materials.forEach((mat) { Object.values(mat).forEach((v) { if (v v.isTexture) v.dispose(); }); mat.dispose(); }); } }); root.parent?.remove(root); }材质如果放在缓存Map里释放时要清缓存否则下一次建场景又拿到已销毁的材质表现为模型变黑或直接报错。5.5 现象移动端发烫、拖拽卡顿帧率掉到 20现象桌面浏览器 60 帧同一页面在平板或手机上拖拽明显拖影机身发热标签越多越卡。原因setPixelRatio跟随设备像素比高分屏手机上实际渲染像素是 CSS 像素的 3 倍阴影贴图 2048 起步每台服务器独立材质、独立几何体draw call 上千CSS2D 标签几百个同时渲染DOM 重排拖垮主线程。解决像素比限到 2 甚至 1.5阴影贴图降到 1024服务器材质按状态缓存同规格服务器用InstancedMesh合批。标签按相机距离和视野裁剪超过阈值直接visible false。移动端默认关阴影只保留环境光和方向光用发光色表达状态视觉差异不大帧率能回来一截。6. 把帧率稳住InstancedMesh 合批、LOD 与上线前的性能验收机房场景一旦超过两百台服务器逐台Mesh的 draw call 就会成为瓶颈。我的做法是把同规格、同状态的服务器合成InstancedMesh用矩阵写位置用setColorAt写状态色材质只保留一份。机柜本身数量通常几十到一百多可以保留独立Group方便拾取远处再用THREE.LOD换低模。验收时别只看“感觉流畅”打开renderer.info.render.calls和triangles记录切换楼层前后的数值再拿performance.now()统计连续 120 帧的平均帧时间超过 16.7ms 就说明没到 60 帧。const MAX_SERVERS 2000; const geo new THREE.BoxGeometry(0.54, 0.04, 0.9); const mat new THREE.MeshStandardMaterial({ metalness: 0.1, roughness: 0.6 }); const instanced new THREE.InstancedMesh(geo, mat, MAX_SERVERS); instanced.instanceMatrix.setUsage(THREE.DynamicDrawUsage); const dummy new THREE.Object3D(); const color new THREE.Color(); let index 0; function pushServerInstance(x, y, z, stateColor) { dummy.position.set(x, y, z); dummy.updateMatrix(); instanced.setMatrixAt(index, dummy.matrix); instanced.setColorAt(index, color.setHex(stateColor)); index; } instanced.count index; instanced.instanceMatrix.needsUpdate true; instanced.instanceColor.needsUpdate true; scene.add(instanced);这段代码的关键参数是MAX_SERVERS要按机房最大容量预留count按实际写入数量设置不然会渲染一堆零矩阵实例在原点。instanceColor需要材质支持顶点颜色状态色才能生效。拾取时InstancedMesh的hit.instanceId能拿到实例索引再映射回服务器 ID不要再用逐台Mesh的userData。验收项目标值查看方式draw calls小于 200renderer.info.render.calls三角面数小于 50 万renderer.info.render.triangles平均帧时间小于 16.7ms连续 120 帧performance.now()GPU 内存切换楼层后不持续上涨浏览器性能面板对比上线前我固定跑三遍空场景、单机柜、全量数据每遍都切一次楼层再切回来看renderer.info是否回到基线。从那以后我每次改完机房模型都强制走一遍这个流程不再靠“看起来不卡”判断。这套源码拿到后建议先跑最小场景再把机柜数据替换成自己的最后才动材质和光照。希望帮到你。本文还有配套的精品资源点击获取