简介3D可视化技术正成为智慧校园与数字孪生场景的重要呈现方式。通过WebGL渲染引擎three.js开发者可以在浏览器中构建交互式三维地图。实现过程中经纬度坐标需经局部坐标系转换以避免浮点精度引发的场景抖动地形可借助PlaneGeometry与噪声函数生成建筑则通过ExtrudeGeometry拉伸并利用InstancedMesh合并绘制从而大幅降低draw call。该技术路径不仅适用于校园也可推广至园区、车间等小范围场景甚至可与vue2百度的3D实景地图模型加载相结合。掌握这些基础原理与工程实践即可高效完成从数据准备到交互展示的完整流程。1. 项目定位与方案选择为什么用 three.js 做 3D 地图前阵子接到一个校园三维可视化需求要求把整个校区的地形、建筑、道路、水系在浏览器里做成可交互的 3D 场景。一提到 3D 地图很多人第一反应是 Cesium、Mapbox GL或者 UE5 像素流但综合考虑项目预算、部署成本、前端技术栈之后我最终选择了 three.js 作为核心渲染引擎。这篇博文就把整个实现过程拆开讲一讲从数据准备到坐标转换从地形生成到建筑建模从交互拾取到性能优化一条线走完。先说说为什么是 three.js 而不是其他方案。Cesium 主打全球尺度加载倾斜摄影、地形瓦片确实强但如果需要的只是一个园区、一个校区、一个厂区这种小范围场景用 Cesium 就像杀鸡用牛刀学习成本高、包体体积大、API 抽象层级也重。Mapbox GL 的地图底图渲染很强但它本身是 2.5D 的想在它上面自由做建筑体块拉伸、做水流动画、做自定义交互限制比较多。three.js 的好处是足够底层也足够灵活场景、网格、材质、相机全部自己掌控做小范围 3D 地图再合适不过。它不叫“地图引擎”但它能拼装出你想要的一切地图效果。这个方案适合谁来参考如果你正在做智慧校园、智慧园区、数字孪生车间、展厅大屏可视化或者单纯想给自己的个人项目做一个炫酷的 3D 小地图这篇文章里的思路和代码都可以直接复用。接下来我会以一个校园 3D 地图项目为案例背景把关键环节逐一拆解每一步该怎么做、为什么这么做、坑在哪里都会讲清楚。2. 数据准备与坐标系转换地图数据怎么变成 three.js 场景2.1 先搞清楚数据从哪来做 3D 地图第一步不是写代码而是搞数据。一个校园地图需要的数据大致分四类地形数据地块范围、高程信息如果没有精确 DEM 数据可以用噪声函数模拟起伏。建筑数据建筑轮廓多边形、建筑高度、楼层数通常可以从 OpenStreetMap 导出 GeoJSON或者从规划图纸里人工绘制。道路与路网道路中心线或边线同样是 GeoJSON 格式。水系与绿地河流、湖泊、池塘的边界以及绿化区域范围。我用的是 OSM 导出的校园 GeoJSON加上自己补充的建筑高度字段。如果你在给一个具体园区做项目拿到 CAD 图纸之后转成 GeoJSON 也是常见路径。注意OSM 的建筑数据常常缺高度需要人工调研或者按楼层数估算。我当时是按“每层 3.5 米”乘楼层数算的误差在可接受范围内。2.2 经纬度坐标怎么变成平面坐标GeoJSON 里存的是经纬度而 three.js 场景是一个三维笛卡尔坐标系X 向右、Y 向上、Z 朝向屏幕外或者用 Z 表示南北方向。所以第一步必须做投影转换。常用的做法是 Web Mercator 投影也就是把经纬度转成米制平面坐标。不过实际项目里不需要引入很重的 GIS 库简单算一个局部切平面就够了function lonLatToMercator(lon, lat) { const x lon * 20037508.34 / 180; let y Math.log(Math.tan((90 lat) * Math.PI / 360)) / (Math.PI / 180); y y * 20037508.34 / 180; return { x, y }; }这样做完所有经纬度点都变成了以米为单位的平面坐标。但 web 墨卡托的数值非常大几百万的量级直接塞进 three.js 会触发浮点数精度问题导致场景抖动、闪烁。解决办法是“局部坐标系化”把所有坐标都减去中心点的坐标让场景原点附近的数值保持在几千以内。const center lonLatToMercator(centerLon, centerLat); const positions feature.geometry.coordinates[0].map(([lon, lat]) { const p lonLatToMercator(lon, lat); return { x: p.x - center.x, z: p.y - center.y }; });这里有个约定我把墨卡托的 y 放到了 three.js 的 z 轴上x 保持不变。这样地形上的东西南北方向和经纬网一致后续摆放模型、调整相机方向都符合直觉。2.3 为什么局部坐标系能避免精度坑three.js 的相机、场景节点在渲染时会做大量矩阵运算坐标值越大浮点数误差越明显。想象一下你在城市的另一端看一栋楼和站在楼底下看这栋楼同一个模型在空间里的表现截然不同。局部坐标把项目范围缩小到原点附近几百米的场景里Float32 精度完全够用。踩过这个坑之后我建议所有 GIS 数据进 three.js 之前都先做“去中心化”。别嫌麻烦这步不做后面模型抖动、贴图闪烁会折腾到你想放弃。3. 地形生成与场景环境先把“地”搭起来3.1 场景初始化核心流程其实只有几行代码但每一步都要有意识地去配置。const scene new THREE.Scene(); const camera new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 10000); camera.position.set(300, 350, 500); const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setSize(window.innerWidth, window.innerHeight); renderer.shadowMap.enabled true; document.body.appendChild(renderer.domElement);相机初始化位置我习惯放在地形的斜上方约 45 度俯视角看校园全景刚刚好。抗锯齿必须打开否则地形边界、建筑边缘的锯齿会非常明显尤其是大屏投放场景锯齿一放大就很廉价。OrbitControls 是必装的辅助库它解决了相机旋转、缩放、平移的基础交互。import { OrbitControls } from three/examples/jsm/controls/OrbitControls.js; const controls new OrbitControls(camera, renderer.domElement); controls.enableDamping true; controls.maxPolarAngle Math.PI / 2.4;maxPolarAngle 限制最大俯视角度防止用户把视角转到地面以下。enableDamping 打开惯性效果手感会顺滑很多。3.2 用 PlaneGeometry 生成地形网格地形我直接用 PlaneGeometry 来生成分段数决定地形细腻度。一个 705 米 x 500 米的校园用 128 段 x 128 段顶点数约 1.6 万个完全够用。const width 800; const depth 600; const segments 128; const geometry new THREE.PlaneGeometry(width, depth, segments, segments); geometry.rotateX(-Math.PI / 2);注意 rotateX。PlaneGeometry 默认在 XY 平面旋转 -90 度后变成 XZ 平面Y 轴朝上这样才符合 three.js 地形的通用做法。接下来要处理顶点高度。有真实 DEM 数据的直接读取高程数组写入顶点 Y 值。没有数据的情况下我用简单柏林噪声来模拟地形起伏保证场景不死板。const positionAttribute geometry.attributes.position; for (let i 0; i positionAttribute.count; i) { const x positionAttribute.getX(i); const z positionAttribute.getZ(i); const height getNoiseHeight(x, z); positionAttribute.setY(i, height); } geometry.computeVertexNormals();computeVertexNormals 一定要调否则地形上光照表现是平的明暗变化完全没有看起来像塑料片。3.3 顶点着色让地形有质感地形高度不只是几何形态还可以映射成颜色。低洼处用蓝绿色山丘用褐色顶部用灰白色这样可以做出等高线般的视觉效果。const colors []; for (let i 0; i positionAttribute.count; i) { const y positionAttribute.getY(i); const t (y - minHeight) / (maxHeight - minHeight); const color new THREE.Color(); if (t 0.3) { color.setRGB(0.3, 0.6, 0.4); } else if (t 0.7) { color.setRGB(0.1, 0.4, 0.2); } else { color.setRGB(0.5, 0.5, 0.4); } colors.push(color.r, color.g, color.b); } geometry.setAttribute(color, new THREE.Float32BufferAttribute(colors, 3));用顶点色而不是贴图的好处是不依赖外部图片资源部署方便而且颜色随地形动态变化时只需要改数组非常灵活。材质记得开启 vertexColors。const material new THREE.MeshStandardMaterial({ vertexColors: true }); const terrain new THREE.Mesh(geometry, material); scene.add(terrain);3.4 光照、雾和天空3D 地图对光照要求不高但不打光不行。我习惯用一束平行光模拟太阳再加一个环境光补亮阴影面。const sunLight new THREE.DirectionalLight(0xffffff, 1.5); sunLight.position.set(200, 400, 300); scene.add(sunLight); const ambient new THREE.AmbientLight(0xffffff, 0.6); scene.add(ambient);如果开了阴影地形要设置 receiveShadow建筑要设置 castShadow。但阴影会显著增加渲染开销移动端建议直接关掉用伪阴影替代。再给场景加一层淡雾一是弱化地平线的硬边二是有一种空间纵深的感觉。scene.fog new THREE.Fog(0xf0f5e8, 800, 2500);4. 建筑、道路和水系的模型化从“地图”到“场景”4.1 建筑用 ExtrudeGeometry 拉伸拿到建筑轮廓后最直接的做法是利用 ExtrudeGeometry 把多边形拉伸成体块。const shape new THREE.Shape(); polygon.forEach((point, i) { if (i 0) shape.moveTo(point.x, point.z); else shape.lineTo(point.x, point.z); }); shape.closePath(); const extrudeSettings { depth: buildingHeight, bevelEnabled: false }; const geometry new THREE.ExtrudeGeometry(shape, extrudeSettings); const mesh new THREE.Mesh(geometry, buildingMaterial);这里的 depth 就是楼高Y 轴方向向上拉伸。bevelEnabled 必须设成 false否则建筑棱边会有斜角楼体看起来圆滚滚而且会大幅增加顶点数。建筑材质可以做成“白天模式”和“夜晚模式”两套白天用浅灰白加一点环境反射夜晚把窗户区域做成自发光。我在项目里给建筑材质单独加了 emissive 属性夜晚让色块微微泛光大屏视觉效果很不错。4.2 建筑数量上百后怎么优化校园里单体建筑四五十栋还好但如果做园区建筑上百栋逐个创建 Mesh 会导致 draw call 爆炸。优化手段是用 InstancedMesh 批量渲染同种模型。不过 InstancedMesh 要求所有实例共享同一个几何体建筑高度各不相同怎么办我的做法是把建筑按高度分成几档每档用一个几何体然后用 InstancedMesh 渲染同一档里的所有建筑。const groupedBuildings buildBuildingsByHeight(buildings, [8, 16, 24, 36]); for (const [height, list] of groupedBuildings) { const geometry createBuildingGeometry(height); const mesh new THREE.InstancedMesh(geometry, material, list.length); list.forEach((building, i) { const matrix new THREE.Matrix4(); matrix.setPosition(building.x, height / 2, building.z); matrix.scale(new THREE.Vector3(building.scaleX, 1, building.scaleZ)); mesh.setMatrixAt(i, matrix); }); scene.add(mesh); }这样一搞上百栋建筑只产生几次 draw call帧率压力小得多。4.3 道路怎么做才不“飘”道路数据通常是线或者窄多边形。最简单的方式是把路网转成 Line 对象配合 LineBasicMaterial 输出。但如果想做出有质感的道路我更推荐把道路两边线和中心线组合成多边形然后贴到地形表面。最稳妥的贴地做法是“偏移法”把道路多边形每个顶点的高度采样地形高度再手动加 0.3 米的偏移量。不要试图让道路物理贴合地形网格那样徒增复杂度。我试过把道路做成独立 Mesh 贴在模型上只要偏移值大于地形起伏俯视看不出破绽侧面看也不会 z-fighting。水系同理用多边形勾勒河岸、湖面边界铺一个透明材质const waterMaterial new THREE.MeshStandardMaterial({ color: 0x3399ff, transparent: true, opacity: 0.7, });河岸边缘多边形的每个点同样需要从地形采样高度。这个步骤漏了的话水面就会在某处悬空或者穿到地下。4.4 河流流动怎么做纯静态水面总感觉差点意思。给水面加一个 UV 偏移做出流动方向感waterMaterial.onBeforeCompile (shader) { shader.uniforms.uTime { value: 0 }; shader.vertexShader uniform float uTime; varying vec2 vUv; ${shader.vertexShader} .replace( #include begin_vertex, #include begin_vertex vUv uv; float flow sin(uv.x * 10.0 uTime) * 0.02; transformed.y flow; ); };要点是让水面顶点做小幅正弦抖动同时让纹理采样点随时间偏移。做过之后河面有微微的波光流动整个场景立刻“活”了。5. 交互与标注点击、悬浮、弹窗和文字标签5.1 鼠标拾取建筑地图没有交互就没有灵魂。three.js 里点击判断用 Raycasterconst raycaster new THREE.Raycaster(); const mouse new THREE.Vector2(); function onMouseClick(event) { mouse.x (event.clientX / window.innerWidth) * 2 - 1; mouse.y -(event.clientY / window.innerHeight) * 2 1; raycaster.setFromCamera(mouse, camera); const intersects raycaster.intersectObjects(buildingMeshes); if (intersects.length 0) { const building intersects[0].object; showBuildingInfo(building); } }这里有个经验buildingMeshes 不要传三维数组嵌套的对象要拍平成一维数组否则 Raycaster 递归遍历会非常慢。建筑数量多的时候建议用三个参数快速筛选raycaster.intersectObjects(buildingMeshes, false)false 表示不递归子节点。5.2 标注用 CSS2DRenderer 比 Sprite 强建筑上的名称标注很多人会想到 Sprite。Sprite 确实会用但文字一旦多了就糊成一片而且缩放距离和相机交互很难控制。我更推荐 CSS2DRenderer它是把 HTML 标签挂在 3D 坐标上清晰度完胜也能很方便地加 CSS 样式、hover 效果。import { CSS2DRenderer, CSS2DObject } from three/examples/jsm/renderers/CSS2DRenderer.js; const labelRenderer new CSS2DRenderer(); labelRenderer.setSize(window.innerWidth, window.innerHeight); labelRenderer.domElement.style.position absolute; labelRenderer.domElement.style.top 0; labelRenderer.domElement.style.pointerEvents none; document.body.appendChild(labelRenderer.domElement);注意 CSS2DRenderer 的 DOM 元素要关闭 pointerEvents否则它会在 three.js canvas 上面盖一层挡住鼠标事件导致点击拾取失效。这个坑我踩了一次排查半天才发现是标签层挡住了画布。创建标注对象const div document.createElement(div); div.className label; div.textContent building.name; const label new CSS2DObject(div); label.position.set(building.x, building.height 5, building.z); scene.add(label);标注渲染循环里必须同时调用 CSS2DRenderer 的 renderlabelRenderer.render(scene, camera);5.3 点击建筑高亮与信息面板点击高亮我用的是两种方案结合一是给建筑材质设置 emissive 提亮二是给选中建筑加一层外发光边框。最简单的是改 emissivebuilding.material.emissive.setHex(0xff8800);注意如果建筑是共享材质直接改 material 会同时改变所有同材质的建筑。所以必须 clone 一份材质再改building.material building.material.clone(); building.material.emissive.setHex(0xff8800);信息面板就是普通的 HTML 绝对定位弹窗点击建筑后显示名称、楼层数、面积、用途。HTML 做展示层的优势是排版、样式、响应式都容易控制不用在 three.js 里画 UI。6. 性能优化与常见问题排查6.1 控制 draw callsthree.js 场景中每个 Mesh 每个材质基本对应一次 draw call。校园场景如果建筑、路灯、树木、路牌全部独立生成几百上千的 draw call 是常态低端设备掉帧严重。经验值如下60 FPS 目标下桌面端尽量控制在 300 次 draw call 以内。移动端大屏尽量控制在 100 次以内。优化手段按优先级排InstancedMesh 合并同类建筑、合并静止的地形道路网格、删除不可见物体、大场景开视锥剔除、合并纹理图集。6.2 浮点精度和坐标抖动前面提过局部坐标能解决大部分精度问题但还有一个补充技巧把 camera 的 position 也往原点靠。如果你做的是超大地图比如整个城市那就需要“随动原点”方案即相机移动时把整个场景反向移动始终保持相机离原点很近。const offset camera.position.clone(); // 当相机距离原点超过阈值时 scene.position.sub(offset); camera.position.sub(offset);这不是我这个项目的刚需但如果你后续要扩展到更大范围建议提前架构。6.3 常见问题速查现象原因解决办法地形边缘闪白z-fighting相邻 Mesh 贴太近偏移 0.01~0.1建筑飘在半空轮廓点高度未采样地形每个点做高度采样再加 baseY水面穿地水面顶点高度低于地形水面统一抬高到地形最高水位点击没反应CSS2D 标签遮挡 canvaslabelRenderer.domElement.style.pointerEvents none移动端卡顿阴影 抗锯齿开销太大关阴影或关 antialias建筑材质全变了多个建筑共享同一个 material修改前先 clone()相机穿地OrbitControls 未限制俯仰角设置 maxPolarAngle这七个问题是我项目里实际遇到过的每一个都花了不少时间定位。尤其 z-fighting 和共享材质定位过程极其迷惑经验不分享出来真心难受。6.4 项目工程化在 Vue 里集成 three.js热词里提到“vue2 百度 3d 实景地图加载 3d 模型”这个方向很多人问。我在实际项目里是把 three.js 场景封装成一个独立的类然后挂在 Vue 的 mounted 钩子初始化卸载时销毁渲染器和 scene。这里给出一个精简的集成模式export default { mounted() { this.map3d new Campus3DMap(); this.map3d.init(document.getElementById(map-container)); }, beforeDestroy() { this.map3d.dispose(); } };所有的 three.js 代码尽量不直接写在 Vue 组件里而是抽成独立模块。好处是后续更换框架、复用场景、单元测试都方便。数据请求放在 Vue 层通过事件或方法注入到三维场景中这样数据和渲染完全解耦。6.5 three.js 版本与资源获取热词里有人问 three.js 怎么下载、中文文档在哪统一说一嘴。three.js 目前最推荐的方式是 npm 安装npm install three如果做 CDN 引入官方推荐用 ES module 的 importmap 方式。中文文档方面three.js 官方文档是英文的国内有一些中文镜像站但更新可能滞后我更建议直接看官方示例和源码遇到不懂的 API 去搜“three.js 类名 用法”比看静态文档更高效。注意 npm 安装版本要用 latest避免旧版本 API 和当前示例代码不一致。有些老教程用的是 Geometry新版已经改成 BufferGeometry照着抄会出现各种报错。7. 还能怎么扩展这个校园 3D 地图做完之后我最大的体会是three.js 做小范围 3D 地图的能力被很多人低估了。它没有内置“地图”的概念但正因如此它的表达完全由你掌控。你可以在上面叠加热力图、动态轨迹、时钟动画、夜景灯光秀、天气系统甚至把 BIM 模型导进去做楼宇内部漫游。后续我打算在这个项目里加入行人导航动画让小红点在校园道路网里自动寻路想一想就觉得可以做很多有趣的玩法。如果你正在规划类似项目我的建议是先从最小可行版本开始一小块地形、两栋建筑、一条路跑通全流程再逐步增加密度和效果。别一上来就想做超大场景先解决“有没有”再解决“好不好”。做 3D 地图最磨人的不是 three.js 本身而是数据清理和坐标系转换这几步耐心做扎实后面就能顺畅很多。本文还有配套的精品资源点击获取