快速入门

本文档将帮助你快速接入百度地图服务，从注册账号到完成第一个地图应用

接入流程

第一步：注册账号

访问百度地图开放平台
点击右上角"登录"按钮
使用百度账号登录，如无账号请先注册
完成开发者认证（个人或企业）

第二步：获取密钥(AK)

密钥(AK)是调用百度地图服务的唯一标识，每个应用需要单独申请。

登录后进入控制台
点击"创建应用"
填写应用信息：
- 应用名称：自定义应用名称
- 应用类型：选择对应类型（浏览器端、服务端等）
- Referer白名单：设置允许访问的域名（开发阶段可设为*）。生产环境请务必设置正确的 Referer 白名单，避免 AK 被盗用
提交后获取 AK 密钥

应用类型选择指南

应用类型	适用场景	注意事项
浏览器端	Web网页应用	需设置Referer白名单
服务端	后端服务器调用	建议使用SN签名
Android SDK	Android原生应用	需配置包名和SHA1
iOS SDK	iOS原生应用	需配置Bundle Identifier
小程序	微信/支付宝小程序	需配置小程序AppID

第三步：集成服务

根据开发需求选择合适的集成方式。

开发环境要求

浏览器支持：

浏览器	最低版本	WebGL版本要求
Chrome	60+	60+
Firefox	55+	55+
Safari	11+	11+
Edge	79+	79+
IE	不支持	不支持

网络要求：

生产环境必须使用 HTTPS 协议
需要访问以下域名：
- api.map.baidu.com - API服务
- map.baidu.com - 地图资源
- *.baidu.com - 静态资源

快速示例

网页地图 v3.0

创建一个简单的地图页面：

html

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>百度地图示例</title>
  <style>
    html, body, #map {
      width: 100%;
      height: 100%;
      margin: 0;
      padding: 0;
    }
  </style>
</head>
<body>
  <div id="map"></div>
  <script src="https://api.map.baidu.com/api?v=3.0&ak=你的密钥"></script>
  <script>
    var map = new BMap.Map('map');
    var point = new BMap.Point(116.404, 39.915);
    map.centerAndZoom(point, 15);
    map.enableScrollWheelZoom(true);
    map.addControl(new BMap.NavigationControl());
    map.addControl(new BMap.ScaleControl());
  </script>
</body>
</html>

WebGL版本（推荐）

使用WebGL版本获得更好的3D渲染效果：

html

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>百度地图WebGL示例</title>
  <style>
    html, body, #map {
      width: 100%;
      height: 100%;
      margin: 0;
      padding: 0;
    }
  </style>
</head>
<body>
  <div id="map"></div>
  <script src="https://api.map.baidu.com/api?v=1.0&type=webgl&ak=你的密钥"></script>
  <script>
    var map = new BMapGL.Map('map');
    var point = new BMapGL.Point(116.404, 39.915);
    map.centerAndZoom(point, 15);
    map.enableScrollWheelZoom(true);
    map.setMapType(BMAP_EARTH_MAP);
  </script>
</body>
</html>

服务端调用

使用HTTP请求调用Web服务API：

javascript

const ak = '你的密钥';
const address = '北京市海淀区上地十街10号';
 
fetch(`https://api.map.baidu.com/geocoding/v3/?address=${encodeURIComponent(address)}&output=json&ak=${ak}`)
  .then(response => response.json())
  .then(data => {
    console.log('地理编码结果：', data);
  });

Vue项目集成

Vue SFC

<template>
  <div class="map-container">
    <div id="baiduMap" ref="mapContainer"></div>
  </div>
</template>
 
<script>
export default {
  name: 'BaiduMap',
  data() {
    return {
      map: null
    }
  },
  mounted() {
    this.initMap()
  },
  methods: {
    initMap() {
      // 动态加载百度地图API
      const script = document.createElement('script')
      script.src = `https://api.map.baidu.com/api?v=3.0&ak=你的密钥&callback=initMap`
      script.async = true
      document.head.appendChild(script)
      
      // 定义回调函数
      window.initMap = () => {
        this.map = new BMap.Map(this.$refs.mapContainer)
        const point = new BMap.Point(116.404, 39.915)
        this.map.centerAndZoom(point, 15)
        this.map.enableScrollWheelZoom(true)
      }
    }
  }
}
</script>
 
<style scoped>
.map-container {
  width: 100%;
  height: 500px;
}
#baiduMap {
  width: 100%;
  height: 100%;
}
</style>

React项目集成

jsx

import React, { useEffect, useRef } from 'react';
 
function BaiduMap() {
  const mapRef = useRef(null);
  const mapInstance = useRef(null);
 
  useEffect(() => {
    // 动态加载百度地图API
    const script = document.createElement('script');
    script.src = `https://api.map.baidu.com/api?v=3.0&ak=你的密钥&callback=initBaiduMap`;
    script.async = true;
    document.head.appendChild(script);
 
    // 定义回调函数
    window.initBaiduMap = () => {
      if (mapRef.current && !mapInstance.current) {
        mapInstance.current = new BMap.Map(mapRef.current);
        const point = new BMap.Point(116.404, 39.915);
        mapInstance.current.centerAndZoom(point, 15);
        mapInstance.current.enableScrollWheelZoom(true);
      }
    };
 
    return () => {
      // 清理
      mapInstance.current = null;
    };
  }, []);
 
  return <div ref={mapRef} style={{ width: '100%', height: '500px' }} />;
}
 
export default BaiduMap;

移动端开发指南

响应式适配

html

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

触摸事件处理

javascript

// 禁用默认的触摸行为，避免与地图交互冲突
document.addEventListener('touchmove', function(e) {
  if (e.target.id === 'map') {
    e.preventDefault();
  }
}, { passive: false });
 
// 移动端地图配置
var map = new BMap.Map('map', {
  enableMapClick: false  // 禁用点击热点
});
 
// 启用拖拽和缩放
map.enableDragging();
map.enableScrollWheelZoom();
map.enableDoubleClickZoom();
map.enableKeyboard();
map.enableInertialDragging();
map.enableContinuousZoom();

移动端性能优化

javascript

// 减少覆盖物数量
if (navigator.userAgent.match(/mobile/i)) {
  // 移动端使用简化版本
  map.setMinZoom(5);
  map.setMaxZoom(18);
}
 
// 延迟加载非必要功能
setTimeout(function() {
  map.addControl(new BMap.NavigationControl());
}, 1000);

开发工具

BMap Draw

百度地图官方提供的绘图工具，支持在线绘制点、线、面等图形，并导出代码。

访问地址：BMap Draw

坐标拾取器

用于获取指定位置的坐标，支持地址搜索和地图点击。

访问地址：坐标拾取器

示例中心

提供丰富的示例代码，涵盖地图展示、覆盖物、事件、控件等各类功能。

访问地址：WebAPI示例中心

调试技巧

控制台调试

javascript

// 开启调试模式
var map = new BMap.Map('map', {
  enableMapClick: true
});
 
// 查看地图状态
console.log('中心点：', map.getCenter());
console.log('缩放级别：', map.getZoom());
console.log('视野范围：', map.getBounds());
 
// 监听所有事件
map.addEventListener('click', function(e) {
  console.log('点击坐标：', e.point.lng, e.point.lat);
});

网络请求调试

javascript

// 使用回调函数调试API请求
fetch('https://api.map.baidu.com/place/v2/search?query=餐厅&region=北京&ak=你的密钥')
  .then(response => {
    console.log('请求URL：', response.url);
    console.log('状态码：', response.status);
    return response.json();
  })
  .then(data => {
    console.log('响应数据：', data);
  })
  .catch(error => {
    console.error('请求失败：', error);
  });

常见调试方法

问题	调试方法
地图不显示	检查容器高度、AK配置、控制台错误
坐标偏移	确认坐标系类型，使用坐标转换
API调用失败	检查网络请求、状态码、错误信息
性能问题	减少覆盖物数量、使用海量点/点聚合

错误码说明

JavaScript API 错误

错误信息	原因	解决方案
"ak不存在"	AK密钥错误或未生效	检查AK是否正确，等待生效
"域名未授权"	Referer白名单限制	添加当前域名到白名单
"权限不足"	AK类型不匹配	使用正确类型的AK
"加载失败"	网络问题或服务不可用	检查网络，稍后重试

Web服务API 状态码

状态码	说明	解决方案
0	成功	-
1	服务器内部错误	重试或联系技术支持
2	参数无效	检查参数格式和必填项
3	权限不足	检查AK配置和权限
4	配额超限	升级配额或购买配额包
5	AK不存在	检查AK是否正确
6	IP或域名未授权	配置白名单
7	SN签名错误	检查签名算法和SK

错误处理示例

javascript

// JavaScript API 错误处理
window.onerror = function(message, source, lineno, colno, error) {
  console.error('全局错误：', message);
  // 上报错误日志
};
 
// Web服务API 错误处理
async function callApi(url) {
  try {
    const response = await fetch(url);
    const data = await response.json();
    
    if (data.status !== 0) {
      throw new Error(`API错误(${data.status}): ${data.message}`);
    }
    
    return data;
  } catch (error) {
    console.error('API调用失败：', error);
    // 显示用户友好的错误提示
    alert('服务暂时不可用，请稍后再试');
    throw error;
  }
}

常见问题

地图无法显示

排查步骤：

检查AK是否正确
检查Referer白名单设置
检查容器是否有高度
查看浏览器控制台错误信息

解决方案：

html

<!-- 确保容器有高度 -->
<style>
  #map {
    width: 100%;
    height: 500px; /* 必须设置高度 */
  }
</style>
 
<!-- 检查AK是否正确 -->
<script src="https://api.map.baidu.com/api?v=3.0&ak=正确的密钥"></script>

跨域问题

服务端 API 调用可能遇到跨域问题，解决方案：

方案1：使用JSONP

javascript

function jsonp(url, callback) {
  const script = document.createElement('script');
  script.src = `${url}&callback=${callback}`;
  document.body.appendChild(script);
}
 
jsonp('https://api.map.baidu.com/geocoding/v3/?address=北京&ak=你的密钥', 'handleResponse');
 
function handleResponse(data) {
  console.log(data);
}

方案2：后端代理

javascript

// Node.js代理示例
const express = require('express');
const axios = require('axios');
const app = express();
 
app.get('/api/baidu/*', async (req, res) => {
  const url = `https://api.map.baidu.com${req.path.replace('/api/baidu', '')}?${req.query}`;
  const response = await axios.get(url);
  res.json(response.data);
});

方案3：配置CORS

javascript

// 服务端添加CORS头
app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Methods', 'GET, POST');
  next();
});

配额限制

免费配额有限，如需更高配额：

申请企业认证
购买配额包
联系商务定制方案

配额监控代码：

javascript

// 监控API调用次数
let apiCallCount = 0;
const DAILY_LIMIT = 5000;
 
async function callApiWithLimit(url) {
  if (apiCallCount >= DAILY_LIMIT) {
    throw new Error('今日配额已用完');
  }
  
  apiCallCount++;
  const response = await fetch(url);
  return response.json();
}

坐标偏移问题

百度地图使用BD09坐标系，与其他坐标系不同：

javascript

// GPS坐标转百度坐标
var convertor = new BMap.Convertor();
var points = [new BMap.Point(116.327, 39.990)];
 
convertor.translate(points, 1, 5, function(data) {
  if (data.status === 0) {
    // 转换成功，使用百度坐标
    var bdPoint = data.points[0];
  }
});
 
// 坐标类型：1-GPS(WGS84), 3-国测局(GCJ02), 5-百度(BD09)

下一步

了解核心概念
学习 [JavaScript API](./03-JavaScript API.md) 详细用法
查看实战案例