简介基于Mapbox GL JS技术构建的中国地质大学武汉未来城校区三维可视化校园地图系统面向地理信息专业学生、Web前端开发者与校园信息化建设者定位为集三维建模、地理信息系统、室内外一体化导航、空间分析与教学资源管理于一体的综合应用项目。资源包共140个文件压缩后大小仅1.38MB其中包含25个JavaScript脚本用于地图渲染与交互逻辑7个GeoJSON文件承载楼层与建筑轮廓等空间数据CSS样式与HTML页面负责界面呈现75个GIF动图直观演示系统各功能模块的实际效果另有字体图标、图片素材及附赠资源文档辅助理解部署过程。整体目录层次清晰便于按功能模块检索学习适合作为课程设计、毕业设计或校园信息化项目的参考实现。目前已有80人学习浏览可直接获取源码与演示素材支撑快速复现和二次开发。1. 用 Mapbox GL JS 做三维校园地图先解决数据再解决渲染给校园做三维可视化地图多数团队会先扑向三维建模软件结果建出好看的楼却导不进网页最后卡在数据格式上。这个标题拆开看它要的其实是一套完整的地理信息系统基于 Mapbox GL JS 渲染三维场景叠加校园导航、空间分析、室内外一体化和教学资源管理。“中国地质大学武汉未来城校区地理与信息工程学院”是场景对象“三维模型”是数据资产“GIS”才是骨架。适合三类人看GIS 专业的课程设计团队、学院信息化的实施人员以及想从二维 WebGIS 转三维可视化的前端。这个方向最值钱的能力不是建模而是把 CAD、倾斜摄影、楼层平面图统一成浏览器能吃下的地理数据。2. 校园三维地图的技术骨架从地理信息数据到前端渲染链路2.1 坐标系与数据格式为什么先整理成 WGS84 的 GeoJSON做校园三维地图第一步不是打开 Mapbox GL JS 文档而是把所有数据统一到同一套坐标系里。国内测绘成果常见的是 CGCS2000 或地方坐标系而 Mapbox GL JS 默认接受 WGS84 经纬度内部渲染又基于 Web Mercator 投影。坐标不一致最典型的翻车是建筑挤出来了位置横跨两条街或者干脆跑到海里。常见做法是先用 GDAL 里的 ogr2ogr 把矢量数据统一转成 WGS84 的 GeoJSON。这条命令我在不同项目里改过无数次参数最常用的是ogr2ogr -f GeoJSON building_4326.geojson building_4528.shp \ -t_srs EPSG:4326 \ -lco COORDINATE_PRECISION6-t_srs EPSG:4326是把源数据的 4528 坐标系CGCS2000 高斯投影转成 WGS84 经纬度COORDINATE_PRECISION6是限制小数点后 6 位约 0.1 米精度对校园建筑足够还能把 GeoJSON 体积压小不少。转换之后用文本编辑器打开看一眼坐标范围应该落在 114.x、30.x 附近基本就对了。数据入库这一步我一般会放到 PostGIS 里做因为后面空间分析、属性筛选、按楼层查教室都要用 SQL 处理。给一个最常用的查询把建筑表直接吐成带楼层字段的 GeoJSONSELECT name, floor_count, ST_AsGeoJSON(ST_Transform(geom, 4326)) AS geojson FROM campus_buildings WHERE campus 未来城 AND function 教学;这里ST_Transform(geom, 4326)是在数据库层完成坐标转换ST_AsGeoJSON把几何对象序列化成 GeoJSON 文本。注意floor_count必须转成数字类型不要在 GeoJSON 里留成字符串不然后面 fill-extrusion 层取高度时会出现 NaN建筑直接消失。2.2 三维建筑模型的两种路线fill-extrusion 程序挤出与 glTF 精模校园三维模型不是只能靠建模软件。Mapbox GL JS 里有两条完全不同的路决定成本和效果的是建筑重要程度。第一类是程序化挤出用 fill-extrusion 图层配合楼层数字段把二维轮廓“拉”成三维体块。这条路适合教学楼、宿舍、食堂这种体量规则、批量生成的建筑。好处是数据量极小一个校园所有楼可能只需要几百 KB GeoJSON坏处是只有外观体块没有细节贴图。但也正因为是程序生成改楼高、换颜色、按属性调整透明度都在前端表达式里完成不需要重新建模。第二类是精模用 Blender、SketchUp 或 3ds Max 手工建模后导出 glTF/GLB再用模型图层加载。这条路线用于校门、图书馆地标、院楼门厅这类需要展示设计细节的位置。代价是一个模型动辄几十 MB而且要和真实坐标对位模型原点的经纬度、旋转角、缩放比例都要在运行时调。对比项fill-extrusion 程序挤出glTF/GLB 精模数据来源GIS 轮廓 楼层属性建模软件手工制作文件大小轻量按 KB 计重按 MB 计修改成本改属性即改外观需要回建模工具改适用对象批量规则建筑标志性建筑与室内细节渲染性能高低需要做 LOD这个标题下的校园系统我建议用混搭策略全部建筑先做 fill-extrusion 挤出保证三维场景整体可看再单独挑地理与信息工程学院楼和校门做精模突出重点。这比一上来就全场景精模更可控也符合三维可视化项目“先有框架再补细节”的推进节奏。2.3 数据链路从 PostGIS 到 Mapbox Style 的发布方式数据有了还需要一条链路把 PostGIS 里的数据送进浏览器。有两种常见做法。第一种是前端直连 GeoJSON 文件。把 2.1 节导出的 GeoJSON 放到静态服务器上前端fetch之后直接addSource。简单直接适合小范围校园系统但每次数据更新都要重新导出文件。第二种是走矢量瓦片服务。PostGIS 里通过 GeoServer 或自建 TileServer 发布成矢量瓦片前端加载 TileJSON 地址。这样属性更新后前端无需重新发布版本数据量大时渲染性能也好。校内项目我一般先用第一种跑通功能等需要接入实时课表、门禁数据时再上第二种。前端加载数据的典型写法是const response await fetch(/data/campus_buildings.geojson); const geojson await response.json(); map.addSource(buildings, { type: geojson, data: geojson });这里addSource的type必须是geojsondata是解析后的对象而不是字符串。经常有人把 response 直接塞进 data导致 source 一直在 loading 状态。这是三维校园项目里最常见的黑匣子问题之一后面避坑章会细说。3. 在 Mapbox GL JS 里搭建三维校园核心代码与参数调整3.1 最小可用的三维地图相机视角与底图初始化三维校园和二维地图的区别开局就在相机参数上。中心点取学院楼坐标zoom控制在 16 左右能看到楼体全貌pitch必须大于 0 才有透视效果否则永远俯视平面图。基础初始化如下const map new mapboxgl.Map({ container: map, style: mapbox://styles/mapbox/light-v11, center: [114.3985, 30.4651], // 未来城校区地信学院楼 zoom: 16, pitch: 60, bearing: -20, antialias: true });pitch: 60是接近人视角的倾角能看到楼侧面bearing: -20给一个斜向的构图比正南正北视角更有立体感。antialias: true会开启抗锯齿楼体边缘在屏幕上不会出现明显锯齿代价是 GPU 占用略升校园这种小场景值得开。初始化之后我建议加一段缓动动画让用户从平滑的过渡中进入三维状态而不是瞬间切换map.easeTo({ pitch: 75, bearing: 0, duration: 2000 });easeTo会在 2 秒内把相机从初始位置过渡到俯仰 75 度、正北朝向。这个视角适合展示建筑群的层次关系也是后续导航视角的基准。3.2 建筑挤出fill-extrusion 的 height、base、color 与楼层字段核心的三维建筑体块靠 fill-extrusion 图层实现。它用每个面要素的轮廓拉伸成柱体高度完全由属性决定。我这里直接写教学楼的挤出配置map.addLayer({ id: building-3d, type: fill-extrusion, source: buildings, filter: [, category, teaching], paint: { fill-extrusion-color: [ case, [, [get, floor_count], 6], #d2b48c, #c8c8c8 ], fill-extrusion-height: [*, [get, floor_count], 3.0], fill-extrusion-base: 0, fill-extrusion-opacity: 0.85 } });fill-extrusion-height是楼顶高度[*, [get, floor_count], 3.0]表示楼层数乘 3 米得到最终海拔高度。fill-extrusion-base是楼底高度整栋建筑从地面起就填 0。fill-extrusion-color用case表达式做了个简单分段6 层楼用浅褐色其余用灰色。这样一眼能从颜色分出教学楼和宿舍。这里有个容易踩的参数坑Mapbox GL JS 里的 fill-extrusion 高度单位是米但他在内部会把经纬度坐标转成 Web Mercator 平面后再算高度所以 3.0 就是 3 米。不要在表达式里额外乘 111000 之类的换算系数否则楼会戳到云层里。opacity不建议写 1透明度过高会导致后面的建筑被完全遮住0.85 左右保留一点透视层次感。3.3 室内外一体化用图层过滤控制楼层显隐校园导航最难的不是室外道路而是从室外进入教学楼后用户还想找到 301 教室。这就要把楼层的平面图也纳入三维场景做一个最简的室内外一体化。我的做法是室内楼层数据按floor字段分层放在同一个 GeoJSON source 里每层的门、走廊、教室边界都带楼层号。切换楼层时通过setFilter控制图层显示对应楼层同时把相机推进到目标楼层高度function showFloor(floorNo) { const floorHeight floorNo * 3.0; map.setFilter(indoor-rooms, [all, [, floor, floorNo]]); map.setFilter(indoor-lines, [all, [, floor, floorNo]]); map.easeTo({ center: [114.3985, 30.4651], bearing: 0, pitch: 70, zoom: 18.5, height: floorHeight, duration: 800 }); }这里floor字段是数据里的属性名[, floor, floorNo]是数据驱动样式的过滤写法。注意filter是图层级别的过滤不是 CSS 那样只影响视觉样式它会把非目标楼层的要素全部剔除掉所以切换效率很高。室内外一体化的关键是楼层切换和室外三维楼体联动。我会在楼层模式下把对应的室外楼体透明度降到 0.2让用户感知到“我现在进入了这栋楼的内部”。这可以用已有图层的 paint 属性覆盖实现map.setPaintProperty(building-3d, fill-extrusion-opacity, 0.2);当showFloor返回 -1 时再把它恢复成 0.85。这套方案不需要加载室内三维模型成本低但已经能满足“从室外定位到教学楼再进入楼层找教室”的完整链路。3.4 校园导航前端实现 Dijkstra 最短路径与路径绘制校园导航部分标题里明确要求但没必要依赖重型路由服务。校园路网规模小节点几十个我一般在前端直接实现 Dijkstra 算法。先把道路交叉口做成路网图存成邻接表const graph { gate: { road1: 120, road2: 200 }, road1: { gate: 120, buildingA: 80 }, road2: { gate: 200, buildingB: 150, road1: 90 } }; // key 是路口或建筑入口value 是相邻节点与步行距离单位米然后实现一个不依赖外部库的最短路径函数function dijkstra(graph, start, end) { const dist {}, prev {}, visited new Set(); const nodes Object.keys(graph); nodes.forEach(n dist[n] Infinity); dist[start] 0; while (visited.size nodes.length) { let current null; nodes.forEach(n { if (!visited.has(n) (current null || dist[n] dist[current])) { current n; } }); if (current null) break; visited.add(current); graph[current] Object.keys(graph[current]).forEach(neighbor { const alt dist[current] graph[current][neighbor]; if (alt dist[neighbor]) { dist[neighbor] alt; prev[neighbor] current; } }); } const path [end]; let cursor end; while (prev[cursor]) { cursor prev[cursor]; path.unshift(cursor); } return path; }这个实现里dist记录每个节点的最短距离prev记录前驱节点visited防止重复访问。每次循环挑出距离最小的未访问节点作为当前节点松弛它的邻居。返回的path是从起点到终点的节点列表。拿到路径后把节点坐标拼接成 LineString 画到地图上const routeCoords path.map(id nodeCoords[id]); map.addSource(route, { type: geojson, data: { type: Feature, properties: {}, geometry: { type: LineString, coordinates: routeCoords } } }); map.addLayer({ id: route-line, type: line, source: route, paint: { line-color: #007cbf, line-width: 6, line-opacity: 0.9 } });nodeCoords是节点 ID 到经纬度的映射表需要和路网数据一起维护。线条宽度 6 像素在三维视角下已经比较醒目如果想让路径贴地走可以把 LineString 的每个坐标加一个极小的高度偏移防止被 fill-extrusion 遮挡。4. 空间分析与教学资源管理把地图变成业务系统4.1 点击建筑查属性queryRenderedFeatures 与 Popup三维校园地图做出来不是用来看的是要拿来查的。点击教学楼弹出“学院名称、楼层数、建筑面积、启用时间”这些信息是 GIS 系统最基本的交互。Mapbox GL JS 的queryRenderedFeatures能直接拾取屏幕坐标下的要素map.on(click, (e) { const features map.queryRenderedFeatures(e.point, { layers: [building-3d, gltf-building] }); if (!features.length) return; const props features[0].properties; new mapboxgl.Popup({ closeButton: false }) .setLngLat(e.lngLat) .setHTML( h4${props.name || 未知建筑}/h4 ul li楼层数${props.floor_count || -}/li li面积${props.area_m2 || -} m²/li li用途${props.function || -}/li /ul ) .addTo(map); });queryRenderedFeatures只查当前相机视野内已经渲染出来的要素所以点击拾取响应的速度非常快。限制layers参数只查建筑层能避免点到路网、室内线等无关要素。这里如果点了精模模型图层properties来自 glTF 的定制属性字段名要和建模时约定好否则弹窗全是 undefined。4.2 空间分析模块量测、缓冲区与通视把这个标题里的“空间分析”落成具体功能我一般会从三个技能入手距离量测、缓冲区分析和通视分析。距离量测用 Haversine 公式算地球上两点的大圆距离校园尺度下误差可忽略function haversineMeters(lngLat1, lngLat2) { const R 6371000; const rad Math.PI / 180; const dLat (lngLat2[1] - lngLat1[1]) * rad; const dLng (lngLat2[0] - lngLat1[0]) * rad; const a Math.sin(dLat / 2) ** 2 Math.cos(lngLat1[1] * rad) * Math.cos(lngLat2[1] * rad) * Math.sin(dLng / 2) ** 2; return 2 * R * Math.asin(Math.sqrt(a)); }参数说明R是地球平均半径 6371 公里rad是角度转弧度系数两点经纬度都用[lng, lat]顺序传入。校园尺度下这个公式比平面投影换算更稳妥因为不受高斯投影分带影响。缓冲区分析用于回答“学院楼 500 米范围内有哪些食堂、宿舍、实验室”。最简单的方式是让用户点击一个点前端画一个半径固定的圆。由于经纬度下半径要用度表示1 度纬度约 111 公里所以 300 米半径大约是 0.0027 度。直接在 GeoJSON 里构造圆function createBufferCircle(center, radiusMeters) { const latOffset radiusMeters / 111000; const points []; for (let i 0; i 36; i) { const angle (i / 36) * Math.PI * 2; const dlng Math.cos(angle) * latOffset / Math.cos(center[1] * Math.PI / 180); const dlat Math.sin(angle) * latOffset; points.push([center[0] dlng, center[1] dlat]); } return { type: Feature, properties: {}, geometry: { type: Polygon, coordinates: [points] } }; }这个圆的半径换算做了经度方向修正Math.cos(center[1])是因为纬度越高同样经度差对应的实际距离越短。36 个点组成圆已经够平滑。之后用map.querySourceFeatures查落在圆内的建筑再做列表展示。通视分析是三维场景里很有“GIS 味”的功能。原理简单说从观察点向目标点发一条射线中间是否有建筑遮挡。简化实现是采样射线上的点比较点位的建筑高度与视线高度function isLineOfSightClear(from, to, buildings) { const steps 50; for (let i 1; i steps; i) { const t i / steps; const lng from[0] (to[0] - from[0]) * t; const lat from[1] (to[1] - from[1]) * t; const sightHeight 1.6 (to[2] - 1.6) * t; // 视线随距离升高 const blocked buildings.some(b { const inside pointInPolygon([lng, lat], b.geometry.coordinates[0]); return inside b.height sightHeight; }); if (blocked) return false; } return true; }steps50是采样精度数字越大越精确但越消耗 CPU。pointInPolygon是经典的射线法判断点是否在多边形内建筑数据里必须有height字段。这个分析能给校园监控点位设计、景观视线规划提供依据也是空间分析能力中比较能体现三维价值的部分。4.3 教学资源管理把楼宇属性扩展成资源台账这个项目标题里还带“教学资源管理”说明地图不只是空间可视化还要当业务系统。我会在建筑的 GeoJSON properties 里扩展维护字段把教室、实验室、课表、设备信息挂到空间对象上{ type: Feature, properties: { id: GIS-6F-301, name: 遥感实验室, floor_count: 6, teaching_resources: { equipment: 高光谱成像仪, manager: 张老师, open_time: 08:30-17:30 } }, geometry: { ... } }然后在地图侧边栏做资源检索。点击建筑时popup 展示基本信息点击“教学资源”页签右侧展开该建筑关联的实验室设备清单、排课时间和管理员信息。配合feature-state还能按房间的占用状态给楼层平面图上色map.setFeatureState( { source: buildings, id: roomId }, { occupied: 1 } ); map.setPaintProperty(indoor-rooms, fill-color, [ case, [, [feature-state, occupied], 1], #e55e5e, #c8e6c9 ]);setFeatureState传入的是要素的id和自定义状态feature-state表达式在 paint 里直接读取。这套机制的优点是状态更新不需要修改源数据适合做实时课表、门禁占用等动态场景。但要注意addSource时 GeoJSON 里的 Feature 必须带id字段否则setFeatureState会报错找不到目标要素。5. 校园三维地图避坑指南6 个常见翻车点与排查路径5.1 建筑浮空或陷地单位与高度基准混乱现象挤出后的楼悬浮在半空中或者陷入地面一截怎么调fill-extrusion-base都不对。原因GeoJSON 里的高度字段单位不统一。有人直接用楼层数有人用米还有人从 CAD 导出的是英尺。更隐蔽的是base值本身带了海拔而校园地形并非绝对水平。解决先明确“在这个系统里高度字段一律用米base 一律写 0”。如果某栋楼建在坡地上就把base设成该楼脚的海拔采样值。我一般用一个统一函数在校验阶段扫一遍所有建筑的 height 和 base凡大于 200 米的基本就是单位错误。5.2 加了 GeoJSON 源却看不到任何要素现象network 面板里数据加载成功控制台没有报错地图上就是空白的。原因source 的 id 和 addLayer 里引用不一致是常见的另一种原因是 GeoJSON 的 geometry 类型不对比如本应是 Polygon 却导出了 MultiLineString。还有一种是数据都渲染了但相机 pitch 为 0建筑只显示成俯视色块看不出立体。解决先console.log(map.getSource(buildings)._data)看数据是否进入 source再检查 addLayer 的 source 字段是否一致。然后临时把 pitch 拉到 60排除视角问题。最后确认 geometry 类型在导出和入库阶段就统一规范。5.3 fill-extrusion 半透明场景下遮挡排序混乱现象把fill-extrusion-opacity设为 0.5 后前面的楼反而变透明能看见后面的楼视觉上穿帮得很厉害。原因Mapbox GL JS 的 fill-extrusion 在透明度渲染时有深度排序限制半透明物体之间的遮挡关系本来就不保证严格正确。这是渲染引擎的已知边界不是代码 bug。解决不要把三维体块做成大面积半透明。需要看内部结构时切换到室内楼层模式把外部楼体透明度降到 0.2 只是过渡状态不要一直停留。对需要透视的核心建筑改用单独的 model 图层并关闭深度写入。5.4 精模加载后帧率骤降旋转地图卡成幻灯片现象加入 glTF 建筑模型后fps 从 60 掉到 20 以下尤其是旋转视角的时候。原因建模软件导出的 glb 面数太多一个楼可能几百万三角面。浏览器 GPU 不可能在低端集显上流畅跑这种数据量。没有做 LOD 也没有做模型减面。解决精模控制在 10 万三角面以内用 Blender 的减面修改器处理。多个同类型建筑用同一个模型实例复用不要为每栋楼单独导出。倾斜摄影模型如果是第三方生产的先做瓦片化裁剪只加载校园核心区域远处用 fill-extrusion 代替。5.5 室内外模型对不齐门在室外图上偏了两米现象室内平面图上墙线、门窗和室外三维建筑体块的轮廓有明显偏移。原因室内图纸一般是 CAD 平面坐标系室外的轮廓来自摄影测量或地理坐标两者本身就有系统误差。直接拼在一起放大到 18 级肯定错位。解决在室内数据入库时选一个基准点做平移校准。常见做法是取建筑外墙角的室内坐标和室外坐标算差值校正整个楼层图层。这个偏移量不是固定值每栋楼都要单独算不要一劳永逸用一个全局偏移。5.6 导航路径穿楼而过看起来极不专业现象Dijkstra 计算的路径从教学楼中间直穿过去而不是沿着道路走。原因路网数据只做了交叉口连接没有把建筑外边界设成障碍。路径在图上表现为直线连接两个节点中间忽略了建筑轮廓。解决路网构建时确保每条路段的几何都沿着真实道路中线采集不要只录起终点。如果路径是纯前端算出来的折线还要做一步平滑处理沿线段按固定间距插值再对落在建筑多边形内部的点做偏移修正。这属于路径后处理常见做法是给每个建筑做一个 0.5 米的缓冲区把穿过的线段打断重算。6. 进阶验证自动巡检与上线前的三维场景核对三维校园地图交付前我习惯写一段自动巡检代码让相机沿着校园主路走一遍同时在控制台记录每一步的帧率。这比手动拖拽地图高效得多也最容易发现模型穿插、遮挡错乱和加载卡顿。function flyAlong(routeCoords, duration) { const startTime performance.now(); const totalDist routeCoords.length; function step(now) { const t Math.min((now - startTime) / duration, 1); const index Math.floor(t * (totalDist - 1)); const coord routeCoords[index]; map.jumpTo({ center: [coord[0], coord[1]], bearing: 30, pitch: 60 }); if (t 1) requestAnimationFrame(step); } requestAnimationFrame(step); }duration控制全程时长我一般设 30 到 60 秒jumpTo比flyTo更适合巡检因为它不做插值平滑能逐帧还原真实渲染状态。巡检时重点盯着三处楼体是否穿地、楼层切换是否干净、路径导航线是否始终贴地。巡检脚本跑完后我会再执行一遍手动清单点击每一栋建筑看 popup 属性是否有空值切换每一层室内图看墙线是否错位跑一次从校门到学院楼的导航看路径是否绕路。这套流程做完剩下的就是交给使用方在真实网络环境里压测了。我做这个方向最后悔的一件事是早期没有在数据入库阶段就统一好建筑 ID 和楼层字段规范导致后期给教室挂资源时反复返工。现在我会在项目第一天就定下一份数据字典包括楼层数、面积、用途、楼栋 ID 的命名规则后面所有代码都按这份字典写。这个习惯帮我在后续项目里省掉了大半的数据排查时间希望帮到你。本文还有配套的精品资源点击获取