简介这是一份面向WebGL与Three.js开发者、3D可视化学习者及智慧城市项目实践者的完整源码实例帮助读者理解如何将浏览器端3D图形技术落地到城市级场景中。资源包共60个文件以23个JavaScript脚本为核心配合10个CSS样式、16个PNG与8个JPG贴图资源另有HTML入口、说明文本及draco解码wasm文件整体约3.06MB结构紧凑、便于本地运行与二次开发。项目覆盖地图与地理数据处理、建筑与道路等3D模型构建、光照材质设置、车辆与人群动画、点击拖动交互、实时数据可视化以及LOD、批处理渲染等性能优化策略并涉及响应式布局与后端数据通信思路。目前已有3927人学习下载适合希望从基础3D编程进阶到城市级可视化实战的开发者参考借鉴。1. 智慧城市可视化为什么总在“看着炫、跑着卡”之间反复横跳做过三维可视化大屏的人大概都有过这种体验演示阶段帧率稳在 60一上真实数据、一叠加图层浏览器风扇就开始起飞鼠标拖拽变成幻灯片。智慧城市这个方向尤其典型——建筑体量动辄几十万面片路网、管线、摄像头点位、实时车流全都要塞进同一个场景还要保证在普通办公本上能转得动。WebGL 加 Three.js 这套组合之所以被大量项目选中核心原因是它把渲染管线压到了浏览器原生能力上不需要插件跨平台部署成本低配合实例化、LOD、合批这些手段确实能把一个城市级别的场景跑起来。这篇要聊的就是围绕“WebGL Three.js 智慧城市应用”这类项目源码实例怎么读懂它的结构、怎么把关键模块拆出来复用到自己的工程里、哪些参数一改就翻车。适合两类人一类是刚接手三维大屏、拿到一份源码不知道从哪下手的开发者另一类是自己搭过场景但性能始终压不下去、想看看成熟项目怎么组织图层和数据的熟手。下面按“场景怎么搭 → 数据怎么进 → 性能怎么保 → 坑在哪 → 怎么验证”的顺序推。2. 从源码实例里拆出智慧城市场景的四层骨架一份能跑的智慧城市 Three.js 工程不管目录怎么起名逻辑上基本都能拆成四层渲染底座、场景内容、数据驱动、交互与状态。看懂这四层的边界比逐行读代码有用得多因为你要复用的往往只是其中一两层。2.1 渲染底座Renderer、Camera、Controls 的初始化顺序底座这层决定了整个应用的“体质”。很多源码实例把初始化写在一个 init 函数里顺序其实有讲究先建 renderer再建 scene然后 camera最后挂 controls。顺序反了不会立刻报错但会在 resize、销毁、多场景切换时出玄学问题。import * as THREE from three; import { OrbitControls } from three/examples/jsm/controls/OrbitControls.js; // 1. 渲染器智慧城市场景面片多开抗锯齿但别盲目开高倍像素比 const renderer new THREE.WebGLRenderer({ antialias: true, alpha: false, powerPreference: high-performance // 提示浏览器优先用独显 }); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); // 关键封顶 2 renderer.setSize(window.innerWidth, window.innerHeight); renderer.shadowMap.enabled true; renderer.shadowMap.type THREE.PCFSoftShadowMap; document.getElementById(app).appendChild(renderer.domElement); // 2. 场景雾用来遮远处裁剪边界比硬裁剪自然 const scene new THREE.Scene(); scene.background new THREE.Color(0x0a1a2f); scene.fog new THREE.Fog(0x0a1a2f, 800, 3000); // 3. 相机智慧城市常用俯视带倾角fov 别超过 60 const camera new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 1, // near 别设 0.1深度精度会被吃掉 5000 // far 按场景实际尺度给给太大 z-fighting 找上门 ); camera.position.set(600, 500, 600); // 4. 控制器限制俯仰角防止用户转到地底下 const controls new OrbitControls(camera, renderer.domElement); controls.maxPolarAngle Math.PI / 2.2; controls.minDistance 100; controls.maxDistance 2500; controls.enableDamping true; controls.dampingFactor 0.08;这段代码里最容易被忽略的是setPixelRatio的封顶。高分屏设备上devicePixelRatio能到 3意味着渲染面积是逻辑像素的 9 倍智慧城市这种重场景直接跪。封到 2 是画质和性能的常见平衡点。near设成 1 而不是 0.1是因为透视相机的深度缓冲精度和 near/far 比值强相关near 太小会让远处建筑闪烁。maxPolarAngle限制到略小于 90 度避免相机穿到地面以下看到背面剔除后的空洞。2.2 场景内容建筑、路网、点位怎么分层管理场景内容这层成熟项目几乎都会用THREE.Group做逻辑分组而不是把所有 mesh 平铺在 scene 下。分组的意义不只是好找更在于可以整组控制可见性、整组做矩阵变换、整组参与射线检测。// 按业务语义分组而不是按模型来源分组 const cityRoot new THREE.Group(); cityRoot.name cityRoot; const buildingLayer new THREE.Group(); // 建筑体块 const roadLayer new THREE.Group(); // 路网与地面 const markerLayer new THREE.Group(); // 摄像头、传感器点位 const effectLayer new THREE.Group(); // 光墙、扫描、飞线 cityRoot.add(buildingLayer, roadLayer, markerLayer, effectLayer); scene.add(cityRoot); // 图层开关大屏上常见的“建筑/路网/点位”勾选框直接映射到这里 function toggleLayer(layer, visible) { layer.visible visible; }分组之后射线检测也能收窄范围。智慧城市里鼠标拾取通常只关心建筑和点位如果对整个 scene 做raycaster.intersectObjects(scene.children, true)每帧遍历所有对象性能会被拖垮。正确做法是只传需要拾取的图层数组并且recursive按需开。2.3 数据驱动把后端 JSON 映射成场景对象源码实例里最值得抄的是数据到场景的映射方式。常见做法是后端返回一份带坐标和类型的 JSON前端用一个工厂函数根据 type 创建对应对象而不是为每种对象写一套加载逻辑。// 假设后端返回的建筑数据坐标是经纬度或工程坐标 const buildingData [ { id: b1, type: building, x: 120, z: 80, w: 40, h: 90, d: 40, color: 0x2a6fb0 }, { id: b2, type: building, x: 200, z: 150, w: 60, h: 140, d: 50, color: 0x2a6fb0 } ]; const geometryCache new THREE.BoxGeometry(1, 1, 1); // 复用几何体 const materialCache new Map(); // 按颜色缓存材质 function createBuilding(item) { if (!materialCache.has(item.color)) { materialCache.set(item.color, new THREE.MeshLambertMaterial({ color: item.color })); } const mesh new THREE.Mesh(geometryCache, materialCache.get(item.color)); mesh.position.set(item.x, item.h / 2, item.z); mesh.scale.set(item.w, item.h, item.d); mesh.userData { id: item.id, type: item.type }; // 业务数据挂在 userData return mesh; } buildingData.forEach(item buildingLayer.add(createBuilding(item)));这里两个细节决定了性能上限几何体和材质都做了缓存复用。如果每个建筑都new THREE.BoxGeometry一千栋楼就是一千个几何体显存和 draw call 都会爆。用单位立方体加scale的方式所有建筑共享同一个几何体draw call 虽然还在但显存占用和上传开销大幅下降。userData挂业务 id 是拾取后反查数据的标准做法比维护一个外部 Map 更省心。2.4 交互与状态拾取、高亮、相机飞行的最小闭环交互层的最小闭环是鼠标移动拾取 → 高亮目标 → 点击后相机飞过去。这三步在源码里通常分散在事件监听和动画循环里拆出来看并不复杂。const raycaster new THREE.Raycaster(); const pointer new THREE.Vector2(); let hovered null; renderer.domElement.addEventListener(pointermove, (e) { pointer.x (e.clientX / window.innerWidth) * 2 - 1; pointer.y -(e.clientY / window.innerHeight) * 2 1; raycaster.setFromCamera(pointer, camera); const hits raycaster.intersectObjects([buildingLayer, markerLayer], true); const first hits[0]?.object || null; if (first ! hovered) { if (hovered) hovered.material.emissive?.setHex(0x000000); hovered first; if (hovered) hovered.material.emissive?.setHex(0x333300); } });高亮用emissive而不是换材质是为了避免频繁创建销毁材质带来的 GC 抖动。相机飞行一般用补间自己写一个简单的 lerp 就够不必引入额外库。注意pointermove里做射线检测要节流否则高刷屏上每秒触发上百次拾取本身就成了瓶颈。3. 性能优化智慧城市场景绕不开的四个参数智慧城市项目能不能落地八成看性能。这一章不讲泛泛的“优化建议”只讲源码实例里真正影响帧率的几个具体参数和手段。3.1 实例化把上千个路灯、树木压成一次 draw call场景里重复元素最多的往往是路灯、树木、护栏这类。用InstancedMesh能把它们合并成一次绘制调用。const lampGeometry new THREE.CylinderGeometry(0.5, 0.5, 8, 6); const lampMaterial new THREE.MeshLambertMaterial({ color: 0xcccccc }); const lampCount 1200; const lamps new THREE.InstancedMesh(lampGeometry, lampMaterial, lampCount); const dummy new THREE.Object3D(); for (let i 0; i lampCount; i) { dummy.position.set(positions[i].x, 4, positions[i].z); dummy.rotation.y Math.random() * Math.PI; dummy.updateMatrix(); lamps.setMatrixAt(i, dummy.matrix); } lamps.instanceMatrix.needsUpdate true; markerLayer.add(lamps);InstancedMesh的关键限制是每个实例共享同一材质没法单独改颜色除非用instanceColor。所以它适合路灯、树木这种外观统一的元素不适合需要逐个高亮变色的建筑。数量上实例化对 draw call 的削减是线性的1200 个路灯从 1200 次调用降到 1 次收益非常直接。3.2 LOD远处建筑该降面就降面智慧城市场景的相机经常从高空俯视远处建筑在屏幕上可能只有几个像素却还在用高模渲染纯属浪费。LOD对象可以按距离切换不同精度的模型。const lod new THREE.LOD(); lod.addLevel(highDetailMesh, 0); // 0-300 距离用高模 lod.addLevel(midDetailMesh, 300); // 300-800 用中模 lod.addLevel(lowDetailMesh, 800); // 800 以上用低模或盒子 lod.autoUpdate true; buildingLayer.add(lod);实际项目里高模和中模的切换距离要根据相机 fov 和屏幕分辨率调。一个经验值当物体在屏幕上的投影小于 50 像素时就可以考虑降级。LOD的autoUpdate默认开着每帧会计算距离对象特别多时这个计算本身也有成本可以改成手动在相机移动后统一更新。3.3 合批与材质合并减少状态切换比 draw call 更隐蔽的瓶颈是材质切换。每次切换材质GPU 都要重新绑定状态。如果场景里几百个建筑各用各的材质即使 draw call 不多状态切换也会拖慢帧率。import { mergeGeometries } from three/examples/jsm/utils/BufferGeometryUtils.js; // 把同材质的静态建筑几何体合并成一个 const mergedGeometry mergeGeometries( buildingGeometries, // 已经应用过世界矩阵的几何体数组 false ); const mergedMesh new THREE.Mesh(mergedGeometry, sharedMaterial); buildingLayer.add(mergedMesh);合并的前提是这些建筑是静态的、不需要单独拾取。如果需要拾取合并后就只能拿到合并后的整体得靠额外的空间索引反查。所以常见做法是静态背景建筑合并需要交互的建筑单独保留。3.4 渲染循环requestAnimationFrame 里的取舍渲染循环里最容易犯的错是每帧都做重计算。比如每帧更新所有点位的位置、每帧重建几何体、每帧遍历全场景做拾取。let lastPickTime 0; const PICK_INTERVAL 100; // 拾取节流到 100ms 一次 function animate(time) { requestAnimationFrame(animate); controls.update(); // 拾取节流不是每帧都做 if (time - lastPickTime PICK_INTERVAL) { doPick(); lastPickTime time; } // 只更新可见图层的动画 if (effectLayer.visible) updateEffects(time); renderer.render(scene, camera); } requestAnimationFrame(animate);controls.update()在开了 damping 后必须每帧调用否则阻尼不生效。但拾取、数据刷新、UI 同步这些没必要每帧做按业务需要节流到 10Hz 甚至 1Hz 都够。渲染循环里省下来的每一毫秒都会体现在低端设备能不能跑起来上。4. 避坑与排查源码跑不起来时先看这几处拿到一份智慧城市源码跑不起来或跑起来不对问题往往集中在几个固定位置。下面按“现象 → 原因 → 解决”列几条血泪经验。4.1 场景全黑或只有背景色现象页面加载后只有背景色看不到任何模型控制台无报错。原因最常见的是相机位置和模型尺度不匹配。源码里的模型可能以米为单位坐标在几百到几千而相机默认在原点附近或者 near/far 范围没覆盖到模型。其次是光照缺失MeshLambertMaterial和MeshStandardMaterial没有光源就是全黑。解决先加一个AxesHelper和BoxHelper确认模型位置把相机放到模型包围盒外侧。再检查场景里有没有AmbientLight或DirectionalLight。如果用的是MeshBasicMaterial还黑那就是模型根本没加进 scene检查add调用。4.2 帧率随运行时间持续下降现象刚打开 60 帧跑几分钟后掉到 20 帧以下且不恢复。原因典型的资源泄漏。常见于每次数据刷新都new几何体或材质旧的没有dispose或者事件监听重复绑定每次刷新都加一个pointermove或者动画循环里不断往场景里加对象从不移除。解决数据刷新时复用对象池只更新矩阵和属性不重建。移除对象时调用geometry.dispose()和material.dispose()。事件监听用命名函数绑定刷新前先removeEventListener。用renderer.info看geometries和textures数量是否随时间增长。4.3 建筑之间出现闪烁的深度冲突现象相邻或重叠的建筑表面出现闪烁的斑块相机一动就变。原因z-fighting深度缓冲精度不足。通常是 near 设得太小、far 设得太大或者两个面几乎共面。解决把 near 调大比如从 0.1 调到 1far 按场景实际范围收紧。如果两个面确实需要共面给其中一个加微小的偏移或者用polygonOffset。建筑底部和地面重叠时把建筑底部抬高 0.01 也能缓解。4.4 拾取不准或拾取不到现象鼠标点在建筑上没反应或者点 A 建筑高亮了 B。原因射线检测的坐标系没对齐。pointer的归一化坐标算错或者 canvas 有 CSS 缩放、偏移导致鼠标位置和渲染区域不一致。另一种是拾取对象数组传错把不该参与拾取的辅助对象也传进去了。解决确认pointer.x/y用的是clientX减 canvas 的getBoundingClientRect()而不是直接除以innerWidth。如果 canvas 被 CSS 拉伸要用实际渲染尺寸换算。拾取时只传业务图层辅助对象设raycast () {}禁用拾取。4.5 移动端直接白屏或崩溃现象桌面正常手机打开白屏或者加载到一半标签页崩溃。原因移动端 GPU 显存和内存都紧张。智慧城市场景的纹理、几何体在桌面可能只占几百 MB到手机上直接超限。另外devicePixelRatio在手机上可能到 3 甚至 4渲染面积爆炸。解决移动端把setPixelRatio封到 1.5 甚至 1纹理用压缩格式并限制最大尺寸几何体做更激进的 LOD。加载阶段分批进行不要一次性把所有模型塞进显存。用renderer.capabilities检查最大纹理尺寸和顶点数限制。5. 怎么判断一份智慧城市源码值不值得参考源码实例的价值不在代码量而在它有没有把上面这些工程问题处理干净。拿到一份源码我一般按下面这个顺序快速过一遍十分钟就能判断要不要深入。检查项值得参考的表现需要警惕的表现图层组织按业务语义分组有可见性开关所有 mesh 平铺在 scene 下几何体复用共享几何体用 scale 变形每个对象独立 new Geometry材质管理材质缓存或合并数量可控每个对象独立材质拾取实现限定图层有节流全场景递归拾取每帧执行资源释放有 dispose 调用和对象池只加不减刷新即重建移动端适配像素比封顶有降级策略直接照搬桌面配置除了看代码还要看它怎么处理数据边界。比如建筑数据量从一千涨到一万时场景是卡死还是有分批加载点位数据实时更新时是重建对象还是更新属性。这些边界处理才是源码实例里最值钱的部分也是最容易在演示版里被省略的部分。一个具体的验证技巧把源码里的数据量乘以 10看帧率和内存怎么变。如果直接崩说明它只适合演示不适合落地如果帧率下降但还能用说明架构基本合理剩下的就是参数调优。这个乘法测试比读一百行代码都管用。我自己踩过最深的一个坑是早期拿到一份源码直接往项目里搬场景跑得挺顺结果数据一接实时接口每秒钟刷新一次点位内存曲线一路向上半小时后页面卡死。后来才发现它每次刷新都new一个Sprite旧的从场景移除但没dispose。从那以后我看任何三维源码第一件事就是搜dispose出现的次数第二件事是看数据刷新路径上有没有对象池。这个习惯帮我省了太多后悔药。希望帮到你。本文还有配套的精品资源点击获取