前端地图 SDK 接入与统一封装

工程化项目里，我更倾向用 NPM 装 loader，版本和加载时机都更好控。

npm install @amap/amap-jsapi-loader --save

import AMapLoader from '@amap/amap-jsapi-loader';

AMapLoader.load({
    key: '你的 KEY',
    version: '2.0',
    plugins: ['AMap.Scale', 'AMap.ToolBar']
}).then((AMap) => {
    const map = new AMap.Map('map-container', {
        center: [116.397428, 39.90923],
        zoom: 12
    });
}).catch(e => console.error(e));

百度地图（Baidu Map）

<script type="text/javascript" src="https://api.map.baidu.com/api?v=3.0&ak=你的 AK"></script>
<div id="baidu-map" style="width: 100%;height: 500px;"></div>
<script>
    const map = new BMap.Map('baidu-map');
    const point = new BMap.Point(116.404, 39.915);
    // 注意：百度使用 Point 对象
    map.centerAndZoom(point, 15);
    map.enableScrollWheelZoom(true); // 启用滚轮缩放
</script>

npm install baidumap-web-api --save

import { BMap } from 'baidumap-web-api';
const map = new BMap.Map('baidu-map');
map.centerAndZoom(new BMap.Point(116.404, 39.915), 15);

腾讯地图（Tencent Map）

<script src="https://map.qq.com/api/js?v=2.exp&key=你的 KEY"></script>
<div id="tencent-map" style="width: 100%;height: 500px;"></div>
<script>
    const map = new qq.maps.Map(document.getElementById('tencent-map'), {
        center: new qq.maps.LatLng(39.916527, 116.397128),
        zoom: 12
    });
</script>

Google Maps

<script async defer src="https://maps.googleapis.com/maps/api/js?key=你的 API_KEY&callback=initMap"></script>
<div id="google-map" style="width: 100%;height: 500px;"></div>
<script>
    function initMap() {
        const map = new google.maps.Map(document.getElementById('google-map'), {
            center: {lat: 39.9042, lng: 16.4074},
            zoom: 12
        });
    }
</script>

初始化时最容易踩的参数

center 和 zoom 基本是绕不开的两个参数。前者决定地图起点，后者决定你第一次看到的是全国还是一条街。

不同 SDK 对坐标顺序的要求不一样，这里最容易写错：

• 高德、Google：[经度，纬度]
• 百度：new BMap.Point(经度，纬度)
• 腾讯：new qq.maps.LatLng(纬度，经度)

常用可选项也不复杂，真正常碰到的就这几个：

多平台统一封装

如果项目里不确定以后会不会换地图服务商，最好一开始就把入口收拢一下。工厂模式是个够用的办法，谈不上优雅，但在业务代码里挺实用，至少不会把 AMap、BMap、qq.maps 和 google.maps 混成一团。

class UniversalMap {
    constructor(type, containerId, options) {
        this.type = type;
        this.container = document.getElementById(containerId);
        this.options = options;
        
        switch(type) {
            case 'amap': this.initAMap(); break;
            case 'baidu': this.initBaidu(); break;
            case 'tencent': this.initTencent(); break;
            case 'google': this.initGoogle(); break;
            default: throw new Error('Unsupported map type');
        }
    }

    initAMap() {
        this.map = new AMap.Map(this.container, {
            center: this.options.center || [116.397428, 39.90923],
            zoom: this.options.zoom || 12
        });
    }

    initBaidu() {
        this.map = new BMap.Map(this.container);
        this.map.centerAndZoom(new BMap.Point(...this.options.center), this.options.zoom || 12);
    }

    initTencent() {
        this.map = new qq.maps.Map(this.container, {
            center: new qq.maps.LatLng(...this.options.center),
            zoom: this.options.zoom || 12
        });
    }

    initGoogle() {
        this.map = new google.maps.Map(this.container, {
            center: { lat: this.options.center[1], lng: this.options.center[0] },
            zoom: this.options.zoom || 12
        });
    }

    // 统一方法：添加标记点
    addMarker(position) {
        switch(this.type) {
            case 'amap':
                new AMap.Marker({ position, map: this.map });
                break;
            case 'baidu':
                new BMap.Marker(new BMap.Point(...position)).addTo(this.map);
                break;
            case 'tencent':
                new qq.maps.Marker({
                    position: new qq.maps.LatLng(...position),
                    map: this.map
                });
                break;
            case 'google':
                new google.maps.Marker({
                    position: { lat: position[1], lng: position[0] },
                    map: this.map
                });
                break;
        }
    }
}

// 使用示例
const myMap = new UniversalMap('amap', 'my-map', {
    center: [116.397428, 39.90923],
    zoom: 12
});
myMap.addMarker([116.397428, 39.90923]);

这类封装的边界也要提前想清楚：像事件系统、覆盖物类型、坐标转换和权限配置，通常不会真的被完全'统一'，硬抹平最后只会给自己挖坑。能抽象的先抽象，差异大的地方保留平台分支，维护成本反而更低。

常见问题

实际项目里，下面这些问题出现得很频繁：

1. 地图容器必须设置宽高吗？ 是的。容器宽高为 0 时，地图通常不会正常渲染。
2. 为什么有时地图加载空白？ 常见原因包括密钥错误、网络拦截、容器未挂载完成或脚本加载失败。
3. 如何动态改变地图中心点？ 调用各 SDK 提供的 setCenter() 或 panTo() 方法。
4. 缩放级别的取值范围是多少？ 通常为 1~20，具体取决于地图服务商。
5. NPM 方式和 CDN 方式怎么选？ NPM 更适合工程化管理和版本控制；CDN 上手快，但依赖外部资源稳定性。
6. 多个地图实例能否共存于同一页面？ 可以，不过要留意性能和内存占用。
7. 如何监听页面加载完成事件？ 监听 complete 或 tilesloaded 事件。
8. 地图密钥泄露怎么办？ 先禁用旧密钥，再申请新密钥，同时检查 Referer 白名单。
9. 什么是懒加载地图？ 页面滚动到可视区域时再初始化地图，这样首屏压力会小很多。
10. 地图 SDK 版本升级需要注意什么？ 先看官方迁移指南，重点确认 API 是否废弃、参数是否变动、旧代码是否还能继续跑。