简介：本资源是一份面向Android初学者与中级开发者的百度地图SDK集成实战项目，聚焦在Android Studio环境下快速实现地图显示、定位及基础交互功能。内容覆盖API密钥申请、Gradle依赖配置、AndroidManifest权限与meta-data注册、MapView初始化、生命周期管理、定位服务启用及POI点击监听等核心环节，可直接用于教学演示或项目快速接入。压缩包共759个文件，包含211个XML布局与配置文件、140个SO本地库、134个Flat资源编译产物、128个JSON配置与数据文件，以及Java源码、DEX字节码、JAR依赖和Gradle构建脚本等，完整还原真实工程结构，总大小232.89MB。目前已有1151人学习下载，配套代码结构规范、注释清晰，附带关键组件生命周期释放示例与内存优化实践，助开发者规避常见崩溃与白屏问题，是系统掌握百度地图Android端集成的高实用性参考工程。

1. Android Studio 集成百度地图 SDK：从白屏到可交互地图的完整链路（含定位、缩放、点击响应）

你刚在activity_main.xml里拖进一个MapView，onCreate()里调了mapView.onCreate(null)，编译通过、安装成功——结果打开 App 只见一片灰白，连百度 logo 都不显示；或者地图能出来，但一动就卡死，logcat里刷满E/BaiduMapSDK: init failed；又或者定位图标一直转圈，onReceiveLocation()死活不回调……这不是玄学，是 SDK 初始化链路上至少 5 个关键断点没对齐。本篇不讲“注册账号→填包名→复制 AK”这种平台流水线，而是聚焦 Android Studio 工程侧真实落地：如何让MapView在真机上稳定加载、支持手势缩放、响应地图点击、并正确触发定位回调。适用于已掌握 Activity 生命周期和 Gradle 基础、正卡在“地图出不来”或“功能不响应”的 Android 开发者。所有操作均基于 Android Studio Giraffe | 2022.3.1 + AGP 8.1.0 + 百度地图 SDK v5.6.0（当前最新稳定版），避坑点全部来自某跨平台系统实测中翻车 7 次后沉淀的血泪经验。

2. 依赖配置与 SDK 初始化：Gradle 同步失败、白屏、API_KEY 不生效的根因拆解

百度地图 SDK 的集成不是简单加一行implementation就完事。v5.6.0 起强制要求 AndroidX、minSdkVersion ≥ 21，且对 AGP 版本敏感。很多白屏问题，根源不在代码，而在 Gradle 构建阶段就埋下了伏笔。

2.1 项目级与模块级 build.gradle 的协同配置

先确认你的项目结构是否满足基础约束：

• build.gradle（Project 级）中必须启用mavenCentral()作为仓库源（百度 SDK 已从 jcenter 迁移）；
• build.gradle（Module: app 级）中compileSdk必须 ≥ 33，targetSdk建议 ≥ 33（适配 Android 13 权限变更）；
• android.useAndroidX=true和android.enableJetifier=true必须在gradle.properties中显式开启（即使新项目默认开启，也建议手动确认）。

提示：若你使用的是 Android Studio Flamingo 或更早版本，AGP < 8.0，请降级使用 SDK v5.5.2（其兼容 AGP 7.4），否则annotationProcessor会报Cannot resolve symbol 'BindView'类错误——这是 AGP 注解处理机制变更导致的兼容性断裂，不是你代码写错了。

正确的build.gradle（Module: app）配置如下：

android { namespace 'com.example.baidumapdemo' compileSdk 34 defaultConfig { applicationId "com.example.baidumapdemo" minSdk 21 targetSdk 34 versionCode 1 versionName "1.0" // 必须添加此段，否则 SDK 初始化时读不到 meta-data manifestPlaceholders = [ BAIDU_MAP_API_KEY: "your_api_key_here" ] } buildTypes { release { minifyEnabled false proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro' } } compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } } dependencies { implementation 'androidx.appcompat:appcompat:1.6.1' implementation 'com.google.android.material:material:1.10.0' implementation 'androidx.constraintlayout:constraintlayout:2.1.4' // 百度地图核心 SDK（注意：v5.6.0 不再拆分 map/base/location，统一为单 aar） implementation 'com.baidu.mapapi:baidumapapi:5.6.0' // 【关键】必须显式引入 support-v4 兼容包（v5.6.0 内部仍强依赖 android.support.v4.app.Fragment） // 若不加，MapView 在 Fragment 中会 crash：java.lang.NoClassDefFoundError: Failed resolution of: Landroid/support/v4/app/Fragment; implementation 'androidx.legacy:legacy-support-v4:1.0.0' // 【可选但强烈建议】定位服务需额外依赖（若用到定位） implementation 'com.baidu.mapapi:location:5.6.0' }

参数说明与逻辑：

• manifestPlaceholders是为后续AndroidManifest.xml中动态注入 API_KEY 做准备，避免硬编码；
• androidx.legacy:legacy-support-v4是 v5.6.0 的隐藏依赖项，官方文档未明示，但实测缺失即崩溃；
• baidumapapi:5.6.0是全功能包（含地图渲染、POI 检索、路线规划、室内图等），无需再单独引入map或base子模块。

同步完成后，在Build → Make Project后检查External Libraries下是否出现baidumapapi-5.6.0.aar和location-5.6.0.aar—— 若无，说明仓库源未生效或网络拉取失败（此时应检查是否被公司代理拦截，而非怀疑 SDK 本身）。

2.2 AndroidManifest.xml 的三重校验：权限、meta-data、application 配置

白屏最常见原因：meta-data写错位置、AK 未替换、或权限声明不全。这里必须逐行核对，不能凭记忆。

权限声明（必须放在<manifest>根节点下，且顺序无关）

<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> <!-- Android 12+ 需要精确位置前台服务权限 --> <uses-permission android:name="android.permission.FOREGROUND_SERVICE" /> <!-- Android 13+ 需要后台定位豁免（仅当需后台持续定位时才加） --> <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

注意：WRITE_EXTERNAL_STORAGE在 Android 10+ 已被分区存储弱化，但百度 SDK 内部仍用其判断存储状态，不声明会导致初始化失败日志中出现storage not available。

Application 节点内 meta-data 配置（必须放在<application>内，且紧邻<activity>上方）

<application android:allowBackup="true" android:icon="@mipmap/ic_launcher" android:label="@string/app_name" android:theme="@style/AppTheme"> <!-- 【第一处校验】API_KEY 必须用 manifestPlaceholders 动态注入 --> <meta-data android:name="com.baidu.lbsapi.API_KEY" android:value="${BAIDU_MAP_API_KEY}" /> <!-- 【第二处校验】必须声明 service，否则定位无法启动 --> <service android:name="com.baidu.location.f" android:enabled="true" android:process=":remote" /> <activity android:name=".MainActivity" android:exported="true"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> </application>

关键点解析：

• android:value="${BAIDU_MAP_API_KEY}"必须与build.gradle中manifestPlaceholders的 key 完全一致，大小写敏感；
• <service>声明是 v5.6.0 新增强制项，漏掉则LocationClient初始化直接返回null；
• android:process=":remote"表示该 service 运行在独立进程，避免主进程 OOM 影响定位服务稳定性。

动态权限申请（运行时必须，非 Manifest 声明可替代）

仅声明权限不够。Android 6.0+ 必须在运行时请求ACCESS_FINE_LOCATION。在MainActivity.java的onCreate()前插入：

private static final int LOCATION_PERMISSION_REQUEST_CODE = 1001; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // 【第三处校验】首次启动必须检查并申请定位权限 if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) { ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, LOCATION_PERMISSION_REQUEST_CODE); } else { initMapView(); } } @Override public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) { super.onRequestPermissionsResult(requestCode, permissions, grantResults); if (requestCode == LOCATION_PERMISSION_REQUEST_CODE) { if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) { initMapView(); } else { Toast.makeText(this, "定位权限被拒绝，地图将无法显示定位点", Toast.LENGTH_SHORT).show(); } } }

为什么必须在这里做？
因为MapView.onCreate()内部会尝试初始化定位模块，若权限未授予，SDK 会静默失败，不抛异常，只在 logcat 打E/BaiduMapSDK: location permission denied—— 你根本看不到。

3. MapView 生命周期管理与地图加载：onCreate/onResume/onDestroy 的黄金三步法

MapView是重量级 View，其生命周期必须严格绑定 Activity 生命周期，否则轻则内存泄漏，重则 ANR。很多开发者把mapView.onCreate(null)写在onCreate()末尾就以为万事大吉，结果滑动地图时频繁 GC，甚至OutOfMemoryError。

3.1 标准生命周期方法调用链（必须逐个实现）

在MainActivity.java中，必须完整实现以下四个方法，且调用顺序不可颠倒：

public class MainActivity extends AppCompatActivity { private MapView mMapView; private BaiduMap mBaiduMap; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); mMapView = findViewById(R.id.bmapView); // 【关键】必须传入 savedInstanceState，否则地图状态无法恢复（如缩放级别、中心点） mMapView.onCreate(savedInstanceState); mBaiduMap = mMapView.getMap(); // 设置地图类型（普通/卫星/空白） mBaiduMap.setMapType(BaiduMap.MAP_TYPE_NORMAL); // 启用缩放控件（右下角 +/- 按钮） mBaiduMap.setZoomControlsEnabled(true); // 启用手势缩放（双指放大/缩小） mBaiduMap.getUiSettings().setZoomGesturesEnabled(true); } @Override protected void onResume() { super.onResume(); // 【关键】onResume 必须调用，否则地图纹理无法刷新，出现黑块或闪烁 mMapView.onResume(); } @Override protected void onPause() { super.onPause(); // 【关键】onPause 必须调用，释放 GPU 纹理资源 mMapView.onPause(); } @Override protected void onDestroy() { super.onDestroy(); // 【关键】onDestroy 必须调用，否则 MapView 持有 Activity 引用导致内存泄漏 mMapView.onDestroy(); } }

参数与逻辑说明：

• mMapView.onCreate(savedInstanceState)的savedInstanceState不能为null，否则地图状态（如用户上次缩放级别）丢失；
• onResume()和onPause()是 GPU 渲染线程开关，漏掉onResume()会导致地图区域变灰、触摸无响应；
• onDestroy()是唯一能彻底释放MapView内存的入口，不调用则 Activity 销毁后MapView仍驻留内存，LeakCanary 会报警。

3.2 地图加载失败的实时诊断：Logcat 过滤与关键日志含义

当MapView白屏或卡顿，不要盲目重启 AS。打开 Logcat，设置过滤器为BaiduMapSDK，重点关注以下三类日志：

血泪经验：某图像处理 Demo 在华为 P30 Pro 上白屏，Logcat 显示texture create failed，最终发现是MapView被包裹在NestedScrollView中——ScrollView强制软件渲染，关闭硬件加速导致纹理创建失败。解决方案：移除ScrollView，改用ConstraintLayout+ScrollView外部嵌套。

3.3 地图交互增强：点击、长按、缩放回调的可靠注册方式

SDK 提供的setOnMapClickListener等回调，默认在主线程执行，但存在两个陷阱：一是回调可能为空（未初始化完成），二是LatLng坐标需手动转为屏幕像素。以下是生产环境验证过的写法：

// 在 initMapView() 方法末尾添加 mBaiduMap.setOnMapClickListener(new BaiduMap.OnMapClickListener() { @Override public void onMapClick(LatLng latLng) { // 【安全写法】先判断地图是否 ready if (mBaiduMap == null || !mBaiduMap.isMapLoaded()) return; // 将地理坐标转为屏幕坐标（用于弹窗定位） Point point = mBaiduMap.getProjection().toScreenLocation(latLng); Toast.makeText(MainActivity.this, String.format("点击位置：%.6f, %.6f", latLng.latitude, latLng.longitude), Toast.LENGTH_SHORT).show(); } @Override public boolean onMapPoiClick(MapPoi mapPoi) { // POI 点击回调，注意：需先调用 mBaiduMap.setMapStatus(MapStatusUpdateFactory.zoomTo(15)) return false; } }); // 缩放级别变化监听（用于动态加载 POI） mBaiduMap.setOnMapStatusChangeListener(new BaiduMap.OnMapStatusChangeListener() { @Override public void onMapStatusChangeStart(MapStatus mapStatus) { // 缩放开始前 } @Override public void onMapStatusChange(MapStatus mapStatus) { // 缩放中（高频触发，慎用耗时操作） } @Override public void onMapStatusChangeFinish(MapStatus mapStatus) { // 缩放结束，此时可安全发起 POI 检索 double zoomLevel = mapStatus.zoom; if (zoomLevel > 14) { searchNearbyPOI(mapStatus.target); } } });

关键保障点：

• 所有回调前加if (mBaiduMap != null && mBaiduMap.isMapLoaded())判空，避免NullPointerException；
• onMapStatusChangeFinish()是唯一适合触发网络请求的时机，onMapStatusChange()触发太频繁，易造成请求风暴。

4. 定位功能落地：从 Service 初始化到位置回调的端到端链路

百度地图 SDK 的定位不是调用getLastKnownLocation()就完事。它依赖独立的LocationClient服务进程，且与BaiduMap的MyLocationConfiguration必须协同工作。很多开发者卡在“定位图标不显示”或“onReceiveLocation()不回调”，本质是服务未启动或配置未对齐。

4.1 LocationClient 初始化与 Service 绑定

LocationClient必须在Application或Activity的onCreate()中初始化，且需指定LocationClientOption。以下是某跨平台系统中稳定运行的初始化模板：

private LocationClient mLocationClient; private MyLocationListener myLocationListener; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); initMapView(); // 初始化定位客户端 mLocationClient = new LocationClient(getApplicationContext()); myLocationListener = new MyLocationListener(); mLocationClient.registerLocationListener(myLocationListener); // 配置定位参数 LocationClientOption option = new LocationClientOption(); option.setOpenGps(true); // 打开 GPS option.setCoorType("bd09ll"); // 返回百度经纬度坐标 option.setScanSpan(5000); // 5秒定位一次 option.setIsNeedAddress(true); // 需要地址信息 option.setNeedDeviceDirect(true); // 需要设备方向 option.setLocationMode(LocationClientOption.LocationMode.Hight_Accuracy); // 高精度模式 mLocationClient.setLocOption(option); // 【关键】必须 start() 才真正启动服务 if (!mLocationClient.isStarted()) { mLocationClient.start(); } } // 自定义定位监听器 public class MyLocationListener implements BDAbstractLocationListener { @Override public void onReceiveLocation(BDLocation location) { if (location == null || mBaiduMap == null) return; // 【关键】必须用 SDK 提供的工具类转换坐标系 LatLng ll = new LatLng(location.getLatitude(), location.getLongitude()); // 构造定位数据 MyLocationData locData = new MyLocationData.Builder() .accuracy(location.getRadius()) .direction(location.getDirection()) .latitude(location.getLatitude()) .longitude(location.getLongitude()) .build(); // 应用定位数据到地图 mBaiduMap.setMyLocationData(locData); // 【关键】必须设置定位图层配置，否则图标不显示 MyLocationConfiguration config = new MyLocationConfiguration( MyLocationConfiguration.LocationMode.NORMAL, // 普通定位模式 true, // 是否允许定位覆盖物 null // 定位图标（null 使用默认蓝点） ); mBaiduMap.setMyLocationConfiguration(config); mBaiduMap.setMyLocationEnabled(true); // 启用定位图层 } }

参数深挖：

• setScanSpan(5000)：值越小定位越频繁，但耗电剧增；生产环境建议 ≥ 10000（10秒）；
• setLocationMode(Hight_Accuracy)：混合定位（GPS+基站+WiFi），比Battery_Saving更准，比Device_Sensors更稳；
• setCoorType("bd09ll")：必须设为bd09ll，否则坐标偏移 500 米以上（WGS84 或 GCJ02 均不兼容）。

4.2 定位图层显示控制与图标自定义

默认蓝点太丑？想换成自定义图标？必须通过MyLocationConfiguration控制，且图标必须是BitmapDescriptor：

// 加载自定义定位图标（推荐 48x48 dp） BitmapDescriptor customIcon = BitmapDescriptorFactory.fromResource(R.drawable.ic_location_custom); MyLocationConfiguration config = new MyLocationConfiguration( MyLocationConfiguration.LocationMode.FOLLOWING, // 跟随模式（地图随定位点移动） true, customIcon ); mBaiduMap.setMyLocationConfiguration(config);

注意：FOLLOWING模式下，地图会自动平移至定位点，若不想自动居中，改用NORMAL；COMPASS模式则显示方向罗盘（需setNeedDeviceDirect(true)）。

4.3 定位失败排查表：从 Logcat 到真机设置的五层穿透

当onReceiveLocation()从未回调，请按以下顺序逐层排查（跳过任意一层都可能浪费 2 小时）：

5. 避坑指南：五个高频翻车现场与后悔药清单

这些坑，我都在某高校地理信息系统课程开发中亲手踩过，每一条都附带「现象 → 原因 → 解决」闭环，照着做能省下至少 3 小时 debug 时间。

5.1 现象：地图能显示，但缩放/拖动后立即黑屏，Logcat 刷E/Surface: queueBuffer: error queuing buffer to Surface

原因：MapView被嵌套在ScrollView或NestedScrollView中，导致 GPU 渲染上下文被破坏。ScrollView强制使用软件渲染，而MapView依赖硬件加速的 OpenGL ES 上下文。
解决：立即将MapView移出ScrollView，改用ConstraintLayout作为根布局。若必须滚动，用ScrollView包裹其他 UI 元素，MapView单独置于ScrollView外部，并用android:layout_below定位。

5.2 现象：真机上地图正常，模拟器（AVD）白屏，Logcat 显示E/libEGL: call to OpenGL ES API with no current context

原因：Android Studio 自带模拟器默认关闭 GPU 加速，或显卡驱动不兼容。百度地图 SDK 的MapView依赖 OpenGL ES 2.0+，无上下文则无法绘制。
解决：

1. 创建 AVD 时，Emulated Performance → Graphics必须选Hardware - GLES 2.0；
2. 启动 AVD 前，在~/.android/emulator.ini中添加gpu.mode = swiftshader_indirect；
3. 终极方案：放弃模拟器，用真机调试（华为/小米/OPPO 均已预装百度地图服务，兼容性最佳）。

5.3 现象：onReceiveLocation()回调中location.getLatitude()恒为 0.0，getLocType()返回 65（离线定位）

原因：LocationClientOption.setCoorType()未设置，或设为gcj02/wgs84，导致 SDK 内部坐标转换失败，返回默认原点（0,0）。
解决：在LocationClientOption配置中必须显式调用option.setCoorType("bd09ll")，且该行必须在mLocationClient.setLocOption(option)之前。bd09ll是百度专有坐标系，不可替换。

5.4 现象：地图缩放级别无法超过 18 级，拖动到边界时自动回弹

原因：MapView默认启用了地图边界限制（setRestrictBounds()），且未配置自定义边界。v5.6.0 将中国国界设为默认限制范围。
解决：在initMapView()后添加：

// 移除默认边界限制（允许全球范围缩放） mBaiduMap.setRestrictBounds(null); // 或设置自定义边界（如仅限北京市） LatLngBounds bounds = new LatLngBounds.Builder() .include(new LatLng(39.4, 115.4)) .include(new LatLng(41.1, 117.5)) .build(); mBaiduMap.setRestrictBounds(bounds);

5.5 现象：App 启动后内存占用飙升至 200MB+，MapView销毁后不回落

原因：MapView.onDestroy()未调用，或调用时机错误（如在onDestroyView()中调用，但Activity未销毁）。MapView持有大量 native 内存（纹理、瓦片缓存），Java 层 GC 无法回收。
解决：

1. 确保mMapView.onDestroy()只在Activity.onDestroy()中调用一次；
2. 在onDestroy()中添加日志：Log.d("MAP", "MapView onDestroy called");，确认执行；
3. 使用 Android Profiler → Memory → Capture Heap Dump，筛选MapView实例，确认数量为 0。

6. 进阶技巧：离线地图预加载、自定义瓦片、以及我每次上线前必做的三件事

做到地图能显示、定位能回调，只是及格线。真正让 App 在弱网、地铁、山区可用，需要离线能力；让地图风格匹配品牌 VI，需要自定义瓦片；而保证每次发版不翻车，则靠一套机械化的上线前 checklist。这些不是文档里的“可选功能”，而是某跨平台系统在 30 万 DAU 下稳定运行的压舱石。

6.1 离线地图预加载：让地铁里也能看北京二环

百度地图 SDK 支持离线地图下载，但官方 API 文档藏得太深。核心是MKOfflineMap类，它与MapView解耦，可独立运行：

private MKOfflineMap offlineMap; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); initMapView(); // 初始化离线地图管理器 offlineMap = new MKOfflineMap(); offlineMap.init(this, new MKOfflineMapListener() { @Override public void onGetOfflineMapState(int i, int i1) { switch (i) { case MKOfflineMap.MK_OFFLINE_MAP_STATE_FINISH: Log.d("OFFLINE", "下载完成，城市ID：" + i1); break; case MKOfflineMap.MK_OFFLINE_MAP_STATE_UPDATE: Log.d("OFFLINE", "更新进度：" + i1 + "%"); break; } } }); // 【关键】预加载北京离线包（城市ID 1305，可通过 MKOfflineMap.getHotCityList() 获取） offlineMap.start(1305); }

参数说明：

• start(cityID)：城市 ID 需通过offlineMap.getHotCityList()查询，北京是1305，上海1310，广州1315；
• onGetOfflineMapState()的i1参数：i==1为下载完成，i==2为更新中，i1为百分比；
• 离线包默认存于/sdcard/baiduMap/offline/，大小约 200MB（北京全境），建议在 WiFi 环境下静默下载。

实战教训：某导师在课堂演示时用 4G 下载北京离线包，耗时 28 分钟，学生手机发热关机。现在我的做法是：App 首次启动时检测网络类型，仅在 WiFi 下自动调用start(cityID)，并在设置页提供手动触发入口。

6.2 自定义瓦片图层：用企业地图替换百度底图

若你的业务需要展示内部园区、工厂管线、物流仓库等私有地理数据，必须用TileOverlay替换默认底图。百度 SDK 支持UrlTileProvider，但要求瓦片 URL 符合x/y/z规则：

// 假设你的瓦片服务地址为 https://tile.yourcompany.com/{z}/{x}/{y}.png public class CustomTileProvider extends UrlTileProvider { public CustomTileProvider() { super(256, 256); // 瓦片尺寸必须为 256x256 } @Override public URL getTileUrl(int x, int y, int z) { try { String url = String.format("https://tile.yourcompany.com/%d/%d/%d.png", z, x, y); return new URL(url); } catch (MalformedURLException e) { return null; } } } // 添加到地图 TileOverlayOptions tileOverlayOptions = new TileOverlayOptions(); tileOverlayOptions.tileProvider(new CustomTileProvider()); tileOverlayOptions.zIndex(10); // 置于所有图层之上 mBaiduMap.addTileLayer(tileOverlayOptions);

关键约束：

• 瓦片坐标系必须为Web Mercator（EPSG:3857），z从 0（全球）到 18（街道级）；
• x/y计算公式：n = 2^z，x ∈ [0, n-1]，y ∈ [0, n-1]；
• 若瓦片服务返回 404，SDK 会自动用灰色占位图，不影响地图交互。

6.3 上线前必做的三件事：我的发布 Checklist

每次发版前，我都会强制自己走一遍这三步，哪怕加班到凌晨。它们不是流程，而是防止线上事故的物理隔离：

1. 真机弱网压测：

   • 用 Android Studio 的 Network Link Conditioner（或第三方工具如Clumsy）模拟 2G 网络（100ms 延迟，10% 丢包）；
   • 启动 App，反复进出地图页 5 次，观察MapView是否白屏、定位是否超时（>15s）、Logcat 是否有timeout日志；
   • 不通过则回滚，绝不抱侥幸心理。

2. 内存泄漏扫描：

   • 在MapView页面停留 2 分钟，触发adb shell dumpsys meminfo com.example.baidumapdemo；
   • 对比Views数量：正常应 ≤ 50，若 > 200 则存在MapView未销毁；
   • 用 LeakCanary 截图，确认MapView实例数为 0。

3. AK 密钥环境隔离：

   • build.gradle中manifestPlaceholders必须区分debug和release：

     buildTypes { debug { manifestPlaceholders = [BAIDU_MAP_API_KEY: "debug_ak_xxx"] } release { manifestPlaceholders = [BAIDU_MAP_API_KEY: "release_ak_yyy"] } }

   • 百度开放平台为 debug 和 release 包名分别生成 AK，混用会导致invalid API_KEY。

从那以后我每次发版前，都强制走一遍这三步——不是为了显得严谨，而是某次跳过弱网测试，上线后地铁用户投诉“地图打不开”，客服电话被打爆。希望帮到你。

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