企业官网建设流程全解析

简介：一份以百度地图网页接口为核心的 Eclipse 工程学习代码包，面向网页前端及 Java 开发者，适合想在真实页面中快速上手地图功能的学习者。代码覆盖地图初始化、中心点设置、添加标记、绘制多边形、拖拽交互、用户定位与路线规划等常见场景，并配有 JSP 页面与脚本逻辑，便于对照运行和调试。压缩包内文件总数为 53 个，以 37 个 JSP 页面为主体，辅以脚本文件、XML 工程配置、图片素材及光标样式等，整体大小仅 86KB，结构紧凑，可直接导入 Eclipse 查看源码。目前已有 550 人学习下载。通过阅读这套示例，开发者可理解百度地图接口的调用方式、密钥申请流程以及联网环境的调试要点，并能够将地图能力灵活迁移到自己的网页项目中，是兼顾入门与实战参考的轻量资料。

1. 百度地图API学习源代码：一份能跟到最后的入门路径

很多开发者在“百度地图API学习源代码”这条路上卡住，不是卡在“不知道接口名”，而是卡在“样例代码拿过来根本跑不起来”。最常见的现象是：从示例页复制一段初始化代码，打开页面只有一片空白，或者地图出来了但标注的位置飘到几条街外。问题通常不是代码本身错了，而是缺了 AK、少了 referer 白名单、坐标系参数没对上，或者压根没把官方示例当成“要自己补全的骨架”来读。这篇文章就用可复现的最小源代码为线索，把从鉴权、初始化、标注到服务端检索的完整链路串一遍。适合正在做前端页面、后端服务、毕设演示或内部管理系统的开发者，新手能照步骤跑通，熟手可以顺带排查自己手头项目里的地图偏移和签名问题。

2. 先看懂百度地图API的体系：三个入口、一次鉴权和一堆坐标系

2.1 三个入口怎么选：JS API、Web服务API与移动端SDK

百度地图API不是一个单一接口，而是一套按使用场景切分的体系。学习源代码的第一步，是先分清你打开的是哪一份“源代码”。前端页面里最常见的是 JS API，它在浏览器里负责渲染地图、显示标注、响应交互；后端拿去换数据的是 Web服务API，它不渲染界面，只通过 HTTP 请求返回 JSON，适合做地点检索、逆地理编码、路线规划；而移动端 SDK 则是给 Android/iOS App 内嵌地图用的，虽然接口思路接近 JS API，但生命周期和权限处理完全不同。

从业者的选择思路通常是这样：如果你的业务只有一个管理后台网页，直接学 JS API；如果你的服务端需要根据用户输入返回地址列表，优先接 Web服务API；如果你做的是即时配送或打卡类 App，再去碰移动端 SDK。三种入口共用同一套 AK 体系，但鉴权方式和请求地址各自不同。我给过一个很朴素的判断标准：页面上要出现“能拖动的、有底图的地图”，就是 JS API；只要数据不要画面，就选 Web服务API；手机端要原生手势和定位，再上 SDK。

建议学习顺序也按这个来：先用 JS API 把地图画出来，建立“坐标→标注→交互”的直观认知，再用 Web服务API 做一次 POI 检索，理解服务端和前端的数据衔接。移动端 SDK 可以在前两条链路都通了之后再补，因为它踩的坑大多是系统权限和生命周期，而非地图业务本身。学习源码的时候，不要整段复制官方示例，而是把示例拆成“初始化、覆盖物、事件”三块，分别改参数跑通，这样后面接到自己工程里才不会一笔糊涂账。

2.2 AK 申请与校验：一把钥匙打开所有接口

所有百度地图API调用的起点，都是控制台里创建的一个应用。创建应用时你会拿到两个字符串：AK 和 SK。AK 是访问密钥，跟在每个请求的 URL 上；SK 是私钥，用来生成 Web服务API 的签名参数 sn，它在服务端使用，绝对不能写进前端页面或打包进 App 安装包里。控制台里创建应用的时候会让你选应用类型，这个选择直接影响校验方式：JS API 通常用“浏览器端”类型，靠 referer 白名单校验；Web服务API 用“服务端”类型，靠 IP 白名单或 SK 签名校验；移动端 SDK 则要绑定包名和签名证书的 SHA1。

我把常见校验方式整理成一张表，方便你在学习源码时先确认自己的应用配置对不对：

学习阶段，我建议你直接创建两个应用：一个浏览器端用来跑 JS API，白名单先填*凑合开发；一个服务端用来跑 Web服务API，校验方式选“SN 校验”，因为 IP 白名单在家庭宽带下经常变出口 IP，反而更麻烦。这里还有一个很容易被忽略的点：AK 是会出现在前端页面源码里的，相当于半公开的钥匙，所以一定要在控制台里把 referer 白名单限制到你的实际域名或localhost，否则别人拿到你的 AK 就能消耗你的配额。这属于最常见的“看起来跑通了但埋了一颗雷”的场景。

2.3 坐标系与偏移：为什么第一个坑是 BD09

百度地图API和国内其他地图体系最大的不同，是坐标系的差异。全球定位卫星拿到的是 WGS84 坐标，国内地图行业普遍讲 GCJ-02，而百度地图自己使用的是 BD09。同一个 GPS 点，扔进 WGS84 和 BD09，在地图上显示的位置可能相差几百米。这个偏移不是网络延迟造成的，而是坐标算法本身就不一样。所以学习源代码时，你迟早会碰到一个看起来像“地图出 bug 了”的问题：明明经纬度是从设备上拿的，标出来的点却在河对岸。

我记得在模拟项目X里，第一次做打卡功能时就有同事直接把手机定位的坐标塞进百度地图，结果所有签到点全部漂到隔壁园区，排查了半天才发现是坐标系没转。百度地图官方给出的常规做法是用坐标转换服务，或者在使用 Web服务API 时明确告诉接口你的输入坐标类型。比如逆地理编码接口里有一个coord_type参数，你传wgs84ll或gcj02ll，接口会先做转换再返回地址；如果你不传，服务端默认按 BD09 处理，偏差自然就出来了。

学习这一块时，不要凭感觉去记“该用哪个坐标系”，而是要在你的源代码里显式声明。前端 JS API 默认接收 BD09，所以BMap.Point的经纬度如果是自己从 GPS 拿的，就要先转一次再centerAndZoom。后端接 Web服务API 也一样，每个请求参数里能带coord_type就带上。坐标系的处理没有难算法，难的是你每次新建一个页面就默认它是 BD09，最后前端、后端、数据库三套坐标混在一起，整个数据就成了黑匣子。我的习惯是在工程里定义一个统一的数据字典：数据库存 WGS84，接口层转成目标坐标系，地图展示层只消费 BD09。

3. 用JS API在本地跑通第一张地图：最小可运行代码与三个必调参数

3.1 最小HTML文件：从引入脚本到地图渲染

学习百度地图API最快的方式，就是先让一张地图出现在浏览器里。我一般会新建一个不依赖任何框架的 HTML 文件，把官方示例瘦身到不能再瘦身的地步。下面这份是我在本地验证时常用的骨架，你直接复制，把你的AK替换成控制台里浏览器端应用的 AK 就能跑：

<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>我的第一张百度地图</title> <style> html, body, #map { height: 100%; margin: 0; } </style> <script src="https://api.map.baidu.com/api?v=2.0&ak=你的AK&callback=myMapInit"></script> </head> <body> <div id="map"></div> <script> function myMapInit() { // 替换成你业务覆盖区域的中心坐标 var point = new BMap.Point(114.30, 30.60); var map = new BMap.Map("map"); map.centerAndZoom(point, 15); map.enableHighResolution(); } </script> </body> </html>

这段代码的关键在于<script>标签里的callback=myMapInit。百度地图的 JS API 脚本加载是异步的，它会在初始化完成后调用你指定的全局函数。如果你不用 callback，而是直接用window.onload去new BMap.Map，很容易出现“脚本还没加载完，你的函数先执行了”的竞态，结果就是地图容器为空。所以callback不是可选项，而是这份最小源代码里最值得记住的结构。

#map这个容器必须要有明确高度，我见过不少翻车案例是只写了width忘了height，地图容器高度为 0，接口返回正常但页面上一片空白。上面样式里html, body, #map { height: 100%; }就是为了堵住这个问题。v=2.0是 JS API 的版本标识，开发时保持默认即可；enableHighResolution()在高分屏上让地图文字和道路更细腻，不加不影响功能，但 4K 屏下差距明显。这份代码跑通后，你就可以像拆玩具一样逐个删掉方法，观察地图行为变化，这比读文档更直观。

3.2 必调的 3 个初始参数：center、zoom 与 enableHighResolution

第一张地图跑通之后，就该认真理解centerAndZoom这一行。它一次做了两件事：设置地图中心点，设置缩放级别。中心点可以是坐标点，也可以直接传地址字符串，但生产环境我强烈建议传经纬度，因为地址字符串在渲染前会先走一次地理编码，多一次异步等待不说，还可能因为地名词典更新导致定位结果漂移。

zoom的取值一般是 3 到 19，数字越大显示越细。15 到 17 适合展示城市级 POI，18 以上就是楼宇级了。很多人学的时候会把zoom当成固定值写死，结果换个城市中心点就发现不是太远就是太近。正确做法是把缩放级别做成初始化参数，让调用方传。另外一个常被忽视的参数是enableHighResolution()，它在高分屏设备上会让渲染更清晰，但也会轻微增加切图数量。移动端业务里我通常会关掉它，省流量；PC 管理后台则建议打开，观感好很多。

只用三个参数就能把地图调得基本能看：center决定“我在哪”，zoom决定“我看多远”，enableHighResolution决定“画面清不清晰”。这三个参数对应了地图初始化的绝大多数需求，其他诸如enableScrollWheelZoom、enableMapClick都属于交互增强。我的学习建议是：先把这三个搞清楚，再往上加交互，不要一上来就堆二十个配置项。

3.3 叠加标注与信息窗口：理解覆盖物的生命周期

地图本身只是底图，业务价值在于上面的标注。百度地图里标注的学名叫覆盖物，Marker 是最常用的一种。它的生命周期很简单：创建 Marker 对象，添加进地图，事件触发时打开 InfoWindow，不需要时从地图移除。下面这段是在刚才那份最小源代码基础上加的覆盖物操作：

var marker = new BMap.Marker(point); map.addOverlay(marker); marker.addEventListener("click", function () { var infoWindow = new BMap.InfoWindow( "<p>这是模拟项目X里的一条POI</p>", { width: 200, title: "点位详情" } ); map.openInfoWindow(infoWindow, point); }); // 半小时后想清除这个标注 map.removeOverlay(marker);

覆盖物对象创建后并不会自动出现在地图上，必须addOverlay；删除时同样要传原来的 marker 实例。这里有一个新手常犯的错：用new BMap.Marker(point)创建了几个结构相同的 marker，删除时随手removeOverlay(new BMap.Marker(point))，但新对象和地图里的不是同一个引用，删不掉。所以业务中要做好 marker 实例的缓存，我的习惯是用一个数组markerList统一维护，批量清理时遍历map.removeOverlay(item)。

Marker 的 click 事件只在标记上触发，如果你想点击地图空白处也能打开信息窗口，需要监听的是map.click，然后map.getInfoWindow()判断当前是否有打开的窗口。这里提醒一点：InfoWindow 不是一次性内容，它可以配合 DOM 字符串更新内容，但频繁创建销毁会让页面上出现白闪，批量数据展示时建议先用BMap.Label或自绘覆盖物扛一下。学习源码时，把“创建→添加→事件→移除”这条链走熟，后面做点聚合、批量标点会顺很多。

4. 把服务端API接进自己的工程：POI检索与逆地理编码的调通案例

4.1 服务端鉴权：AK、SK 与 sn 签名

页面地图跑通后，就该让服务端接地点数据了。Web服务API 的请求格式是拼 URL 拿 JSON，和 JS API 完全是两种思维方式。这一步最容易卡住的反而不是业务参数，而是鉴权。如果你在控制台里把应用校验方式设成了 SN 校验，那每个请求都要带上一个由 AK、SK 和请求参数共同计算出的sn签名。SK 就是一串密钥，签名算法本质上是把“请求路径+参数”的整体编码后与 SK 拼接，再做一次 MD5。

我整理了一段生成 sn 的 Python 代码，这也是我每次接百度地图 Web服务API 都会先写好并反复使用的工具函数：

import hashlib import urllib.parse AK = "你的AK" SK = "你的SK" endpoint = "/place/v2/search" # 注意：这里的参数值保持原始状态，先不要做百分号编码 params = { "query": "便利店", "region": "某软件园所在城市", "output": "json", "ak": AK, "page_size": 20, } query_str = "&".join(f"{k}={v}" for k, v in params.items()) path_query = endpoint + "?" + query_str encoded = urllib.parse.quote(path_query, safe="/:=&?#+!$,;'@()*[]") sn = hashlib.md5((encoded + SK).encode("utf-8")).hexdigest() request_url = "https://api.map.baidu.com" + path_query + "&sn=" + sn print(request_url)

这段代码里最关键的是urllib.parse.quote的safe参数。它保留了/、:、?、&这些 URL 结构字符，只编码中文和空格。我把完整请求发给服务端时，服务端会用同样的规则重新生成 sn 来比对，所以“先拼明文参数、再整体编码”的顺序不能乱。如果你先urlencode了参数再拼路径，签名就永远对不上，接口回你一个INVALID_PARAMETER，你还以为是参数名写错了。

签名工具写好后，建议单独放在一个模块里，不要散落在业务代码中。各业务接口的params字典可能不同，但签名函数只要一份。还有个小习惯：测试时先把request_url打印出来，放到浏览器地址栏里直接访问，如果返回预期 JSON，说明 AK、SN 链路没问题；如果返回STATUS CODE 2这类鉴权错误，就专心检查 SK 配置和算法顺序，不要再动业务参数。

4.2 地点检索：query、region 与 page_size 的搭配

地点检索是后端接入地图服务最常见的需求，比如输入“便利店”返回周边列表。这个接口的路径是/place/v2/search，核心参数是query和region，一个表示要找什么，一个表示在哪里找。query支持名称、类别、电话等；region可以是城市名或经纬度，城市名和经纬度的组合规则会影响检索范围，并非所有组合都合法。

我用 requests 把完整调用写成函数，方便在模拟项目X里直接复用：

import requests def search_poi(query, region, page_size=20): params = { "query": query, "region": region, "output": "json", "ak": AK, "page_size": page_size, } query_str = "&".join(f"{k}={v}" for k, v in params.items()) path_query = "/place/v2/search?" + query_str encoded = urllib.parse.quote(path_query, safe="/:=&?#+!$,;'@()*[]") sn = hashlib.md5((encoded + SK).encode("utf-8")).hexdigest() resp = requests.get( "https://api.map.baidu.com" + path_query, params={"sn": sn} ) return resp.json() data = search_poi("便利店", "某软件园所在城市", 20) if data.get("status") == 0: for item in data.get("results", []): print(item.get("name"), item.get("location")) else: print("接口报错：", data.get("message"))

这里有一个很多人会忽略的点：requests.get的第一个参数是带中文的路径，第二个参数是sn，requests 会自动把中文做百分号编码后发送。但如果你把sn直接拼进 URL，再用 requests 发送，部分环境下 requests 会重写编码顺序，导致服务端拿到的请求和签名时不一致。我通常的做法是把业务参数拼到路径里生成sn，发送时再用params传sn，这样路径本身已经带上了中文明文，由 requests 统一处理编码，签名校验的成功率最高。

失败时先看status和message。status=0是成功；status=302通常是 AK 校验失败；status=401常见于 SN 签名错误。page_size最大一般到 20，如果你需要更多结果，要翻页，而不是把page_size调到 100。每次翻页还会继续消耗配额，所以业务上先用scope=2拿到完整字段，再在本地做筛选，比请求多次接口划算。

4.3 逆地理编码：coord_type 参数决定结果准不准

要把 GPS 坐标转换成“XX路XX大厦”这样的地址，用的是逆地理编码接口，路径是/reverse_geocoding/v3/。这个接口的参数很少，但每一个都值得较真。location传“纬度,经度”的字符串，coord_type告诉接口你传进来的坐标系是什么。默认值是bd09ll，也就是百度自己的坐标系，如果你手头拿的是手机的原始 GPS 坐标，属于 WGS84，不显式声明的话，返回的地址误差会很明显。

下面这段是我在服务端打印地址时反复调用的函数：

def reverse_geocode(lat, lng, coord_type="wgs84ll"): params = { "location": f"{lat},{lng}", "coord_type": coord_type, "output": "json", "ak": AK, } query_str = "&".join(f"{k}={v}" for k, v in params.items()) path_query = "/reverse_geocoding/v3/?" + query_str encoded = urllib.parse.quote(path_query, safe="/:=&?#+!$,;'@()*[]") sn = hashlib.md5((encoded + SK).encode("utf-8")).hexdigest() resp = requests.get( "https://api.map.baidu.com" + path_query, params={"sn": sn} ) return resp.json() result = reverse_geocode(30.60, 114.30, "wgs84ll") if result.get("status") == 0: print(result["result"]["formatted_address"])

coord_type的取值除了wgs84ll和gcj02ll，还有bd09ll。如果你知道自己的数据源是国测局坐标，比如从其他国内地图服务商导出的 POI，就传gcj02ll；如果是设备 GPS 模块拿的，传wgs84ll。这里吃不准时有个笨办法：先用坐标系转换接口把坐标转成 BD09，再按默认值调逆地理编码，结果等效。你不要觉得多一步转换浪费配额，接口给你返回一条错误的地址，浪费的是整个业务对数据的信任。

逆地理编码返回的result里除了formatted_address，还有location、addressComponents、pois等字段。addressComponents里的city、district可以直接用于省市区联动，比自己在结果字符串里抠效率高得多。我建议你写个小脚本，把一次返回的 JSON 完整打印到文件里，逐个字段过一遍，这个接口到底能拿到哪些数据就心里有数了，比对着文档猜字段更省时间。

5. 百度地图API的避坑指南：五个高频翻车点与排查思路

5.1 现象：地图白屏，控制台报 401 或 “APP REFUSED”

新页面引入 JS API 后，页面结构完整，但地图区域整片空白，打开 DevTools 的 Network 面板能看到脚本请求返回了 401，或者 Console 里出现APP REFUSED相关报错。原因通常是两种：一种是 AK 写错了，包括复制时多了空格；另一种是 referer 白名单没把当前域名加进去。本地开发用localhost:8080，白名单只写了localhost，端口一换就拦。

解决方式是回到控制台，把应用的安全设置里 referer 白名单改成你实际访问的完整地址，开发阶段可以临时填*，但要记住上线前改回来；同时检查页面上script src里的ak=参数和控制的 AK 是否一字不差。我习惯把 AK 抽到一个独立的config.js里，页面多处引用时只改一处，能少踩不少复制粘贴的坑。

5.2 现象：POI 搜索返回 INVALID_PARAMETER，但参数看起来都对

调/place/v2/search时，query、region都传了，返回结构的status是INVALID_PARAMETER。很多人的第一反应是去检查 AK，其实问题往往出在签名阶段：你先把query做了 URL 编码再拼到path_query里生成sn，而服务端是按原始中文明文生成签名，两边编码结果不一致，导致签名校验失败。这个错误通常表现为 HTTP 请求能到达服务器，但服务端认为参数不合法。

解决方式就是按第 4 章里的顺序：业务参数保持原始中文，整体拼接后做一次quote，再把sn带上请求。如果你确认签名没问题但依然报参数错误，可以打印出完整的request_url，用浏览器访问一次，看返回体里的message字段。它会告诉你具体是哪个参数不合法，比盯着接口文档猜效率高。我用这个办法排查过一次，最后发现是region传了个不存在的城市名，接口直接判定参数非法。

5.3 现象：坐标标在海里或房顶上，实际地址偏了几百米

地图能显示，Marker 也加上去了，但点不在正确位置。这个翻车案例在打卡、巡检、配送类业务里几乎每天都有。原因是坐标系没统一，最常见的是把 GPS 芯片拿到的 WGS84 坐标直接当 BD09 用，或者从其他地图服务商导出的 GCJ-02 坐标直接传给了百度。

解决方式要分两端看。展示端，在new BMap.Point之前先做坐标转换，百度提供坐标转换服务/geoconv/v1/，可以把 WGS84 或 GCJ-02 转成 BD09。服务端，反地理编码时显式传coord_type，让接口自己在内部转一次。关键是把“数据来源坐标系”作为字段存在数据库里，而不是靠猜。我吃过一次大亏，数据库里混了两套坐标，后面所有地图页面都像是得了帕金森，这就不是单个接口能解决的问题了。

5.4 现象：HTTPS 页面加载地图脚本被浏览器拦截

后台管理系统升级到 HTTPS 后，地图突然不见了，Console 里提示Mixed Content。原因是页面是 HTTPS，但你引入的百度地图脚本地址还是 HTTP，浏览器出于安全策略拦截了所有不安全的子资源。这个问题很隐蔽，因为你在本地 HTTP 环境调试得很好，一上测试服就变白屏。

解决方式简单粗暴：把脚本地址统一改成https://api.map.baidu.com/...，同时检查页面里有没有其他地方用http://引用地图相关 JS。另一个建议是部署前在控制台看一次完整页面请求列表，把所有http资源一次性揪出来。这里没有后悔药，因为一旦上线后才发现，用户端的浏览器缓存可能让问题延长很久。

5.5 现象：PC 一切正常，安卓端地图拖动不跟手或白屏

同一份页面代码，在 PC 浏览器上地图正常，安卓手机自带浏览器或 WebView 里要么白屏要么拖动时像卡了帧。原因很可能是页面没有设置合理的viewport，或者外层容器有overflow相关样式拦截了触摸事件。百度地图 JS API 在移动端对容器高度的计算更敏感，100%高度如果依赖父级高度而父级没有确定高度，移动端得到的容器高度就是 0。

解决方式是在 HTML 头部加<meta name="viewport" content="width=device-width, initial-scale=1.0">，并且给地图容器设置确定的高度而不是百分比，必要时用vh单位兜底。如果地图能显示但拖动不跟手，检查地图容器外的元素有没有设touch-action: none，这个 CSS 属性会破坏地图手势。我排查过一次，最后发现是某个弹窗组件在页面加载后给 body 加了overflow: hidden，把地图容器的高度挤没了，地图实际上渲染在了一个看不见的 0 高盒子里。

6. 进阶：把学习源码拆成自己的工具箱，并在浏览器里验证

学习一份 API 的源代码，最终目的是把它变成自己项目的公共能力。我的做法是每次跑通一个功能，就把它封装成一个可复用的函数或组件。比如地图初始化这块，我习惯封装成一个小工厂函数，配置文件统一管理：

function createBaiduMap(config) { var map = new BMap.Map(config.containerId); var point = new BMap.Point(config.lng, config.lat); map.centerAndZoom(point, config.zoom || 15); map.enableScrollWheelZoom(); // 调试锚点：Console 里直接 window.__map 就能操作当前地图 window.__map = map; return map; } var map = createBaiduMap({ containerId: "map", lng: 114.30, lat: 30.60, zoom: 16 });

封装完之后，验证就成了日常开发里最重要的一环。我不建议每一步都依赖页面点点点，把window.__map挂到全局，打开浏览器 Console 就能直接执行map.getCenter()、map.getZoom()、map.getBounds()，快速确认当前地图状态。服务端接口那边也一样，把search_poi封装成模块后，写个 test 脚本循环调用三个不同城市，对比status和返回条数，基本就能确定参数组合稳不稳。

我自己的一个习惯是：在 Console 里保存几条常用的调试指令，比如查看中心点、列出所有覆盖物、手动调用map.panTo。这些指令看起来不起眼，但在接第三方数据源的调试期特别管用，能立刻看出坐标是不是又偏了。地图这块技术，代码本身不算深，真正花时间的都是“数据对不对、坐标系准不准、配额够不够”这一类跟业务强相关的问题。希望这篇围绕“百度地图API学习源代码”展开的路径，能帮你在学习与复用的路上少绕几个弯，也希望你封装出的那一套工具能一直跟着你的项目走，越用越顺手。

本文还有配套的精品资源，点击获取