简介面向Android开发初学者的百度地图SDK接入教程资源包围绕在Android Studio中集成百度地图、完成地图展示与基础定位展开。内容从添加Gradle依赖、申请API密钥、配置Manifest权限与meta-data到MapView初始化、定位回调、地图点击监听、Marker覆盖物及生命周期资源释放均有完整讲解覆盖普通地图显示、定位服务开关、地图事件监听与覆盖物绘制等高频需求。压缩包共759个文件约232.89MB包含xml布局与配置、so动态库、flat构建产物、json资源配置、jar库、java源码、txt说明以及可直接安装验证的apk方便对照工程实际结构排查问题。尤其是LocationSource定位接口和MapView的onCreate/onResume/onPause/onDestroy调用能帮助初学者避开常见的初始化顺序与内存泄漏问题。已有1151人学习下载适合希望快速打通百度地图SDK接入流程、需要参考完整工程与成品验证效果的Android开发者。1. 在 Android Studio 里接百度地图 SDK为什么第一步不是写代码很多人在 Android Studio 里集成百度地图 SDK卡住的不是 Gradle 配置而是「地图不出图」。明明官方 Demo 能跑换到自己工程就一片灰底白网格日志里只有一句笼统的鉴权失败。这篇笔记先解决的问题就是这句话背后的三件事AK 和包名、签名是不是对上了so 文件有没有被放进正确的 ABI以及 MapView 的生命周期有没有和 Activity 联动好。读完后你能从零申请密钥、配置工程、渲染出第一张地图并且知道改包名、上混淆、发 release 时会在哪些地方栽跟头。适合接过 Android 工程、想在现有项目里快速加一个地图页面的开发者也适合纯新手拿来做第一个 LBS 练手项目。2. AK 与安全码开发者账号、SHA1 和密钥存放位置2.1 申请密钥时的三个选项别选错百度地图开放平台创建应用时会让你选接入类型Android SDK、iOS SDK、服务端 API。很多人图省事选了「服务端 API」回头在 Android Studio 里配完发现根本鉴权不过。原因是 Android SDK 的 AK 是和包名加 SHA1 绑定校验的服务端 AK 没有这套校验逻辑两者不能混用。正确做法是控制台「创建应用」时选择 Android SDK创建完拿到一串 AK这串 AK 是明文存在 AndroidManifest.xml 里的没有服务端密钥的概念。创建应用时还需要填包名和安全码。安全码就是签名证书的 SHA1注意是 SHA1 不是 MD5。官方文档里把这两项标为必填但实际调试阶段很多人还没定 release 签名先用 debug 签名的 SHA1 顶上去后面再改。我建议第一次接入直接用 debug 签名的 SHA1先把地图跑出来再上 release 签名折腾的路径会短一半。2.2 三种签名环境下的 SHA1 获取方式开发调试、release 正式包、多渠道打包这三种场景下签名文件通常不一样对应的 SHA1 也不一样。只要换签名就得回控制台把安全码改一遍否则地图就会静默鉴权失败。获取 SHA1 用 keytool 命令Android Studio 自带的 JDK 里就有直接在终端里敲# Windows CMD查看默认 debug 签名 keytool -list -v -keystore %USERPROFILE%\.android\debug.keystore -alias androiddebugkey -storepass android -keypass android # macOS / Linux keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android # 查看 release 签名jks 文件路径和别名按你的实际来 keytool -list -v -keystore ./release.jks -alias 你的别名 -storepass 你的密码这条命令的输出里有一个「SHA1:」开头的行一串 40 位十六进制字符把它复制到控制台安全码输入框。注意几个细节复制时去掉中间的空格也不要带换行output 里同时有 MD5 和 SHA1别复制错列。开发机如果重新生成过 debug.keystoreSHA1 会变得重新去控制台更新这是很多「昨天还好好的今天突然白屏」的元凶。2.3 AK 放在 AndroidManifest 哪里拿到 AK 之后在 AndroidManifest.xml 的 application 节点里加下面这段application android:usesCleartextTraffictrue meta-data android:namecom.baidu.android.apikey android:value你的AK / /application这里的 value 必须是字符串字面量不能写成string/baidu_map_ak这种资源引用。百度地图 SDK 在本地初始化时直接读取字面值资源引用方案在部分版本上会读不到表现就是地图初始化正常但鉴权一直失败。用manifestPlaceholders做 Gradle 注入也能跑通但那是工程级配置新手阶段不建议碰玄学问题太多。另外提一句AK 是跟着应用走的换电脑、换签名、换包名都必须回控制台核对。多人协作时建议把 AK 写进项目的local.properties或者本地 gradle.properties不进 Git避免泄露和跨环境误用。公司项目里见过有人把 AK 写死在源码里提交到仓库后面被爬虫抓走去刷流量地图账单直接爆掉。3. 工程接入依赖仓库、权限声明和 Gradle 配置3.1 依赖来源二选一官方 Maven 仓库还是 libs 目录百度地图 SDK 不在 Maven Central 里需要单独配置官方仓库。新工程推荐直接用 Maven 引入升级版本时改一行版本号就行。在项目根目录的 build.gradle 里加allprojects { repositories { google() mavenCentral() // 百度地图 SDK 独立仓库 maven { url https://map.bdimg.com/maven/ } } }然后模块级 build.gradle 里加依赖dependencies { // 版本号以百度地图开放平台「相关下载」页当前推荐为准 implementation com.baidu.lbsyun:BaiduMapSDK:{version} }版本号不要照抄网上博客里的旧数字开放平台会滚动更新旧版本可能在新系统上出兼容问题。另一种常见做法是下载官方 SDK 压缩包把 jar 和 so 文件手动放进 libs 目录这适合网络受限、没法访问境外仓库的团队。两种方式的差异只在依赖来源代码写法上没有区别。我一般倾向 Maven 方案因为 so 和 jar 的版本能统一管理换版本时不会出现「jar 换了 so 没换」这种隐蔽的崩溃。libs 方案一旦升级需要手动同步替换 jar 和 jniLibs 下的 so漏一个就是启动时UnsatisfiedLinkError。3.2 AndroidManifest 权限清单少一条地图就白屏地图 SDK 要联网拿瓦片、要读取网络状态做流量策略、要尝试定位所以权限声明比普通页面多不少。下面这份是保守的全量清单照着声明不会缺uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE / uses-permission android:nameandroid.permission.ACCESS_WIFI_STATE / !-- 定位相关地图SDK的“我的位置”功能需要 -- uses-permission android:nameandroid.permission.ACCESS_COARSE_LOCATION / uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION / !-- 部分旧版本SDK需要读写存储新版本已可去除这一项 -- uses-permission android:nameandroid.permission.WRITE_EXTERNAL_STORAGE android:maxSdkVersion28 /ACCESS_NETWORK_STATE和ACCESS_WIFI_STATE容易被忽略缺了之后地图区域会出现长时间空白不报错也不退出非常难排查。定位权限里ACCESS_FINE_LOCATION在 Android 6.0 起是运行时权限只声明还不够Android 12 及以上需要同时在代码里动态申请后才能打开「我的位置」图层。存储权限用maxSdkVersion28限制后Android 10 以上的设备不会自动授予避免应用商店审核时被追问为什么一个地图应用要读写存储。3.3 编译期配置JDK 版本、targetSdk 和 so 文件保留SDK 官方文档对 targetSdk 有上限要求接新版本 SDK 时如果 targetSdk 拉得太高可能出现地图渲染黑屏或定位回调异常。稳妥做法是先按官方文档的推荐值设置跑通后再逐步往上调。同时确认模块的 Java 版本兼容SDK 编译目标通常在 Java 8 及以上在 build.gradle 里保持android { compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } }so 文件方面SDK 默认带armeabi-v7a和arm64-v8a两个 ABI。如果项目里配置了 abiFilters记得把这两个加进去否则部分机型上会在System.loadLibrary时崩溃defaultConfig { ndk { abiFilters arm64-v8a, armeabi-v7a } }这个配置的坑我放在第五章模拟器白屏和这个有直接关系。4. 把地图渲染到界面MapView 初始化与生命周期联动4.1 MapView 还是 TextureMapView百度地图 SDK 提供了两个地图控件MapView和TextureMapView。MapView 基于 GLSurfaceView 实现层级在普通 View 之上如果你的地图页面要盖自定义按钮、弹窗、卡片GLSurfaceView 会和这些 View 产生 z-order 冲突盖上后可能出现地图区域黑块。TextureMapView 基于 TextureView可以正常和普通 View 混排适合地图页面上有搜索框、底部弹层这类交互较强的场景。我的习惯是统一用 TextureMapView性能损耗在绝大多数手机上感知不到但省掉了以后在页面上叠 View 时的规避成本。两者的 API 基本一致代码迁移只要替换布局标签和类名。新手直接用 TextureMapView 起步可以少踩一类显示层级问题。4.2 最小可运行布局、初始化、生命周期联动布局文件里声明一个地图控件com.baidu.mapapi.map.TextureMapView android:idid/map_view android:layout_widthmatch_parent android:layout_heightmatch_parent /Activity 里的最小代码public class MainActivity extends AppCompatActivity { private TextureMapView mMapView; private BaiduMap mBaiduMap; Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); // 1. 初始化 SDK整个进程只调用一次 SDKInitializer.initialize(getApplicationContext()); setContentView(R.layout.activity_main); mMapView findViewById(R.id.map_view); mBaiduMap mMapView.getMap(); // 2. 把视野移动到指定坐标缩放级别设成 15 LatLng target new LatLng(39.908823, 116.397470); MapStatusUpdate update MapStatusUpdateFactory.newLatLngZoom(target, 15f); mBaiduMap.animateMapStatus(update, 500); } Override protected void onResume() { super.onResume(); mMapView.onResume(); } Override protected void onPause() { super.onPause(); mMapView.onPause(); } Override protected void onDestroy() { if (mBaiduMap ! null) { mBaiduMap.setMyLocationEnabled(false); } mMapView.onDestroy(); mMapView null; super.onDestroy(); } }这里有几个点值得说清楚。SDKInitializer.initialize()必须传getApplicationContext()不能传 Activity 实例否则会造成内存泄漏和重复初始化崩溃。animateMapStatus的第二个参数是动画时长单位毫秒传 0 表示直接跳转不带动画需要快速定位用户位置时我一般传 0需要页面上视觉平滑过渡时传 300 到 500。onDestroy里先关掉定位图层再销毁 MapView顺序反了可能出现 native 层崩溃的日志属于保命写法。4.3 地图事件、手势和状态调整地图显示出来后下一步通常是响应点击和移动。给 BaiduMap 挂监听器mBaiduMap.setOnMapClickListener(new BaiduMap.OnMapClickListener() { Override public void onMapClick(LatLng latLng) { // latLng 是 BD-09 坐标别直接当成 GPS 原始坐标 } Override public boolean onMapPoiClick(BaiduMapPoi baiduMapPoi) { return false; } });监听器的挂载位置放在onCreate里一次挂好不要每次进入页面重复 add否则会触发多次回调。地图类型切换用mBaiduMap.setMapType()支持普通图、卫星图和空白图。卫星图是很占流量的模式如果在列表页或低端机上用用户会明显感觉到卡顿。交通图图层也是同理默认关闭需要时动态打开、离开页面关闭这是性能上的一个细节。5. 集成避坑改包名鉴权失败、白屏与混淆的 5 个排查点5.1 改了 applicationId 之后地图鉴权失败现象工程从单模块改成多模块或者发布时把applicationId从com.example.demo换成com.company.app装到手机上后地图显示网格底图logcat 里输出Authenticate errorAK 检查不通过。原因百度地图的 Android SDK 校验三元组——包名、SHA1 和 AK任何一个对不上就直接拒绝出图。applicationId在构建产物里就是包名改动后原 AK 绑定的包名自然失效。解决不用重新申请 AK去百度地图开放平台控制台找到对应应用把包名改成新的applicationId。注意不是改 AndroidManifest 里的 package 属性新工程里包名由 Gradle 的namespace和applicationId共同决定以applicationId为准。保存后约一分钟后生效不需要重新打包。5.2 模拟器白屏但真机正常so 文件 ABI 没对齐现象AS 自带的模拟器上运行地图区域全白连网格都没有同一份代码装到真机上完全正常。logcat 里没有 Java 异常偶尔能看到UnsatisfiedLinkError或者系统 so 加载失败的 trace。原因模拟器 CPU 架构是 x86_64百度地图 SDK 大部分版本只提供 ARM 架构的 so 文件。工程里没有显式配置 abiFilters 时APK 里只有 ARM 的 sox86 模拟器加载不了地图渲染引擎根本起不来。解决临时在defaultConfig里把x86_64加进 abiFilters或者直接用arm64-v8a的真机调试。发布包务必去掉x86_64多带一个 ABI 会让包体多出不少体积。这是典型的「谷歌官方仓库没有、文档也没有明说」的坑我第一次遇到时排查了近一小时。5.3 release 包鉴权失败而 debug 正常现象debug 包地图显示正常打 release 包后地图灰块模糊日志提示 SHA1 不匹配或者签名不一致。原因release 构建用独立的 keystore 签名SHA1 和 debug 完全不同。控制台里只配置了 debug 的 SHA1release 包的校验自然过不了。另一个隐蔽场景是 CI 打包机上有多套 keystore配置串了。解决用 release 的 jks 文件跑一遍 keytool把输出的 SHA1 追加到控制台的安全码输入框同一个应用可以配置多个 SHA1分别对应 debug 和 release。验证签名是否匹配的办法是解包 APK# 用 apksigner 查看 APK 实际签名证书的 SHA1 apksigner verify --print-certs app-release.apk把输出内容和控制台比对不一致就是签名配错了。我习惯在 release 验证流程里固定加这一步避免「本地能出图、分发出去就不行」的问题。5.4 Android 12 及以上安装后一打开就崩exported 没声明现象targetSdk 升到 31 之后应用装到 Android 12 手机上点击图标直接闪退logcat 里有一大段AndroidRuntime异常提示某个 Activity 缺少android:exported属性。原因Android 12 要求四大组件显式声明android:exported。地图 SDK 自带的服务和 Activity 如果没显式处理打包时就会触发这个限制。解决在 AndroidManifest.xml 里给所有带 intent-filter 的组件加android:exportedtrue没有 intent-filter 的 service 加android:exportedfalse。如果用的是 SDK 内置的定位服务、离线地图服务它们的 manifest 已由 SDK 声明你需要做的是检查自己的 MainActivity 和自定义组件。这个崩溃表面上看和地图 SDK 无关但新手在接地图时最容易一起触发。5.5 开混淆后地图空白keep 规则没配上现象release 包开启minifyEnabled true后地图显示区域空白或者启动直接崩溃错误日志指向com.baidu.mapapi下的类找不到。原因SDK 内部有大量通过反射调用的类以及 JNI 层的 native 方法混淆后类名或方法名被改写native 层找不到对应入口地图引擎就废了。解决proguard-rules.pro 里加上-keep class com.baidu.** { *; } -keep class vi.com.gdi.bgl.android.** { *; } -dontwarn com.baidu.**不要自己去细抠哪些类需要 keepSDK 的反射调用范围比你想的大得多全量 keep 是成本最低的稳定方案。keep 的范围只涉及地图 SDK 自身不会影响你的业务代码混淆。6. 从显示到能用自定义 Marker、坐标转换与发版前验证6.1 自定义 Marker 和坐标转换地图显示只是第一步实际业务里你要在地图上打点、标注、定位。打点用 MarkerOptions配合 BitmapDescriptor 来自定义图标LatLng point new LatLng(31.2304, 121.4737); View customView LayoutInflater.from(this).inflate(R.layout.marker_view, null); BitmapDescriptor icon BitmapDescriptorFactory.fromView(customView); MarkerOptions options new MarkerOptions() .position(point) .icon(icon) .anchor(0.5f, 0.5f); mBaiduMap.addOverlay(options);anchor参数决定图标的锚点位置(0.5f, 0.5f)表示图标中心对准坐标点。常用的是底部中间对位也就是(0.5f, 1.0f)做地图大头针效果时这样设。另一个高频坑是坐标系。手机 GPS 拿到的坐标是 WGS-84 或 GCJ-02而百度地图用的是 BD-09直接把 GPS 坐标往 Marker 上填会出现几十米到几百米的偏移。SDK 提供CoordinateConverter工具类做转换不同坐标系的转换是一行代码的事但前提是先搞清楚自己手里的数据是什么坐标系。我的建议是所有外部坐标统一在服务端转成 BD-09 再下发客户端不承担转换逻辑这样 App 升级和 SDK 换版本时少很多隐患。6.2 发版前的地图核验流程基于过去几年被地图相关 release 问题翻车的经历我整理了一套发版前十分钟的验证流程分享给你。第一用apksigner verify --print-certs查 APK 实际签名确认和开放平台配置的 SHA1 一致第二在 release 包里手动操作地图页面拖动、缩放、点击 Marker 各试一次确认底图瓦片正常加载第三断网一次再进地图页确认无网络时的提示或缓存的兜底逻辑正常。这套流程看起来简单但能挡住大多数「debug 好好的一发 release 就翻车」的问题。直到现在每次发版我仍然会多花这十分钟跑一遍地图页因为地图不像普通页面它的渲染链路太长——签名、权限、so、混淆、坐标、网络策略任何一环悄悄变了表面症状都可能是一个白屏。希望帮到你。本文还有配套的精品资源点击获取