基于three.js的校园3D地图开发实践：从坐标转换到性能优化

简介：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 里点击判断用 Raycaster：

const 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 的 render：

labelRenderer.render(scene, camera);

5.3 点击建筑高亮与信息面板

点击高亮我用的是两种方案结合：一是给建筑材质设置 emissive 提亮，二是给选中建筑加一层外发光边框。最简单的是改 emissive：

building.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 calls

three.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 和共享材质，定位过程极其迷惑，经验不分享出来真心难受。

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 本身，而是数据清理和坐标系转换，这几步耐心做扎实，后面就能顺畅很多。

本文还有配套的精品资源，点击获取