简介：这是一份专为Web开发者整理的百度地图API学习源代码包，适合具备基础Java Web知识、希望在实际项目中快速集成地图展示与位置服务的初学者。压缩包为标准Eclipse动态Web工程，共53个文件、大小约86KB，主体为37个JSP页面，同时包含JavaScript脚本、Eclipse工程配置、XML配置以及少量图片和光标资源，导入完整工作区后即可运行调试。源码围绕百度地图JavaScript API系统梳理了地图初始化、中心点设置、标注添加、多边形绘制、拖拽交互、用户位置获取、路径规划等典型场景，并串联了前端页面与后端结构，方便按模块拆解学习。目前已有543人学习浏览，相比零散查阅官方文档，这份可直接运行的源码包能显著降低地图开发的上手门槛，帮助开发者快速迁移到自己的实际项目开发中。 做了几年移动端开发，手里碰过的地图SDK不算少，但从零开始啃百度地图API的源代码，把定位、地图展示、逆地址解析这一整套跑通，还是踩了不少有意思的坑。这篇就把我整理的百度地图API学习源码思路和实操记录分享出来，从AK申请到核心代码解析，再到真机调试中那些让人抓狂的定位失败问题，一次性讲清楚。适合刚接触地图开发的初学者，也适合正在集成百度地图SDK但被各种编译和运行时问题卡住的朋友。看完你不仅能跑通一套完整的示例工程，还能明白每个核心接口为什么这么写、调不通时先从哪儿查。
1. 百度地图API整体设计思路：先想清楚再写代码
1.1 为什么选择百度地图SDK而不是H5地图
做地图功能之前，我其实纠结过一阵子：直接用WebView加载百度地图JavaScript API，还是集成原生SDK？两种方案各有取舍。JS API的优势是开发速度快、不用发版就能更新地图逻辑，但缺点也很明显——地图渲染完全依赖WebView，流畅度和交互体验比原生差一截，而且定位信息需要JS和原生桥接，回调时机不好控制。
百度地图原生SDK最大的优势在于封装好了定位、地图渲染、POI检索、路线规划这些高频能力，接口设计也很成熟。尤其对需要持续定位的应用来说，原生LocationClient对定位策略的控制粒度更细，省电和精准度方面表现都更好。我最终选择了原生SDK方案，下面这套源代码就是围绕"原生SDK + 核心功能拆分 + 问题可排查"三个原则来组织的。
1.2 项目源码的整体结构
这套学习源码不算复杂，但模块边界我刻意分得比较清楚，方便随时拿某个类出来复用：
com.example.bdmapdemo ├── MapActivity.java // 地图展示主界面 ├── LocationActivity.java // 定位功能演示 ├── GeocoderActivity.java // 逆地址解析演示 ├── application │ └── DemoApplication.java // 全局初始化SDK ├── util │ ├── PermissionUtils.java // 权限请求工具 │ └── CoordinateUtils.java // 坐标系转换工具 └── libs ├── baidu_map_sdk.jar ├── locSDK.jar └── libBaiduMapSDK.so这样拆的好处是定位、地图、地理编码之间互不干扰，每个功能模块出问题都能快速定位。很多初学者喜欢把定位和地图初始化写在一个Activity里，结果地图没显示、定位还报错，排查起来两个功能互相干扰，特别难受。我建议学习阶段宁可多建几个Activity，先把每个功能独立跑通，再做整合。
2. 集成前的关键准备工作：AK申请与环境配置
2.1 申请AK：密钥、包名和SHA1一个都不能错
百度地图开放平台申请AK本身不难，但很多人第一次都挂在签名信息上。Android SDK的AK绑定的是"包名+SHA1签名指纹"，这两个值必须和你的应用完全一致，否则运行时SDK会直接抛异常或者地图白屏。
获取开发环境的SHA1很简单，Android Studio右侧Gradle面板里找到签名任务执行一下，或者用命令行：
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android需要注意，调试时期用的是debug签名，发布时如果换成了正式签名，必须回到开放平台把AK的指纹信息更新掉，否则用户手机上地图会悄悄失效，那个排查过程相当酸爽。
2.2 权限声明与SDK初始化
在AndroidManifest.xml里，定位和地图需要用到的权限比较多，我按用途分了组：
<!-- 地图展示 --> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- 定位能力 --> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" /> <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />注意Android 6.0以上不仅要在Manifest里声明，还要在代码里动态申请。ACCESS_BACKGROUND_LOCATION这个权限是Android 10之后新增的，后台定位需要单独申请，用户弹窗比较多，即使申请了用户也可能拒绝，所以如果App只在前台用定位，完全没必要加这个权限，加了反而增加用户反感度。
SDK初始化要在Application里完成：
public class DemoApplication extends Application { @Override public void onCreate() { super.onCreate(); // 初始化地图SDK，传入的是ApplicationContext，不要传Activity SDKInitializer.initialize(this); // 如果需要关闭隐私合规弹窗，需要在初始化之前设置 // SDKInitializer.setAgreePrivacy(this, true); } }这里有两个关键点。第一，initialize必须传入application context，传Activity会导致内存泄漏；第二，新版SDK加强了隐私合规要求，如果应用内部有自己的隐私弹窗，需要在用户同意后调用setAgreePrivacy(true)，否则SDK的某些功能会拒绝工作。我在学习版本里直接置true方便调试，但商业项目里千万别这么写死。
3. 核心功能源码解析：定位、地图展示与坐标转换
3.1 定位功能：LocationClient的正确使用姿势
定位是整个地图功能里最容易出幺蛾子的环节，先看核心代码：
public class LocationActivity extends AppCompatActivity { private LocationClient locationClient; private MyLocationListener locationListener; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_location); // 1. 初始化定位客户端 LocationClient.setAgreePrivacy(true); locationClient = new LocationClient(this); // 2. 配置定位参数 LocationClientOption option = new LocationClientOption(); option.setLocationMode(LocationClientOption.LocationMode.Hight_Accuracy); option.setScanSpan(1000); // 连续定位的回调间隔，单位毫秒 option.setNeedNewVersionRgc(true); // 需要逆地址信息 option.setIsNeedAddress(true); // 返回地址描述 option.setOpenGps(true); // 打开GPS locationClient.setLocOption(option); // 3. 注册监听并启动 locationListener = new MyLocationListener(); locationClient.registerLocationListener(locationListener); locationClient.start(); } public class MyLocationListener extends BDAbstractLocationListener { @Override public void onReceiveLocation(BDLocation location) { if (location == null) return; double lat = location.getLatitude(); double lng = location.getLongitude(); String addr = location.getAddrStr(); Log.d("LocationDemo", "纬度: " + lat + ", 经度: " + lng + ", 地址: " + addr); } @Override public void onLocDiagnosticMessage(int locType, int diagnosticType, String message) { // 定位失败时诊断信息会回到这里，调试阶段强烈建议打印 Log.w("LocationDemo", "定位诊断: type=" + locType + ", detail=" + message); } } }这段代码里有几个细节值得展开说。**setScanSpan(1000)**表示连续定位时每1秒回调一次，如果只是单次定位，可以设成0，拿到结果后立即调用locationClient.stop()，避免一直占用GPS和网络，非常耗电。Hight_Accuracy模式是GPS、Wi-Fi、基站三种方式协同定位，精度最好但功耗也最高，如果想省电可以改成Battery_Saving，但高楼层室内定位精度会明显下降。
还有一个没人提醒你容易忽略的点：LocationClient.start()是异步的，调用后定位结果会通过Listener回调，不要在start之后的下一行代码里直接取定位值，那个值肯定还是默认的0或者上一次的缓存。
3.2 地图初始化：MapView生命周期管理
地图这部分，百度SDK要求MapView必须跟随Activity的生命周期调用对应方法，这是无数人崩溃的重灾区：
public class MapActivity extends AppCompatActivity { private MapView mapView; private BaiduMap baiduMap; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_map); mapView = findViewById(R.id.map_view); baiduMap = mapView.getMap(); // 开启定位图层 baiduMap.setMyLocationEnabled(true); } @Override protected void onResume() { super.onResume(); mapView.onResume(); } @Override protected void onPause() { super.onPause(); mapView.onPause(); } @Override protected void onDestroy() { // 先关闭定位图层，再销毁MapView baiduMap.setMyLocationEnabled(false); mapView.onDestroy(); mapView = null; super.onDestroy(); } }很多人把生命周期方法漏掉，或者调换了顺序，表现就是页面切换回来地图就变成灰色，严重时直接崩溃。顺序上有个原则：关闭定位图层要在MapView销毁之前，否则定位图层还在申请位置更新，MapView已经没了，SDK内部的回调会碰到空对象。
想实现"我的位置"蓝点显示，仅仅调setMyLocationEnabled(true)还不够，需要往baiduMap.setMyLocationData()里投喂定位数据，也就是把LocationClient拿到的经纬度封装成MyLocationData对象。常见做法是在定位回调里做一次消息转发，或者直接把MapActivity作为Listener接收定位结果。这里我推荐用接口解耦的方式，定位只负责上报经纬度，地图只负责渲染，两个模块通过回调通信，以后维护起来省心很多。
3.3 坐标系转换：别忘了百度坐标系的特殊之处
百度地图用的是BD-09坐标系，和WGS-84（GPS原始坐标）有偏移。如果你从外部设备拿到GPS坐标直接丢给百度地图，会发现标记位置偏了几十米到几百米。这是我在做设备轨迹展示时候踩的大坑。
百度SDK自带转换接口可以解决这个问题：
// 把WGS-84坐标转换为BD-09坐标 CoordinateConverter converter = new CoordinateConverter(); converter.from(CoordinateConverter.CoordType.GPS); converter.coord(new LatLng(deviceLat, deviceLng)); LatLng convertedLatLng = converter.convert();但注意，这个转换接口有调用频率限制，做离线批量转换不现实，建议批量场景用官方提供的坐标转换算法自己实现一遍转换逻辑，把这部分写成工具类维护。CoordinateUtils这个工具类就是从官方算法里抽出来的，支持大批量本地转换，不依赖网络接口。
4. 实战排坑：不同手机定位测试与API调用故障处理
4.1 不同手机的定位差异：芯片、系统定制和权限策略
我在真机测试阶段凑了几台不同品牌的手机，发现定位表现差异大到离谱。同样是在办公室窗边，高通芯片的手机定位秒回、误差十几米；某国产定制系统手机等了七八秒才返回坐标，误差四五十米；还有一台老机型干脆不回调。这不是百度SDK的问题，而是手机系统定位服务的行为差异。
定制系统对自启动、后台定位、省电策略管得非常严格。有些系统默认把应用的后台定位权限关闭了，即使用户在前台使用，系统也可能把定位请求降级。我的建议是，真机测试一定要覆盖不同品牌不同Android版本的设备，定位失败的时候不要急着怀疑SDK，先看诊断回调返回的定位类型码。
百度定位的类型码里，locType=161表示网络定位成功，这是最理想的。locType=167表示离线定位成功，精度稍差。locType=505表示定位结果已被缓存，可能就是之前某次定位的旧值。如果出现locType=62这类错误码，一般对应的是定位权限缺失或者定位服务未开启，优先检查这两项。手册里有一张完整的定位错误码对照表，强烈建议通读一遍，比你瞎猜快得多。
另外分享一个测试小技巧：拿同一台设备、同一个位置，分别测试GPS模式、Wi-Fi模式、流量模式的定位结果，记录每次的定位耗时和精度。这样能给用户提供一个合理的预期，也能在出现问题的时候判断是不是用户所在环境本身信号差。
4.2 地图白屏或加载失败的排查流程
百度地图的AK校验失败时，不会像网络请求那样返回一个明确的HTTP错误码，而是在Logcat里打一条Authentication Error的日志，界面上就是一片空白网格。很多初学者不知道去看Logcat，只盯着UI层干瞪眼。我遇到这类问题，排查的顺序非常简单：先确认AK在代码里有没有真的传到SDK，再确认包名和SHA1是否和开放平台绑定的一致，最后检查网络是否能访问百度地图的瓦片服务器。
有些应用设置了全局代理或者自定义的网络安全配置，默认情况下SDK的网络请求是正常走系统栈的，一旦你在项目里配了network_security_config.xml并限制了明文流量的域名，地图瓦片请求就会被拦掉，表现也是白屏。如果你发现地图在debug包正常、release包白屏，基本都是签名变化引起的AK失效，或者在release混淆时把SDK里的类给混淆了。无解的办法没有，就是在混淆配置里把百度地图SDK相关类全部keep住，开放平台文档里有现成的混淆配置模板，直接抄。
还有一个不太起眼但影响很大的点：SDK的so文件架构。现在很多应用的APK拆分了ABI，只保留armeabi-v7a和arm64-v8a，如果你只放了一家的so目录，用另一家芯片的手机就会因为找不到so文件导致加载崩溃。最简单的方案是，把libBaiduMapSDK.so放到main的jniLibs目录下，按四种ABI全量打进去，不要做裁剪。包体积多个几十兆虽然肉疼，但换来的是兼容性安全。
4.3 定位权限被用户拒绝后的优雅降级
我在测试时故意把定位权限拒绝掉，发现应用直接没有反应，连个提示都没有，用户会以为App坏了。良好的做法是：在权限回调里判断用户是否永久拒绝，并给出引导去设置页开启的弹窗。
@Override public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) { super.onRequestPermissionsResult(requestCode, permissions, grantResults); if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) { locationClient.start(); } else { // 每次启动都提示，但不要刷屏，避免用户反感 showPermissionGuideDialog(); } }这里有个体验细节：用户拒绝定位不代表他要放弃App，所以地图页面仍然要能打开，只是没法显示当前位置。我做了一个降级逻辑——拿不到定位时地图默认居中到某个城市中心，并在地图上给一个"定位不可用"的Toast提示，用户想用定位随时可以通过页面上的按钮重新请求权限。让核心功能"刚性需求"前置、其他功能"柔性降级"，对用户留存率的影响会小很多。
5. 这套源代码的扩展建议与我的学习体会
跑通这套基础Demo之后，往业务落地的方向扩展其实有很多现成的路子可走。百度地图API还提供了POI关键词检索、周边检索、路线规划、地理围栏、热力图等接口，API设计风格和定位模块高度一致，都是先建Client，再配置Option，然后注册回调发起请求。掌握了这套模式，迁移到其他功能模块基本没有学习成本。
以POI搜索为例，核心调用链路是：
PoiSearch poiSearch = PoiSearch.newInstance(); OnGetPoiSearchResultListener poiListener = new OnGetPoiSearchResultListener() { @Override public void onGetPoiResult(PoiResult result) { if (result != null && result.error == AbstractSearchResult.ERROR_NO_ERROR) { List<PoiInfo> poiList = result.getAllPoi(); // 遍历结果，往地图上添加Marker } } }; poiSearch.setOnGetPoiSearchResultListener(poiListener); poiSearch.searchInCity(new PoiCitySearchOption().city("北京").keyword("餐厅").pageNum(0));这类接口普遍都有个翻页参数pageNum/pageCapacity，很多坑就出在这里——一次性拿完所有结果是有条数上限的，必须做分页加载。我做周边搜索的时候没注意，结果接口明明返回成功，列表却只有几页数据，排查了一圈才发现是分页逻辑没写对。这算是地图接口的通用素养，你在其他地图平台上也会遇到同样的事。
最后分享一个小经验：调地图类接口千万别只看UI表现，Logcat里的系统日志才是真正的排障入口。onLocDiagnosticMessage、Authentication Error、so加载异常、权限拒绝，这些日志在Logcat里都有明确的关键字。我把这套Demo工程里的日志都规范成了LocationDemo和MapDemo前缀，配合Android Studio的Logcat过滤器，调试效率提升非常明显。
对我个人而言，学习地图API最有价值的不是记住每个类怎么用，而是理解一套完整的地图能力是如何通过"初始化-配置-回调"的模型组织起来的。你对这套模型越熟，将来切换到高德、腾讯地图，甚至接入海外地图服务的时候，都会发现它们的设计哲学惊人地相似。这种底层理解能力，恰恰是地图开发里最值钱的部分。
本文还有配套的精品资源，点击获取
