简介：本资源是一个基于Three.js与Vue.js实现的交互式中国3D地理可视化项目，面向前端开发者、GIS初学者及Web 3D技术实践者，解决传统二维地图缺乏空间感知与动态交互的问题，适用于数字孪生、政务可视化、教学演示等场景。压缩包共2000个文件，主体为2002个JavaScript文件（含three.module.js、web-ifc-api.js等核心3D库）、165个JSON格式地理数据与配置文件、50个Markdown文档说明及少量CSS/HTML资源，整体体积11.35MB，结构模块清晰，涵盖场景初始化、省份网格建模、相机控制、光照纹理配置与Vue响应式状态管理逻辑。已有3829人学习下载，提供开箱即用的Three-chinaMap-Demo.html入口，完整包含地形渲染、鼠标拖拽缩放、区域点击高亮、LOD性能优化等可运行功能，是深入理解WebGL封装、Vue 3D状态联动与大规模地理数据可视化的优质实践样本。 去年接了一个展厅数据可视化需求，要在现场大屏上放一张中国3D地图，能看省份海拔差异、重点城市分布、还有点击省份弹出业务数据。当时第一反应就是用 Three.js，因为要的是真三维，不是那种用 CSS 搞出来的伪 3D。整个项目最终用 Vue + Three.js 完成，前后大概两周时间，踩了不少坑，也总结出一套可以直接复用的流程。这篇文章就把整个项目从技术选型到核心实现、再到坑位排查完整拆一遍，希望对正在做 Web 3D 可视化大屏的朋友有帮助。
先说结论：Vue 负责页面骨架、交互状态和业务数据，Three.js 负责地图渲染和三维场景；两者通过组件生命周期绑定，用 ref 挂载 DOM，用 reactive 驱动场景状态。这套分工在实操里非常顺，也是后文展开的主线。
1. 为什么是 Three.js + Vue，而不是其他方案
1.1 Three.js 到底解决了什么问题
很多人会问，地图可视化用 ECharts 或者 Mapbox 不就行了，为什么还要上 Three.js？我的回答是：视业务目标而定。ECharts 的 map3D 确实能做出带挤出效果的 3D 地图，但它的扩展边界很明显——你想在某个城市上方放一个动态波纹标记、想从北京画一条飞到乌鲁木齐的曲线、想让相机沿着某个路径自动巡航，这些在 ECharts 里做起来要么依赖 hack，要么干脆做不了。Three.js 是底层 WebGL 渲染引擎，本质上是给你一块自由的 3D 画布，地图只是你在这块画布上搭出来的一个场景而已。换句话说，Three.js 不是“地图库”，它比地图库更底层，也更灵活。
这次项目里实际用到的高频能力包括：几何体挤出（ExtrudeGeometry）、多边形轮廓线、Raycaster 点击拾取、OrbitControls 相机控制、Sprite 标记点、CatmullRomCurve3 飞线。这些在 Three.js 里都是成熟能力，组合起来就能做出一张交互感很强的中国3D地图。
1.2 Vue 在这里不是主角，但离了它很别扭
地图主体虽然是 Three.js 干的，但整个页面不可能只有一张地图：左侧要放省份数据排行，右侧要放选中省份的详情面板，底部可能还有时间轴筛选。这些 UI 和地图之间需要联动，比如鼠标悬停到某个省，右侧面板实时更新；点击某个省，地图视角飞过去。如果纯用原生 JS 写，这些状态管理会非常痛苦，而 Vue 的响应式数据天生就适合干这事。
我的做法是：把“当前选中省份”“当前悬停省份”这类状态放在 Vue 的 reactive 对象里，Three.js 侧监听这些状态变化，对应更新地图材质颜色、相机位置、UI 面板内容。反过来，Three.js 的 Raycaster 拾取到省份后，修改的也是 Vue 的响应式对象，这样 UI 和 3D 场景就形成了一个闭环数据流。这个思路对于所有用 Three.js 做数据可视化大屏的项目都适用。
2. 环境搭建与地图数据预处理
2.1 快速初始化 Vue3 + Vite + Three.js 开发环境
这个项目我用的 Vite 而不是 Vue CLI，原因很简单：Vite 冷启动快、热更新快，在开发阶段会舒服很多。Node.js 版本用的是 18+，直接按官方文档创建，命令如下：
npm create vite@latest china-3d-map -- --template vue cd china-3d-map npm install npm install three npm install --save-dev unplugin-auto-import unplugin-vue-components装完以后，先确认一下 three 的版本。我写这篇文章时 three 已经到 0.160+ 了，API 基本稳定，下面示例代码在 0.150 ~ 0.170 之间都能跑。不过要注意一个小变化：新版本里THREE.Geometry已经移除很久了，所有几何体都是BufferGeometry，写代码时别再用旧 API。
项目里还需要引入地图 GeoJSON 数据。中国省份边界的 GeoJSON 可以在阿里云 DataV 的公开数据集里拿到，搜索“china.json”或者“中国地图 geojson”就能找到。我用的这份数据包含了省份名称、adcode、以及对应的多边形坐标数组，格式是标准的 GeoJSON FeatureCollection。
2.2 GeoJSON 坐标数据解析：从经纬度到 3D 平面坐标
拿到 GeoJSON 以后，第一步不是急着渲染，而是把经纬度坐标转换成 Three.js 场景里能用的平面坐标。这里面有个新手最容易踩的坑：直接把经纬度当成 x/y 用。中国地图的大致范围是经度 73°~135°、纬度 18°~54°，如果你原样用这组数字去创建几何体，地图确实能显示出来，但它会跑到坐标轴的右上方很远的地方，而且比例失衡，相机很难定位。
比较稳妥的做法是，先计算整个数据集的最小/最大经纬度，然后按比例映射到一个以原点为中心的矩形区域内。下面是我项目里实际用的投影函数：
function normalizeGeoJSON(features, width = 100, height = 100) { // 1. 计算经纬度范围 let minLon = Infinity, maxLon = -Infinity; let minLat = Infinity, maxLat = -Infinity; features.forEach(feature => { const coords = getAllCoordinates(feature); coords.forEach(([lon, lat]) => { minLon = Math.min(minLon, lon); maxLon = Math.max(maxLon, lon); minLat = Math.min(minLat, lat); maxLat = Math.max(maxLat, lat); }); }); // 2. 计算等比缩放比例，保持地图不变形 const xScale = width / (maxLon - minLon); const yScale = height / (maxLat - minLat); const scale = Math.min(xScale, yScale); // 3. 返回一个经纬度转 x/y 的函数 return function project(lon, lat) { const x = (lon - minLon) * scale - width / 2; const y = (lat - minLat) * scale - height / 2; return { x, y }; }; } function getAllCoordinates(feature) { // GeoJSON 可能是 Polygon 也可能是 MultiPolygon，统一拍平处理 const geometry = feature.geometry; if (geometry.type === 'Polygon') return geometry.coordinates.flat(); if (geometry.type === 'MultiPolygon') return geometry.coordinates.flat(2); return []; }这里有个细节值得多说一句：为什么用Math.min(xScale, yScale)而不是分别用 x 和 y 方向的缩放？因为如果不取等比例，地图的横向和纵向会被拉伸，中国地图看起来会比实际“胖”或者“瘦”。很多教程没提这一点，做完以后地图轮廓总觉得不对劲，其实就是这里出了问题。等比例缩放牺牲的是一部分展示面积，但换来的地图形状保真是完全值得的。
2.3 三种可选的“高度”数据来源
这个项目标题叫“3D地图”，3D 体现在哪里？最直观的就是每个省份的墙体和挤出高度。在实操里，高度数据常见有三种来源：
- 真实地形高程：比如 NASA 的 SRTM 30米分辨率 DEM 数据，但处理起来很麻烦，需要切片、读像素值，对前端来说成本太高，一般不做；
- 业务指标映射：比如各省 GDP、人口、销售额，用数值大小决定挤出高度，这是大屏项目最常用、也是效果最直观的方案；
- 模拟海拔：如果只是想要一个酷炫的展示效果，并不需要反映真实业务数据，那可以直接给每个省份设定一个“虚拟海拔”，比如西藏高度 5000，四川 1000，你只需要维护一个省名对应高度的字典就行。
我这次项目一开始用了真实海拔数据（模拟方案），后来客户要求能反映业务数据变化，于是改成按指标映射高度。建议你把高度计算抽成一个函数，后续切换数据源会非常方便：
function getProvinceHeight(provinceName, data) { const value = data[provinceName] || 0; return 3 + value * 20; // 最低 3 个单位，最高根据数据自适应 }实践下来，如果所有省份高度都是平的，比如都是 3，地图看起来就是一张“饼”，没有立体感。至少要保证西藏、青海、云南这些区域比东部省份高一点，视觉上才有“中国地势三级阶梯”的感觉。这虽然不是真实地理数据，但观众的直觉会觉得“对，就是这种感觉”。
3. 核心功能拆解与实现
3.1 用 ExtrudeGeometry 把省份从“平面”变成“立体”
处理完坐标以后，就可以为每个省份创建几何体了。Three.js 里做立体地图最直接的方法是ExtrudeGeometry：先画一个多边形平面，再沿 z 轴方向挤出一个高度，就得到了有“墙体”的立体形状。
具体流程分三步：
第一步，把省份的多边形轮廓转成THREE.Shape。注意，一个省可能有多个不相连的轮廓（比如广东省包含海南岛？不对，海南是单独的省份，但有些省份确实有飞地或岛屿），所以一个Shape可能不够，需要循环处理。
function createProvinceShape(coordinates, project) { const shape = new THREE.Shape(); coordinates.forEach(([lon, lat], index) => { const { x, y } = project(lon, lat); if (index === 0) shape.moveTo(x, y); else shape.lineTo(x, y); }); return shape; }第二步，用ExtrudeGeometry挤出。这里有两个关键参数：depth是挤出高度，也就是省份的“海拔”；bevelEnabled默认是true，会产生一个倒角，我建议在大多数地图场景里把它关掉，否则省份边缘会有一个斜切面，影响视觉精度，而且会额外增加顶点数。
const geometry = new THREE.ExtrudeGeometry(shape, { depth: provinceHeight, bevelEnabled: false, });第三步，把几何体平移到合适的位置。ExtrudeGeometry默认从 z=0 向上挤，所以省底和顶都在一个很小的范围内。为了让地图看起来是“悬浮”的或者“沉在底座上的”，可以整体平移geometry.translate(0, 0, -provinceHeight / 2)，让省体居中。
每个省份对应一个独立 Mesh，把这个 Mesh 放进一个THREE.Group里，方便统一管理。给每个 Mesh 的userData上挂省份名称、adcode、原始高度等业务字段，后面做点击高亮和飞线都会用到。
3.2 省份高亮、选中与点击交互
交互是大屏项目的重头戏。Three.js 里做点击拾取的标准方式是用Raycaster，从相机发射一条射线，检测与哪些 Mesh 相交。这里有个性能优化的点：场景里可能有几十个省份 Mesh，如果每一次鼠标移动都做全量射线检测，会有一些多余的 CPU 开销。我一般会单独维护一个provinceMeshes数组，只对这个数组做检测，而不是对scene.children全部检测。
const raycaster = new THREE.Raycaster(); const mouse = new THREE.Vector2(); function onMouseMove(event) { // 将鼠标位置转换成 NDC 坐标（-1 ~ 1） mouse.x = (event.clientX / window.innerWidth) * 2 - 1; mouse.y = -(event.clientY / window.innerHeight) * 2 + 1; raycaster.setFromCamera(mouse, camera); const intersects = raycaster.intersectObjects(provinceMeshes); if (intersects.length > 0) { const mesh = intersects[0].object; hoverProvince(mesh.userData.name); } else { clearHover(); } }高亮的效果，我推荐两种方案一起用。一是改变材质颜色，悬停时从默认蓝色调变成亮一点的青色或绿色；二是叠加一个描边效果，用EdgesGeometry+LineSegments把省份轮廓线画出来，选中时让轮廓线变成亮色。只有颜色变化的话，在展厅大屏的高亮环境下容易被忽略，加上轮廓线以后辨识度会高很多。
关于点击后如何把 Vue 侧的 UI 面板带出来，我的数据流是这样的：点击某个省，先更新 Vue 的 reactivestate.currentProvince，然后地图侧通过watch监听这个值，执行相机飞行动画（用 Tween 或自定义轨迹飞行到目标省份上方），同时把省份材质换成选中色。UI 面板里展示的业务数据，直接根据state.currentProvince从接口或者本地 JSON 里读取。
3.3 城市标记与飞线动画：让地图有生命力
光有立体的省份轮廓还不够，大屏上还得有“点”和“线”——点代表重点城市，线代表城市之间的关联。城市标记我用的是THREE.Sprite+ Canvas 生成的纹理，这样能保证文字（比如城市名）始终面向相机，而且成本很低。
function createCitySprite(name, position) { const canvas = document.createElement('canvas'); canvas.width = 128; canvas.height = 64; const ctx = canvas.getContext('2d'); ctx.fillStyle = '#ffffff'; ctx.font = 'bold 24px sans-serif'; ctx.textAlign = 'center'; ctx.fillText(name, 64, 36); const texture = new THREE.CanvasTexture(canvas); const material = new THREE.SpriteMaterial({ map: texture, transparent: true }); const sprite = new THREE.Sprite(material); sprite.position.copy(position); sprite.scale.set(8, 4, 1); return sprite; }飞线是这种地图展示里最出效果的一环。我的做法是：拿到起点和终点城市的三维坐标后，用CatmullRomCurve3创建一条贝塞尔曲线。为了让飞线看起来有弧度，我在起点和终点中间加一个抬升的中间点，控制点高度向上偏移 20~30 个单位。然后用TubeGeometry生成管状线条，或者用Line直接渲染曲线。带渐变效果的飞线更推荐用Line2（FatLines），但实现复杂度会高一些。第一次做的话，先用CatmullRomCurve3.getPoints(50)生成一系列点，再用THREE.Line画出来，效果已经足够。
飞线动画有两种常见做法：一种是让线的透明度或宽度沿路径随时间变化（需要 Shader），另一种是移动一个“光点”从起点到终点，后面这种比较好理解。用一个球体或 Sprite 作为飞行光点，每一帧更新它在曲线上的位置：
// 预先计算曲线 const curve = new THREE.CatmullRomCurve3([startPoint, controlPoint, endPoint]); // 在 requestAnimationFrame 里更新 const t = (Date.now() / 1500) % 1; // 1.5 秒走完一次 const point = curve.getPoint(t); flyPoint.position.copy(point);3.4 Vue 生命周期与 Three.js 场景的绑定
把 Three.js 塞进 Vue 组件里，有一个老生常态但很多人还是会踩的坑：场景只能在组件挂载后创建，组件销毁前必须清理。我的组件结构大概是这样的：
<template> <div ref="mapContainer" class="map-container"></div> </template> <script setup> import { ref, onMounted, onBeforeUnmount } from 'vue'; const mapContainer = ref(null); let renderer, scene, camera, controls; let animationId = null; function initScene() { const container = mapContainer.value; const width = container.clientWidth; const height = container.clientHeight; scene = new THREE.Scene(); camera = new THREE.PerspectiveCamera(45, width / height, 0.1, 1000); camera.position.set(0, -80, 80); camera.lookAt(0, 0, 0); renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true }); renderer.setSize(width, height); container.appendChild(renderer.domElement); controls = new OrbitControls(camera, renderer.domElement); controls.enableDamping = true; } function animate() { animationId = requestAnimationFrame(animate); controls.update(); renderer.render(scene, camera); } onMounted(() => { initScene(); loadMapData(); animate(); window.addEventListener('resize', onResize); }); onBeforeUnmount(() => { cancelAnimationFrame(animationId); window.removeEventListener('resize', onResize); renderer.dispose(); mapContainer.value.removeChild(renderer.domElement); }); </script>这里额外提醒一下：renderer.dispose()之后一定要把 canvas 从 DOM 里移除，否则在 Vue 的 HMR 热更新或路由切换时，你的页面里会保留很多幽灵 canvas，占用显存。
4. 性能优化与三个最值得记录的坑
4.1 大屏渲染性能优化
展厅大屏的分辨率一般是 1920x1080 或者更高，数据量大的时候容易掉帧。我做过的优化主要有几个方向：
- 合并静态几何体：如果某些省份的几何体不需要单独交互，可以先把它们合并成一个几何体，一次 draw call 渲染完，能显著降低 GPU 压力。需要交互的省份再单独保留；
- 减少透明物体：大量半透明叠加会触发透明度排序，GPU 开销成倍增加。标记点、贴片能用不透明的就尽量不透明；
- GeoJSON 数据简化：中国地图的 GeoJSON 原始文件可能有几百 KB，顶点数非常多。可以用 mapshaper 之类的工具把精度从 5 位小数降到 2~3 位，肉眼几乎看不出差别，但顶点数可以减少一半以上；
- 使用 DRACOLoader 压缩模型：如果还有 GLTF/GLB 模型（比如建筑模型、装饰物），务必用 Draco 压缩，压缩率通常在 70% 以上。
我记得有一次地图旋转的时候掉帧特别严重，检查了半天发现是 GeoJSON 里每个省份的轮廓精度都特别高，渲染时的顶点数达到了十几万。用 mapshaper 简化到 2% 以后，帧率从 30 以下直接拉回 60，效果非常明显。
4.2 坐标偏移导致省份轮廓“错位”的排查思路
这个项目里最典型的一个问题：地图渲染出来以后，某个省份的形状整体偏离了它本来的位置，或者省份之间有交叠。排查下来，原因通常出在getAllCoordinates函数把MultiPolygon拍平的逻辑写错了。GeoJSON 里Polygon的坐标层级是三层数组：最外层是环（Ring），每个环里是坐标点数组；而MultiPolygon是四层数组。拍平时如果flat(1)或flat(2)层级不对，取出来的点就会错乱。
建议你写完之后做一个可视化调试：先把所有省份的轮廓线用LineSegments画出来，叠加在平面底图上对比，这样可以快速判断题是否出在轮廓解析上。如果轮廓整体错位，一定是投影函数的问题；如果只有个别省份错位、扭曲，那就是MultiPolygon解析的问题，按上面提到的拍平层级逐层检查即可。
4.3 透明材质渲染顺序问题
Three.js 里透明物体的渲染顺序是一个老大难问题。地图场景里如果既要有透明的省份漂浮块（半透明膜状效果），又要有透明的飞线、透明的标记点，经常会出现“透过一个透明物体看到另一个透明物体时，后面的物体有一部分不显示”的现象。
这个问题没有一劳永逸的解决办法。我的经验是：depends 优先级 + renderOrder 手动调整。在创建 Mesh 的时候显式设置：
provinceMesh.renderOrder = 1; flyLineMesh.renderOrder = 2; sprite.renderOrder = 3;同时把透明材质的depthWrite: false设上，防止透明物体写入深度缓冲导致后面的透明物体被遮挡。这个技巧不是万能的，但对大多数情况能明显改善。
5. 项目还能怎么扩展：从“会动的地图”到“可用的产品”
做完主体功能以后，我并没有马上收工，而是按客户需求加了几个扩展点，这里也一并分享出来。
第一是时间轴播放。在 Vue 侧做一个 slider，拖动时间轴时，各省的挤出高度会按照时间变化而重新计算，形成一个数据演变的动画效果。实现起来并不复杂，因为省份高度已经抽成了getProvinceHeight函数，改动高度时只需要循环省份 Mesh，更新几何体或者重新创建几何体就行。不过要注意，频繁重建几何体很耗内存，更好的做法是用geometry.attributes.position动态修改顶点位置，但计算量会大一些，需要自己权衡。
第二是图表面板与地图联动。页面右侧放一个 ECharts 折线图，展示选中省份的历史数据。点击省份时，Vue 侧更新 ECharts 的option，这个很简单，重点在于地图和图表要共用一套数据源，避免两侧数据不一致。
第三是部署和加载体验。地图 GeoJSON 文件如果比较大，建议放到 CDN 上，并用fetch异步加载，期间显示一个 loading 状态。还可以用topojson-client把 TopoJSON 转 GeoJSON，文件更小，加载更快。不过 TopoJSON 会增加一个转换步骤，如果不是特别在意首屏速度，直接用优化后的 GeoJSON 就够。
我在实际部署时踩过一个相关的小坑：如果项目部署在 Nginx 子路径下，比如http://example.com/geo/，静态资源路径默认是相对路径，直接fetch('china.json')会 404。解决方法是给 Vite 配置base: '/geo/'，或者用相对路径fetch(new URL('./china.json', import.meta.url).href)。
6. 最后几个实用建议
写到这里，项目主体基本讲完了。按照我的经验再给大家几个通用建议：
- 别期待一次写对。三维场景坐标系远比二维 Web 页面复杂，最好先把地图轮廓线渲染出来看形状，再往上叠加立体和交互。一步一步来，更容易定位问题。
- 相机位置和灯光是照片质量的关键。同一种蓝色材质，在偏暗的展厅大屏和明亮的办公显示器上呈现效果差别巨大。建议用
HemisphereLight作为环境光，再配一个DirectionalLight作为主光，并花时间调光的方向，阴影和高光会比默认光照自然很多。 - 保持场景可配置化。把省份颜色、高度、飞线速度、相机初始位置这些参数全部抽到一个配置文件里。因为大屏项目的需求沟通通常不是一次性能敲定的，客户总会在交付前提出“这个紫色换一下”“地图转得再慢一点”之类的改动。配置化之后，改起来就是调参数的事。
最后再分享一个我在项目交付阶段学到的经验：不要只盯着技术指标，还要多考虑“使用场景”。客户看大屏的时候，不会关注你用的是 Three.js 的哪个 API，只会关注视觉效果是否够震撼、交互反馈是否够流畅。所以宁可减少几个花哨功能，也要保证相机旋转、飞线动画、点击响应这些核心交互的流畅度。我这次项目里最受好评的一个设置，其实是 OrbitControls 的autoRotate——地图加载完成后自动缓慢旋转，立刻让整个大屏的科技感上了一个台阶。这个设置对代码来说只有一行，但现场效果提升非常大，强烈建议也试一下。
本文还有配套的精品资源，点击获取
