外观
常见报错 FAQ
730字约2分钟
2026-10-20
本页目标
把“地图不显示、瓦片空白、坐标偏移、类报错、跨域、打包失败”等高频问题集中成一张速查表。先在这里对号入座，再点进对应章节。
1. 地图不显示 / 白屏
| 现象 | 常见原因 | 解决 |
|---|---|---|
| 页面空白，控制台有版本信息 | 容器 DIV 没有高度 | 给容器设置 height（如 height:100% 或固定像素） |
| 容器有高度但一片灰白 | 底图未配置或 show:false | 检查 basemaps 中是否有 show:true 的底图 |
控制台报 xxx is not defined | JS 未引入或引入顺序错误 | 先引入 leaflet，再引入 mars2d |
2. 瓦片空白 / 404
3. 坐标偏移（地图“跑偏”、点位对不上）
国内地图存在 GCJ02 / BD09 偏移，需按图层坐标系做加偏/纠偏：
- 阅读坐标系中的“国内的偏移坐标系”。
- 矢量数据与底图坐标系不一致时，使用
mars2d.ChinaCRS相关配置。
4. 类不存在 / is not a constructor
| 原因 | 解决 |
|---|---|
| 版本不匹配 | 检查 mars2d 版本与代码写法是否对应 |
| 引入顺序错误 | 先 leaflet 后 mars2d |
| 重复引入 | 打包时排除重复的 leaflet（见下方“打包问题”） |
5. 跨域问题
地图服务、GeoJSON 文件跨域时浏览器会拦截，需要服务端允许 CORS。详见跨域问题。
6. ECharts / MapV 图表不显示
- 确认已安装并引入了对应插件（
mars2d-echarts/mars2d-mapv），见官方插件。 - 确认插件的引入顺序在
mars2d之后。
7. 打包后报错 / 页面崩溃
常见为 leaflet 被重复打包：
// vite.config.js
build: {
commonjsOptions: { include: /node_modules/ }
}或按1-NPM方式集成中的“常见问题”处理。
8. 切换路由后地图失效 / 内存上涨
单页应用卸载组件时未销毁地图。务必在 onUnmounted / useEffect 清理函数中调用 map.destroy()，见生命周期与资源释放。
9. 卡顿 / 内存高
参考性能优化与大数据量：批量加载、聚合、减少 DivGraphic、及时 remove 图层。
10. TypeScript 报类型错误
- 确认已包含
mars2d.d.ts类型声明。 - 参考框架集成与 TypeScript。