咱们直接进入正题。用Echarts实现中国地图，这活儿看起来简单，官网上拖下来一个demo就能跑，但真到自己项目里，从数据到渲染，从适配到交互，坑一个接一个。这篇东西不聊虚的，直接把我从零到一做完一个中国地图可视化页面的完整过程和踩坑记录摊开来讲，从地图数据怎么拿，到散点怎么飞线怎么画，再到vue3里自适应为什么失效，全部给你捋清楚。
1. 内容整体设计与思路拆解
先说我拿到这个需求时候的第一反应。Echarts做地图，核心不是图表本身，而是地图的“底图数据”。说白了，Echarts本身不携带任何中国地图的经纬度边界信息，它需要你给它一份GeoJSON，它才知道中国的轮廓长什么样、各省的边界在哪、中心点在什么位置。很多人第一步就卡在这，拿不到合适的GeoJSON，后面全白搭。
1.1 核心需求解析
一个典型的地图可视化需求，拆开来看通常是这几层：
- 底图展示：整个中国地图轮廓要出来，省份边界清晰，鼠标悬浮能高亮，点击能下钻。
- 数据映射：各省份要有对应的数值，通过颜色深浅来体现大小关系，这个在Echarts里叫visualMap。
- 标记与动效：在地图上方叠加散点、涟漪、飞线，用来表示重点城市、迁徙关系、流向等。
- 交互联动：点击省份下钻到市级，或者点击散点弹出详情，配合tooltip展示信息。
我的做法是先把这些需求拆成“静态底图 + 动态标记 + 交互事件”三个模块，分别实现再组装。这样做的好处是，每一块出问题都能定位到具体代码，不用整个页面一起排查。
1.2 方案选型：为什么是Echarts而不是其他
市面上做地图可视化的方案其实不少，D3.js、Mapbox、Leaflet、高德地图JS API都能做。之所以在项目里选Echarts，主要是这几点考虑：
- 上手曲线低，配置项是纯对象声明式，不需要像D3那样手动操作SVG路径。
- 内置geo坐标系，叠加散点、飞线、柱状图都很方便，不用自己在Canvas上计算投影坐标。
- 社区生态成熟，遇到问题基本都能搜到答案。
- 对设计师友好，配置项里颜色、字体、边框都能细调，比较容易还原设计稿。
当然Echarts也有一些局限，比如大数据量的实时渲染性能不如专门的地图引擎，3D效果需要额外扩展。但就“中国地图 + 省级数据展示 + 散点飞线”这个场景来说，Echarts是综合成本最低的选择。
2. 地图数据准备：GeoJSON的获取与处理
这一步是整个地图项目的基石，但偏偏很多人不重视。我见过不少同事，代码写得飞快，结果地图渲染出来一片空白，或者只有南海诸岛飘在海面上，根本原因就是GeoJSON数据不对。
2.1 GeoJSON从哪里来
国内能用的GeoJSON来源主要有这几个：
- DataV.GeoAtlas（阿里云）：提供中国、各省份、各城市的GeoJSON，按需下载，格式标准，坐标精度足够用。这是我最常用的来源。
- 高德地图数据开放平台：提供行政区划边界数据。
- echarts-maps仓库：GitHub上有人维护的老版本地图数据包，但更新不够及时，部分边界精度一般。
我建议直接去DataV.GeoAtlas，在页面上选择“中国”就能下载到完整的全国GeoJSON，文件大小大概在几百KB到几MB之间，按需裁剪后完全够用。
注意：如果只是做全国省级展示，记得下载“中国”底图后，检查一下GeoJSON里是否包含“南海诸岛”这个要素。Echarts默认的坐标范围是包含南海诸岛的，如果数据里没有，地图下方会空掉一块，视觉上不完整。
2.2 数据裁剪与压缩
下载下来的GeoJSON往往包含很多我们用不到的字段，比如adcode（行政区划代码）、center（中心点坐标）、centroid（质心坐标）、childrenNum（子级数量）等。如果后端接口的数据只按省份名称匹配，这些字段就是冗余的。
我通常会在项目里用Node.js脚本做一次预处理，核心逻辑是：
const fs = require('fs'); const raw = JSON.parse(fs.readFileSync('./china.json', 'utf-8')); const features = raw.features.map(f => ({ type: 'Feature', properties: { name: f.properties.name, adcode: f.properties.adcode }, geometry: f.geometry })); const compressed = { type: 'FeatureCollection', features }; fs.writeFileSync('./china-simple.json', JSON.stringify(compressed));这样处理后文件大小能减掉30%到40%，加载更快。如果你对坐标精度要求不是极高，还可以用mapshaper做简化和抽稀，把坐标小数位从6位减到3位甚至2位，视觉上几乎看不出差别，但体积能再小一半以上。
2.3 注册地图的正确姿势
拿到GeoJSON之后，用Echarts的registerMap接口注册：
import * as echarts from 'echarts'; import chinaJson from './china-simple.json'; echarts.registerMap('china', chinaJson);这里有个细节值得说：registerMap的第二个参数除了GeoJSON对象本身，还可以传一个可选的specialAreas对象，用来调整特殊区域的坐标或缩放比例。比如有的版本里“南海诸岛”默认在右下角的小方框里，如果你想让海南省的标识位置更准确，就能在这里微调。不过大多数场景下保持默认就行，不需要动。
注册地图的时机也很重要。如果是在vue3里，我建议在组件onMounted阶段注册，不要在模块顶层就执行registerMap，除非你的项目在服务端渲染（SSR）场景下，顶层执行会导致window未定义报错。这个坑后面细说。
3. 基础地图渲染与配置详解
地图数据注册好，接下来就是写option了。中国的省级地图，最基础的配置分三块：geo或map坐标系、series里的map类型、visualMap视觉映射。很多人搞不清楚geo和map到底有什么区别，这里我一次说透。
3.1 geo坐标系和map系列的区别
geo是一个独立的坐标系组件，它本身不生产数据，只提供地图底图，供其他系列（如scatter、lines、effectScatter）在上面绘制。而map是一个系列类型，它直接把数据和地图区域绑定，用颜色深浅表示数值大小。
简单说：
- 只要一张静态地图，不打算在上面叠其他东西，用
map系列最简单。 - 地图只是作为背景，重点是要画散点、飞线、涟漪，用
geo组件更合适，因为geo和series可以解耦，series只负责数据，不负责地图样式。 - 两者也能同时用，
geo负责底图显示，series里的map负责数据映射，通过geoIndex关联。但大部分业务场景不需要这么复杂。
我的做法是：如果只是“按省份数值填色”这一个需求，直接用series-map；如果要在地图上叠散点、飞线、下钻交互，就拆成geo + scatter/lines/effectScatter组合。
3.2 一个能直接用的基础配置
先给一个省份数值填色的最简配置，这段代码我经常当成模板用：
const option = { tooltip: { trigger: 'item', formatter: function(params) { if (params.seriesType === 'map') { return params.name + '<br/>数值：' + (params.value || 0); } return ''; } }, visualMap: { type: 'continuous', min: 0, max: 1000, left: 20, bottom: 20, text: ['高', '低'], inRange: { color: ['#e0f3f8', '#abd9e9', '#74add1', '#4575b4', '#313695'] } }, series: [{ type: 'map', map: 'china', roam: true, label: { show: true, fontSize: 10 }, itemStyle: { areaColor: '#f5f5f5', borderColor: '#999' }, emphasis: { label: { show: true, color: '#333' }, itemStyle: { areaColor: '#ffd666' } }, data: [ { name: '北京', value: 800 }, { name: '上海', value: 600 }, { name: '广东', value: 900 } ] }] };这段配置里几个关键点：
visualMap的min和max决定了颜色映射的范围，这个不能直接写死，最好根据后端接口返回的数据动态计算。我一般会让后端同时返回一个maxValue字段，前端直接用。roam控制地图是否允许拖拽缩放。如果不需要，建议设为false，避免用户误拖后回不到初始位置。emphasis里配置鼠标悬浮的高亮态，areaColor选一个和默认色对比明显的颜色，交互反馈会更清晰。label默认显示所有省份名称，如果地图缩小到全国范围，字体容易重叠。建议在全国视角下只显示部分省级名称，下钻到省后再全量显示。
3.3 新版本里容易踩的属性坑
Echarts从5.x开始，对map系列的一些属性做了调整。最常见的问题有两个：
一个是mapType属性。网上大量老教程里写的是mapType: 'china'，这个写法在Echarts 3和4里能跑，但5.x里已经改成了map: 'china'。如果你从老项目升级到5.x，代码会直接报错，地图不出来，别慌，改成map就行。
另一个是label的show属性。在新版本里，如果series-map的label不设置show: true，默认是不显示省份名称的。有同事改了半天样式，发现字体设置没生效，一查就是这里。
还有emphasis里的label：默认情况下，鼠标悬浮时标签会变成粗体加颜色变化，如果不想让悬浮时标签变化太大，可以把emphasis.label全部显式设置一遍，防止继承到一些奇怪的默认值。
4. 地图上的数据标注：散点、涟漪与飞线
底图和省份填色做完，项目其实才完成一半。大多数真实业务里，地图上还要叠加重点城市标记、迁徙轨迹、流量流向这些动态信息。这一节重点说这些叠加层的实现细节。
4.1 散点（scatter）的定位原理
散点的位置由经纬度决定。Echarts里，scatter系列配合geo坐标系时，直接给[longitude, latitude]的坐标数组就行。
比如我要在北京、上海、广州各画一个点：
const scatterData = [ { name: '北京', value: [116.46, 39.92, 100] }, { name: '上海', value: [121.48, 31.22, 80] }, { name: '广州', value: [113.23, 23.16, 60] } ]; series.push({ name: '重点城市', type: 'scatter', coordinateSystem: 'geo', data: scatterData, symbolSize: function(val) { return Math.max(val[2] / 10, 8); }, label: { show: true, position: 'right', formatter: '{b}' }, itemStyle: { color: '#ff6600' } });这里的value数组前三项对应[lng, lat, 数值]，symbolSize根据第三维数值动态缩放，这是很常见的需求。经纬度从哪来？和后端约定好，他们返回的每个城市节点带lng和lat字段即可。实在没有，前端也可以维护一个城市编码表，但不太建议，因为后端接口经常换城市，前端维护代价高。
4.2 涟漪动效（effectScatter）的视觉优先级
effectScatter是带扩散动画的散点，适合用来标记需要重点突出的城市或事件节点。配置上比scatter多了rippleEffect：
series.push({ name: '重点事件', type: 'effectScatter', coordinateSystem: 'geo', data: focusData, symbolSize: 12, showEffectOn: 'render', rippleEffect: { period: 4, scale: 4, brushType: 'stroke' }, itemStyle: { color: '#ff3333', shadowBlur: 10, shadowColor: 'rgba(255, 51, 51, 0.5)' } });这里有个性能细节：showEffectOn有两个值，render表示动画持续播放，emphasis表示只有鼠标悬浮时才播放。如果地图上有几十个涟漪点且都用render，页面会明显掉帧。像大屏展示这种场景，我一般会让大部分点用scatter静态展示，只给2到3个核心事件节点开effectScatter动画。视觉层次反而更清爽，重点突出，不刺眼。
4.3 飞线（lines）的常见坑：轨迹数据格式
飞线用的是lines系列，配合geo坐标系。常见需求是表示A地到B地的“流动关系”，比如人口迁入迁出、物流路径等。
配置如下：
const lineData = [ { fromName: '北京', toName: '上海', coords: [ [116.46, 39.92], [121.48, 31.22] ] } ]; series.push({ name: '迁移路线', type: 'lines', coordinateSystem: 'geo', data: lineData, effect: { show: true, period: 6, trailLength: 0.2, symbol: 'arrow', symbolSize: 8 }, lineStyle: { color: '#ffaa00', width: 2, opacity: 0.6, curveness: 0.3 } });几个细节注意：
coords是二维数组，至少包含起点和终点两个经纬度。curveness控制线的弯曲程度，0是直线，0.2到0.5看起来比较自然。尤其是多条线起点相同终点相似时，没有弯曲度会全部重叠成一条粗线，看不清关系。- 飞线的“动画小尾巴”由
effect配置控制，period是动画周期（秒），trailLength是拖尾长度比例，数值越大拖尾越长。 - 如果飞线数量巨大（几百条以上），建议把
effect.show在首屏渲染完成后再打开，或者干脆做成静态线，否则动画会让Canvas重绘压力陡增。
4.4 tooltip换行和自定义样式
很多时候，地图的tooltip需要展示的信息不止一行，比如同时显示城市名、数值、占比、同比。直接用默认的tooltip会很挤。我在项目里的做法是，用formatter返回一段HTML字符串：
tooltip: { trigger: 'item', formatter: function(params) { if (params.seriesType === 'scatter' || params.seriesType === 'effectScatter') { const data = params.data.value; return [ '<div style="font-weight:bold;margin-bottom:4px;">' + params.name + '</div>', '数值：' + data[2], '<br/>占比：' + (data[2] / totalValue * 100).toFixed(2) + '%', '<br/>同比：' + data[3] + '%' ].join(''); } return params.name; } }这里有个小技巧：需求方经常要“同比”和“环比”这种额外字段，但地图系列的数据只能挂一个value数组。我在实际项目里会把所有附加字段都塞进value数组里，比如value: [lng, lat, value, yoy, mom]，然后在tooltip的formatter里按索引取。这样不用额外维护一个Map结构，数据源和渲染层一一对应，排查问题也方便。
tooltip换行方面，用<br/>是最直观的。还有网友说“tooltip自动换行”不生效，多半是用了\n但没在HTML模式下转成<br/>，或者formatter返回的是数组而不是字符串。Echarts的formatter里，数组会自动用<br/>拼接，字符串就要自己手动加。
5. 交互下钻：从省份到市级的实现思路
做中国地图，十有八九要加“点击省份下钻到市级”的交互。这个功能第一次做会觉得复杂，拆开看其实就两步：监听点击事件，换地图数据。但实现质量差距很大，下面说细节。
5.1 下钻的完整数据链路
要做下钻，需要准备“省级GeoJSON + 各省市级GeoJSON”两份数据。我的组织方式是：
- 先把全国地图注册为
china。 - 点击某个省份时，动态加载该省的GeoJSON，注册成自定义名称（比如
guangdong），然后重新设置geo的map属性。 - 当前处于省级视角时，
geo.map = 'china'；下钻到广东时，geo.map = 'guangdong'。
伪代码思路：
myChart.on('click', function(params) { if (currentLevel === 'province') { const adcode = provinceAdcodeMap[params.name]; fetch(`/geojson/${adcode}.json`).then(res => res.json()).then(geoJson => { echarts.registerMap(params.name, geoJson); myChart.setOption({ geo: { map: params.name } }); currentLevel = 'city'; }); } else if (currentLevel === 'city') { // 返回上一级 myChart.setOption({ geo: { map: 'china' } }); currentLevel = 'province'; } });这里面有个很关键的体验细节：点击省份时，如果注册地图和setOption之间隔了网络请求，用户会感觉“点了没反应”。我一般先加一个loading状态，用myChart.showLoading()，拿到数据后再hideLoading()。虽然只是一个小细节，但客户观感会好很多。
5.2 下钻等级与数据刷新
另一种常见的下钻模式是“地图只是导航器，真正的数据在旁边的图表里”。比如点击广东省，旁边的柱状图联动展示广东省21个地级市的指标。
这种模式不需要切换geo的map，只要在click事件里重新请求数据、更新旁边的图表即可。相比切换地图数据，这种方案性能开销小，而且不容易出现地图渲染错乱的问题。
我通常推荐这种“地图联动图表”的方案，除非产品经理明确要求必须看到市级地图边界。原因很简单：市级GeoJSON的数据量不小，每个省份都要维护一份，打包体积大、加载慢，而且市与市之间如果数据不全，地图上会留白，观感很差。
5.3 下钻后的返回与缩放比例
下钻成功后，地图的缩放级别最好自动调整，让用户一眼聚焦在当前省份。这里可以调用myChart.setOption里的geo.zoom和geo.center来实现：
myChart.setOption({ geo: { center: provinceCenterMap[params.name], zoom: 3 } });center用该省的中心点经纬度，zoom根据具体省份的大小微调。这个参数没有固定公式，靠调试效果来定。测试的时候我建议把所有省份都点一遍，记录下哪些省份自动缩放后偏了，针对性地调一个provinceCenterMap映射表。
注意：返回上一级时，一定要把
zoom重置回1，center重置为null，否则地图会停留在下级视角。
6. 在Vue3项目里落地：注册时机与自适应失效问题
现在前端项目基本都用Vue3或者React，把Echarts地图接进去，常见的坑集中在两块：组件生命周期里注册地图的时机，以及rem适配方案下图表尺寸不对。热搜词里“pxtorem对echarts没起到效果”就是典型症状，我在这里一起说清楚。
6.1 为什么pxtorem对Echarts不生效
先说结论：Echarts是在Canvas上画图的，它内部用的是像素坐标，和DOM的CSS像素不是一回事。pxtorem这种工具转换的是CSS样式里的px，而Echarts的fontSize、symbolSize、width等配置项，是直接作为数值传入Canvas绘图上下文的，不经过CSS解析，所以不会被转换。
如果你使用的适配方案是postcss-pxtorem或者amfe-flexible一类的，Echarts内部配置里的字号和尺寸都不会跟着根字体大小变化。项目中常见的表现是：在1920设计稿下开发，一切正常；切到手机或更小屏的Pad上，图表文字和标记要么太大要么太小，和页面上其他用rem控制的元素完全不在一个尺度上。
解决方案通常有两种：
第一种，在初始化图表前，先读取当前根元素的字体大小：
const fontSize = parseFloat(getComputedStyle(document.documentElement).fontSize); // 例如设计稿是按1920宽，基准fontSize为16px，实际屏宽为750时根字体可能变成10px然后把所有需要自适应的配置项都乘以fontSize / 16这个缩放系数。
第二种，监听resize事件时，重新计算并setOption，或者干脆不用pxtorem去做图表适配，用Echarts自带的resize结合宽度比例来控制symbolSize和fontSize。我的建议是在大型大屏项目里，用百分比定位容器 + JS动态计算图表内元素尺寸的方式实现适配，不要指望CSS工具能帮你处理Canvas内部。
6.2 组件卸载时销毁实例
Vue3里，useEffect（React）或onUnmounted（Vue）阶段如果不把Echarts实例销毁，会出现内存泄漏，以及切路由后重复初始化导致的地图渲染错乱。
标准做法是在onMounted里初始化并保存实例，onUnmounted里调用myChart.dispose()。注意不是myChart.clear()，clear()只是清空当前图，不释放实例；dispose()才会销毁实例。
import * as echarts from 'echarts'; import { onMounted, onUnmounted, ref } from 'vue'; const chartRef = ref(null); let myChart = null; onMounted(() => { myChart = echarts.init(chartRef.value); myChart.setOption(buildOption()); window.addEventListener('resize', handleResize); }); onUnmounted(() => { window.removeEventListener('resize', handleResize); if (myChart) { myChart.dispose(); myChart = null; } });6.3 动态数据更新时的合并技巧
地图组件接异步接口时，setOption要分清楚是整体替换还是增量更新。Echarts的setOption默认是增量合并的，如果结构变了但你没传完整的option，会导致一些旧配置残留，比如区域高亮色、tooltip显示等。
我的习惯是：地图注册和geo配置只设一次，后续数据更新只更新series里的data字段：
myChart.setOption({ series: [{ name: '省份数据', data: newData }] });这样既保证性能，也避免全量更新带来的视觉闪烁。同理，如果切换了下钻级别，需要改geo的map时，记得把geo整段配置传进去，不要只传一个map字段，否则可能出现新旧map叠加的脏状态。
7. 常见问题与排查技巧实录
最后把做地图项目时高频踩坑的问题集中整理一份，附带排查思路，方便大家直接对着翻。
7.1 地图区域空白或只显示南海诸岛
这是最典型的问题，原因90%以上是GeoJSON注册失败或者注册名和series里的map不一致。
排查顺序：
- 确认
registerMap('china', json)有被执行，且json不是undefined。 - 确认series里的
map: 'china'和注册名完全一致，大小写都对。 - 检查GeoJSON数据有没有被后端或公司网关过滤掉内容，有时候请求到的不是JSON而是HTML错误页，注册后地图自然空白。
这里提供一个调试技巧：在registerMap之后，用echarts.getMap('china')检查返回对象是否存在。如果返回对象有geoJson属性且features长度大于0，说明注册成功。
7.2 visualMap颜色不显示，地图全是一个色
出现这种问题一般有两个原因：
一是data里省份name和GeoJSON里properties.name对不上。比如GeoJSON里写的是“北京”，而后端返回的是“北京市”，就匹配不上，地图不会报错，但颜色映射不到。
二是visualMap的min和max范围不对。如果所有数据值都在50到60之间，但min设成了0、max设成了1000，视觉上所有颜色都趋近最低值，看不出差异。
排查时可以给visualMap加一个calculable: true，手动拖拽看看颜色变化是否正常，这样能快速分辨是数据问题还是映射配置问题。
7.3 散点不在预期位置上，偏到海里去了
散点位置偏了，多半是经纬度坐标系用错了。GeoJSON里的坐标是GCJ-02还是WGS-84，不同数据源可能混用。Echarts默认用的是WGS-84（或近似），如果后端给的是高德坐标系（GCJ-02）的经纬度，会有几百米到一两公里的偏移，在地图缩放到市级以下时非常明显。
解决办法有两个方向：
- 后端统一用WGS-84或GCJ-02，前端不关心。
- 前端引入坐标转换库，如
coordtransform，在渲染前统一转成Echarts需要的坐标系。
此外还有一种情况是，散点的坐标数组是[lat, lng]而不是[lng, lat]。Echarts的geo坐标系只认[longitude, latitude]顺序，后端如果给的是“纬度在前”的数据，所有点都会横向镜像错位。排查方法很简单：拿一个已知城市比如北京[116.46, 39.92]，对比一下就知道顺序对不对。
7.4 地图被拉伸变形，南海诸岛位置诡异
出现这种情况，通常是因为页面容器宽高比和地图数据默认的宽高比差异过大。Echarts的geo组件有layoutCenter和layoutSize属性，可以用来手动控制地图在容器中的位置和大小。
推荐的做法是设置：
geo: { map: 'china', layoutCenter: ['50%', '50%'], layoutSize: '80%' }这样地图会按自身比例居中显示在容器中，不会因为容器宽高比而拉伸变形。
7.5 大数据量渲染时的性能优化
如果地图上要同时显示几百个散点、几十条飞线，加上涟漪动效，首屏渲染会有明显卡顿。我的优化策略是：
- 散点用
scatter，不用effectScatter，或者只在少数核心节点上用。 - 飞线的
effect.show在首屏渲染后再开，或者缩短trailLength。 - 关闭不需要的动画，
animation: false。 - 开启动态分层，低优先级的数据延迟到空闲时渲染。
8. 工具选型与周边资源推荐
最后把做地图项目时比较实用的工具和资源列一个清单，都是我实测后觉得能提升效率的。
8.1 GeoJSON处理工具
- mapshaper：在线简化GeoJSON，压缩体积，支持批量操作。
- DataV.GeoAtlas：阿里云的地图数据下载，细分到区县级。
- geojson.io：在线预览和编辑GeoJSON，调试定位很快。
8.2 Echarts周边
- echarts社区：官方社区，很多现成地图配置和扩展。
- vue-echarts：Vue3项目里用这个封装好的组件，注意版本和Echarts5的兼容性。
- echarts-gl：需要3D地球或3D柱状图时使用，但体量大，谨慎引入。
8.3 自研数据可视化平台
如果你所在团队的项目长期依赖地图可视化，每次都从零做一套GeoJSON管理、地图注册、下钻逻辑，成本很高。有一定资源的话，可以沉淀一个内部组件库，把“中国地图/省份地图的数据加载、注册、渲染、交互下钻”封装成一个通用组件。后续其他业务线要做类似需求，直接传数据和事件回调就能使用。
我在实际项目里就是这么做的，第一次做中国地图用了两个工作日，第二次做省级地图下钻只花了半天，第三次做同类需求基本是复制改参数。这不是偷懒，而是地图可视化本身有很多可复用的部分，把它们沉淀下来，对整个团队都是收益。
以上这些，就是我从零到一完成一个Echarts中国地图可视化项目的完整记录。每个坑都是我实际踩过的，每个配置都是可以复制到项目里直接改的。如果你严格按照这个思路走，从数据准备到交互联动，基本不会遇到什么大问题。剩下的就是结合你自己业务的数据结构和视觉风格，把颜色、字体、动画节奏调成你喜欢的模样。
