1. ECharts 世界地图空白，先分清是哪一种空白
如果你是从 ECharts 3/4 时代过来的，大概率经历过这样一个瞬间：把老项目升到 ECharts 5，页面打开，别的地图好好的，唯独世界地图那块区域一片空白，控制台一行红字，人直接愣住。这个问题我在做ECharts 世界地图大屏的时候踩过不止一次——不是一两次，是升级一次踩一次。核心原因说起来很简单：ECharts 5 已经不再随包提供map/js/world.js这类地图资源脚本了，series里写map: 'world'之前，你必须自己把一份 GeoJSON 通过registerMap注册进去，否则它连"要画什么形状"都不知道。
这篇内容我想聊的就是这个事：一份可以直接拿来注册的 world.js 资源该怎么组织，以及从数据准备到上屏显示这一整条链路上，那些文档里不会写的坑。适合两类人看：一类是刚接手大屏项目、看见Map world not exists报错不知道从哪下手的前端；另一类是已经能画出地图、但数据老是点不亮、颜色上不去的同学。你会看到数据从哪来、怎么做体检、怎么包装成模块、怎么注册、数据怎么对名字，以及出问题时按什么顺序排查最省时间。全文不聊虚的，都是能直接抄进项目的代码和判断逻辑。
先说清楚一件事，"空白"这个词底下其实是四种完全不同的故障，你得分清了再动手，不然改半天改不到点上。
第一种，容器是干净的空白，控制台有报错。通常长这样：Map world not exists. The GeoJSON of the map must be provided.，或者registerMap相关的 undefined 报错。这种是注册问题，也是最常见的，好治。
第二种，容器空白，控制台一声不吭。没有报错，但就是什么都没有。这时候九成不是地图的问题，而是容器的问题——父级display: none、height: 0、flex 布局里没给flex: 1、或者初始化时 DOM 还没挂载完，echarts.init拿到的宽高是 0，画布根本没尺寸，画了你也看不见。
第三种，地图出来了，但所有区域一个颜色，数据像没生效。这种是最气人的，因为你以为成了，其实只是图形渲染成功、数据绑定失败。根因基本都是series.data[].name和 GeoJSON 里properties.name对不上，或者数值类型不对。
第四种，地图显示出来了，但形状很怪：要么一块区域被拉成横贯全图的细长条，要么整个图形挤成一个小点，要么上下颠倒。这分别对应跨经线的多边形、坐标单位不是经纬度、坐标系顺序写反。
排查的第一原则：先看控制台，再看容器尺寸，最后才去怀疑数据。顺序反了，你会在最不该花时间的地方耗掉一整天。
我见过太多人一上来就怀疑世界地图数据有问题，换数据源换了三四份，最后发现是父容器height: 100%但爷爷容器没高度。所以下面每一节，我都会把"怎么判断自己处在哪种情况"写进去。
2. 一份可直接注册的 world.js 资源：从哪来、怎么包、怎么验
2.1 三种世界地图数据来源的取舍
要让 ECharts 画出世界地图，本质只需要一个东西：符合 GeoJSON 规范的 FeatureCollection。ECharts 不关心你的数据从哪来，只关心结构对不对。所以选数据源的时候，真正要比的不是"哪个更权威"，而是"哪个更省事、更适配你的业务"。
我实际用过的路线有三条。
第一条，从旧版 ECharts 包里把world.json抠出来用。老版本的发行包里有一份纯数据文件，是标准 GeoJSON，registerMap('world', 这份JSON)直接能跑，不需要做任何转换。优点是零改造、结构一定兼容；缺点是它带的是英文国名，你要展示中文就得自己做映射，而且这份数据比较旧，一些要素的边界和名称是多年前的。适合"我就想让地图显示出来，别的不讲究"的场景。
第二条，用 npm 上现成的世界地图 GeoJSON 包。这类包通常分成"英文名版"和"中文名版"，中文版直接省掉了你维护 nameMap 的功夫。挑的时候我一般看三点：最近半年有没有更新、properties里是否带中文名字段、是否包含南极洲这个大块。第三点很重要，后面会讲。缺点是质量参差，有的包里geometry.type混着Polygon和MultiPolygon，有的坐标精度过高导致文件几百 KB。
第三条，自己从公开地理数据集裁剪生成。可控性最高，可以按需删掉不想展示的要素、简化坐标精度、统一名称字段。代价是要写构建脚本，而且第一次跑通要花点时间。如果你的项目对地图样式、要素范围有强要求，这条最值得投入。
我的取舍习惯是：做一次性的展示页，走第一条；做长期维护的业务系统，走第二条；做需要严格控制要素和体积的大屏，走第三条。判断标准就一句话——这份地图数据你以后还要不要改。
不管走哪条，都有一个共同前提：别去直接引老版本的world.js脚本文件。那个文件是 UMD 格式的，加载时会自动去全局找echarts然后自己调registerMap。在 ECharts 5 的模块化环境里，全局echarts可能压根不存在，你会得到一堆Cannot read property 'registerMap' of undefined。要引就引.json数据，注册这一步自己写，主动权在自己手里。
2.2 把 GeoJSON 包装成可复用的 world.js 模块
拿到数据之后，我建议你不要在每个页面里散着写echarts.registerMap，而是包一个独立模块。原因有三个：一是注册是幂等的但重复调用没意义，二是注册时机（什么时候加载数据）在项目里往往是需要统一控制的，三是出问题时排查入口只有一个。
最基础的版本长这样：
// src/map/world.js import * as echarts from 'echarts'; import worldGeo from './world.geo.json'; const MAP_NAME = 'world'; export default function ensureWorldMap() { // 5.x 提供 getMap，用来判断同名地图是否已经注册过 if (typeof echarts.getMap === 'function' && echarts.getMap(MAP_NAME)) { return MAP_NAME; } echarts.registerMap(MAP_NAME, worldGeo); return MAP_NAME; }这段代码里有两个设计点值得说一下。
第一，为什么用getMap判断而不是直接注册。registerMap重复调用本身不一定会报错，但它会用新数据覆盖旧数据，而且每次都会重新解析一遍 GeoJSON、重建内部索引。在热更新频繁的开发环境里，这个动作可能一秒执行好几次，你会在 Performance 面板上看到明显的长任务。加一层判断，成本几乎为零。
第二，为什么要return MAP_NAME。因为调用方经常需要把这个名字传给series.map或者geo.map，返回出去能避免"模块里改了个名字，页面里忘了同步"这种低级错误。
如果你的世界地图只在一个页面用，或者不希望它进主包，用动态导入更合适：
// src/map/world.js import * as echarts from 'echarts'; const MAP_NAME = 'world'; let fetching = null; export async function ensureWorldMap() { if (typeof echarts.getMap === 'function' && echarts.getMap(MAP_NAME)) { return MAP_NAME; } // 用 pending 变量合并并发请求，避免同时触发多次 import if (!fetching) { fetching = import('./world.geo.json').then((mod) => { echarts.registerMap(MAP_NAME, mod.default); fetching = null; return MAP_NAME; }); } return fetching; }这里加fetching这个中间变量是有原因的。大屏项目里经常出现"两个组件同时挂载、同时请求地图数据"的情况，如果不管并发，你会看到两份完全相同的地图数据被解析两次，白白多花几十毫秒。用一个 promise 把并发合并掉，是成本最低的优化。
注意：动态导入 JSON 需要构建工具支持。Webpack 5、Vite 默认都支持 JSON 模块；TypeScript 项目要在
tsconfig.json里打开resolveJsonModule，否则类型检查会先挂掉。
还有一个容易被忽略的点：注册用的echarts实例，和渲染用的必须是同一个。如果你在项目里做了按需引入，用的是import * as echarts from 'echarts/core'，那registerMap也必须来自echarts/core。混用echarts全量包和echarts/core，会出现"注册成功了但图表说地图不存在"的诡异现象，因为那是两个不同的内部注册表。
2.3 入库前先体检：一份 GeoJSON 校验脚本
我在项目里有个固定习惯：任何外部拿到的 GeoJSON，进仓库之前先跑一遍校验。这不是洁癖，是因为地图数据的错误极其隐蔽——它不会在加载时抛异常，只会在渲染时给你一个说不清道不明的结果。
校验要查的东西其实就四样：顶层结构、几何类型、坐标顺序、坐标范围。写成一个 Node 脚本，几十行就够：
// scripts/check-geo.js const fs = require('fs'); const file = process.argv[2] || './world.geo.json'; const geo = JSON.parse(fs.readFileSync(file, 'utf8')); if (geo.type !== 'FeatureCollection') { throw new Error(`顶层 type 必须是 FeatureCollection，当前是 ${geo.type}`); } if (!Array.isArray(geo.features) || geo.features.length === 0) { throw new Error('features 为空'); } const problems = []; const names = new Set(); function walkCoords(coords, name, depth) { if (typeof coords[0] === 'number') { const [lng, lat] = coords; if (Math.abs(lng) > 180.01) problems.push(`${name}: 经度越界 ${lng}`); if (Math.abs(lat) > 90.01) problems.push(`${name}: 纬度越界 ${lat}`); return; } coords.forEach((c) => walkCoords(c, name, depth + 1)); } geo.features.forEach((f) => { const name = f.properties && f.properties.name; if (!name) problems.push(`存在没有 properties.name 的要素`); if (names.has(name)) problems.push(`名称重复: ${name}`); names.add(name); const type = f.geometry && f.geometry.type; if (type !== 'Polygon' && type !== 'MultiPolygon') { problems.push(`${name}: 几何类型不支持 ${type}`); return; } walkCoords(f.geometry.coordinates, name, 0); }); console.log(`要素数量: ${geo.features.length}`); console.log(`要素名称示例: ${[...names].slice(0, 5).join(', ')}`); if (problems.length) { console.error(`发现 ${problems.length} 处问题:`); problems.slice(0, 20).forEach((p) => console.error(' - ' + p)); process.exit(1); } console.log('校验通过');这段脚本能挡掉绝大多数"无效数据"，其中最关键的是坐标范围检查。如果某份数据里出现12000000这种量级的数字，说明它用的是投影坐标（米）而不是经纬度，ECharts 拿到之后会把整张地图压缩到画面左上角一个像素点里，你以为地图没显示，其实它显示了你没看见。这个判断靠肉眼是看不出来的，必须靠脚本。
另外两个容易忽视的检查项：名称重复和缺少 name。GeoJSON 里properties.name是 ECharts 用来做数据绑定的唯一键，一旦有两个要素同名，ECharts 只会认其中一个，你会莫名其妙发现某个区域永远点不亮。而缺 name 的要素，会完整地画出来，但永远吃不到数据，也很难发现。
校验通过之后再入库，是我这些年省下最多时间的一个习惯。
3. 注册与配置的完整实操
3.1 最小可运行示例：不依赖构建工具的写法
有时候你就是想快速验证一下数据行不行，不想起一个完整的工程。那就用最原始的方式：一个 HTML 加一个本地 echarts 脚本，数据用fetch拉。
<div id="map" style="width: 100%; height: 600px;"></div> <script src="./echarts.min.js"></script> <script> const dom = document.getElementById('map'); fetch('./world.geo.json') .then((res) => { // fetch 404 时不会 reject，拿到的是错误页 HTML，这里必须挡一下 if (!res.ok) throw new Error('地图数据加载失败: ' + res.status); return res.json(); }) .then((geo) => { echarts.registerMap('world', geo); const chart = echarts.init(dom); chart.setOption({ backgroundColor: '#0b1220', geo: { map: 'world', roam: true, itemStyle: { areaColor: '#1c2b45', borderColor: '#31456b', borderWidth: 0.6 }, emphasis: { itemStyle: { areaColor: '#2b6cb0' }, label: { show: true, color: '#ffffff', fontSize: 11 } } } }); }) .catch((err) => console.error(err)); </script>这段代码虽然短，但里面有三个点是我特意加的，都是踩过坑之后补的。
第一，res.ok的判断。fetch有一个反直觉的行为：HTTP 404 或 500 不会让 promise reject，它会正常返回响应对象。如果路径写错了，你res.json()拿到的是一段 HTML，解析时报一个莫名其妙的Unexpected token '<'。加上这行判断，报错信息立刻变得有指向性。
第二，registerMap放在setOption之前。严格来说 ECharts 在setOption时才会去查地图，所以两者顺序不是强制的。但我习惯先注册后渲染，因为一旦注册失败，你能立刻定位到是哪一步，而不是在setOption里对着"地图不存在"发呆。
第三，geo组件的写法。这里我用了geo而不是series.map，因为后面要叠加散点和飞线的时候，geo是唯一能作为公共坐标系的容器。这一点在第 4 节会详细讲。
跑通这一段，你就有了一个可以复用的验证环境。以后拿到任何一份新地图数据，先在这里跑一下，能省掉大量"到底是我代码有问题还是数据有问题"的纠结。
3.2 工程化写法：Vue / React 里怎么放才不出事
真实项目里，世界地图大概率是嵌在一个组件里的。这里我以 Vue 3 的组合式 API 为例，因为它的响应式系统和 ECharts 之间有一个非常经典的冲突，值得单独拎出来说。
<template> <div ref="containerRef" class="map-container"></div> </template> <script setup> import { onMounted, onBeforeUnmount, ref, shallowRef } from 'vue'; import * as echarts from 'echarts'; import { ensureWorldMap } from '@/map/world'; const containerRef = ref(null); // 关键点：图表实例用 shallowRef，不要用 ref const chartRef = shallowRef(null); let resizeObserver = null; onMounted(async () => { const mapName = await ensureWorldMap(); const chart = echarts.init(containerRef.value); chartRef.value = chart; chart.setOption({ tooltip: { trigger: 'item', formatter: (p) => `${p.name}<br/>数值：${p.value ?? '无'}` }, geo: { map: mapName, roam: true, zoom: 1.2, layoutCenter: ['50%', '52%'], layoutSize: '108%' } }); // 用 ResizeObserver 而不是 window.resize resizeObserver = new ResizeObserver(() => chart.resize()); resizeObserver.observe(containerRef.value); }); onBeforeUnmount(() => { resizeObserver && resizeObserver.disconnect(); chartRef.value && chartRef.value.dispose(); chartRef.value = null; }); </script> <style scoped> .map-container { width: 100%; height: 100%; min-height: 480px; } </style>这段代码里有四个决策，每一个我都吃过教训。
图表实例用shallowRef。ECharts 实例内部持有大量 DOM 引用和内部对象，如果放进ref()里，Vue 会递归地把它变成响应式代理。结果就是图表内部每一次数据读写都要走一层 Proxy 拦截，滚动、缩放都会明显卡顿，严重的时候直接堆栈溢出。shallowRef只代理最外层，内部对象保持原样，这是标准做法。
同理，GeoJSON 数据本身千万不要放进ref或reactive。世界地图有两百多个要素，每个要素的坐标数组里可能有几千个点，全部被 Proxy 包一遍，光是初始化就能卡住主线程好几秒。如果确实需要放在组件状态里，用markRaw()或者shallowRef()包一层。
用ResizeObserver而不是监听window.resize。大屏项目里容器的尺寸变化来源太多了：侧边栏折叠、标签页切换、父级 Grid 布局变化，这些都不会触发window.resize。用ResizeObserver监听容器本身，才是真的"容器变了就重绘"。记得在卸载时disconnect()，否则组件销毁了观察器还在，典型的内存泄漏。
dispose()必须调。ECharts 实例不会自动回收，尤其在路由切换频繁的后台系统里，不 dispose 就会一路累积，用久了页面越来越卡。
React 那边逻辑是一样的，只是把生命周期换成useEffect，实例用useRef存，ResizeObserver放在 cleanup 里。核心的三个点——实例别进响应式、观察器要断开、卸载要销毁——是通用的。
3.3 中文名映射、南极洲与"拉丝"的地图边界
地图能画出来了，接下来是"好不好看"和"显不显示得对"的问题。这一小节聊三个最常见的形状问题。
第一个，中文名映射。世界地图的 GeoJSON 里，properties.name通常是英文原名，而你的业务数据大概率是中文。这时候有两个方案：一是换一份自带中文字段的数据源，二是在配置里用nameMap做一层映射。
nameMap的写法是这样（下面用占位名演示，实际项目中请对着你数据里的properties.name一一替换真实值）：
const nameMap = { 'CountryA': '甲国', 'CountryB': '乙国', 'CountryC': '丙国' }; geo: { map: 'world', nameMap: nameMap }这里有一个非常容易踩的坑：映射之后，series.data[].name到底该写原名还是映射名？不同版本的 ECharts 在这个行为上有细微差别，稳妥的做法是——数据侧统一用映射后的名字，让nameMap只承担一次转换。也就是所有业务数据先过一遍映射表，转成中文再喂给 ECharts，这样你就完全不用关心内部匹配逻辑。我在几个项目里都这么做，从没出过匹配问题。
顺带一提，nameMap还有一个副作用：开启之后 tooltip 和 label 显示的都是映射后的名字，这对中文用户是好事，但如果你同时想保留英文名做搜索，就需要在数据里额外带一个字段。
第二个，南极洲。世界地图数据里一般会包含南极洲这一大块，它在地图底部占掉大概五分之一的纵向空间，而且是又长又扁的一条。结果就是：你明明想让欧亚大陆占满屏幕，ECharts 为了把南极洲塞进来，会把整个地图缩得很小，上半部分留出一大片空白。
解决办法很直接——过滤掉它：
const filteredGeo = { ...geo, features: geo.features.filter( (f) => f.properties.name !== 'Antarctica' ) }; echarts.registerMap('world', filteredGeo);过滤之后地图的包围盒会自动重算，可视区域利用率立刻提升。这个操作对"数据合规"也是加分项，南极洲在业务大屏上通常没有数据，留着纯占地方。
提示：过滤要素会改变地图的包围盒，如果你在配置里写死了
zoom和center的具体数值，过滤后需要重新调一遍。用layoutCenter+layoutSize这种相对单位会更稳。
第三个，横贯全图的细长条，俗称"拉丝"。这个现象的成因是：某些区域横跨 ±180 经线，在一个多边形里同时存在 -179 和 +179 这样的经度值。ECharts 画多边形时是按顺序连点的，从 -179 连到 +179，中间就画出了一条横穿整个地图的长条。
处理思路有两条。一是在数据层面解决，找一份已经把这些区域切分成东西两块的 GeoJSON，这是最干净的方案，很多精简版世界地图数据就是为此做过处理的。二是在注册时用specialAreas做区域偏移，格式大致如下：
echarts.registerMap('world', { geoJSON: geo, specialAreas: { // 键名必须与 GeoJSON 里 properties.name 完全一致 'SomeRegion': { left: -180, top: 40, width: 180, height: 60 } } });specialAreas里的left/top/width/height是"经纬度坐标系下的矩形"，含义是把对应要素整体搬到你指定的这个矩形范围内，原位置就不再绘制了。这套参数没有通用值，需要对着你的数据一点点试。它更适合"某块区域单独拿出来放大展示"的场景，而不是通用的拉丝修复。
我个人的实际选择是：能用切好的数据就用数据，实在找不到再考虑specialAreas。因为前者是一次性的工作量，后者是每次调样式都要重新对齐的工作量。很多大屏项目干脆就不管那根线，反正深色背景下不显眼——这也不算错，看你老板的要求。
4. 地图画出来了，数据却对不上
4.1 name 匹配：世界地图上最容易翻车的 5 分钟
地图能显示，说明注册成功了。数据不显示，八成是 name 对不上。这个环节我总结了一句话：ECharts 认的是字符串完全相等，不是"看起来像"。
差一个空格、大小写不同、多了个括号、用了连字符还是空格、有没有the前缀——任何一个差异都会导致匹配失败。更麻烦的是，失败的表现非常温和：地图正常渲染，只是那个区域保持默认颜色，没有任何报错。
所以我写了一个对账脚本，每次接新数据源都跑一遍：
// 把对不上的名字全找出来 const geo = require('./world.geo.json'); const data = require('./my-data.json'); const geoNameSet = new Set( geo.features.map((f) => f.properties.name) ); const missing = data .map((d) => d.name) .filter((n) => !geoNameSet.has(n)); if (missing.length) { console.warn(`有 ${missing.length} 条数据在地图上找不到对应要素：`); console.warn(missing.slice(0, 30)); } else { console.log('全部匹配'); }这个脚本的价值在于，它把"猜测"变成了"清单"。你不需要一个个点开地图去看哪个区域没颜色，直接把差集打出来，对着改就完了。
再补两个实战经验。一是名称里的空格问题，有的数据源写成"United States"，有的写成"UnitedStates"，还有的会带不可见字符。用差集脚本打印的时候，建议用JSON.stringify包一下，能看出前后是否有隐藏的空格。二是同一个地图数据里，要素名可能和你的业务口径不一致，比如你的业务库里用的是简称，数据集里是完整名称。这时候老老实实维护一张映射表，别指望自动化匹配。
另外还有一个反向检查也很有用：地图上有、数据里没有的要素，可以用于判断"是不是漏了几个地区的数据"。这个检查在业务上往往更有意义，因为漏数据比多数据更危险。
4.2 visualMap 与数值类型
名字都对上了，地图还是不染色？那就是数值的问题。ECharts 的visualMap是按数值大小做颜色映射的，它对数据类型是有要求的。
最常见的错误是数值存成了字符串。比如后端返回"12"而不是12。在 JavaScript 里，visualMap内部做比较时，字符串会走隐式转换，大多数情况下"看起来能用"，但在分档（pieces）模式下就会出现诡异的结果——明明设了 0 到 10 一档，"5"就是不分进去。
我的处理方式是：在数据进入 ECharts 之前，强制转一次数字：
const safeData = rawData.map((d) => ({ name: d.name, value: Number.isFinite(Number(d.value)) ? Number(d.value) : null }));这里用Number.isFinite而不是isNaN，是因为Number(null)是 0、Number('')也是 0，用isNaN判断会把空值当成 0 处理掉。地图上"没有数据"和"数据是 0"是完全不同的语义——前者应该不染色，后者应该染成最小值颜色。用isFinite把空值转成null，ECharts 就会跳过这个要素，保持默认样式。
visualMap本身的配置也有讲究：
visualMap: { type: 'continuous', min: 0, max: 100, inRange: { color: ['#12263f', '#1f4e79', '#2b6cb0', '#63b3ed'] }, left: 24, bottom: 24, textStyle: { color: '#cbd5e1' }, calculable: false }几个细节：min和max一定要手写，不要让 ECharts 从数据里自动推。因为自动推的时候，如果最大值的那个要素刚好被过滤掉了，色阶就会全部错位。色阶数组建议 4 到 5 段，太少分不出层次，太多在深色背景上会糊成一片。calculable: false是因为世界地图的图例本来就没多少交互价值，开着反而占地方。
4.3 散点、飞线与 map/geo 二选一
世界地图上最常见的需求是叠加点：某个地区的数值、某条线路的流向。这里有一个结构性选择必须先定下来——你到底用geo组件还是用series.map。
这两种写法在配置上长得像，但能力完全不同：
| 对比项 | series.type = 'map' | geo组件 |
|---|---|---|
| 单独渲染地图 | 支持 | 支持 |
| 叠加散点/飞线 | 不支持（散点无法绑定到它） | 支持，作为公共坐标系 |
| series 绑定数据 | 直接写在 series.data | 需要额外的 map series 或只用 geo |
| 支持多图层 | 一般 | 强，可叠加多种 series |
| 适用场景 | 纯地区着色 | 着色 + 打点 + 飞线 |
结论很清楚：只要你要往地图上叠东西，就用geo。用geo打点的写法是这样：
series: [ { type: 'effectScatter', coordinateSystem: 'geo', data: [ { name: 'PointA', value: [116.4, 39.9, 88] } ], symbolSize: (val) => Math.max(6, Math.sqrt(val[2]) * 2), rippleEffect: { scale: 3, brushType: 'stroke' } }, { type: 'lines', coordinateSystem: 'geo', data: [ { coords: [[116.4, 39.9], [2.35, 48.85]] } ], lineStyle: { color: '#63b3ed', width: 1, opacity: 0.6, curveness: 0.2 } } ]三个注意点。一是coordinateSystem必须显式写'geo'，默认是'cartesian2d'，不写的话你的经纬度会被当成笛卡尔坐标，点会跑到图表外面去。二是值的顺序是[经度, 纬度]，和 GeoJSON 保持一致，写反了点位会跑到海里，而且因为经度范围是 -180~180、纬度是 -90~90，有时候反过来的点还在合法范围内，导致你很难发现错了。三是同时写了geo和series.map会出现两层地图叠在一起，边线重影，颜色互相盖，看起来像渲染 bug。二选一，别贪心。
5. 排查顺序与生产环境避坑
5.1 按顺序走的排查表
我把这些年的排查经验压缩成一张表，按从上到下的顺序走，基本不会绕路：
| 顺序 | 现象 | 优先检查 | 判断方法 |
|---|---|---|---|
| 1 | 控制台有Map xxx not exists | 是否调用了registerMap，注册名与map值是否一致 | 打印注册名，核对大小写 |
| 2 | 无报错，容器纯空白 | 容器宽高是否为 0 | containerRef.value.offsetWidth打印出来看 |
| 3 | 数据加载报Unexpected token '<' | 数据路径 404，拿到的是 HTML | 检查res.ok和网络面板 |
| 4 | 地图挤在角落成一个小点 | 坐标不是经纬度（投影坐标） | 用校验脚本查坐标范围 |
| 5 | 地图上下颠倒或左右镜像 | 坐标顺序写反成[lat, lng] | 抽查几个知名城市的坐标 |
| 6 | 有地图无颜色 | series.data[].name与要素名不匹配 | 跑差集脚本 |
| 7 | 部分区域有颜色部分没有 | 名称空格、大小写、别名不一致 | 打印JSON.stringify(name) |
| 8 | 颜色全是最小值 | 数值是字符串或含 NaN | 强制Number()并过滤 |
| 9 | 一条横线贯穿地图 | 跨 ±180 经线的多边形 | 换切分过的数据 |
| 10 | 地图闪一下就没了 | 热更新重复注册或实例被销毁 | 检查getMap判断和dispose |
这张表我建议直接存进项目的 README。它的价值不在于多全，而在于顺序——先查报错，再查容器，再查数据，最后查样式。很多人一上来就查数据，结果在一个 CSS 高度问题上耗了两小时。
5.2 HMR、响应式代理、体积与性能
到了生产环境，问题会换一副面孔。下面这几个是我在真实项目里被咬过的。
热更新导致的重复注册。开发环境改一行代码，模块重新执行，registerMap又跑一遍。虽然第二次之后地图数据一样，但每次注册都会重建内部索引结构，改十次代码之后你会发现页面明显变卡。解决办法就是前面写的getMap判断。如果你用的 ECharts 版本没有getMap，用模块级变量兜底：
let registered = false; export function ensureWorldMap() { if (registered) return 'world'; echarts.registerMap('world', worldGeo); registered = true; return 'world'; }响应式代理带来的性能悬崖。前面提过一次，这里再强调：把 GeoJSON 放进ref()、reactive()，或者放进 Vuex/Pinia 的 state，都会被深度代理。世界地图的数据在深拷贝和代理之后，初始化时间可能从 200ms 涨到 3 秒以上。正确的做法是markRaw(geo)或干脆放在模块作用域的普通变量里。
包体积。一份精简的世界地图 GeoJSON 大概 200 到 400KB，gzip 之后 60 到 100KB。这个体积不算离谱，但也不该塞进首屏主包。我的做法是把它拆成独立 chunk，在"图表容器进入视口"或者"用户切到地图 Tab"的时候再import()。配合一个 loading 状态，体验上完全无感。
渲染性能。世界地图有两百多个要素，如果默认把label.show打开，每一帧都要排两百多个文字，缩放的时候直接掉帧。正确姿势是label.show: false，只在emphasis里开。同理，roam: true缩放的时候如果同时开着effectScatter的涟漪动画，会明显卡，可以给涟漪加个节流，或者缩小时临时隐藏散点。
移动端的手势冲突。roam: true开启后，在地图上滑动会触发 ECharts 的缩放平移，但同时也可能触发页面滚动，体验很怪。可以在触摸开始时临时把父容器设成overflow: hidden，或者干脆移动端关掉roam，只保留点击。
5.3 我现在固定下来的几个默认设置
踩了这么多坑之后，我在所有用到世界地图的项目里都会先摆一组默认配置，后面再按需改。这套东西不一定最适合你的场景，但它能保证"第一眼不出错"。
第一，数据源固定用一份带中文字段的精简版，单独存成一个 JSON 文件放进仓库，不依赖任何外部包。理由很实际：外部包哪天更新了、改名了、删了，你的线上就是一片空白，而这份数据你其实一年也改不了两次。
第二，注册逻辑统一收口到ensureWorldMap()，页面里只 import 这个函数，不直接碰registerMap。这样哪天要换数据源、要过滤要素、要加specialAreas，只改一个文件。
第三，数据进 ECharts 之前必过一道清洗，名字转成地图里的名字、值转成数字、空值转null。这一步看似多余，但它把"为什么这个区域不亮"的排查成本从半小时降到了零。
第四，地图配置里label默认关闭，itemStyle.borderWidth不超过 1。世界地图的要素太多，边框一粗，整个画面立刻糊成一团，尤其深色背景配浅色边框，密集区域会连成一片白。
第五，容器给一个min-height。这一条听起来最不像技术建议，但它救过我两次——一次是 flex 布局里父级高度塌陷，一次是 Tab 切换时组件还没渲染就初始化了。给个兜底高度，最差情况下你能看见地图变形，而不是看着一片空白怀疑人生。
