简介适用于 ECharts 地图可视化场景的世界地图 GeoJSON 数据包面向需要快速绘制世界地图的前端开发者与数据分析人员。作者结合项目实践将常用世界地图边界数据整理为单个 JSON 文件下载解压后即可导入 ECharts 项目使用免去自行从多源拼合地图数据的麻烦尤其适合地图展示、大屏可视化、区域统计等场景。包内共 1 个文件为 JSON 格式地图数据格式统一、结构清晰整体大小仅 279KB导入后不占用过多项目体积。目前已有 1705 人学习/下载说明该资源在同类需求中具备实用性和参考价值。通过这份文件读者可以获得完整的世界地图轮廓数据开箱即用地完成地图注册与渲染若配合自定义样式或交互配置即可快速构建出符合业务需求的全世界地图可视化效果。 兄弟们做 ECharts 地图可视化的时候卡得最狠的往往不是图表配置而是那个“地图 JSON”本身找不到、不对、渲染出来缺块漏块。尤其做世界地图和主要国家下钻这类项目JSON 文件的质量直接决定了后续所有工作量。这篇东西不聊虚的就围绕 ECharts 世界地图和主要国家 JSON 文件的获取、处理、加载、渲染和踩坑复盘来写。适合刚接触地图可视化的前端也适合要接手地图项目但被数据文件搞到头疼的后端同学。看完你至少能搞清楚三件事地图 JSON 从哪来、怎么加工成 ECharts 能用的格式、加载后出问题怎么排查。1. 地图JSON到底是什么GeoJSON格式和ECharts的约定1.1 GeoJSON和ECharts地图JSON的关系先说个基本概念。ECharts 地图组件本身不内置任何地图数据它只是定义了一套渲染规则真正决定“画什么形状、覆盖什么区域”的数据全靠外部传入的 GeoJSON。GeoJSON 是一种用 JSON 格式描述地理空间信息的标准核心结构分三类Point 表示点、LineString 表示线、Polygon 表示面。世界地图里每个国家基本就是一个 Polygon 或者 MultiPolygon。ECharts 的地图 JSON 其实就是简化过的 GeoJSON把每个区域的几何坐标和属性信息按特定方式组织起来再通过echarts.registerMap(mapName, geoJson)注册后地图组件才能拿到这份“底图”。看一下典型的世界地图 JSON 里一个国家的数据结构大概是这个意思{ type: FeatureCollection, features: [ { type: Feature, properties: { name: China, cp: [104.1954, 35.8617] }, geometry: { type: MultiPolygon, coordinates: [ [[[x1, y1], [x2, y2], ...]], [[...]] ] } }, { type: Feature, properties: { name: United States, cp: [-95.7129, 37.0902] }, geometry: { type: MultiPolygon, coordinates: [...] } } ] }这里的properties.name就是 ECharts 用来和series.data中的name字段做匹配的关键字段。geometry.coordinates里存的是一串经纬度坐标ECharts 会把它们投影成平面上的路径来绘图。cp这个字段很多人不熟它表示中心点主要用在label显示上如果没有它会自动计算几何中心但那可能落在海上或国界外显示效果差。1.2 坐标精度和区域完整度是首要筛选条件处理世界地图 JSON 时我最频繁遇到两类问题坐标精度太低导致国界线“一坨一坨的”以及区域不完整导致某些国家或者地区渲染不出来。坐标精度低通常是因为文件经过过度压缩边界点抽稀太狠大比例尺下看着还行一旦放大地图越南那个狭长的海岸线会变成锯齿状。区域不完整主要是数据源本身没采集完整比如有些世界地图的 JSON 里把台湾地区、克什米尔地区画没了这在一些业务场景里是不可接受的。所以选数据源时我一般会关注三点一是坐标点的密度是否满足项目缩放范围的展示需求二是区域边界是否符合业务要求尤其是涉及中国地图、世界地图这种对国界有严格展示要求的场景三是文件体积是否适合前端直接加载。这三点互相制约需要提前权衡而不是拿一个 JSON 就开始怼代码。2. 世界地图和主要国家JSON的获取与预处理2.1 获取完整世界地图JSON的渠道与筛选标准市面上的地图 GeoJSON 源不算少但真正能直接用在 ECharts 里的并不多。我这些年用得比较顺的是以下几条渠道按推荐程度排个序数据源格式说明特点阿里云 DataV.GeoAtlasGeoJSON国内访问稳定支持中国及世界各国家提供行政区划边界数据加载速度快比较适合国内业务Natural EarthGeoJSON / Shapefile国际开源项目提供1:110m、1:50m、1:10m多级精度精度分级明确适合做世界地图但需要自行转换裁剪GADMGeoJSON / Shapefile行政边界数据覆盖国家地区广适合科研级应用精度高但文件体积极大开源 GitHub 仓库如 geojson-maps、echarts-map-jsonGeoJSON社区维护分国家和区域裁剪好方便但需注意许可证和时效性实际项目中我的习惯是做世界地图优先用 Natural Earth 的 1:110m 或 1:50m 数据配合脚本裁剪出主要国家再手动调优边界。如果是国内业务需要强调中国国界那必须对齐标准地图服务的数据别拿国外源直接硬上容易在国界问题上出岔子。2.2 从完整世界地图JSON中抽取主要国家子集完整的世界地图 JSON 通常有 10MB 以上如果只展示几个主要国家直接扔到前端把其他国家的坐标也全加载进来完全没必要。最佳实践是后端先做好裁剪只抽出业务需要的国家生成一个精简 JSON 给前端。我之前写过一段 Node.js 脚本从世界地图全量 GeoJSON 中按国家名抽取子集核心思路就是逐条 feature 过滤。注意用正则匹配部分国家因为不同数据源里的国名拼写可能不太一致const fs require(fs); const world JSON.parse(fs.readFileSync(world.json, utf8)); const targetCountries [/^China$/, /United States/, /Japan/, /Germany/i]; const selectedFeatures world.features.filter((feature) { const name feature.properties.name || ; return targetCountries.some((regex) regex.test(name)); }); const result { type: FeatureCollection, features: selectedFeatures, }; fs.writeFileSync(main-countries.json, JSON.stringify(result));这样一个全量世界地图直接瘦身到十几KB前端加载速度立竿见影。抽出来以后还要检查一次properties里有没有明显缺name或cp的因为 ECharts 对name是强依赖的缺了它会直接忽略这个区域。2.3 简化边界数据控制文件体积如果做全国级或者省级地图对精度要求没那么高可以考虑用 mapshaper 工具做简化。mapshaper可以降低坐标点密度、简化多边形边界同时控制文件体积。命令行这样用mapshaper world.json -simplify 10% -o formatgeojson world-simplified.json-simplify 10%表示保留约 10% 的坐标点。百分比越低文件越小但是边界失真也越明显。我的经验是世界地图场景下 5%~10% 是个比较甜的点既保证国家轮廓能看清又不会出现明显锯齿。如果地图里有细小岛屿简化后可能只剩一个点这时候需要对岛屿类小 feature 做单独处理避免形状完全消失。注意mapshaper 默认使用 Douglas-Peucker 算法简化后的边界可能会出现自相交在 WebGL 渲染时偶尔会产生闪烁。生成后最好用 QGIS 或者开源库做一次拓扑检查确认没有严重拓扑错误再上生产。3. ECharts地图的加载、注册与渲染关键配置3.1 加载方式一script标签直接引入如果地图 JSON 是静态文件最简单的方案是直接在 HTML 里用 script 引用因为 ECharts 支持全局变量形式的 GeoJSONscript srchttps://cdn.jsdelivr.net/npm/echarts5/dist/echarts.min.js/script script srchttps://your-cdn/main-countries.js/script script // 假设 main-countries.js 末尾把 JSON 挂到了 window.mainCountries echarts.registerMap(world, window.mainCountries); /script注意这种文件里通常是一行window.mainCountries {...}而不是裸的 JSON 对象这样不会和页面里其他全局变量冲突。这个方法适合地图数据不常变化的场景利用浏览器缓存能显著减少重复请求。3.2 加载方式二异步请求动态注册实际项目里地图数据往往需要根据用户筛选条件变化比如只加载亚洲区域、或只加载某个大洲的国家静态引入就不灵活了。更常见的做法是用 fetch 动态加载 GeoJSON 文件拿到后再注册地图fetch(/geo/world.json) .then((res) res.json()) .then((geoJson) { echarts.registerMap(world, geoJson); const chart echarts.init(document.getElementById(map)); chart.setOption({ series: [ { type: map, map: world, roam: true, label: { show: true, fontSize: 10, }, data: [ { name: China, value: 100 }, { name: United States, value: 200 }, { name: Japan, value: 150 }, ], }, ], }); }) .catch((error) { console.error(地图数据加载失败, error); });这里有个容易被坑的点echarts.registerMap必须在setOption之前执行而且地图注册是全局的多个图表实例之间不能重复注册同名地图否则第二个图表会继续引用第一次注册的数据导致数据不更新。如果需要动态替换地图数据建议先echarts.dispose(dom)销毁旧的实例再重新 init。如果前端使用 Webpack 或 Vite我习惯把地图 JSON 直接 import 成模块避免额外的网络请求import worldJson from ../assets/world.json; echarts.registerMap(world, worldJson);Vite 里默认支持 JSON 导入但建议在build时开启json.stringify合并或者用import maps做预加载避免首屏白屏等待。3.3 visualMap配合地图做数据着色和分档联动热词里出现了echarts visualmap pieces我猜很多朋友卡在给世界地图做“数值分段着色”上。ECharts 的visualMap组件有两种模式连续型type: continuous和分段型type: piecewise。做世界地图的指标对比时我强烈推荐用分段型因为不同国家数据量级差距往往很大连续型会把差异扁平化看不出重点。分段型通过pieces手工指定区间能精准控制每个区间的颜色、标签甚至图标。visualMap: { type: piecewise, pieces: [ { min: 1000, label: 1000以上, color: #b71c1c }, { min: 500, max: 999, label: 500-999, color: #f57c00 }, { min: 100, max: 499, label: 100-499, color: #fbc02d }, { min: 0, max: 99, label: 0-99, color: #c5e1a5 }, { max: 0, label: 无数据, color: #eeeeee }, ], left: 20, bottom: 20, },这里要特别注意pieces边界值是否包含端点。ECharts 文档里规定min和max都是包含的所以两个区间会重合。比如{ min: 500, max: 999 }和{ min: 100, max: 499 }之间不会重合但{ min: 499 }这样的写法就可能落进上一个区间导致数据值 499 被归到 100-499 还是 500-999 取决于文档里对边界的规定。实际开发中我建议每个区间都写清min和max避免歧义。此外地图数据里没有匹配到name的区域会默认不显示但如果selectedMode: false点击交互也不会触发。所以如果要做国家点击下钻还得配合eventschart.on(click, (params) { if (params.name) { console.log(点击了, params.name); // 这里可以做下钻、路由跳转或打开详情抽屉 } });4. 常见报错与地图开发的高频卡点4.1 渲染白屏cant get dom width or height热词里有一条log.js:72 [echarts] cant get dom width or height. please check dom.clientWidth这基本是地图项目中出场率最高的报错之一。原因很简单图表容器在 ECharts 初始化时还没有宽度或高度。出现这个报错的典型场景有三类一是容器用了display: none或父元素未渲染二是容器在 Tab 切换中被隐藏三是移动端某些WebView在加载时容器还没布局完成。我的排查套路是第一步在 init 前打印container.clientWidth和container.clientHeight确认是不是 0。是 0 就说明容器布局有问题先解决布局再谈渲染。第二步如果容器初始时确实不可见可以提供一个兜底宽高const chart echarts.init(container, null, { width: container.clientWidth || 600, height: container.clientHeight || 400, });第三步如果是 Tab 切换后地图不显示老项目里经常用window.dispatchEvent(new Event(resize))重置尺寸但 ECharts 5 响应resize事件的方式稍有变化更好的做法是切到 Tab 时手动调用chart.resize()。4.2 移动端地图点击不生效热词里出现了echarts移动端无法点击这个也很真实。移动端地图点击不生效往往有两层原因。一层是事件本身ECharts 的click事件默认监听了 DOM 的 click但在 touch 设备上存在 300ms 延迟或者滚动和点击冲突需要设置roam: true时注意区分click和roam的手势。另一层是映射区域太小。世界地图里一些面积很小的国家比如新加坡、马尔代夫在手机屏幕上就可能只有几像素非常难点到。解决方案是增加layoutCenter和layoutSize调整地图比例或者用emphasis高亮选中区域同时缩小roam的最小缩放级别map: world, roam: true, scaleLimit: { min: 1, max: 8, },还有种少见但真实存在的情况容器宽度特别小地图缩放后某个国家区域被裁剪到边缘点击位置偏差明显。这个可以通过增大 padding 或者用layoutCenter: [50%, 52%]把地图整体往中间收一点来缓解。4.3 区域渲染不出来或名称匹配失败区域渲染不出来第一步去排查properties.name和series.data里的name是否精确匹配。ECharts 的匹配是严格区分大小写和空格的China和中国不会自动对应上。如果项目里要求界面显示中文、但 JSON 的 name 是英文可以在拿到数据后做一次映射const nameMap { China: 中国, United States: 美国, Japan: 日本, Germany: 德国, }; data data.map((item) ({ name: nameMap[item.name] || item.name, value: item.value, }));我一般建议在series.data里就转好不要把转换逻辑散落在format或tooltip回调里那样排查起来非常乱。还有一种坑是地图 JSON 里某些区域的name带了空格或特殊字符比如Russia 末尾多了个空格渲染时数据匹配不到区域直接空白。这个问题我建议在处理脚本里直接trim()一遍属性字段一劳永逸feature.properties.name (feature.properties.name || ).trim();4.4 地图立体效果和 3D 渲染问题的取舍热词里提到echarts地图立体效果、echarts制做3d饼图。很多场景里大家想要“立体感”我会建议先想清楚地图数据本身是 2D 几何立体感主要靠geo3D组件或者叠加阴影模拟来实现。如果只是想稍微有点层次感在 2D 地图上通过areaColor的渐变和shadowBlur就能达到八成效果itemStyle: { areaColor: { type: linear, x: 0, y: 0, x2: 1, y2: 1, colorStops: [ { offset: 0, color: #1a3a5c }, { offset: 1, color: #0b1e30 }, ], }, borderColor: #4aa3df, shadowBlur: 15, shadowColor: rgba(0, 0, 0, 0.5), },如果确实要三维地图那就要引入echarts-gl配置geo3D组件但是数据加载量会明显增大移动端性能也会下降建议只在 PC 端大屏场景使用。5. 地图JSON与业务数据的整合和自动化处理5.1 用Python批量处理和合并JSON实际项目中地图数据很少只有世界地图一个文件。很多时候需要把世界地图、各大洲、主要国家、重点省份的 JSON 都维护好还要和后端数据做关联。这种情况下我习惯用 Python 做一轮预处理加工成前端可直接使用的数据包。一个常见需求是从世界地图 JSON 里按洲分组生成多份 JSON 文件。参考脚本如下import json with open(world.json, r, encodingutf-8) as f: data json.load(f) continents { Asia: [China, Japan, India, South Korea], Europe: [Germany, France, United Kingdom], North America: [United States, Canada, Mexico], } for continent, countries in continents.items(): features [ feat for feat in data[features] if feat.get(properties, {}).get(name) in countries ] with open(f{continent}.json, w, encodingutf-8) as f: json.dump({type: FeatureCollection, features: features}, f, ensure_asciiFalse)这种模式最大的好处是可以把“按国家拽数据”的逻辑固化成脚本下次想换国家列表直接改配置就行不用每次手工打开文本编辑器一点点删坐标。5.2 地图JSON和业务数据的合并策略地图加载之后必须把业务指标值挂到对应区域上。这里有两种策略同步合并和异步匹配。同步合并适合数据量小、一次性加载的场景前端把业务数据和地图 JSON 的features合并然后批量构造series.data。异步匹配适合后端大数据量的场景先加载地图空壳再通过接口拿指标数据用name做 key 关联。这样地图可以先渲染数据到了再setOption更新用户体验更流畅。需要注意的坑是业务数据里如果存在某个国家不在地图 JSON 中setOption时会静默丢弃数据区域会显示空白。所以建议在合并前做一次对比校验把缺失的name打日志。我就是被这种问题坑了很久才养成的习惯。5.3 地图调试面板的搭建技巧最后分享一个实用的小技巧开发地图页面时建议在页面上临时放一个调试面板实时展示当前地图注册的name列表和series.data的匹配情况。这样不用反复打开控制台直接在页面上看到“哪些区域没数据、哪些数据没映射上”排查效率能提升一个层级。我常用的做法是在配置setOption之后把所有地图区域名塞到一个隐藏的debug区域里const registeredNames Object.keys(chart.getModel().getSeriesByIndex(0).get(map)); console.table(registeredNames.filter((name) !dataMap[name]));把所有映射不上的名字打出来一眼就能定位是数据源缺了还是 name 拼写不一致。这套调试方式在我维护地图项目时基本成了标配。地图可视化项目里JSON 文件是整个链路的地基。不要图省事随便抓一个 GeoJSON 就往上怼建议花点时间把数据源、预处理脚本和校验逻辑固定成模板后面再做新项目时直接复用效率会高很多。本文还有配套的精品资源点击获取