简介中国及34个省市地图JSON文件是一套可直接用于前端地理可视化的数据包面向使用D3.js、ECharts绘制全国或省级地图的开发者和数据分析人员。文件以省市拼音命名覆盖全国34个省级行政区读者无需自行拼接或抓取地理边界数据省去坐标边界整理环节可快速实现各级地图的加载与交互配置。整个压缩包共35个JSON文件容量约466KB单文件体积小、结构规整适合按需提取单个省份或整体引入项目。该资源目前已有3640人学习下载常用于大数据可视化大屏、疫情/人口分布图、区域业务看板等场景。包内JSON均按国内常用地理坐标系组织属性字段便于映射到ECharts的map对象也能在D3中配合投影使用同时提供china.json与各省文件方便做下钻联动效果是地图类前端项目的轻量级基础工具。 做数据可视化这几年我下载次数最多的素材大概率就是中国及34个省市的地图JSON文件了。无论是给客户做ECharts大屏还是用Python做行政区划数据分析第一步永远卡在同一个问题上地图数据从哪来、拿到的JSON能不能直接用。尤其是每次接到“全国地图下钻到省、市、区”的需求时最怕的就是边界数据不完整、坐标对不上、名称匹配失败。今天这篇就把我攒下来的这套地图JSON文件的获取、解析和落地经验一次性说清楚。全文会从文件结构讲到下载渠道再讲到ECharts注册与坐标转换最后附上我踩过的几个典型坑。希望对正在折腾地图可视化的朋友有点用不管你是纯前端、用Python处理数据还是偶尔做后端接口应该都能找到自己能直接抄走的东西。1. 地图JSON到底是个什么东西地图JSON从本质上说就是用一个JSON文件把一块区域的边界、中心点、层级关系全部描述出来。日常开发里最常见的格式是GeoJSON它有自己固定的数据结构最外层通常是一个FeatureCollection对象里面装着一个个Feature要素每个要素又分成properties和geometry两部分。Properties里放的是属性信息比如行政区编码、名称、中心点坐标geometry里放的才是这条边界的真正远近点坐标数组。很多人第一次打开地图JSON文件最大的感受是“头晕”。因为省一级边界的坐标数组动辄几千上万个点层层嵌套的结构让人根本看不清哪里是开头哪里是结尾。其实你只需要记住一点就好地图JSON最核心的信息就是边界点的坐标集合其他的字段都是给业务逻辑用的辅助信息。1.1 一张地图JSON的内部结构以DataV.GeoAtlas这套最常见的省级数据为例一个省份的JSON文件打开后大概长这样{ type: FeatureCollection, features: [ { type: Feature, properties: { adcode: 110000, name: 北京市, center: [116.405285, 39.904989], centroid: [116.41995, 40.04404], childrenNum: 16, level: province, parent: { adcode: 100000 }, acroutes: [100000] }, geometry: { type: MultiPolygon, coordinates: [...] } } ] }我来拆开说一下里面几个关键字段。adcode是行政区划代码相当于每个行政区的身份证号全国是100000北京市是110000后面下钻到区县就接着用六位编码往上叠加。name是区域名称center和centroid都是中心点但含义不同center是官方公布的地理中心centroid是边界多边形计算出来的几何质心如果做标注点位建议用centroid视觉上更居中。childrenNum表示下一级行政区数量parent表示上一级acroutes表示完整的父级链路数组从全国一直映射到当前层级。geometry里的coordinates是重头戏它存放的是区域边界的点坐标。如果区域是完整的连续地块一般是MultiPolygon类型里面会有多个多边形每个多边形再由多个环组成环由一个个经纬度坐标点组成。经纬度顺序通常是[经度, 纬度]也就是[lon, lat]这一点千万别搞反很多新手直接把反了的坐标丢进地图画出来的形状会歪到天上去。1.2 34个省市文件的数据关系34个省市的地图JSON在数据组织上有一个很有意思的特征它们并不是一堆完全孤立散落的文件而是有明确父子关系的。全国地图文件里只包含34个省级行政区的外层边界不包含市的边界每个省级文件里则包含它下面所有地级市的边界再往下每个市级文件里包含区县边界。这种层级在DataV的数据命名里体现得很清楚adcode为100000的全国文件内部的features数组就是34个省级区域每个元素里都有adcode和name字段方便你按名称或编码去匹配数据。所以在实际使用中全国总图和省图的关系就像母图和子图。你要做成“点击省份下钻到市级”根本不需要一次性加载所有文件只需要先加载全国文件点击某个省后动态加载对应的省级文件再把地图实例重新注册一遍就行。这种按需加载的方式能明显减少首屏加载体积尤其是当你只需要展示几个省份的时候完全没必要拖着一个几十兆的全国完整边界文件。2. 免费下载中国及省市地图JSON的三大渠道地图JSON文件看起来稀松平常但要找到一份边界准确、坐标系正常、带层级关系的靠谱文件并不容易。我这些年用下来真正稳定省心的渠道就三个下面按推荐程度排序讲清楚。2.1 DataV.GeoAtlas最省事的官方渠道第一个要推荐的肯定是阿里云DataV出的GeoAtlas地理数据小工具地址在datav.aliyun.com的学校/地图选择器板块。进去之后你可以直接点击中国地图上的任意省份也可以搜索行政区名称页面会实时展示该区域的地图预览同时提供一个JSON文件下载链接。我实际使用下来发现它还有一个非常好用的规律就是下载地址可以直接拼接。全国地图的JSON接口是这个格式https://geo.datav.aliyun.com/areas_v3/bound/100000_full.json后面加不加_full区别很大。带_full表示返回的是包含下一级全部子区域的完整文件比如100000_full.json返回的就是34个省级边界加全部地级市边界文件更大但信息更全不带_full则只返回当前层级的边界。实际做项目时全国大屏用100000_full.json单独做某个省下钻时再用对应省份的adcode加_full。这套数据里默认用的是GCJ-02加密坐标在国内地图组件上直接渲染是没问题的后面章节我会细说坐标系的坑。用DataV的另一个好处是文件里已经把名称、adcode、中心点这些属性都整理好了基本不需要再做二次清洗拿过来直接registerMap就能用。我做过十多个ECharts大屏项目地形边界部门从来没因为这个渠道掉过链子。2.2 高德地图行政区划接口接实时数据的方案第二个渠道是高德地图的行政区域查询接口。如果项目的数据本身就跑在高德上或者你希望每次请求都拿到最新的边界数据那用高德接口会更合适。需要在高德开放平台申请一个Web服务Key然后请求下面这个地址https://restapi.amap.com/v3/config/district?keywords北京市subdistrict2key你的Keysubdistrict参数控制返回下级层级的深度0表示只返回当前区域2表示返回省、市、区三级。接口返回的是JSON但高德的边界数据藏在districtList下的polyline字段里是一段用分号和逗号分隔的经纬度字符串并不是标准的GeoJSON。你需要自己解析成坐标数组再组装成FeatureCollection。而且高德返回的是GCJ-02加密坐标如果项目底图用的是WGS-84的OpenStreetMap之类的地图解析完之后还得再做一次坐标纠偏工作量就会上来。所以这个渠道更适合后端有一定处理能力的团队前端拿到的应该是后端组装好的GeoJSON而不是直接把高德原始返回丢给前端解析。如果你只是快速做个静态展示没必要选这条路。2.3 其他开源GeoJSON资源与质量对比除了上面两个主力渠道还有几个开源项目也能找到中国地图边界数据。OpenStreetMap上可以通过Overpass API拉取国界和省界但它导出的是WGS-84坐标且中国区域在OSM上的边界完整性要看贡献者的维护情况某些省市边界会比较粗糙导出后还需要大量清理。Github上有不少个人维护的China GeoJSON仓库质量参差不齐有些甚至是用早期数据转的省界和市界会出现重叠、空洞等问题用之前务必打开检查。我整理了一张对比表方便你按项目情况选择渠道坐标系统数据完整性实时性适合场景DataV.GeoAtlasGCJ-02高层级完整低频更新ECharts等国内地图可视化高德APIGCJ-02高但需自行组装GeoJSON实时后端处理、动态数据系统OSM / Github仓库WGS-84为主参差不齐不定需自行清洗不建议生产环境我个人的建议是默认优先用DataV能省掉九成麻烦。只有当项目对坐标系统有特定要求或者需要用WGS-84做跨平台地图分析时再转向OSM渠道并做好坐标转换。3. ECharts地图可视化从JSON文件到可交互大屏拿到地图JSON之后下一步基本就是把它渲染出来。国内做地图大屏最常用的就是ECharts它对GeoJSON的原生支持做得非常好只需要两三个步骤就能把省级地图挂到页面上。3.1 JSON文件加载和注册在ECharts里使用自定义地图数据核心是registerMap方法。如果你用的是Vite或Webpack这类打包工具可以这样写import * as echarts from echarts; import chinaJson from ./assets/china.json; echarts.registerMap(china, chinaJson); const chart echarts.init(document.getElementById(map-container)); chart.setOption({ series: [ { type: map, map: china, roam: true, data: [ { name: 北京市, value: 100 }, { name: 广东省, value: 88 } ] } ] });registerMap的第一个参数是你给这份地图起的注册名想叫什么都可以但保持一致就行。第二个参数就是刚才讲过的GeoJSON对象可以直接import也可以先用fetch请求回来再传入。这里有个容易踩的坑就是打包工具对json模块的解析方式可能不一样比较稳妥的方式是先通过fetch把JSON文本取回来再用JSON.parse转成对象这样在Node环境、浏览器环境里都不容易出岔子。如果是做省份下钻点击事件里需要重新注册地图再setOption。伪代码大概是这样的chart.on(click, (params) { const adcode params.data.adcode || mapAdcodeMap[params.name]; fetch(https://geo.datav.aliyun.com/areas_v3/bound/${adcode}_full.json) .then(res res.json()) .then(json { echarts.registerMap(province, json); chart.setOption({ series: [{ type: map, map: province }] }); }); });这样整体体验就顺了点省份地图无缝下钻到市级用返回按钮或屏幕左上角一个路径导航再做上钻交互手感基本可以对齐很多商业大屏模板了。3.2 数据名称匹配与样式适配做地图可视化最头大的问题之一是名称匹配。ECharts的map数据是根据name字段去匹配GeoJSON里features的properties.name的如果后端返回的名称是“北京”而地图JSON里的名称是“北京市”那么这件数据就不会落到地图上对应区域会变成空白。处理办法是在后端或前端做一层名称归一化我一般会维护一个映射字典把所有常见缩写和全称统一成标准名称function normalizeName(name) { const map { 北京: 北京市, 上海: 上海市, 广东: 广东省, 内蒙古: 内蒙古自治区, 新疆: 新疆维吾尔自治区, 西藏: 西藏自治区 }; return map[name] || name; }规格化之后再传给series.data里的name字段匹配率能达到接近百分之百。名称匹配上之后剩下的就可以自由发挥了比如给区域加渐变颜色、给tooltip加单位后缀、根据value大小做视觉映射这些都可以用ECharts的visualMap组件实现。我通常会把省份名称作为第一列可视化维度因为地图天然就有地理空间感比柱状图带入感强太多。4. 坐标系、数据清洗与文件转换的深坑地图JSON用久了之后你会发现真正的坑往往不在渲染而在数据和坐标。这一节说几个我反复踩、也反复帮别人排查过的问题。4.1 坐标系三兄弟WGS-84、GCJ-02、BD-09国内做地图绕不开的坐标系就是WGS-84、GCJ-02和BD-09。WGS-84是GPS全球定位系统用的国际标准坐标谷歌地球、OpenStreetMap这类平台用的大多是这个GCJ-02是中国国内使用的一种加密坐标也叫火星坐标高德、腾讯地图以及阿里DataV的GeoJSON用的都是它BD-09则是百度地图在GCJ-02基础上再做一层偏移的坐标只用于百度体系。很多困惑都可以归结为一个点不同来源的坐标不能直接混合使用。比如你从高德接口拿到的边界是GCJ-02但从Github上下载的地图JSON可能是WGS-84两者相差大概几百米在大比例尺的区县级地图上非常明显边界会整体偏出底图轮廓。处理的办法就是在数据层面做坐标转换。网上有很多现成的坐标转换库Node端可以用coordtransformPython端可以用几种开源实现核心就是把WGS-84和GCJ-02之间的偏移量算出来再修正回去。我自己的习惯是如果项目所有底图和边界数据都来自国内渠道那统一用GCJ-02如果涉及海外地图或OpenStreetMap底图那就统一转成WGS-84。最忌讳的是一个项目里混用两套坐标那排查起来真的会让人崩溃。4.2 压缩、格式转换与Python处理地图JSON文件通常几兆到十几兆不等如果项目对首屏性能要求高建议做压缩和简化。最常用的工具是mapshaper一条命令就能把GeoJSON转换成简化后的版本npx mapshaper china.json -simplify 10% -o china_simplified.json-simplify 10%表示保留大约10%的点文件体积能减小到原来的十分之一左右。需要注意比例太小会让省界变得非常粗糙出现明显的折线和锯齿一般做省级大屏用20%到30%比较稳妥做全国总览用10%也能接受。如果你习惯用Python处理数据也可以用geopandas来读取和转换GeoJSONimport geopandas as gpd gdf gpd.read_file(china.json) gdf gdf.to_crs(EPSG:4326) gdf.to_file(china_4326.json, driverGeoJSON)geopandas最大的好处是可以方便地对属性字段做过滤和清洗。比如你只需要华东地区的几个省市直接对name字段做条件筛选后导出就行比手工维护文件要省事得多。另外部分老文件是TopoJSON格式它把边界做成了拓扑编码体积更小但结构更复杂ECharts不直接支持需要先用topojson-client或mapshaper转成GeoJSON后再用。4.3 省市名称不一致问题与兜底方案名称不一致这个问题我单独拿出来说是因为它在实际项目中出现的频率实在太高。数据源可能返回“广东省”也可能返回“广东”甚至可能返回“广东省-广州市”这种带路径的格式。如果只是展示全国大屏名称不匹配最多让某个省市空白但如果是做下钻交互名称对不上会导致点击事件拿不到adcode整个下钻链路直接断掉。除了维护映射字典我还会在数据接入层做一个兜底逻辑先用name精确匹配匹配不到就改用adcode匹配再匹配不到就尝试去掉“省、市、区、自治区、特别行政区”等后缀后进行模糊匹配。三层匹配下来基本能覆盖百分之九十九的场景。如果你手头数据源比较多还可以把映射表存成一份独立JSON文件前端和后端共用方便后续增量维护。5. 常见问题速查与排查思路最后整理几个我实际操作中大概率会遇到的问题按“现象、原因、解决”的方式写出来收藏一下下次排查能少走很多弯路。5.1 地图白屏或完全不显示的五个检查项地图白屏是最常见的问题大部分时候都不是代码写错了而是数据本身有问题。我从易到难排一下检查顺序。第一确认JSON文件内容是否为合法JSON很多编辑器会默认给文件加BOM头用JSON.parse解析时会直接报错第二确认数据里是否包含features字段如果下载的是不带FeatureCollection结构的普通JSONECharts没法识别第三确认registerMap的第二个参数是对象而不是字符串一种低级错误是直接传了文件名第四确认地图容器有实际高度ECharts初始化时容器高度为0会导致图表不渲染第五确认坐标系与底图是否匹配如果底图是高德而边界是WGS-84地图虽然能渲染但边界会整体偏移看起来就像显示了一块错误区域。5.2 常见报错信息解读报错信息常见原因解决思路Unexpected token in JSON文件不是纯JSON混入了HTML或注释检查下载链接是否正确去掉BOMCannot read properties of undefinedGeoJSON结构不完整features为空换数据源或重新导出series.map.map can not be foundregisterMap未执行或注册名不一致核对map参数名确认执行顺序Invalid GeoJSON坐标范围异常或因高维数组层级错误无效用geopandas重新校验并精简结构5.3 地图边界偏移问题如何处理如果你的地图渲染出来边界和底图明显错位十有八九是坐标系不一致。用高德底图配GCJ-02数据最稳用OSM底图配WGS-84最稳。如果非要把GCJ-02的数据放到WGS-84底图上就得自己写偏移修正函数。网上有很多现成代码核心思想是先计算GCJ-02相对WGS-84的偏移量再把每个坐标点减去这个偏移。修改完之后建议在一个已知坐标点做验证比如某个城市的市政府位置渲染出来要能正好落在正确位置。我个人在实际操作中的体会是地图JSON这层数据选对来源解决了八成问题剩下两成时间基本都花在名称和层级的匹配逻辑上。DataV的文件虽然好用但也要在项目里做一层数据缓存不要每次刷新页面都从远程拉全量的几百兆内容部署时尽量把这些JSON文件放到自己的静态目录下既保证访问速度也避免依赖外部接口的稳定性。最后再分享一个小技巧在下钻交互里我会额外缓存用户点击过的省份JSON返回上钻时直接从内存或localStorage里读而不是再fetch一次。这样反复切换省市时体验会顺滑很多整个地图感觉才会真正“活”起来。本文还有配套的精品资源点击获取 中国地图JSON获取、解析与ECharts可视化完整指南
简介中国及34个省市地图JSON文件是一套可直接用于前端地理可视化的数据包面向使用D3.js、ECharts绘制全国或省级地图的开发者和数据分析人员。文件以省市拼音命名覆盖全国34个省级行政区读者无需自行拼接或抓取地理边界数据省去坐标边界整理环节可快速实现各级地图的加载与交互配置。整个压缩包共35个JSON文件容量约466KB单文件体积小、结构规整适合按需提取单个省份或整体引入项目。该资源目前已有3640人学习下载常用于大数据可视化大屏、疫情/人口分布图、区域业务看板等场景。包内JSON均按国内常用地理坐标系组织属性字段便于映射到ECharts的map对象也能在D3中配合投影使用同时提供china.json与各省文件方便做下钻联动效果是地图类前端项目的轻量级基础工具。 做数据可视化这几年我下载次数最多的素材大概率就是中国及34个省市的地图JSON文件了。无论是给客户做ECharts大屏还是用Python做行政区划数据分析第一步永远卡在同一个问题上地图数据从哪来、拿到的JSON能不能直接用。尤其是每次接到“全国地图下钻到省、市、区”的需求时最怕的就是边界数据不完整、坐标对不上、名称匹配失败。今天这篇就把我攒下来的这套地图JSON文件的获取、解析和落地经验一次性说清楚。全文会从文件结构讲到下载渠道再讲到ECharts注册与坐标转换最后附上我踩过的几个典型坑。希望对正在折腾地图可视化的朋友有点用不管你是纯前端、用Python处理数据还是偶尔做后端接口应该都能找到自己能直接抄走的东西。1. 地图JSON到底是个什么东西地图JSON从本质上说就是用一个JSON文件把一块区域的边界、中心点、层级关系全部描述出来。日常开发里最常见的格式是GeoJSON它有自己固定的数据结构最外层通常是一个FeatureCollection对象里面装着一个个Feature要素每个要素又分成properties和geometry两部分。Properties里放的是属性信息比如行政区编码、名称、中心点坐标geometry里放的才是这条边界的真正远近点坐标数组。很多人第一次打开地图JSON文件最大的感受是“头晕”。因为省一级边界的坐标数组动辄几千上万个点层层嵌套的结构让人根本看不清哪里是开头哪里是结尾。其实你只需要记住一点就好地图JSON最核心的信息就是边界点的坐标集合其他的字段都是给业务逻辑用的辅助信息。1.1 一张地图JSON的内部结构以DataV.GeoAtlas这套最常见的省级数据为例一个省份的JSON文件打开后大概长这样{ type: FeatureCollection, features: [ { type: Feature, properties: { adcode: 110000, name: 北京市, center: [116.405285, 39.904989], centroid: [116.41995, 40.04404], childrenNum: 16, level: province, parent: { adcode: 100000 }, acroutes: [100000] }, geometry: { type: MultiPolygon, coordinates: [...] } } ] }我来拆开说一下里面几个关键字段。adcode是行政区划代码相当于每个行政区的身份证号全国是100000北京市是110000后面下钻到区县就接着用六位编码往上叠加。name是区域名称center和centroid都是中心点但含义不同center是官方公布的地理中心centroid是边界多边形计算出来的几何质心如果做标注点位建议用centroid视觉上更居中。childrenNum表示下一级行政区数量parent表示上一级acroutes表示完整的父级链路数组从全国一直映射到当前层级。geometry里的coordinates是重头戏它存放的是区域边界的点坐标。如果区域是完整的连续地块一般是MultiPolygon类型里面会有多个多边形每个多边形再由多个环组成环由一个个经纬度坐标点组成。经纬度顺序通常是[经度, 纬度]也就是[lon, lat]这一点千万别搞反很多新手直接把反了的坐标丢进地图画出来的形状会歪到天上去。1.2 34个省市文件的数据关系34个省市的地图JSON在数据组织上有一个很有意思的特征它们并不是一堆完全孤立散落的文件而是有明确父子关系的。全国地图文件里只包含34个省级行政区的外层边界不包含市的边界每个省级文件里则包含它下面所有地级市的边界再往下每个市级文件里包含区县边界。这种层级在DataV的数据命名里体现得很清楚adcode为100000的全国文件内部的features数组就是34个省级区域每个元素里都有adcode和name字段方便你按名称或编码去匹配数据。所以在实际使用中全国总图和省图的关系就像母图和子图。你要做成“点击省份下钻到市级”根本不需要一次性加载所有文件只需要先加载全国文件点击某个省后动态加载对应的省级文件再把地图实例重新注册一遍就行。这种按需加载的方式能明显减少首屏加载体积尤其是当你只需要展示几个省份的时候完全没必要拖着一个几十兆的全国完整边界文件。2. 免费下载中国及省市地图JSON的三大渠道地图JSON文件看起来稀松平常但要找到一份边界准确、坐标系正常、带层级关系的靠谱文件并不容易。我这些年用下来真正稳定省心的渠道就三个下面按推荐程度排序讲清楚。2.1 DataV.GeoAtlas最省事的官方渠道第一个要推荐的肯定是阿里云DataV出的GeoAtlas地理数据小工具地址在datav.aliyun.com的学校/地图选择器板块。进去之后你可以直接点击中国地图上的任意省份也可以搜索行政区名称页面会实时展示该区域的地图预览同时提供一个JSON文件下载链接。我实际使用下来发现它还有一个非常好用的规律就是下载地址可以直接拼接。全国地图的JSON接口是这个格式https://geo.datav.aliyun.com/areas_v3/bound/100000_full.json后面加不加_full区别很大。带_full表示返回的是包含下一级全部子区域的完整文件比如100000_full.json返回的就是34个省级边界加全部地级市边界文件更大但信息更全不带_full则只返回当前层级的边界。实际做项目时全国大屏用100000_full.json单独做某个省下钻时再用对应省份的adcode加_full。这套数据里默认用的是GCJ-02加密坐标在国内地图组件上直接渲染是没问题的后面章节我会细说坐标系的坑。用DataV的另一个好处是文件里已经把名称、adcode、中心点这些属性都整理好了基本不需要再做二次清洗拿过来直接registerMap就能用。我做过十多个ECharts大屏项目地形边界部门从来没因为这个渠道掉过链子。2.2 高德地图行政区划接口接实时数据的方案第二个渠道是高德地图的行政区域查询接口。如果项目的数据本身就跑在高德上或者你希望每次请求都拿到最新的边界数据那用高德接口会更合适。需要在高德开放平台申请一个Web服务Key然后请求下面这个地址https://restapi.amap.com/v3/config/district?keywords北京市subdistrict2key你的Keysubdistrict参数控制返回下级层级的深度0表示只返回当前区域2表示返回省、市、区三级。接口返回的是JSON但高德的边界数据藏在districtList下的polyline字段里是一段用分号和逗号分隔的经纬度字符串并不是标准的GeoJSON。你需要自己解析成坐标数组再组装成FeatureCollection。而且高德返回的是GCJ-02加密坐标如果项目底图用的是WGS-84的OpenStreetMap之类的地图解析完之后还得再做一次坐标纠偏工作量就会上来。所以这个渠道更适合后端有一定处理能力的团队前端拿到的应该是后端组装好的GeoJSON而不是直接把高德原始返回丢给前端解析。如果你只是快速做个静态展示没必要选这条路。2.3 其他开源GeoJSON资源与质量对比除了上面两个主力渠道还有几个开源项目也能找到中国地图边界数据。OpenStreetMap上可以通过Overpass API拉取国界和省界但它导出的是WGS-84坐标且中国区域在OSM上的边界完整性要看贡献者的维护情况某些省市边界会比较粗糙导出后还需要大量清理。Github上有不少个人维护的China GeoJSON仓库质量参差不齐有些甚至是用早期数据转的省界和市界会出现重叠、空洞等问题用之前务必打开检查。我整理了一张对比表方便你按项目情况选择渠道坐标系统数据完整性实时性适合场景DataV.GeoAtlasGCJ-02高层级完整低频更新ECharts等国内地图可视化高德APIGCJ-02高但需自行组装GeoJSON实时后端处理、动态数据系统OSM / Github仓库WGS-84为主参差不齐不定需自行清洗不建议生产环境我个人的建议是默认优先用DataV能省掉九成麻烦。只有当项目对坐标系统有特定要求或者需要用WGS-84做跨平台地图分析时再转向OSM渠道并做好坐标转换。3. ECharts地图可视化从JSON文件到可交互大屏拿到地图JSON之后下一步基本就是把它渲染出来。国内做地图大屏最常用的就是ECharts它对GeoJSON的原生支持做得非常好只需要两三个步骤就能把省级地图挂到页面上。3.1 JSON文件加载和注册在ECharts里使用自定义地图数据核心是registerMap方法。如果你用的是Vite或Webpack这类打包工具可以这样写import * as echarts from echarts; import chinaJson from ./assets/china.json; echarts.registerMap(china, chinaJson); const chart echarts.init(document.getElementById(map-container)); chart.setOption({ series: [ { type: map, map: china, roam: true, data: [ { name: 北京市, value: 100 }, { name: 广东省, value: 88 } ] } ] });registerMap的第一个参数是你给这份地图起的注册名想叫什么都可以但保持一致就行。第二个参数就是刚才讲过的GeoJSON对象可以直接import也可以先用fetch请求回来再传入。这里有个容易踩的坑就是打包工具对json模块的解析方式可能不一样比较稳妥的方式是先通过fetch把JSON文本取回来再用JSON.parse转成对象这样在Node环境、浏览器环境里都不容易出岔子。如果是做省份下钻点击事件里需要重新注册地图再setOption。伪代码大概是这样的chart.on(click, (params) { const adcode params.data.adcode || mapAdcodeMap[params.name]; fetch(https://geo.datav.aliyun.com/areas_v3/bound/${adcode}_full.json) .then(res res.json()) .then(json { echarts.registerMap(province, json); chart.setOption({ series: [{ type: map, map: province }] }); }); });这样整体体验就顺了点省份地图无缝下钻到市级用返回按钮或屏幕左上角一个路径导航再做上钻交互手感基本可以对齐很多商业大屏模板了。3.2 数据名称匹配与样式适配做地图可视化最头大的问题之一是名称匹配。ECharts的map数据是根据name字段去匹配GeoJSON里features的properties.name的如果后端返回的名称是“北京”而地图JSON里的名称是“北京市”那么这件数据就不会落到地图上对应区域会变成空白。处理办法是在后端或前端做一层名称归一化我一般会维护一个映射字典把所有常见缩写和全称统一成标准名称function normalizeName(name) { const map { 北京: 北京市, 上海: 上海市, 广东: 广东省, 内蒙古: 内蒙古自治区, 新疆: 新疆维吾尔自治区, 西藏: 西藏自治区 }; return map[name] || name; }规格化之后再传给series.data里的name字段匹配率能达到接近百分之百。名称匹配上之后剩下的就可以自由发挥了比如给区域加渐变颜色、给tooltip加单位后缀、根据value大小做视觉映射这些都可以用ECharts的visualMap组件实现。我通常会把省份名称作为第一列可视化维度因为地图天然就有地理空间感比柱状图带入感强太多。4. 坐标系、数据清洗与文件转换的深坑地图JSON用久了之后你会发现真正的坑往往不在渲染而在数据和坐标。这一节说几个我反复踩、也反复帮别人排查过的问题。4.1 坐标系三兄弟WGS-84、GCJ-02、BD-09国内做地图绕不开的坐标系就是WGS-84、GCJ-02和BD-09。WGS-84是GPS全球定位系统用的国际标准坐标谷歌地球、OpenStreetMap这类平台用的大多是这个GCJ-02是中国国内使用的一种加密坐标也叫火星坐标高德、腾讯地图以及阿里DataV的GeoJSON用的都是它BD-09则是百度地图在GCJ-02基础上再做一层偏移的坐标只用于百度体系。很多困惑都可以归结为一个点不同来源的坐标不能直接混合使用。比如你从高德接口拿到的边界是GCJ-02但从Github上下载的地图JSON可能是WGS-84两者相差大概几百米在大比例尺的区县级地图上非常明显边界会整体偏出底图轮廓。处理的办法就是在数据层面做坐标转换。网上有很多现成的坐标转换库Node端可以用coordtransformPython端可以用几种开源实现核心就是把WGS-84和GCJ-02之间的偏移量算出来再修正回去。我自己的习惯是如果项目所有底图和边界数据都来自国内渠道那统一用GCJ-02如果涉及海外地图或OpenStreetMap底图那就统一转成WGS-84。最忌讳的是一个项目里混用两套坐标那排查起来真的会让人崩溃。4.2 压缩、格式转换与Python处理地图JSON文件通常几兆到十几兆不等如果项目对首屏性能要求高建议做压缩和简化。最常用的工具是mapshaper一条命令就能把GeoJSON转换成简化后的版本npx mapshaper china.json -simplify 10% -o china_simplified.json-simplify 10%表示保留大约10%的点文件体积能减小到原来的十分之一左右。需要注意比例太小会让省界变得非常粗糙出现明显的折线和锯齿一般做省级大屏用20%到30%比较稳妥做全国总览用10%也能接受。如果你习惯用Python处理数据也可以用geopandas来读取和转换GeoJSONimport geopandas as gpd gdf gpd.read_file(china.json) gdf gdf.to_crs(EPSG:4326) gdf.to_file(china_4326.json, driverGeoJSON)geopandas最大的好处是可以方便地对属性字段做过滤和清洗。比如你只需要华东地区的几个省市直接对name字段做条件筛选后导出就行比手工维护文件要省事得多。另外部分老文件是TopoJSON格式它把边界做成了拓扑编码体积更小但结构更复杂ECharts不直接支持需要先用topojson-client或mapshaper转成GeoJSON后再用。4.3 省市名称不一致问题与兜底方案名称不一致这个问题我单独拿出来说是因为它在实际项目中出现的频率实在太高。数据源可能返回“广东省”也可能返回“广东”甚至可能返回“广东省-广州市”这种带路径的格式。如果只是展示全国大屏名称不匹配最多让某个省市空白但如果是做下钻交互名称对不上会导致点击事件拿不到adcode整个下钻链路直接断掉。除了维护映射字典我还会在数据接入层做一个兜底逻辑先用name精确匹配匹配不到就改用adcode匹配再匹配不到就尝试去掉“省、市、区、自治区、特别行政区”等后缀后进行模糊匹配。三层匹配下来基本能覆盖百分之九十九的场景。如果你手头数据源比较多还可以把映射表存成一份独立JSON文件前端和后端共用方便后续增量维护。5. 常见问题速查与排查思路最后整理几个我实际操作中大概率会遇到的问题按“现象、原因、解决”的方式写出来收藏一下下次排查能少走很多弯路。5.1 地图白屏或完全不显示的五个检查项地图白屏是最常见的问题大部分时候都不是代码写错了而是数据本身有问题。我从易到难排一下检查顺序。第一确认JSON文件内容是否为合法JSON很多编辑器会默认给文件加BOM头用JSON.parse解析时会直接报错第二确认数据里是否包含features字段如果下载的是不带FeatureCollection结构的普通JSONECharts没法识别第三确认registerMap的第二个参数是对象而不是字符串一种低级错误是直接传了文件名第四确认地图容器有实际高度ECharts初始化时容器高度为0会导致图表不渲染第五确认坐标系与底图是否匹配如果底图是高德而边界是WGS-84地图虽然能渲染但边界会整体偏移看起来就像显示了一块错误区域。5.2 常见报错信息解读报错信息常见原因解决思路Unexpected token in JSON文件不是纯JSON混入了HTML或注释检查下载链接是否正确去掉BOMCannot read properties of undefinedGeoJSON结构不完整features为空换数据源或重新导出series.map.map can not be foundregisterMap未执行或注册名不一致核对map参数名确认执行顺序Invalid GeoJSON坐标范围异常或因高维数组层级错误无效用geopandas重新校验并精简结构5.3 地图边界偏移问题如何处理如果你的地图渲染出来边界和底图明显错位十有八九是坐标系不一致。用高德底图配GCJ-02数据最稳用OSM底图配WGS-84最稳。如果非要把GCJ-02的数据放到WGS-84底图上就得自己写偏移修正函数。网上有很多现成代码核心思想是先计算GCJ-02相对WGS-84的偏移量再把每个坐标点减去这个偏移。修改完之后建议在一个已知坐标点做验证比如某个城市的市政府位置渲染出来要能正好落在正确位置。我个人在实际操作中的体会是地图JSON这层数据选对来源解决了八成问题剩下两成时间基本都花在名称和层级的匹配逻辑上。DataV的文件虽然好用但也要在项目里做一层数据缓存不要每次刷新页面都从远程拉全量的几百兆内容部署时尽量把这些JSON文件放到自己的静态目录下既保证访问速度也避免依赖外部接口的稳定性。最后再分享一个小技巧在下钻交互里我会额外缓存用户点击过的省份JSON返回上钻时直接从内存或localStorage里读而不是再fetch一次。这样反复切换省市时体验会顺滑很多整个地图感觉才会真正“活”起来。本文还有配套的精品资源点击获取