简介这是一份基于three.js实现的轻量级3D地图可视化项目源码面向前端开发者、GIS初学者及Web 3D兴趣实践者解决传统二维地图缺乏空间沉浸感与交互深度的问题。资源包共45个文件包含15个核心JavaScript脚本如OBJLoader.js、OrbitControls.js、disaster.js等用于模型加载、视角控制与事件交互、22张PNG图标与UI素材、4张JPG背景图、1个OBJ三维模型及其配套MTL材质文件、1个Blender源文件.blend和1个主入口HTML页面整体压缩后仅2.26MB兼顾功能完整性与部署便捷性。已有3950人学习下载反映出其在Web 3D入门实践中的高关注度。购买者可获得完整可运行工程涵盖高德地图风格底图渲染、车辆/飞机等动态模型加载、点击事件响应、灾害点位标注及全景漫游逻辑并支持作者一对一答疑协助部署与问题排查切实降低3D地理可视化落地门槛。 前阵子接到一个校园3D导视的小项目需求一句话就能说清把学校里的楼、路、水系按真实位置摆进一个可旋转缩放的3D场景里点任意一栋楼就能浮出楼名和介绍。动手之前我以为是建模的事真正做了几天才意识到用Three.js做3D地图真正麻烦的不是“画得好看”而是怎么把一堆经纬度坐标、多边形边界、河岸线变成Three.js能理解的顶点和几何体。这篇文章没有任何花哨的行业黑话就是把我从数据到场景完整跑通的过程拆给你看包括坐标投影、GeoJSON解析、挤出面、水位动画和交互拾取。适合刚接触Three.js或正准备做3D地图项目的人照着抄作业基本不会翻车。1. 坐标转换是第一道坎经纬度怎么变成Three.js里的点1.1 为什么投影和中心点设置这么重要很多新手做3D地图第一步就栽在坐标上。地理数据里的每个点都是经纬度比如[117.20, 39.10]而Three.js的场景是笛卡尔坐标系原点在(0,0,0)X轴向右、Y轴向上、Z轴朝外。你不做转换是没法直接把经纬度塞进Vector3的。这里要分清两个概念球面坐标和平面坐标。经纬度本质是球面角度Three.js的坐标是平面距离。要把球面“摊平”到平面上就得做投影。做全球级3D地球时一般用球坐标或墨卡托投影但如果你只做校园、园区、小城市这种局部区域完全没必要上复杂的投影公式用等距近似就够了。原因很简单几十公里范围内地球曲率造成的形变基本可以忽略误差在几米量级做可视化完全看不出差异。还有一个细节容易被忽略中心点设置。假设你把一个城市的坐标直接转换不做平移得到的数值会非常大比如x1172xxxxz391xxxx。Three.js处理这么大的数值时浮点精度会出问题场景会出现不明原因的抖动、深度冲突。正确做法是选取项目中心点作为原点所有经纬度都相对这个中心点偏移这样场景坐标就能控制在几百米范围内计算稳定相机控制也更顺手。1.2 一个可抄的经纬度转平面坐标函数下面是我在这个项目里实际用到的转换函数。它没有用正经的Web墨卡托公式而是做了局部等距近似代码短、容易理解精度对局部地图完全够用。// 局部等距投影把经纬度转换为场景平面坐标 // 以项目中心点为原点避免浮点精度问题 const CENTER_LON 117.20; // 项目中心经度 const CENTER_LAT 39.10; // 项目中心纬度 const R 6371000; // 地球平均半径单位米 // 经度方向每度对应的米数需要按中心纬度修正 const M_PER_LON (Math.PI / 180) * R * Math.cos((CENTER_LAT * Math.PI) / 180); const M_PER_LAT (Math.PI / 180) * R; function geoToLocal(lon, lat) { const x (lon - CENTER_LON) * M_PER_LON; const z -(lat - CENTER_LAT) * M_PER_LAT; // 北向取负让北方在Z轴负方向 return { x, z }; }解释一下两个关键点。第一为什么经度方向要乘以Math.cos(CENTER_LAT)因为纬度越高相同经度差对应的实际地面距离越短。比如哈尔滨和三亚同样跨1度经度实际距离差很多。这个余弦修正是等距近似里最核心的一步少了它整个地图在东西方向会明显拉伸。第二为什么Z轴取负Three.js里如果相机在Z轴正方向朝原点看那么Z轴负方向就是屏幕里的“上方”。把北向映射到Z轴负方向地图摆出来后上北下南的直觉就对了。1.3 把坐标转换写错时的典型现象这类问题非常坑因为代码不报错但画面怪。我见过最典型的两个现象地图整体旋转了90度或左右镜像这是X和Z分配错了。东西方向被拉长几倍这是漏了纬度余弦修正或者图省事直接x (lon - centerLon) * 10000这种粗暴写法。如果你跑出来的地图也这样先别急着调材质和灯光回头检查坐标转换函数八成是这里的问题。这个环节值得花十分钟写几个已知坐标点在控制台打印转换结果确认和预期一致再继续往下做。2. 地理数据从哪来GeoJSON解析与河岸线处理2.1 常见数据源怎么选做3D地图坐标转换只是第一步第二步是拿到能用的地理边界数据。这块的选型会直接影响后续所有工作我用过几种来源列出来给你参考。数据来源覆盖范围格式优点缺点OpenStreetMap导出全球GeoJSON / PBF / Shapefile免费、开放、更新还算及时需要二次处理数据分类较杂地图下载器水经注、Bigemap等国内主要城市矢量、栅格可直接导出常见GIS格式商业软件高级功能要付费甲方提供CAD / GIS数据具体项目范围DWG / DXF / GeoJSON / SHP最精确不用自己画可能缺属性字段需要沟通手绘 / 手动标记小范围GeoJSON完全可控坐标要自己踩工作量大对我来说做校园、园区级别的项目最稳妥的路线是先看甲方有没有现成的平面图或CAD图没有就找OpenStreetMap或者地图下载器拿基础路网和水系最后用GeoJSON编辑器手动修正缺失的地块。记住一个原则数据清洗的时间一定比渲染的时间长别在数据源上省事。2.2 GeoJSON几何类型到Three.js几何体的映射GeoJSON最常见的结构是FeatureCollection里面每个Feature有geometrygeometry 类型有Point、LineString、Polygon、MultiPolygon等。对应到Three.jsPoint→ 用Sprite或小球体做POI标记LineString/MultiLineString→ 用Line、LineSegments或TubeGeometry画路网、河岸线Polygon/MultiPolygon→ 用THREE.Shape描述地块再用ExtrudeGeometry挤出成三维体解析的核心是遍历坐标数组把经纬度逐个喂给geoToLocal()得到平面点再构造几何体。下面这段代码处理Polygon和MultiPolygon生成THREE.Shape数组并支持孔洞。import * as THREE from three; function buildShapeFromGeoJSON(feature) { const coords feature.geometry.coordinates; const shapes []; const convert (polys) { polys.forEach((poly) { const outer poly[0]; // 外环 const holes poly.slice(1); // 孔洞例如地块里的湖 const shape new THREE.Shape(); outer.forEach(([lon, lat], i) { const { x, z } geoToLocal(lon, lat); if (i 0) shape.moveTo(x, z); else shape.lineTo(x, z); }); shape.closePath(); // 孔洞用Path描述塞进shape.holes holes.forEach((hole) { const path new THREE.Path(); hole.forEach(([lon, lat], i) { const { x, z } geoToLocal(lon, lat); if (i 0) path.moveTo(x, z); else path.lineTo(x, z); }); shape.holes.push(path); }); shapes.push(shape); }); }; if (feature.geometry.type Polygon) { convert([coords]); } else if (feature.geometry.type MultiPolygon) { convert(coords); } return shapes; }这里有个特别容易坑的点GeoJSON里的坐标顺序是[经度, 纬度]不是[纬度, 经度]。如果你平时习惯写[lat, lon]解析出来地图会整个错位而且因为数值差异不大肉眼很难立刻发现。我建议在解析函数里直接按[lon, lat]解构然后加一行注释提醒自己。2.3 河岸线坐标点太多怎么办抽稀思路热搜里有“three.js 河岸”我猜很多人是卡在河岸线绘制上。水系的GeoJSON边界通常非常密一条河动辄几千上万个坐标点。如果你一股脑全转成顶点画线性能会明显下降而且视觉上有大量冗余折角。解决思路是抽稀业界最常用的是道格拉斯-普克算法Douglas-Peucker核心逻辑是保留首尾点找出离首尾连线最远的点如果距离超过阈值就保留并递归处理两侧否则舍去中间点。简单实现不复杂你可以在纯JavaScript里写一个几十行的版本也可以通过Turf.js的simplify直接搞定。// 用Turf.js做坐标抽稀的示例 const line turf.lineString(coords); const simplified turf.simplify(line, { tolerance: 0.0001, highQuality: true }); const simplifiedCoords simplified.geometry.coordinates;tolerance的单位和你传入坐标系一致。GeoJSON原始坐标是经纬度所以0.0001大约对应十几米你可以根据水岸细节需求调整。抽稀后检查一下拐角处是否还平滑如果某些弯曲被抹平了把tolerance调小一点。2.4 解析时最容易被坑的两个细节第一个是重复点问题。有些GIS导出的数据相邻点完全重合或者图形自相交。这种数据喂给THREE.Shape后三角剖分会失败或者生成碎片表现就是地块上出现撕裂的黑色三角形、某个面突然消失。写个循环把相邻重复点去掉能解决大部分问题。第二个是坐标系偏移。从不同数据源拿到的数据可能用的不全是WGS84坐标系比如国内有些数据是GCJ-02火星坐标。如果你的底图是天地图、高德而数据用的是WGS84两块拼在一起会偏移几十到几百米。简单判定方法和甲方确认坐标系或者拿一个已知地标对照验证。如果偏移是固定值可以在geoToLocal里给经纬度加上常量修正如果偏移不规律还是得回到数据源头解决。3. 用ExtrudeGeometry把地块和楼栋“撑”起来3.1 为什么选Shape加挤出而不是手动建模拿到地块边界后下一步是让地图立体。Three.js里最直接的方式就是ExtrudeGeometry先用THREE.Shape画平面多边形再指定一个depth沿Z轴拉伸形成棱柱体。这个方案的好处是你能直接把GeoJSON里的多边形边界变成三维体块不需要任何建模软件所有参数都可以用代码控制。也有其他方案比如用BufferGeometry手动构建顶点或者先建平面再逐个抬高。前者写起来复杂后者处理复杂地块时容易漏面。ExtrudeGeometry把三角剖分和侧面生成都封装好了对绝大多数地图场景是效率最高的选择。3.2 顶点顺序、孔洞和三角剖分THREE.Shape的顶点顺序是有讲究的。Three.js内部做三角剖分时依赖顶点的绕行方向来判断多边形的内外。经过我的实测外环用逆时针更稳定孔洞用顺时针。如果你的数据来源比较乱可以先判断一下环的方向必要时用Array.reverse()反转。孔洞这块很多人在这一步卡住。比如一个校园地块里有个湖湖就是地块的孔洞。在GeoJSON的Polygon结构中外环是第一个数组孔洞是从第二个开始的后续数组。对应的THREE.Shape里孔洞要放进shape.holes。我上面给的buildShapeFromGeoJSON已经处理了这个逻辑你只需要确保数据结构正确即可。自相交多边形是三角剖分失败的重灾区。Three.js遇到自相交图形时不会给你明确的报错而是生成一个“看起来对但面片乱飞”的模型。排查方法把图形用LineSegments单独画出来加粗线条、半透明显示检查边是不是交叉了。3.3 动态楼高和批量生成要做“看起来像城市”的效果就得让每栋楼有不同高度。GeoJSON的properties里通常会有层数或高度字段没有的话可以通过属性值映射。function buildBuilding(feature) { const shapes buildShapeFromGeoJSON(feature); // 优先取属性里的高度如果没有就按面积或随机生成 const height feature.properties.height || Math.max(8, Math.round(shapes[0].area() / 100) * 5); const meshes []; shapes.forEach((shape) { const geometry new THREE.ExtrudeGeometry(shape, { depth: height, bevelEnabled: false, // 建筑不要导角保持硬朗 }); // 默认沿Z轴拉伸需要旋转到Y轴向上 geometry.rotateX(-Math.PI / 2); // 计算中心点方便后面加标注和拾取 geometry.computeBoundingBox(); const meshes new THREE.Mesh(geometry, buildingMaterial); meshes.position.y height / 2; // 让建筑底部贴地中心抬高 mesh.userData.feature feature; // 把原始数据挂上去拾取时能用 meshes.push(mesh); }); return meshes; }这里有一个细节挤出方向默认是Z轴而地图平面在XZ平面Y轴向上所以必须执行geometry.rotateX(-Math.PI / 2)把拉伸方向转到Y轴。旋转之后几何体的包围盒会变我给position.y设置的是height / 2这样楼栋以底部为中心放置而不是中心在原点。不然整个建筑有一半埋进地面或者悬浮在半空。3.4 挤出后的法线、旋转和材质处理挤出几何体的法线方向在旋转后可能反了表现是楼栋只能看到里面外面是黑面或透明。快速验证方法打开场景里的side: THREE.FrontSide如果某个方向看楼栋是黑的就改成THREE.DoubleSide。但更推荐在材质里用side: THREE.FrontSide然后检查法线旋转后的法线通常会保持正确真有问题才用DoubleSide因为双面渲染会多一倍片元计算量。材质这块我给建筑用了MeshLambertMaterial或MeshStandardMaterial。如果只是普通可视化MeshLambertMaterial性能更好阴影表现也够用。需要更真实的反射和光照细节再用MeshStandardMaterial。同一批建筑尽量共用材质实例这样渲染时能合并DrawCall。4. 水面、道路和交互让地图看起来不只是“模型”4.1 水面透明贴图和UV滚动动画地图场景里水面基本是绕不开的。河岸线围成的区域用THREE.ShapeGeometry或者直接用挤出后的顶面就能得到水面平面。材质上我会做两件事透明 UV滚动。首先是贴图。找一张水面纹理设置成THREE.RepeatWrapping让它在河面区域重复平铺。然后是动画在requestAnimationFrame循环里持续更新texture.offset.x让贴图按时间轴滚动看起来就像河水在流动。const waterTexture new THREE.TextureLoader().load(water.png); waterTexture.wrapS waterTexture.wrapT THREE.RepeatWrapping; waterTexture.repeat.set(4, 1); const waterMaterial new THREE.MeshStandardMaterial({ map: waterTexture, transparent: true, opacity: 0.85, roughness: 0.1, metalness: 0.1, }); function updateWater(delta) { waterTexture.offset.x - delta * 0.05; // 滚动速度按需调 }细节在于水平面的高度设定。水面要稍微高出地面一点点避免和河岸底面重叠造成Z-fighting。我一般把水面网格放在y 0.2左右。此外transparent: true会带来排序问题多个透明物体之间可能出现遮挡错乱遇到时可以把水面单独放在一个渲染组里或微调renderOrder。4.2 道路Line还是Tube怎么选道路的渲染方式取决于你的场景需求没有绝对答案。我按不同场景给你一套选择标准只是看路网走向不需要宽度变化 → 用THREE.LineSegments性能最好。需要道路有真实宽度且视角经常拉近 → 用MeshLine或TubeGeometry能看出路面质感。需要沿路有立体围栏、标线等 → 用TubeGeometry因为它的几何体是真实表面能承接各种贴图和碰撞。TubeGeometry的用法是把道路中心线的Vector3点数组输入进去再指定半径。它自带CatmullRomCurve3平滑所以即使原始点比较稀疏也能生成平滑的曲面。缺点是顶点密度高长路段要控制分段数不然容易卡。4.3 鼠标拾取与高亮交互一个3D地图没有交互就只是好看的模型。最基本的交互是鼠标悬停和点击识别用户点到了哪栋楼、哪个地块然后弹窗显示信息。Three.js的Raycaster是干这个的标准方案。const raycaster new THREE.Raycaster(); const pointer new THREE.Vector2(); function onPointerMove(event) { pointer.x (event.clientX / window.innerWidth) * 2 - 1; pointer.y -(event.clientY / window.innerHeight) * 2 1; } function hoverPick() { raycaster.setFromCamera(pointer, camera); const hits raycaster.intersectObjects(buildingGroup.children); if (hits.length 0) { clearHighlight(); return; } const hit hits[0].object; highlight(hit); }这里有两个细节非常值得注意。第一raycaster.setFromCamera接收的pointer坐标是标准化设备坐标NDC范围是 -1 到 1所以要把鼠标的像素坐标做换算。第二intersectObjects默认只检测传入数组的第一层子对象。如果你的建筑网格被嵌套在Group里需要传入true参数做递归检测。高亮的实现方式有很多种。最简单的做法是临时把mesh.material换成一个emissive值更高的材质鼠标移开后换回来。如果建筑很多共享同一个材质实例直接替换会连累所有建筑这时要先用material.clone()复制一份或者用不同的材质实例管理分组。4.4 OrbitControls相机控制要注意的边界地图做完了用户还得能自由看。Three.js官方自带的OrbitControls是最常用的相机控制器但直接裸用会出很多体验问题。比如用户把相机转到地下或者缩放太近直接穿模。我会限制三个参数const controls new OrbitControls(camera, renderer.domElement); controls.enableDamping true; // 阻尼平滑不然旋转很生硬 controls.maxPolarAngle Math.PI / 2.2; // 限制俯仰角防止转到地平线以下 controls.minDistance 50; // 最近缩放距离 controls.maxDistance 5000; // 最远缩放距离enableDamping值得多说一句。它开启后控制器的旋转和缩放会带惯性手感立刻高级很多代价是在动画循环里得调用controls.update()。忘了调用的话你只会看到相机“卡”在原地不动这是新手最容易踩的坑。我自己见过不止一个项目阻尼开了但忘了在渲染循环里更新最后以为OrbitControls坏了其实是更新逻辑没补。5. 大数据量下的性能优化实践5.1 先看DrawCall再看顶点数3D地图的数据量比想象中容易膨胀。一个城市级别的地图建筑地块动辄上万如果每栋楼一个Mesh每次渲染就是上万个DrawCall哪怕每栋楼只有几百个顶点帧率也会被瞬间拖垮。所以性能优化的第一件事不是减少顶点是减少DrawCall。我习惯打开渲染器的统计数据看指标renderer.info.render.calls; // 当前帧DrawCall数 renderer.info.render.triangles; // 三角形数量如果calls上千基本就卡了。要优先合并几何体、实例化重复物体如果triangles很高但calls不大再考虑减面、简化模型。5.2 InstancedMesh处理成片楼栋项目里如果有大量形状相同、只是位置和缩放不同的楼栋InstancedMesh是性能最优解。它把同一份几何体在GPU里实例化多次每次只传递一个变换矩阵DrawCall从几千降到几十。const buildingGeo new THREE.BoxGeometry(10, 10, 10); const instancedMesh new THREE.InstancedMesh(buildingGeo, buildingMaterial, count); buildingData.forEach((data, i) { const matrix new THREE.Matrix4(); matrix.setPosition(x, y, z); matrix.scale(new THREE.Vector3(data.w, data.h, data.d)); instancedMesh.setMatrixAt(i, matrix); }); instancedMesh.instanceMatrix.needsUpdate true;用InstancedMesh之后原来的Raycaster拾取方式也要跟着变。官方推荐用raycaster.intersectObject(instancedMesh)配合instanceId来区分具体实例命中后从instanceMatrix取出矩阵或者从预存的数据数组里按instanceId拿属性。5.3 合并几何体、关闭阴影、纹理压缩如果你的建筑不是统一形状没法用InstancedMesh另一个思路是合并几何体。Three.js官方提供BufferGeometryUtils.mergeGeometries把多个几何体合并成一个整体只占一个DrawCall。缺点是合并后没法单独控制每个物体的位置和旋转所以只能在所有物体都使用同一个变换规则时用。通常做法是先在本地坐标把几何体摆好再统一合并。阴影是另一个性能杀手。地图场景不像游戏不需要给每栋楼都开实时阴影。实测下来一个几千Mesh的场景开阴影后帧率直接掉一半。我的建议是主视角看整体时阴影全关或者只用一个虚拟方向的平行光用假阴影贴图做视觉补偿只有拉近到具体楼栋时再局部开启阴影。纹理这块地图里的建筑、道路、水面贴图尽量用压缩过的WebP或JPEG尺寸不要超过1024×1024能用256就够。大尺寸贴图占显存非常快尤其是大量共享同一贴图的时候反而没必要追求高精度。5.4 Three.js中文文档与本地化部署很多人在查ExtrudeGeometry、InstancedMesh这类API时习惯直接百度结果经常翻到过时教程。Three.js官网自带中文文档路径是threejs.org/docs右上角可以切语言。它更新速度快API说明和示例都完整这是我最推荐的中文学习渠道。开发依赖推荐走npmnpm install three。如果是纯静态项目可以用CDN或者直接把three.module.js下载到本地通过import map引入。需要提醒的是Three.js从r150之后很多示例代码改到了three/addons/路径下直接从旧文章里复制import路径经常会404用three/examples/jsm/这个路径最稳。本地开发时建议把下载的three.min.js和addons目录放到自家项目里避免运行时依赖外网部署到内网才能稳定。6. 从“能看”到“能用”校园导视和地图SDK叠加案例6.1 校园3D导视图的完整链路这次项目就是典型的高校校园场景类似郑州大学那种三维地图展示。完整流程我梳理一遍你可以当checklist用拿到校园范围的高清图或CAD底图确定中心经纬度和旋转方向。从GIS数据或地图服务中导出建筑轮廓、路网、水系转成GeoJSON。写坐标转换函数把数据全部映射到Three.js平面坐标。解析建筑地块用ExtrudeGeometry按楼层生成楼栋道路、水面分别建组。给建筑按功能区做颜色编码教学区、宿舍区、食堂、行政楼一眼就能分清。加POI标注用CSS2DRenderer或Sprite显示楼名。接上Raycaster悬停拾取和点击弹窗数据绑定从网格的userData里取。最后调相机参数初始视角对准校门限制俯仰角避免穿地。6.2 与百度/高德3D实景地图叠加时的坐标系对齐如果需求是“在百度/高德3D实景地图上加载自己的3D模型”比如 vue2 项目里接入百度地图WebGL版本再往上面放模型这时你的模型和地图SDK之间需要坐标系对齐。地图SDK一般提供经纬度转墨卡托或转局部坐标的方法你要做的就是把模型里的每个点也用相同的方法转一次再塞进SDK的3D场景。比较稳妥的做法是把three.js的渲染器挂到地图SDK的WebGLOverlayView或者自定义覆盖物里拿到SDK提供的相机矩阵用它同步更新three.js的相机。这样地图的旋转、缩放、平移会实时驱动你的模型不需要手动做两套相机逻辑同步。实际踩下来的坑是这类SDK的坐标基准通常也是WGS84或GCJ-02两种情况模型位置会偏移。处理方式和前面说的一致先确认坐标系再加偏移修正。6.3 不必自己搭3D地图的时候最后说点掏心窝的话。并不是所有需求都值得从头用Three.js搭一整套3D地图。如果你的场景只是“地图上放几个3D模型”那直接用地图SDK的3D模型覆盖物、或者简单覆盖层最后用CSS3动画做个假3D视角性价比反而更高。Three.js全链路方案适合什么情况你需要的不是现成地图而是完全自定义的地块边界、建筑细节、实时数据联动。比如校园导视系统要把每栋楼的楼名、部门、楼层实时的信息绑定到三维建筑上比如园区能耗可视化要根据传感器数据动态改变楼栋颜色再比如河道水位模拟要动态改变水面高度和流速。这些需求地图SDK的通用模型覆盖物很难做到细节级控制这时候自己搭建才是值得的。我个人的体会是用Three.js做3D地图最核心的竞争力不是渲染效果而是你把“地理数据”和“三维场景”打通的那套能力。坐标转换、数据清洗、交互拾取这些基础功扎实了后面不管接什么项目都能快速落地。如果你正在做类似的东西先把坐标系和数据解析搞定再谈效果这条路不会走偏。本文还有配套的精品资源点击获取