ECharts 5.x地图数据迁移指南：从china.js到JSON注册的平滑过渡
1. 为什么你的ECharts地图突然不显示了？
最近不少开发者反馈，把ECharts从4.x升级到5.x后，原本好好的中国地图突然报错，提示找不到echarts/map/js/china.js文件。这个问题我也遇到过，当时一个紧急项目上线前突然地图消失，差点没把我急死。
其实这是ECharts团队在5.x版本做的一个重大调整：移除了内置的china.js等地图文件。官方解释是为了减小核心库体积，让开发者按需加载所需地图数据。这个改动本身是合理的，但确实让不少升级的用户措手不及。
我查了下GitHub上的讨论，发现这个问题从2021年5.x发布就一直被频繁提起。主要报错有两种：
Error: Component series.map not exists. Load it first.Module not found: Error: Can't resolve 'echarts/map/js/china.js'
2. 新旧版本地图加载机制对比
2.1 老版本的"全家桶"模式
在ECharts 4.x时代，中国地图数据是直接打包在核心库里的。我们只需要简单引入：
// 4.x时代的写法 import echarts from 'echarts' import 'echarts/map/js/china' // 内置的中国地图这种方式虽然方便，但也带来了两个问题：
- 即使用户只需要展示一个简单的折线图，也必须加载完整的地图数据
- 所有地图数据都打包在一起，导致库体积膨胀
2.2 新版本的"按需注册"模式
ECharts 5.x开始采用更灵活的模块化方案：
- 核心库不再包含任何地图数据
- 开发者需要自行准备JSON格式的地图数据
- 通过
registerMap方法显式注册
// 5.x的正确打开方式 import * as echarts from 'echarts' import chinaJson from './china.json' // 外部地图数据 // 关键步骤：注册地图 echarts.registerMap('china', chinaJson)3. 两种主流迁移方案详解
3.1 手动引入JSON文件（推荐小项目使用）
第一步：获取地图数据官方推荐从两个渠道获取：
- ECharts官方GitHub
- DataV.GeoAtlas
我建议下载china.json后放在项目的public/maps目录下，这样打包时不会被处理。
第二步：注册地图数据
// 在生产环境中建议使用异步加载 async function initChart() { const response = await fetch('/maps/china.json') const chinaJson = await response.json() const chart = echarts.init(document.getElementById('map')) echarts.registerMap('china', chinaJson) chart.setOption({ series: [{ type: 'map', map: 'china' }] }) }优点：
- 完全自主控制地图数据
- 不增加额外依赖
- 适合对包体积敏感的项目
缺点：
- 需要手动更新地图数据
- 多地图项目维护成本高
3.2 通过npm包管理（推荐企业级项目）
ECharts社区提供了多个地图数据包：
echarts-china-provinces-pkg（中国省级）echarts-countries-js（全球国家）echarts-china-cities-pkg（中国市级）
安装与使用：
npm install echarts-china-provinces-pkg --saveimport * as echarts from 'echarts' import chinaJson from 'echarts-china-provinces-pkg/china.json' // 热更新环境下可能需要缓存 let registered = false if (!registered) { echarts.registerMap('china', chinaJson) registered = true }版本管理技巧： 在package.json中锁定版本号：
{ "dependencies": { "echarts-china-provinces-pkg": "~1.0.0" } }优点：
- 自动更新地图数据
- 版本控制方便
- 支持tree-shaking
缺点：
- 会增加node_modules体积
- 需要信任第三方维护者
4. 常见问题排查指南
4.1 地图显示空白但无报错
这种情况通常是因为：
- DOM容器没有设置宽高
#map-container { width: 800px; height: 600px; } - 没有正确设置geo或series.map配置
option = { geo: { map: 'china', roam: true } }
4.2 注册后仍然报错"map not exists"
检查三个关键点：
- 确保
registerMap的name参数和option中的map名称一致 - 确认在调用
setOption之前已经完成注册 - 在Vue/React等框架中，注意生命周期顺序
4.3 如何优化大型地图性能
对于省级或市级精细地图：
- 使用简化版GeoJSON
- 启用渐进渲染
series: [{ type: 'map', map: 'china', progressive: 400, progressiveThreshold: 3000 }] - 考虑使用WebWorker异步处理
5. 高级技巧：动态地图加载方案
对于需要多地图切换的应用，可以封装一个地图加载器：
class MapLoader { constructor() { this.cache = new Map() } async loadMap(mapName) { if (this.cache.has(mapName)) { return this.cache.get(mapName) } const json = await import( /* webpackChunkName: "map-[request]" */ `@geo-maps/${mapName}` ) echarts.registerMap(mapName, json.default) this.cache.set(mapName, true) return true } } // 使用示例 const loader = new MapLoader() await loader.loadMap('china-provinces')这个方案结合了：
- 动态import实现按需加载
- 内存缓存避免重复注册
- Webpack代码分割优化
6. 版本兼容性处理
对于需要同时支持4.x和5.x的项目，可以这样适配：
function initMap(echarts) { // 5.x+版本 if (typeof echarts.registerMap === 'function') { import('./china.json').then(json => { echarts.registerMap('china', json) }) } // 4.x版本 else { require('echarts/map/js/china') } }在webpack配置中添加别名：
resolve: { alias: { 'echarts/map/js/china': process.env.EC5 ? false : require.resolve('echarts/map/js/china') } }7. 最佳实践建议
- 性能优先：对于移动端项目，建议使用压缩版的JSON数据
- 错误处理：注册地图时添加错误边界
try { echarts.registerMap('china', chinaJson) } catch (err) { console.error('地图注册失败:', err) // 降级处理 } - TypeScript支持：为自定义地图添加类型定义
declare module '*.json' { const value: GeoJSON.FeatureCollection export default value }
我在最近的一个数据大屏项目中，就因为没注意地图注册顺序导致页面卡顿。后来通过性能分析发现是重复注册造成的，添加缓存机制后渲染时间从1200ms降到了400ms。