简介一套覆盖全国、地市、区县三级地图的js资源共343个文件专为ECharts使用设计压缩包约25.79MB。所有文件按“行政区划代码_省份_城市”命名涵盖黑龙江、吉林、新疆等多省市便于按区域定位并引入对应地图。开发者只需引入ECharts库与对应js设置series的type为map并指定mapType即可绘制可交互地图随后可通过visualMap分段着色、绑定业务数据、添加标记或事件交互适合经济指标展示、人口分布对比、选举结果可视化等场景。地图js由官方不再直接下载这套资源弥补了空白已有2183人学习使用能省去繁琐的GeoJSON坐标整理直接用于大屏或后台数据可视化项目。1. 一张地图文件折腾两天ECharts 行政区划 JS 到底怎么选做可视化大屏的人迟早都会撞上同一个需求要在 ECharts 上画中国地图、点出地市、下钻到区县。早期 ECharts 官网还能直接下载地图 JS后来官方把下载入口砍了网上搜出来的资源要么版本对不上、要么坐标系飘了、要么只有全国没有区县。这个标题对应的就是一套完整的解决方案——全国、地市、区县三个层级的 ECharts 地图 JS 文件本质上是把 GeoJSON 地理数据包了一层registerMap让浏览器能直接加载渲染。适合正在做大屏看板、需要地图下钻、或者刚接手一个地图模块却不知道数据从哪来的开发者。本文往下给的每一段都是我实际处理过多个地图项目后沉淀下来的做法能把选型、获取、渲染、排错这条路走通。2. 地图 JS 文件的前世今生从 GeoJSON 到 registerMap2.1 JS 文件里装的到底是什么ECharts 的地图 JS 文件打开看其实就两部分一大段坐标数据加一行注册代码。坐标数据就是 GeoJSON 格式的 FeatureCollection每个 Feature 的coordinates里存的是经纬度数组properties里放着name和adcode行政区划编码注册代码则是一个define或registerMap调用。常见做法是整个文件用 AMD 风格包裹// 全国地图的典型结构文件末尾会有一行类似这样的定义 (function (root, factory) { if (typeof exports object typeof module ! undefined) { module.exports factory(); } else if (typeof define function define.amd) { define([], factory); } else { root.chinaMap factory(); } })(this, function () { return { type: FeatureCollection, features: [ /* 省份边界坐标 */ ] }; });逻辑说明这段代码做了一件事——把 GeoJSON 数据暴露出去让下面echarts.registerMap(china, chinaMap)能拿到数据。你如果用的是 npm 包管理也可以直接import chinaMap from ./china.json再注册。参数说明里最关键的是type字段必须是FeatureCollection这是 ECharts 能识别的最外层结构features里的每个 Feature 对应一个行政区。需要注意的边界是有的第三方文件会在注册时加一个svg缩放参数官方文档里registerMap的specialAreas选项就是给南海诸岛这类离岛用的。ECharts 5 之后对 GeoJSON 的校验更严格只要你拿到的数据是合法 GeoJSON不管文件名是什么注册名自己定就行。我这里习惯把全国地图注册名固定为china地市用cityName区县用countyName代码里好记后续做下钻联动时命名规则也统一。2.2 三个主流获取渠道哪条路最省事先说结论我只推荐阿里云 DataV 的 GeoJSON 数据服务不是因为它完美而是因为大部分免费源要么覆盖不全要么不稳定。表格里是没有收录完整地市区县的免费源的DataV 有全套。渠道对比渠道层级数据格式坐标系更新频率坑点DataV GeoAtlas全国/省/市/县GeoJSONGCJ-02 加密坐标按月更新部分虚线边界需要自己处理某开源 GitHub 聚合项目全国/部分省/市JS 文件WGS-84 / GCJ-02 混用不定期版本老旧区县覆盖不全自建 GeoJSONOSM 导出自定义GeoJSONWGS-84完全可控需要清洗边界工作量大选型理由DataV 的坐标是 GCJ-02 火星坐标跟国内在线底图是对得上的如果你叠加的是高德底图完全不用做坐标转换开源的 WGS-84 数据放到国内底图上会有几十米偏移做网格下钻时这种偏移直接让散点落在隔壁区县。A 同学当初图省事用了一个 WGS-84 的 JS 包结果某市散点始终压在邻市边界上排查平台只看到坐标漂移最后换成 GCJ-02 才解决。自建这条路适合定制化强、对边界精度要求高的项目成本也高小项目别碰。还有一个渠道经常被忽略echarts 官方仓库的map/js目录是历史遗留里面还躺着旧版的中国地图 JS格式和 ECharts 5 不兼容直接拿去用会报Cannot read property push of undefined。每次网上搜到这种资源的我都劝先看文件头部有没有旧的echarts全局依赖有就直接放弃。2.3 三个层级的文件组织方式和大小差异全国地图、地市地图、区县地图这三层不是一个文件是三个目录。常见的组织方式是/static/map/china.js、/static/map/province.js、/static/map/city.js用行政编码做文件名后缀来区分比如330000.js表示浙江省。文件大小上全国约几百 KB地市根据边界精度在几十到几百 KB 之间区县单个一般不超过 100 KB。很多人会犯一个错把全国地图下载回来后在里面找地市数据。全国 GeoJSON 只精确到省级边界城市边界和区县边界是不存在的。三级地图之间没有包含关系必须分别下载。我一般拿到项目先做一个盘点脚本把需要的省份和城市名单列出来一次性检查文件是否存在而不是等到渲染时才发现缺了某块。关于精度DataV 数据默认到县级乡镇级的 GeoJSON 不在本标题范围内。如果标题里的“区县”是指街道乡镇那数据源就不一样了别硬用区县文件去画乡镇边界。3. 从下载到渲染把地图 JS 接进项目的完整步骤3.1 目录组织和静态资源引入项目结构按这种来放前后端分离和传统多页都能用frontend/public/static/map/ ├── china.js # 全国省级地图 ├── province/ │ ├── 330000.js # 浙江省含地市级边界 │ └── 440000.js # 广东省 └── city/ ├── 330100.js # 杭州市含区县级边界 └── 440100.js # 广州市对数说明用行政编码做文件名是第一推荐别用拼音缩写后端的区域表里都是数字编码接口返回code: 330100时前端可以直接拼出 URL用拼音还得维护一张映射表纯属给自己加工作。引入方式上传统 script 标签加全局变量最省心Vue/React 工程化项目里可以用import echarts配合动态import做按需加载。3.2 全国地图注册与一个能跑起来的最小示例// 全国地图渲染的最小代码先注册再 setOption import * as echarts from echarts; // 假设已经在 index.html 里用 script src/static/map/china.js/script 引入 // 或通过 import chinaMap from assets/map/china.js 引入 const chart echarts.init(document.getElementById(map-container)); // 指定 map 为 china这个名称必须和 registerMap 的第一个参数一致 chart.setOption({ tooltip: {}, visualMap: { min: 0, max: 1000, left: left }, series: [{ type: map, map: china, roam: true, label: { show: false }, data: [ /* 后端返回的数据 [{ name: 广东省, value: 300 }] */ ] }] });逻辑说明echarts.init的容器要是块级元素且有明确高度否则地图画不出来registerMap这步要么在引入文件时自带很多 JS 文件在 define 之后直接执行注册要么显式调用一次。如果项目是纯前端没有后端渲染数据也可以直接用前端 mock 数据填data字段。roam开启后支持鼠标拖拽和缩放大屏展示建议设为true但要注意如果容器宽度小roam 会放大误操作概率。参数需要调的核心就三个map的值对应注册名label.show控制省名是否显示visualMap控制颜色深浅。实际项目里视觉映射不要用默认的百分位直接给min和max才能稳定看到颜色分布。另外 ECharts 5 的 series 里必须设map类型否则地图不会渲染这是新一代版本跟旧版最大的区别。3.3 地市、区县地图的下钻实现下钻的交互逻辑很简单点击省加载省文件渲染地市边界点击市加载市文件渲染区县边界点击空白返回上一层。关键代码在于动态加载// 地市下钻点击省份后加载对应地市 JS 文件 function drillDown(adcode) { const jsonpUrl /static/map/province/${adcode}.js; // 动态加载 script加载完成后再执行渲染 const script document.createElement(script); script.src jsonpUrl; script.onload function () { // 此处假设文件的 define 中已经把地图注册成 jiangsu 或按省份拼音注册 // 实际项目在文件末尾会调用 echarts.registerMap(jiangsu, json) chart.setOption({ series: [{ type: map, map: getMapName(adcode) }] }); }; document.head.appendChild(script); }逻辑说明adcode是行政区划编码点击省份时从params.name映射到编码。getMapName要维护一张“行政编码 → 注册名”的映射表因为 DataV 下载的文件注册名可能是拼音如zhejiang不是数字编码。这段代码里没有写registerMap因为很多现成 JS 文件在define之后就自动注册了你直接用注册名渲染即可如果是纯 JSON 文件就得先await fetch再registerMap那种情形下载的时候看文件格式是 JS 还是 GeoJSON 就能判断。区县级文件用法完全一样只是 URL 路径换成/static/map/city/${adcode}.js。返回上一层的逻辑一般用chart.on(click, params { if (!params.name) goBack(); })点击空白区域时params.name是空的正好用来做返回。4. 加载策略与性能取舍一次性全载还是按需加载4.1 按需加载的三种方案对比地图文件如果一次性全部引入首屏会多出好几 MB 的 JS 开销这在移动端尤其致命。常见做法是拆分加载方案 A全国文件随首屏引入省市文件按需动态加载。适合大屏项目数据量大但是层级清晰。方案 B所有文件打包成异步 chunk用动态 import 触发。适合中后台管理系统。方案 C后端把 GeoJSON 人存在数据库前端通过接口拿。适合行政区划频繁调整的项目但前置条件是后端能维护这套数据。我通常选方案 A原因是大屏数据看板是重前端用户交互路径固定是“全国 → 省 → 市”把全国文件常驻缓存省市文件用 script 插标签的方式加载兼容性最好。用 webpack 拆 chunk 没有错但有跨域和构建配置成本插标签的方式配合静态目录反而最简单。4.2 文件加载失败怎么办兜底和重试动态加 script 标签很容易踩到网络请求失败、文件不存在这类问题加一层兜底逻辑// 加载脚本并在失败时给出提示 function loadScriptWithTimeout(url, timeout 10000) { return new Promise((resolve, reject) { const script document.createElement(script); script.src url; const timer setTimeout(() { script.onload null; script.onerror null; reject(new Error(timeout)); }, timeout); script.onload function () { clearTimeout(timer); resolve(); }; script.onerror function () { clearTimeout(timer); reject(new Error(load error)); }; document.head.appendChild(script); }); }逻辑说明设置 10 秒超时是因为地图文件再大也不至于超过这个时间若超时就提示“地图数据加载失败”同时保留上一次的渲染结果不变。很多项目在这里还会做一个重试按钮但实际用户更强的是直接刷新页面所以把加载失败的错误提示写得具体点就行——写清楚“哪个区域的地图加载失败”不要只弹一个“系统错误”。4.3 渲染数据的缓存与复用地图文件加载后是不变的不需要每次渲染都重新拉。做好这两个缓存一个是浏览器的 HTTP 缓存静态文件服务器配Cache-Control另一个是内存缓存。内存缓存的写法很简单const mapCache new Map(); async function loadMap(adcode) { if (mapCache.has(adcode)) { return mapCache.get(adcode); } const res await fetch(/static/map/${adcode}.js); const text await res.text(); mapCache.set(adcode, text); return text; }注意动态 script 标签不会触发 fetch这里是走另一种方式——把 JS 文件当文本 fetch 下来存入缓存后通过eval或new Function执行。这种方式能拿到内容做预处理但注意 CSP内容安全策略会禁止eval。大多数常规项目不限制eval限制严的项目还是要用 script 标签加载这里要跟安全部门提前确认。5. 地图渲染避坑指南白屏、偏移、漏岛这些坑我都踩过5.1 只显示网格线看不到任何区域边界现象初始化完成后页面只有一个灰蓝色背景的 canvas坐标轴都没有一片空白。 原因最常见的是registerMap没有被执行或者执行了但注册名和series.map不一致其次是 GeoJSON 数据格式不合法比如features里的coordinates是空数组。 解决先在控制台输入echarts.getMap(china)返回undefined说明没注册返回对象但没有geoJson字段说明数据有问题。另外要确认代码执行顺序registerMap必须在setOption之前如果你是用动态加载要在onload回调里先registerMap再setOption别在回调外执行。5.2 地图边界满天飞位置完全不对现象地图渲染出来了但图形整体变形边界线纠缠在一起缩放后像网格碎片。 原因数据源坐标是 WGS-84而你渲染时使用的是 ECharts 默认的 Web 墨卡托投影或者坐标系定义混乱。某些开源资源甚至把经纬度数组顺序写反了。 解决优先确认数据源的坐标系说明。国内在线地图默认是 GCJ-02如果拿到 WGS-84 数据就做坐标转换如果只是个别边界像锯齿一样那是数据精度问题换一个来源的 GeoJSON 就行。另一种常见情况是你在一个自建坐标系的地图上混用了 GeoJSONECharts 对坐标系的适配能力有限除非用自定义系列去画否则别指望它能自动纠正底图偏移。5.3 南海诸岛和台湾显示异常现象全中国地图渲染出来后右下角的南海诸岛没有显示或者台湾不在预期位置。 原因ECharts 5 对 GeoJSON 的specialAreas支持需要显式声明数据源如果缺失这部分地图自然没有南海。台湾位置偏是因为数据里它不在主要区域的bbox范围内投影后位置看起来“掉出去”。 解决使用registerMap的第三个参数echarts.registerMap(china, geoJson, { 南海诸岛: { scale: 1.2, left: 0, top: 0 } });这里的scale控制南海地图块的缩放倍数left和top控制它在画布上的位置。官方示例推荐scale: 1.0和left: -20这类微调实际项目中我会根据容器长宽比手动调scale到 1.21.5不然南海区域太小看不清。这个参数的作用仅限调整显示位置不影响数据映射。5.4 地市代码对不上点击地区无法下钻现象点击省份后没有进入下钻或下钻到了错误的省份。 原因params.name返回的是 GeoJSON 里的name字段如“江苏省”而你的下钻函数需要的是行政编码如320000这两者之间的映射关系没有维护。 解决建立地名到行政编码的映射表。不要手写直接从数据源附带properties里取DataV 的 GeoJSON 里properties.adcode就是编码。代码里优先用params.data.adcode而不是通过名称查表。如果项目里已经有后端接口返回区域树让后端把编码和名称一起返回前端把 GeoJSON 的编码跟接口编码做一次对齐校验避免表格数据和地图数据不一致。5.5 地图渲染性能差缩放手感卡顿现象地图能显示但拖动和缩放帧率很低尤其是在某省地图上操作时更明显。 原因GeoJSON 数据精度过高坐标点密度大或渲染容器尺寸过大导致散点图形绘制压力大。 解决在数据精度和性能之间做平衡。上游拿到的区县级数据坐标点动辄上千实际上画到屏幕上并不需要那么多点。用简单抽稀或引入工具库做坐标抽稀后坐标点能减到三分之一。另一个更快的办法是直接换成 ECharts 5 的svg渲染模式const chart echarts.init(container, null, { renderer: svg });逻辑说明renderer参数使用svg时地图边界是矢量绘制缩放时不需要重算像素很多场景下比默认的canvas流畅。代价是 svg 模式下大量散点和动态数据会吃力所以只在地图为主的数据大屏里推荐用 svg 模式。如果两者都不能满足就压缩 GeoJSON 文件体积把coordinates数组做定点舍入到 5 位小数肉眼几乎无差别体积能小三分之一。6. 进阶用法用 label 和 visualMap 把地图做成年报效果地图文件接进来只是第一步真正让大屏显得专业的往往是 label、颜色映射和联动交互这三块。我自己有一个固定的优化顺序先调 label 字体和避让再调 visualMap 的分段颜色最后加点击事件联动旁边的折线图。label 的避让是大屏最容易忽略的点。全国地图的省名默认全部显示字号一大就糊成一团。常用配置是label: { show: true, fontSize: 12, formatter: function (params) { // 数值为 0 时不显示标签减小视觉噪音 return params.value ? params.name : ; } }formatter的作用不只是改文字内容还能做条件筛选。地图省级边界多隔壁省份数值为零时密集的标签会互相遮挡用这个逻辑过滤掉空值省份会比较舒服。如果还是不理想再调labelLayout: { hideOverlap: true }这是在 ECharts 5 里内置的防重叠参数比手工算位置省心太多。visualMap 的坑在于默认连续渐变在极差值场景下会失效。做犯罪热力或销售分布这种帕累托分布很强的数据时最大值比中位数大几个数量级连续色条基本看不出层次。把visualMap切成分段visualMap: { type: piecewise, pieces: [ { gte: 1000, label: 高, color: #c23531 }, { gte: 500, lt: 1000, label: 中, color: #e6b450 }, { gte: 0, lt: 500, label: 低, color: #749f83 } ] }pieces数字范围可以按项目数据分布动态生成不要写死。视觉上分段比连续更能突出“重点区域”也更适合大屏上拉远看。另外 map 系列里还有一个zoom参数控制地图初始缩放倍数我经常把它和center配合让首屏聚焦目标省份series: [{ type: map, map: china, zoom: 1.2, center: [105, 36] }]center的值是经纬度中心点位置需要先反复试两次不同投影下同一个经纬度的出画位置差异明显调一次不理想就再挪一点。配合前面第 4 章的按需加载这个配置可以让下钻后的城市地图初始就放大到适合操作的尺度。最后一个习惯地图文件引入到项目后先写一个自动比对脚本校验每个 GeoJSON 的adcode是否覆盖了业务需要的全部行政区别等到上线了才发现某县没有边界数据。用户开放注册的区县如果有新增行政区划代码会变地图文件是静态的这部分只能靠定时手工核对。希望这些方案帮到你至少能让你在这个方向上少折腾两天。本文还有配套的精品资源点击获取