简介本资源提供 ECharts 3D 地图所需的 china.json 地理数据文件面向从事 Web 数据可视化开发的前端工程师与数据大屏设计者用于在三维空间中渲染中国地图并展示区域数据差异。压缩包内共 1 个文件为 GeoJSON 格式的 json 数据包含中国各省级行政区的边界坐标与属性信息可直接通过 echarts.registerMap 注册后配合 geo3D 组件使用整体包体约 13KB体积轻量便于快速集成。该数据支持区域颜色、边界样式、标签显示及平移缩放等交互配置适合构建地理数据大屏、区域统计展示等场景。目前已有 246 人学习下载可作为 3D 地图开发的即用型基础数据帮助开发者省去自行整理地理边界的工作将精力集中于视觉定制与业务数据接入。1. 从一份 china.json 说起ECharts 3D 地图到底能跑出什么效果前阵子帮一个做数据看板的朋友排查问题他甩过来一个压缩包里面就一个china.json说“地图加载不出来控制台报 404”。我打开一看他项目里 ECharts 版本是 5.x却还在用echarts/map/json/china.json这种老路径去引而新版 ECharts 早就把内置地图数据剥离出去了。这个坑其实特别典型——很多人搜“echarts 3d json”本质上是想找一份能直接喂给geo3D或map3D组件的中国地图 GeoJSON 数据然后快速搭出一个带立体感、能交互的区域可视化页面。这份资源就是干这个的一份标准的china.json地理边界数据配合 ECharts 的 GL 扩展能渲染出可旋转、可缩放、可下钻的 3D 地图。它适合两类人一是做数据大屏、区域业务监控的前端需要快速出效果二是想基于地图做二次开发比如叠加散点、飞线、热力层的开发者。下面我就按“数据怎么用 → 环境怎么搭 → 代码怎么写 → 坑怎么避 → 怎么改”的顺序把这份资源拆开讲透。2. 数据与渲染链路china.json 在 ECharts 3D 里扮演什么角色2.1 GeoJSON 数据结构与 ECharts 的消费方式china.json本质是一个 GeoJSON 格式的 FeatureCollection里面每个 Feature 代表一个省级行政区geometry字段存的是多边形坐标串properties里通常带name、cp中心点等属性。ECharts 的registerMap方法会读取这份数据把它转成内部的地图坐标系。3D 模式下geo3D组件再基于这些边界做三角剖分生成带高度的立体面。// 引入 ECharts 核心与 GL 扩展 import * as echarts from echarts; import echarts-gl; // 3D 能力依赖这个扩展包 // 异步加载本地 china.json注册为名为 china 的地图 fetch(/static/map/china.json) .then(res res.json()) .then(geoJson { echarts.registerMap(china, geoJson); // 关键一步注册后才能被 geo3D 引用 initChart(); }); function initChart() { const chart echarts.init(document.getElementById(map)); chart.setOption({ geo3D: { map: china, // 对应 registerMap 的名字 roam: true, // 开启旋转缩放 itemStyle: { areaColor: #1a3a5c, borderColor: #4fd1ff, borderWidth: 1 }, viewControl: { alpha: 45, // 俯仰角控制立体感 beta: 0, // 旋转角 distance: 120 // 视距越小越近 } } }); }这段代码里registerMap是整条链路的枢纽——没有它geo3D.map找不到数据源页面就是一片空白。viewControl的三个参数决定了你第一眼看到的立体角度alpha给 40 到 60 之间比较舒服太小像平面太大像俯冲。roam: true让用户能用鼠标拖拽旋转这是 3D 地图区别于 2D 的核心体验。2.2 3D 与 2D 地图的选型差异很多人纠结到底用geo2D还是geo3D。从渲染成本看2D 走 Canvas 或 SVG几千个区域也扛得住3D 走 WebGL面数一多、叠加图层一复杂低端显卡直接掉帧。从交互看2D 适合精确点击下钻3D 适合展示宏观态势。我一般建议如果只是省市区三级联动用 2D如果要做大屏那种带光效、带高度柱的才上 3D。维度geo2Dgeo3D3D渲染引擎Canvas / SVGWebGL数据依赖registerMap 后直接可用需 echarts-gl 扩展交互方式点击、缩放旋转、缩放、俯仰性能瓶颈区域数量面数 叠加图层数适用场景业务下钻、表单联动数据大屏、态势展示选型定下来之后环境搭建就是下一步。这里有个容易被忽略的点echarts-gl的版本必须和echarts主版本匹配5.x 的 echarts 配 2.x 的 gl混用会出现geo3D is not a function这种玄学报错。3. 环境搭建与最小可运行 Demo从零到看见立体中国3.1 依赖安装与目录组织不管你用 Vue、React 还是原生页面依赖就两个echarts和echarts-gl。用 npm 装的话建议锁版本避免自动升级带来的兼容问题。# 初始化项目以 Vite 为例 npm create vitelatest my-map-demo -- --template vanilla cd my-map-demo # 安装核心依赖锁大版本 npm install echarts5 echarts-gl2 # 把 china.json 放到 public 目录构建时不会被处理直接可访问 mkdir -p public/map # 将下载的 china.json 复制到 public/map/china.json目录结构建议这样组织public/map/china.json放地理数据src/main.js写初始化逻辑index.html里给一个固定宽高的容器。容器必须有明确高度否则 ECharts 初始化时拿不到尺寸图表不显示——这是新手最常见的翻车点之一。3.2 完整初始化代码与参数说明下面是一个能直接跑起来的最小 Demo包含地图注册、3D 配置和自适应。import * as echarts from echarts; import echarts-gl; const chartDom document.getElementById(map); const chart echarts.init(chartDom); // 加载并注册地图 async function loadMap() { const res await fetch(/map/china.json); const geoJson await res.json(); echarts.registerMap(china, geoJson); chart.setOption({ backgroundColor: #0b1a2b, // 深色底突出地图 geo3D: { map: china, roam: true, regionHeight: 3, // 区域挤出高度值越大越厚 itemStyle: { color: #1f4e79, opacity: 0.9, borderWidth: 1, borderColor: #6ec6ff }, emphasis: { // 鼠标悬浮高亮 itemStyle: { color: #ffd166 }, label: { show: true, color: #fff } }, label: { show: false, // 默认不显示省名避免拥挤 formatter: {b} }, viewControl: { alpha: 50, beta: 10, distance: 110, autoRotate: false, // 自动旋转大屏可开 autoRotateSpeed: 5 }, light: { // 光照配置影响立体明暗 main: { intensity: 1.2, shadow: true }, ambient: { intensity: 0.3 } } } }); } loadMap(); // 窗口变化时自适应 window.addEventListener(resize, () chart.resize());逐项说下关键参数regionHeight控制每个省挤出的厚度设 0 就是平面设 3 到 8 立体感明显light.main.shadow开启阴影后区域之间的层次会清楚很多但性能开销也上去autoRotate适合无人值守的大屏配上autoRotateSpeed控制转速太快会让人晕。emphasis里的高亮色建议和主色拉开对比不然悬浮反馈不明显。3.3 验证运行结果跑npm run dev之后浏览器打开对应地址应该能看到一个深色背景上的立体中国地图鼠标拖拽能旋转滚轮能缩放悬浮到某个省上会变色。如果只看到背景色没有地图按 F12 看 Network 里china.json是否 200再看 Console 有没有Map china not exists的报错——有的话就是registerMap没执行成功多半是 fetch 路径写错了。4. 常见问题排查地图不显示、报错、卡顿的 5 个真实坑4.1 地图一片空白控制台报 Map not exists现象是页面只有背景色Console 提示Map china not exists。原因通常是registerMap在setOption之后才执行或者 fetch 失败导致注册逻辑没走到。解决办法是把setOption放进registerMap的回调里确保顺序同时检查china.json路径Vite 项目里public下的文件要用/map/china.json这种绝对路径引不能写相对路径。4.2 报 geo3D is not a function这个报错基本就是echarts-gl没装或没引入。现象是setOption时提示geo3D不是有效组件。原因是 ECharts 主包不含 3D 能力必须额外引入echarts-gl。解决是在入口文件顶部import echarts-gl并确认package.json里两个包的版本匹配5.x 的 echarts 对应 2.x 的 gl。4.3 地图能显示但拖不动、缩放没反应现象是地图出来了但鼠标交互无效。原因多半是roam没开或者容器被上层元素挡住了鼠标事件。解决是确认geo3D.roam: true再检查容器的 CSS 有没有pointer-events: none以及父级有没有设置overflow: hidden导致事件被截断。4.4 叠加散点后帧率骤降现象是单独地图很流畅加上scatter3D或lines3D后卡顿。原因是 3D 场景里每个数据点都参与光照和深度计算点数过万就吃力。解决是控制数据量或者把散点改成effectScatter只渲染关键点另外关掉light.main.shadow能省不少性能。4.5 省界边框粗细不一、有锯齿现象是某些省边界看起来比别的粗或者边缘有毛刺。原因是 GeoJSON 精度和屏幕像素比不匹配加上borderWidth设得偏大。解决是把borderWidth降到 1 以内并确认devicePixelRatio正常如果数据源本身精度低可以换更高精度的边界数据但文件体积会变大。5. 二次开发改造从静态地图到业务可视化5.1 叠加业务数据的三种方式拿到这份china.json之后真正让它有价值的是往上叠数据。最常用的是scatter3D打点适合展示城市级指标lines3D画飞线适合展示区域间的流向bar3D做柱状适合对比各省数值。这三种可以共存但要注意图层顺序geo3D放最底层业务图层依次往上加。// 在 geo3D 同级追加散点与飞线 series: [ { type: scatter3D, coordinateSystem: geo3D, data: [ { name: 某区域A, value: [116.4, 39.9, 100] }, // 经纬度 数值 { name: 某区域B, value: [121.5, 31.2, 80] } ], symbolSize: 12, itemStyle: { color: #ff6b6b }, label: { show: true, formatter: {b} } }, { type: lines3D, coordinateSystem: geo3D, effect: { show: true, trailWidth: 2, trailLength: 0.3 }, data: [ { coords: [[116.4, 39.9], [121.5, 31.2]] } ], lineStyle: { color: #4fd1ff, width: 1 } } ]coordinateSystem: geo3D是关键它告诉 ECharts 这些点要贴到 3D 地图的坐标系上。value数组前两位是经纬度第三位是高度或权重。lines3D的effect开启后会有流动光效trailLength控制拖尾长度0.3 左右比较自然。5.2 下钻交互与数据联动3D 地图做下钻比 2D 麻烦因为点击事件返回的是区域名你需要再加载对应省份的 GeoJSON 重新注册。常见做法是准备一套省级 json点击时chart.on(click, params { ... })拿到params.name然后 fetch 对应文件、registerMap新名字、更新geo3D.map。注意每次下钻要清空旧图层否则数据会叠加。5.3 我踩过的坑与验证习惯有次改完配置地图死活不显示排查半小时才发现是china.json被构建工具当模块处理了路径变了。从那以后我每次引入地理数据都强制走一遍 Network 面板确认请求 200再看 Console 有没有注册成功的日志。另外3D 地图的配置项很多是“玄学”生效——比如light不设也能跑但设了之后立体感完全不一样建议一开始就把光照和阴影配好别等效果不满意再回头补。希望这份拆解能帮你把这份china.json真正跑起来也跑出自己想要的效果。本文还有配套的精品资源点击获取