百度地图JavaScript API v3.0入门：显示地图与添加标记的代码实例

作者：青柠

时间：2026-10-30

本文详细讲解如何使用百度地图JavaScript API v3.0在网页中显示地图并添加位置标记。通过完整的代码实例、核心对象解析、事件交互扩展与常见排查要点，帮助初学者快速掌握地图接入技能。

文章目录

在网页中嵌入电子地图是企业官网、门店检索和数据可视化系统中极其基础且高频的需求。百度地图 JavaScript API v3.0 提供了轻量、易用且性能稳定的地理信息呈现能力。要在页面上成功展示地图并标注指定位置，核心路径仅需四步：申请访问密钥（AK）、在页面中引入脚本、设定具备明确宽高的容器，以及通过 JavaScript 实例化 BMap.Map、BMap.Point 与 BMap.Marker 对象。本文将直接提供一份完整可运行的代码实例，并逐层剖析其背后的初始化逻辑、标记交互扩展以及初学者最容易遇到的白屏与坐标偏移排查方法。

一、前置准备与开发步骤全景

接入百度地图服务前，开发者需要登录百度地图开放平台并注册成为个人或企业开发者。在控制台的“应用管理”中创建应用，应用类型选择“浏览器端”，并根据实际调试环境设置 Referer 白名单（在本地测试阶段可临时填入 * 允许所有域名请求）。创建成功后，系统会生成一串唯一的字符串，即访问密钥（AK，Access Key）。

完成密钥获取后，即可按照标准开发生命周期进行页面编写。整个实施过程从脚本引入到标注呈现的完整路径如下图所示：

百度地图JavaScript API v3.0入门：显示地图与添加标记的代码实例

图1：百度地图 JavaScript API v3.0 开发流程全景

二、完整可运行的代码实例

为了让读者对整体实现有直观认识，下面给出单文件形式的完整 HTML 代码。该示例包含了结构层、样式层以及核心脚本逻辑。读者将代码保存为 index.html，并将其中的 您的密钥AK 替换为真实申请的密钥后，在任意现代浏览器中双击或通过本地 Web 服务器打开即可看到效果。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>百度地图JS API v3.0显示地图与添加标记示例</title>
  <style>
    /* 容器必须具有明确的宽高，否则地图无法渲染 */
    html, body {
      margin: 0;
      padding: 0;
      width: 100%;
      height: 100%;
    }
    #map-container {
      width: 100%;
      height: 500px; /* 或根据业务需要设为百分比、vh等绝对计算高度 */
      border: 1px solid #e2e8f0;
    }
  </style>
  <!-- 引入百度地图API v3.0，请将 ak 参数替换为您在百度地图开放平台申请的密钥 -->
  <script src="https://api.map.baidu.com/api?v=3.0&ak=您的密钥AK"></script>
</head>
<body>

  <!-- 地图宿主DOM容器 -->
  <div id="map-container"></div>

  <script>
    // 1. 初始化地图实例并绑定DOM容器
    var map = new BMap.Map("map-container");

    // 2. 创建地理坐标点（经度, 纬度）示例为北京天安门广场附近
    var point = new BMap.Point(116.404, 39.915);

    // 3. 初始化地图，设置中心点坐标和缩放级别（级别范围通常为3-19）
    map.centerAndZoom(point, 15);

    // 4. 开启鼠标滚轮缩放支持（默认处于关闭状态）
    map.enableScrollWheelZoom(true);

    // 5. 创建红色标注对象
    var marker = new BMap.Marker(point);

    // 6. 将标注添加至地图覆盖物图层中
    map.addOverlay(marker);
  </script>
</body>
</html>

注意：如果直接以 file:// 协议在浏览器打开本地 HTML 文件，某些浏览器会因为协议限制或百度服务器对空 Referer 的安全校验策略导致请求受限。建议使用 Visual Studio Code 的 Live Server 插件、Nginx 或 Python 的 python3 -m http.server 在 http://localhost 域下进行本地调试。

三、核心架构与关键对象解析

百度地图 JavaScript API v3.0 采用了典型的面向对象与图层合成架构。理解各个核心类的职能与层级归属，有助于在后续开发中灵活组合功能。以下是运行上述代码时内部对象之间的关系模型：

图2：百度地图核心对象结构与层级运转机制

1. 容器与实例化 (BMap.Map)

代码中通过 var map = new BMap.Map("map-container"); 创建地图对象。该方法接收一个参数，既可以是字符串形式的容器 DOM 元素 ID，也可以是实际的 HTMLElement 对象引用。百度地图会在该 DOM 内部动态构建多层绝对定位的 Canvas/Div 元素用于拼接瓦片切片与响应手势。

2. 地理坐标表达 (BMap.Point)

BMap.Point(lng, lat) 是地理坐标的核心表示类。必须特别留意参数顺序：第一个参数是经度（Longitude），第二个参数是纬度（Latitude）。在日常口语中人们常习惯先说“纬度”后说“经度”，如果在代码中颠倒顺序，会导致地图中心直接定位到大洋彼岸或两极冰盖，造成无法正常显示所需位置的假象。

3. 视口初始化 (centerAndZoom)

创建 BMap.Map 实例后，地图处于未激活状态，必须显式调用 map.centerAndZoom(point, zoomLevel)。其中 zoomLevel 为缩放级别，取值范围通常在 3 到 19 之间：数值越小视野越宏观（如 3 对应国家级概览），数值越大视野越微观（如 18-19 对应街道及建筑物级）。若未调用此方法，容器中将无法载入任何底图瓦片。

4. 标记与覆盖物管理 (BMap.Marker & addOverlay)

BMap.Marker(point) 用于生成一个默认样式的红色图钉图标。它自身只是一个独立的内存对象，只有通过 map.addOverlay(marker) 将其注册到地图实例的覆盖物管理器中，地图引擎才会将其计算并投影到当前的屏幕像素坐标系统进行绘制。

四、进阶扩展：为标记添加点击事件与信息窗口

在实际业务应用中，仅显示静态标记往往无法满足需求。最常见的场景是用户点击标记时，弹出一个包含地名、联系电话和地址详情的信息弹窗（InfoWindow）。

百度地图 API 提供了 BMap.InfoWindow 类与事件监听器 addEventListener，两者的组合执行流程如下：

图3：标记事件绑定与 InfoWindow 弹窗打开逻辑

以下为在基础示例之上增加自定义信息窗口的实现代码片段：

// 创建信息窗口配置对象
var opts = {
  width: 260,         // 信息窗口宽度（单位：像素）
  height: 80,         // 信息窗口高度（单位：像素）
  title: "故宫博物院" // 信息窗口标题内容
};

// 创建信息窗口对象，内容支持传入纯文本或标准 HTML 字符串
var infoWindow = new BMap.InfoWindow("地址：北京市东城区景山前街4号
开放时间：08:30-17:00", opts);

// 为标注对象绑定点击事件
marker.addEventListener("click", function () {
  // 在指定坐标位置打开信息窗口
  map.openInfoWindow(infoWindow, point);
});

五、常见问题排查与避坑指南

初学者在集成百度地图时，经常遇到页面没有任何报错但地图显示为灰白空白、或者标注点位置明显出现几百米偏差的情况。以下列出排查频率最高的技术诱因：

图4：四大核心常见问题与排查指南

1. 容器样式未设高度（最常见白屏原因）

HTML 中的普通 div 属于块级元素，默认宽度为 100%，但在没有子元素填充内容时，其默认计算高度为 0px。因为地图瓦片全部是通过绝对定位动态注入到容器内的，不会撑开容器的高度。如果不显式为容器设置例如 height: 500px; 或者对父级设置百分比高度，整个地图就会因为高度为 0 而呈现出“白屏”假象。调试时可通过浏览器审查元素查看该容器的实际像素尺寸。

2. 地理坐标系区别与纠偏

国内常见的地理坐标系分为三大标准：

坐标系代码	名称 / 来源	适用平台与代表服务
WGS-84	地球坐标系（国际标准）	GPS 设备硬件直出、海外地图服务（如 OpenStreetMap、Google 地图全球版）
GCJ-02	火星坐标系（国测局加偏）	高德地图、腾讯地图、Google 地图中国区
BD-09	百度坐标系（在 GCJ-02 基础上二次加偏）	百度地图所有 Web 端及移动端 API

如果使用手机定位接口获取的原始 WGS-84 经纬度，或者从其他地图系统导出的 GCJ-02 坐标直接传入 new BMap.Point()，标注在百度地图上会出现数百米的系统性偏移。如遇到此类数据，必须调用百度地图提供的 BMap.Convertor 批量转换接口，将原坐标纠偏转换为 BD-09 坐标后再进行渲染。

六、全文总结

掌握百度地图 JavaScript API v3.0 的核心在于把握好生命周期中的依赖关系：

环境与权限：确保脚本携带正确的 v=3.0 和有效的 ak，网络策略允许当前域名访问。
挂载时序：确保目标 DOM 节点在实例化前已经解析完成，并具备明确的像素高度。
三步成图：通过 new BMap.Map() 初始化实例，通过 new BMap.Point(lng, lat) 锚定坐标，最后通过 centerAndZoom() 激活视口。
图层挂载：通过 new BMap.Marker() 创建标记实例，使用 map.addOverlay() 完成渲染，并可通过事件监听与 BMap.InfoWindow 完善交互能力。