ECharts自定义地图加载与错误处理

ECharts 的地图可视化并不局限于内置地图类型。项目中遇到行政区划、园区、校园、商圈、厂区等特殊区域时，通常需要加载 GeoJSON 数据并注册为自定义地图。真正容易出问题的地方，也往往不是图表配置本身，而是地图数据格式、名称匹配、资源路径、坐标体系以及异步加载流程。

掌握自定义地图的加载方式，同时建立一套针对常见报错的排查思路，可以明显降低地图项目的调试成本。

一、ECharts自定义地图的基本原理

ECharts 的地图组件本质上依赖地图数据。对于自定义区域，常见方案是准备一份 GeoJSON 文件，然后通过 JavaScript 获取数据，再调用 echarts.registerMap() 注册地图。

基本流程可以概括为：

GeoJSON地图文件
      ↓
异步加载地图数据
      ↓
JSON解析
      ↓
echarts.registerMap()
      ↓
series.type = 'map'
      ↓
地图渲染

例如准备 custom-map.json：

JSON
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "区域A"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [120.1, 30.1],
            [120.2, 30.1],
            [120.2, 30.2],
            [120.1, 30.2],
            [120.1, 30.1]
          ]
        ]
      }
    }
  ]
}

然后加载并注册：

JavaScript
fetch('/maps/custom-map.json')
  .then(response => response.json())
  .then(geoJson => {
    echarts.registerMap('customMap', geoJson);

    const option = {
      series: [
        {
          type: 'map',
          map: 'customMap',
          data: [
            { name: '区域A', value: 100 }
          ]
        }
      ]
    };

    chart.setOption(option);
  });

这里的关键点是，registerMap() 使用的地图名称必须与 series.map 中的名称一致。

二、为什么推荐使用GeoJSON加载自定义地图

GeoJSON 是目前前端地图数据中非常常见的一种格式，结构清晰，也比较适合与 ECharts 配合。

一个标准的 GeoJSON 地图通常包含：

JSON
{
  "type": "FeatureCollection",
  "features": []
}

每个区域通常对应一个 Feature：

JSON
{
  "type": "Feature",
  "properties": {
    "name": "区域A"
  },
  "geometry": {
    "type": "Polygon",
    "coordinates": []
  }
}

其中：

• properties.name 通常用于区域名称匹配；

• geometry.type 可以是 Polygon 或 MultiPolygon；

• coordinates 保存具体的地理边界；

• FeatureCollection 保存多个区域。

对于行政区地图，一个地区可能包含多个不连续区域，此时使用 MultiPolygon 比单纯的 Polygon 更合适。

三、使用axios加载自定义地图

如果项目已经使用 Axios，也可以直接通过 Axios 获取 GeoJSON。

JavaScript
import axios from 'axios';

axios.get('/maps/custom-map.json')
  .then(response => {
    const geoJson = response.data;

    echarts.registerMap('customMap', geoJson);

    chart.setOption({
      series: [
        {
          type: 'map',
          map: 'customMap'
        }
      ]
    });
  })
  .catch(error => {
    console.error('地图加载失败：', error);
  });

异步请求方式最大的好处是地图文件可以独立维护，不需要把大量 GeoJSON 数据直接写进 JavaScript 文件。

对于较大的地图文件，这种方式也更利于缓存和资源管理。

四、地图加载成功但无法显示的常见原因

“请求成功”并不意味着“地图一定能够正常显示”。

例如：

JavaScript
axios.get('/maps/custom-map.json')

返回 HTTP 200，只能说明服务器成功返回了文件。GeoJSON 是否符合预期，还需要进一步检查。

可以先输出数据：

JavaScript
console.log(response.data);

正常情况下应该看到：

JavaScript
{
  type: "FeatureCollection",
  features: [...]
}

如果返回的是：

HTML


...

那么问题通常不在 ECharts，而在资源路径。

例如：

JavaScript
axios.get('/maps/custom-map.json')

请求路径写错后，开发服务器可能返回 index.html。Axios 如果尝试按照 JSON 解析，就可能出现类似 JSON 解析错误。

因此，浏览器开发者工具中的 Network 面板非常重要。

五、检查自定义地图文件路径

地图资源路径是实际项目中非常容易忽略的问题。

假设项目结构如下：

public/
├── maps/
│   └── custom-map.json
└── index.html

src/
├── App.vue
└── main.js

对于 Vite 项目，通常可以直接：

JavaScript
fetch('/maps/custom-map.json')

因为 public 下的文件会作为静态资源直接提供。

如果地图文件放在：

src/assets/maps/custom-map.json

则更适合通过模块方式引入：

JavaScript
import customMap from './assets/maps/custom-map.json';

echarts.registerMap('customMap', customMap);

不同构建工具对静态资源的处理方式有所区别，因此不要简单地把一个项目中的路径写法复制到另一个项目。

六、处理“Map xxx not exists”错误

如果控制台出现类似：

Map customMap not exists

通常意味着 ECharts 在执行：

JavaScript
series: {
  type: 'map',
  map: 'customMap'
}

时，没有找到名为 customMap 的已注册地图。

首先确认是否执行了：

JavaScript
echarts.registerMap('customMap', geoJson);

其次检查名称是否完全一致：

JavaScript
echarts.registerMap('customMap', geoJson);

对应：

JavaScript
map: 'customMap'

下面这种写法就会出问题：

JavaScript
echarts.registerMap('customMap', geoJson);

const option = {
  series: [
    {
      type: 'map',
      map: 'CustomMap'
    }
  ]
};

地图名称是区分大小写的。

另外，还需要特别注意异步执行顺序。错误示例：

JavaScript
axios.get('/maps/custom-map.json').then(response => {
  echarts.registerMap('customMap', response.data);
});

chart.setOption({
  series: [
    {
      type: 'map',
      map: 'customMap'
    }
  ]
});

这里 setOption() 可能先于地图注册执行。

更安全的方式是：

JavaScript
axios.get('/maps/custom-map.json')
  .then(response => {
    echarts.registerMap('customMap', response.data);

    chart.setOption({
      series: [
        {
          type: 'map',
          map: 'customMap'
        }
      ]
    });
  });

七、解决地图名称与数据名称不匹配

地图能够正常显示，但 data 中的数据没有对应区域颜色，这是另一类非常常见的问题。

例如 GeoJSON：

JSON
{
  "properties": {
    "name": "北京市"
  }
}

而业务数据写成：

JavaScript
data: [
  {
    name: '北京',
    value: 100
  }
]

这两个名称并不相同，ECharts 无法自动判断它们属于同一个区域。

应该保持名称一致：

JavaScript
data: [
  {
    name: '北京市',
    value: 100
  }
]

对于大量业务数据，可以建立名称映射：

JavaScript
const nameMap = {
  '北京': '北京市',
  '上海': '上海市',
  '广州': '广州市'
};

然后在处理数据时统一转换：

JavaScript
const mapData = sourceData.map(item => ({
  name: nameMap[item.name] || item.name,
  value: item.value
}));

这比在大量业务代码中到处修改名称更加容易维护。

八、检查GeoJSON坐标数据

地图空白还有一个重要原因：GeoJSON 坐标数据本身存在问题。

例如坐标数组结构错误：

JSON
"coordinates": [
  [120.1, 30.1]
]

对于 Polygon，通常需要符合相应的嵌套结构：

JSON
"coordinates": [
  [
    [120.1, 30.1],
    [120.2, 30.1],
    [120.2, 30.2],
    [120.1, 30.2],
    [120.1, 30.1]
  ]
]

Polygon 的环通常还需要闭合，即最后一个坐标与第一个坐标相同。

如果 GeoJSON 来自第三方地图数据，还应检查：

• geometry 是否为空；

• coordinates 是否完整；

• Polygon 是否闭合；

• MultiPolygon 嵌套层级是否正确；

• 是否存在非法坐标；

• 是否混入了异常 Feature。

地图数据越复杂，越不能只通过 ECharts 控制台报错判断问题。

九、处理地图坐标范围异常

有时候地图并不是完全不显示，而是出现缩放异常，甚至整个容器看起来是空白。

这可能与坐标范围有关。

例如地图数据的坐标应该位于：

120.x, 30.x

结果某个 Feature 却出现：

0, 0

或者：

12000000, 3000000

那么地图整体范围可能被异常坐标拉大。

可以简单检查：

JavaScript
console.log(geoJson.features);

重点查看：

JavaScript
feature.geometry.coordinates

如果地图数据来源经过坐标转换，还需要确认不同数据是否使用了相同的坐标体系。

十、注意不同坐标体系之间的差异

真实项目中的地图数据可能来自不同来源，例如 WGS84、GCJ-02、BD-09 等。

这些坐标体系并不是简单地把经纬度数字复制过去就能完全重合。

如果底图和 GeoJSON 使用不同坐标体系，就可能出现：

• 区域边界错位；

• 标记点偏移；

• 路径与区域无法对齐；

• 地图看起来整体偏移。

因此，自定义地图项目在数据准备阶段就应该明确坐标来源，而不是等页面渲染之后才排查偏移问题。

十一、处理异步加载失败

地图文件可能因为网络异常、服务器错误或者部署路径问题加载失败。

建议对 HTTP 状态进行检查：

JavaScript
fetch('/maps/custom-map.json')
  .then(response => {
    if (!response.ok) {
      throw new Error(`地图请求失败：HTTP ${response.status}`);
    }

    return response.json();
  })
  .then(geoJson => {
    echarts.registerMap('customMap', geoJson);

    chart.setOption({
      series: [
        {
          type: 'map',
          map: 'customMap'
        }
      ]
    });
  })
  .catch(error => {
    console.error(error);
  });

相比直接：

JavaScript
fetch('/maps/custom-map.json')
  .then(response => response.json())

增加状态判断后，更容易定位 404、403、500 等服务器问题。

十二、给地图加载增加加载状态

地图文件较大时，用户可能会在短时间内看到空白区域。

可以增加加载提示：

JavaScript
chart.showLoading();

fetch('/maps/custom-map.json')
  .then(response => {
    if (!response.ok) {
      throw new Error('地图数据请求失败');
    }

    return response.json();
  })
  .then(geoJson => {
    echarts.registerMap('customMap', geoJson);

    chart.setOption({
      series: [
        {
          type: 'map',
          map: 'customMap',
          roam: true
        }
      ]
    });
  })
  .catch(error => {
    console.error(error);
  })
  .finally(() => {
    chart.hideLoading();
  });

这样用户能够明确知道地图正在加载，而不是误以为页面出现故障。

十三、Vue项目中如何避免重复注册

Vue组件可能因为路由切换、组件重新挂载等原因重复执行地图初始化逻辑。

可以将地图加载与注册过程封装：

JavaScript
async function loadCustomMap() {
  const response = await fetch('/maps/custom-map.json');

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  const geoJson = await response.json();

  echarts.registerMap('customMap', geoJson);

  return geoJson;
}

组件中：

JavaScript
onMounted(async () => {
  try {
    await loadCustomMap();

    chart.setOption({
      series: [
        {
          type: 'map',
          map: 'customMap'
        }
      ]
    });
  } catch (error) {
    console.error('自定义地图初始化失败', error);
  }
});

如果多个页面都使用同一份地图数据，还可以进一步把地图加载逻辑放到公共模块中，避免重复请求。

十四、React项目中的加载思路

React 中通常可以结合 useEffect 处理地图初始化。

JavaScript
useEffect(() => {
  let chart;

  async function initMap() {
    try {
      chart = echarts.init(document.getElementById('map'));

      const response = await fetch('/maps/custom-map.json');

      if (!response.ok) {
        throw new Error(`地图加载失败：${response.status}`);
      }

      const geoJson = await response.json();

      echarts.registerMap('customMap', geoJson);

      chart.setOption({
        series: [
          {
            type: 'map',
            map: 'customMap',
            roam: true
          }
        ]
      });
    } catch (error) {
      console.error(error);
    }
  }

  initMap();

  return () => {
    chart?.dispose();
  };
}, []);

组件销毁时调用：

JavaScript
chart.dispose();

可以减少图表实例重复创建带来的内存占用和事件绑定问题。

十五、地图容器尺寸导致的空白问题

有些情况下，GeoJSON、注册过程和 setOption() 全部正常，但页面仍然没有地图。

这时应该检查 DOM 容器。

例如：

HTML
 id="map">