企业官网建设流程全解析

前阵子接到一个业务看板的需求：销售额指标得先看全国，点某个省份看省内的市，再点某个市看县区，而且还要能一级一级返回来。技术栈是 Vue 3 + ECharts。说白了，我要做的就是一个完整的“省 → 市 → 县”三级地图下钻和上钻组件：省级视图下点击一个省份，下钻到该省的市级地图；市级视图下点击一个城市，下钻到该市的县级地图；同时能通过返回按钮一层层上钻回全国。

这篇文章我把这个实现过程完整梳理一遍，从方案选型、地图数据准备、组件设计到实际踩坑，尽量讲具体。涉及的关键点包括：GeoJSON 的加载与注册、下钻和上钻的状态管理、ECharts 的 map 配置、行政编码如何取名、以及异步请求竞态这些容易翻车的细节。想把地图下钻做成一个可靠组件的开发者，这篇应该能帮你省不少事。

1. 整体设计：先想清楚再写代码

1.1 为什么是 ECharts

先说结论：如果需求只是“行政区域 + 数值填充 + 点击下钻”，在 Vue 项目里用 ECharts 地图是最省事的一条路。

原因有三条。第一，ECharts 本身提供 map 系列，渲染 GeoJSON 的成本很低，一个registerMap注册底图，一个setOption填充数据和样式就能出图。第二，点击事件、tooltip、滚轮缩放、拖拽这些交互都是内置的，不需要自己处理 Canvas 命中和坐标系换算。第三，如果一个项目里本身就有各种图表，ECharts 的视觉风格和包体管理都很统一。

有些地图库在复杂地理场景下更强，但在我这个业务场景里反而有点大材小用。我简单对比过三个方向：

如果将来需求变成了“展示某个路线的轨迹”“在地图上打点并做距离计算”，那确实得换专业地图库；但如果只是数据看板式的区域下钻，ECharts 完全够用。

1.2 交互模型：下钻靠点击，上钻靠按钮

我把交互定成一套非常直观的模型：

• 第一次打开，渲染全国地图，显示各个省份。
• 点击某个省份的高亮区域，进入该省的市级地图。
• 在市级地图上点击某个城市，进入该市的县区地图。
• 地图右上角或左上角放置“返回上一级”按钮，一层层回退。

为什么上钻不放在地图空白区域点击？因为公共地图区域外的空白点击太容易误触。用户本想在空白处缩放地图，结果误触返回到上一级，体验会非常差。用按钮和面包屑，交互意图明确得多。

我在组件里通常会同时放两块东西：返回按钮和面包屑导航。返回按钮负责一级一级回退，面包屑则显示当前在“全国 / 省份A / 城市B / 县区C”中的哪个位置。面包屑本身也可以做成可点击跳转，但前期没必要一次做太复杂，先保证基本的下钻和上钻稳定。

1.3 状态与数据流：GeoJSON 和业务数据分开管

做地图组件前要把两条数据线分清楚：

• 地图底图数据：也就是 GeoJSON，描述区域形状和行政编码，属于展示层数据，变化频率极低。
• 业务指标数据：比如某个区域对对应的销售额、用户数，属于业务层，会动态变化。

这两类数据必须解耦。底图负责画轮廓、提供地域的 name 和 adcode，业务数据负责把数值对应到具体区域上。渲染时再把两条线合并成 ECharts 的 series data。

组件内部最核心的状态有三个：

当前层级 level：0 表示全国，1 表示省级，2 表示市级 下钻栈 mapStack：记录“从哪来”的历史 当前地图注册名 currentMapName

有同学可能会问，直接用 level 变量做返回行不行？不行。比如用户在省级点进 A 市，再在 A 市下点进 B 县，然后一路返回到省级，这时候如果只靠 level 数字，根本不知道应该重新加载哪张省级地图。用栈把每次进入下钻前的上一级地图完整保存下来，上钻就是从栈里把上一级地图恢复出来，无脑且可靠。

2. 数据准备与关键配置解析

2.1 GeoJSON 数据从哪里来

地图数据是整个组件的基石，这里必须说清楚。

最实用的建议：寻找一个稳定的开源 GeoJSON 数据仓库，下载三类文件：

• 全国地图 GeoJSON，包含所有省级区域的边界。
• 每个省份的市级 GeoJSON，包含该省内所有城市的边界。
• 每个城市的县级 GeoJSON，包含该市内所有县区的边界。

文件命名我强烈建议按行政编码来组织，例如：

geo-json/china.json geo-json/{省级adcode}.json geo-json/{市级adcode}.json

用这个约定，下钻时只需要拿到点击区域的 adcode，就能拼出下一级地图的路径，不需要靠中文名匹配。这是我做了几版之后最省心的方案。

关于行政边界数据，技术上我没有任何资格在地图渲染层去改动边界，所以一直坚持直接用数据源发布的原始边界。如果业务方对边界有特殊审核要求，应该在数据引入阶段由业务方确认使用哪个版本的底图数据，而不是前端自己悄悄改坐标。地图数据本身也是可能存在更新滞后问题的，上线之前必须检查时效性。

如果项目部署在内网环境，我建议把所有 GeoJSON 拷贝到public/geo-json目录或打成静态资源，加载走相对路径。一方面避免跨域限制，另一方面避免运行环境访问不到外部资源。外部数据源虽然用起来方便，但生产环境不可控，这种依赖能省则省。

2.2 地区命名与行政编码

这是下钻组件最容易出问题的地方：名称对不上。

行政编码通常是 6 位数字，比如省一级到省下辖的市，前四位能体现隶属关系；市下面的区县，后两位接着往下分。拿 adcode 作为关联 key 是最稳的，因为编码唯一且不会因为地名简称变化而波动。ECharts 渲染时，把 name 展示给用户看；匹配业务指标时，优先用 adcode。

如果业务数据只有地名、没有编码，前端或后端就维护一张“地名 → adcode”的映射表。千万不要直接拿地图 name 去业务数据里做 Object 的 key 查找。原因很简单：业务系统里可能写的是“省份甲”，地图数据里写的是“省份甲（某区）”，甚至某些地图数据会把名称写成简称，匹配失败是常态。

还有两类特殊层级需要单独考虑：

• 少数省份下面没有完整的地级市概念，会存在“省直辖县级行政区域”这样的数据项。如果用户点击这种区域，市级地图文件可能为空，组件要能识别出来，并在 UI 上提示“暂无更细粒度地图数据”。
• 几个直辖市本身就是省、区县两级结构，理论上从省级下钻时，直接进入区县级视图即可。如果你拿到的数据里只有市级文件而没有重置，可以在下钻逻辑里对这类编码做特判。

2.3 地图渲染的核心配置解析

ECharts 5 中一个最基础的地图 series 配置大概是这样的：

const option = { tooltip: { trigger: 'item', formatter: (params) => `${params.name}：${params.value ?? '无数据'}` }, visualMap: { type: 'continuous', min: 0, max: 500, inRange: { color: ['#e0f3f8', '#74add1', '#313695'] } }, series: [ { type: 'map', map: currentMapName, roam: true, center: null, zoom: 1, label: { show: true, fontSize: 10 }, itemStyle: { borderColor: '#ffffff', areaColor: '#f0f0f0' }, emphasis: { label: { show: true }, itemStyle: { areaColor: '#ffd666' } }, data: regionMetrics } ] };

几个关键点：

• map字段的值必须和registerMap(mapName, geoJson)的第一个参数完全一致。白屏问题八成出在这里。
• roam: true开启滚轮缩放和拖拽，下钻地图基本都要开。
• center不填写时，ECharts 首次渲染会自动让整张地图居中。但切换地图时如果不显式重置 center 和 zoom，它会沿用上一张图的位置和比例。后面我会给出一个计算中心点的方法。
• label控制区域名称显隐。地图缩得很小时不要显示全部名称，否则标签重叠严重；通常我设置label.show为 true，配合zoom联动，再给小于某个缩放比例时隐藏标签。
• emphasis是鼠标悬停高亮样式，这里可以写得明显一点，帮助用户感知“这个区域可以点击”。

关于用series.map还是geo，我的建议是：只要你的需求是“区域 + 数据 + 点击”，就用 series。series 可以直接把业务数据data绑定到地图的每个区域上，visualMap 也是基于 series 的 data 做映射的。geo 组件更像一个纯底图，更适合需要叠加多个自由图层的时候，对常规下钻场景没必要。

3. 实操过程与核心环节实现

3.1 依赖安装与按需引入

项目里先安装 ECharts：

npm install echarts@5

在 Vue 3 中，我不建议把整个 ECharts 包全部引入，尽量按需引入模块：

import * as echarts from 'echarts/core'; import { MapChart } from 'echarts/charts'; import { TooltipComponent, VisualMapComponent } from 'echarts/components'; import { CanvasRenderer } from 'echarts/renderers'; echarts.use([MapChart, TooltipComponent, VisualMapComponent, CanvasRenderer]);

如果你还需要 geo 底图，就加上GeoComponent。

这里要提醒一下：ECharts 5 已经不再内置任何地图 GeoJSON，所以像import 'echarts/map/js/china'这种旧写法在 5.x 里会直接报错。网上老教程很多，新手上手看到旧写法改不过来会非常痛苦。正确姿势就是统一用registerMap注册外部 GeoJSON，后面所有代码都围绕这个思路写。

3.2 组件主体骨架

我用 Vue 3 组合式 API 封装一个DrillMap.vue，模板大致长这样：

<template> <div class="drill-map"> <div class="map-toolbar"> <button v-if="mapStack.length" type="button" @click="handleBack">返回上一级</button> <span class="breadcrumb">{{ breadcrumb.join(' / ') }}</span> </div> <div ref="chartRef" class="chart-container"></div> </div> </template>

模板很简单，重点在业务逻辑。下面这段是核心的渲染函数：

const chartRef = ref(null); let chart = null; const mapStack = ref([]); const currentGeoJson = ref(null); const baseGeoPath = '/geo-json'; async function loadGeoJson(path) { const res = await fetch(path); if (!res.ok) throw new Error(`地图数据加载失败：${path}`); return res.json(); } function buildRegionData(geoJson, metrics) { return geoJson.features.map((feature) => { const adcode = feature.properties.adcode; const name = feature.properties.name; return { name, value: metrics[adcode] ?? metrics[name] ?? null }; }); } async function renderMap(geoJson, mapName) { echarts.registerMap(mapName, geoJson); const data = buildRegionData(geoJson, props.metrics); chart.setOption( { tooltip: { trigger: 'item' }, visualMap: { type: 'continuous', inRange: { color: ['#e0f3f8', '#74add1', '#313695'] }, text: ['高', '低'] }, series: [ { type: 'map', map: mapName, roam: true, center: calcMapCenter(geoJson), zoom: 1, label: { show: true, fontSize: 10 }, itemStyle: { borderColor: '#ffffff', areaColor: '#f0f0f0' }, emphasis: { label: { show: true }, itemStyle: { areaColor: '#ffd666' } }, data } ] }, true ); currentGeoJson.value = geoJson; }

注意setOption的第二个参数传了true，也就是notMerge模式。切换地图时如果不传 true，上一次的 series 数据可能残留，尤其是 visualMap 的映射区间、label 显隐这些状态会混在一起，造成地图数据和显示不同步。

calcMapCenter是一个自己封装的函数，后面第 4 章会展开说。

3.3 下钻逻辑实现

下钻的核心是监听 ECharts 的 map 点击事件：

chart.on('click', async (params) => { const name = params.name; if (!name) return; const feature = currentGeoJson.value?.features.find( (item) => item.properties.name === name ); if (!feature) return; const adcode = feature.properties.adcode; const nextGeoJson = await loadGeoJson(`${baseGeoPath}/${adcode}.json`).catch( () => null ); if (!nextGeoJson || !nextGeoJson.features.length) { // 提示：当前区域没有更细粒度地图数据 return; } // 保存当前地图上下文，用于上钻 mapStack.value.push({ mapName: `map_${adcode}`, geoJson: currentGeoJson.value, adcode }); await renderMap(nextGeoJson, `map_${adcode}`); emit('regionChange', { name, adcode, level: mapStack.value.length }); });

这里有几个细节值得展开：

• 用params.name去找currentGeoJson.features里的 feature，而不是直接在params里取 adcode。因为 ECharts 在点击事件里给出的 name 来自 series 的 data 字段，只要数据里没有把 adcode 透传上来，你就拿不到。最靠谱的方式还是回到所维护的 GeoJSON 里去查。
• 地图注册名我用了map_${adcode}，而不是固定的map或currentMap。为什么不固定？因为如果你反复使用同一个名字注册不同的 GeoJSON，ECharts 内部虽然会替换，但在做上钻、做多实例渲染时很容易出现旧地图缓存串扰。用编码后缀做唯一等价物，能省去很多排查时间。
• 加载下一级地图失败时不能直接忽略。用户点击一个区域没反应会以为坏了，所以要有一个轻提示。我的做法是在点击回调里 catch 一下，弹个 toast，不让异常冒泡到控制台。

3.4 上钻与面包屑恢复

上钻逻辑是下钻的镜像操作：

function handleBack() { if (!mapStack.value.length) return; const prev = mapStack.value.pop(); renderMap(prev.geoJson, prev.mapName); // 如果需要，可以把当前高亮区域带回去 emit('regionChange', { name: prev.name, adcode: prev.adcode, level: mapStack.value.length }); }

栈结构非常直观。上钻时把栈顶项弹出，重新渲染上一级地图。如果栈空了，就回到全国地图。

回到上一级后，有一个小体验问题：用户是从“省份A”钻进去的，返回时地图应该还保持在全国视图，并且最好能高亮刚才进入的“省份A”。实现方式有几种：

• 简单方案：返回后自动把地图 center 定位到之前点击的区域，并加一个短暂的 emphasis 高亮。
• 复杂方案：监听 ECharts 的select事件，结合selectedMode: 'single'记录选中项。

我的建议是：第一版别做复杂方案。先把往返逻辑跑通，然后再加高亮，否则一旦选中态和下钻状态相互影响，排查起来会很痛苦。

3.5 指标数据与视觉映射

业务数据传进来时，最好统一转成以 adcode 为 key 的对象，比如：

// 输入 props.metrics = { [adcode1]: 120, [adcode2]: 80 };

如果只有中文名，就单独维护一张映射表。我实际项目里就遇到过数据源一会儿给“省份A”，一会儿给“省份A省”，靠 name 匹配连不上，改成 adcode 后一条 bug 都没再出现过。

visualMap 连续型颜色映射，要让空数据和零值有视觉区分。当区域没有业务值时，data 里的value为null，这时候visualMap不会为它上色，我建议通过 itemStyle 里设置一个统一的默认灰色：

itemStyle: { areaColor: '#f0f0f0' }

这样没有数据的区域呈现灰色，有数据的区域通过 visualMap 上色，用户一眼能分辨哪些区域没有指标数据。

3.6 初始化、销毁和 resize

图表组件的生命周期处理很关键：

onMounted(() => { chart = echarts.init(chartRef.value); renderChinaMap(); window.addEventListener('resize', resizeHandler); }); onBeforeUnmount(() => { window.removeEventListener('resize', resizeHandler); if (chart) { chart.dispose(); chart = null; } }); function resizeHandler() { chart?.resize(); }

有一个细节：如果页面里用<transition>或v-if控制图表容器的显隐，不要在容器display: none的时候init，否则图表宽高会拿到 0。要么用nextTick等容器真正渲染后再初始化，要么在显隐变化之后调用一次resize()。

4. 常见问题与排查技巧实录

4.1 地图白屏或者只显示一个点

这类问题最打击新人，但实际上核心原因就那么几个。我把排查顺序列成一个表，定位速度会快很多：

我提到过注册名一致这个事，实际项目里真的会因为手抖多打个空格导致白屏。调试技巧：不要靠眼睛看，直接把registerMap的第一个参数和series.map打出来，用字符串比较工具看，效率最高。

4.2 点击区域下钻没反应

点击区域没反应分几种情况。

一种是点击到非地图区域，比如地图下方的空白。ECharts 的 click 事件在地图空白区域也会触发，但params.name为空，所以我在事件回调最前面加了一个if (!name) return。

另一种是点击区域有名字，但currentGeoJson.features里找不到对应 feature。这种情况通常是因为地图数据里的 name 和 ECharts 渲染时用的 name 不完全一致。下钻事件里千万不要用params.data.adcode直接拿编码。因为当 series.data 里某个字段不匹配时，params.data可能是 undefined，整个回调就会报错。

还有一种容易被忽略的原因：地图容器上叠加了其他元素的透明遮罩，导致点击事件根本没有传到底下的 Canvas。排查方法是在点击区域时看事件是否触发，没触发就去查元素层级。用浏览器的 DevTools 把鼠标悬停在对应位置，看看最上层是什么元素。

4.3 返回上一级后视野错乱

这是高频问题。表现是：从省级下钻到市级，返回省级时，地图不在全国视角了，而是停留在某个奇怪的位置和缩放比例上。

原因就是前面说的：ECharts 切换地图时会沿用上一次的center和zoom，除非你在下一次 setOption 里显式改掉。

我的做法是写一个calcMapCenter函数，每次渲染新地图时根据 GeoJSON 重新算一个中心点：

function calcMapCenter(geoJson) { const points = []; geoJson.features.forEach((feature) => { const geom = feature.geometry; if (geom.type === 'Polygon') { geom.coordinates.forEach((ring) => ring.forEach((point) => points.push(point))); } else if (geom.type === 'MultiPolygon') { geom.coordinates.forEach((polygon) => polygon.forEach((ring) => ring.forEach((point) => points.push(point))) ); } }); if (!points.length) return undefined; const lons = points.map((point) => point[0]); const lats = points.map((point) => point[1]); return [ (Math.min(...lons) + Math.max(...lons)) / 2, (Math.min(...lats) + Math.max(...lats)) / 2 ]; }

如果 GeoJSON 的 feature properties 里本身有 center 或 centroid 字段，直接用那个更好，毕竟多边形的中心不等同于 bounding box 的中心。但大部分公开数据里不一定有，所以这个兜底函数很有用。

4.4 异步请求竞态与缓存

地图下钻过程中，用户可能会快速连续点击多个区域。如果不对异步请求做控制，会出现“明明点了 A 市，结果加载出 B 市地图”的情况。原因很简单：A 请求还没返回，B 请求已经发出并先返回了，setOption 被 B 覆盖，然后 A 返回后又被覆盖，最终显示的是后完成的那张图，而用户自以为点在 A 上。

最便宜的做法是维护一个请求序号：

let requestSeq = 0; async function loadGeoJsonWithGuard(path) { const seq = ++requestSeq; const json = await loadGeoJson(path); if (seq !== requestSeq) return null; return json; }

在点击回调里把loadGeoJson换成loadGeoJsonWithGuard，旧请求的返回值直接丢弃。这个套路没有任何学习成本，却能避免掉绝大多数竞态 bug。

地图数据体积不小，我建议在组件内部做一层缓存。用户退出下钻再进入同一个省，不想再重新请求一次文件：

const geoCache = new Map(); async function loadGeoJsonWithCache(path) { if (geoCache.has(path)) return geoCache.get(path); const json = await loadGeoJson(path); geoCache.set(path, json); return json; }

缓存对象放在组件模块作用域，甚至可以直接提升到全局，跨组件复用。

4.5 tooltip 和 visualMap 数据不显示

tooltip 里的数据不显示，大概率是业务数据匹配没成功。我见过很多次params.value返回 undefined 的情况，原因是buildRegionData里用 name 去找 metrics 的 key，但地图和 metrics 两侧的名字差了一个字。

所以我在组件里会加一个调试方法，把最终传给 ECharts 的 data 打出来：

console.table(buildRegionData(geoJson, props.metrics));

只要看表格里有没有数据，就能定位是匹配问题还是数据源本身缺数。这个排查技巧比一步步打断点都快。

visualMap 不显示颜色映射，同样先看 data 里的 value 是否有有效数值。如果所有 value 都是 null，visualMap 默认区间可能根本压不出颜色。

4.6 其他容易忽略的问题

图表组件的内存泄漏问题经常等到页面 SPA 路由切换很久之后才开始暴露。onBeforeUnmount里必须dispose实例，同时移除 resize 事件和 chart 上手动绑定的 click 事件。如果使用chart.on绑定过事件，销毁前用chart.off解除。

还有一个很反直觉的坑：chart.clear()和chart.dispose()不是一回事。clear 是清空 option 但实例还能继续用；dispose 是把整个实例干掉。如果你在多次切换路由时只 clear 不 dispose，旧实例会一直占用内存。我自己的习惯是，组件卸载一律 dispose，不搞什么优雅过渡，反正重新进入会重新 init。

窗口 resize 之后地图标签位置偶尔会漂移，这个问题在 ECharts 5 某些版本里出现过。如果遇到，调用chart.resize()后，等下一帧再根据当前中心点恢复一下视野即可。

5. 进阶玩法与落地经验

5.1 从下钻到带参跳转

如果业务想从地图区域跳到对应的业务页面，最好在组件里提供事件，把点击区域的 name、adcode、当前层级都传出去：

emit('regionChange', { name, adcode, level: mapStack.value.length });

业务侧可以直接监听这个事件做路由跳转或联动筛选。我在实际项目里就是拿这个事件把地图和旁边的明细表格联动起来的：点击省份，表格就刷新成该省的城市列表；点击城市，表格刷新成该市的县区列表。

5.2 关于组件稳定性的经验

我自己在项目里踩了几次坑之后，总结出三个优先级最高的原则：

第一，所有地图文件路径、编码规则、命名规则，在项目和团队内部定成规范。比如 adcode 一律用 6 位编码、GeoJSON 文件统一放geo-json目录、文件名必须是adcode.json。只要数据规则定了，组件代码就非常薄，剩下的只是拼路径和做渲染。

第二，异步加载地图数据必须同时做缓存和竞态保护。这两个机制缺一个，在低网速、高点击速度的场景下都会出问题。缓存是性能优化，竞态保护是正确性保障，两者不能混为一谈。

第三，关于 map 的注册名，不要嫌麻烦。每次下钻都用带 adcode 后缀的独立字符串来注册，这样可以避免旧地图污染。我也见过只维护一个mapName变量就能跑通的例子，但那种方案在快速切换层级加返回时很容易触发莫名奇妙的问题，不如多写几行代码换个心安。

最后还有一个小技巧：开发阶段把临时调试数据打到console.table，把地图渲染相关的数据流可视化，等确认无误再删掉。地图组件的排错成本比普通表格组件的排错成本高得多，早一点把数据拉出来看，能少走很多弯路。