Android 百度地圖開發：真機調試只顯示網格無建築物的常見原因與解決方案

現象描述

使用百度地圖 SDK 進行真機調試時，地圖區域僅顯示灰白網格背景，不加載任何地圖瓦片 (道路、建築物、POI 等)，但模擬器或部分機型正常。

核心原因排查清單

1. SHA1 簽名與包名不匹配 (最常見)：
   • 百度地圖 Key 綁定的是**發布版簽名**的 SHA1，而調試時使用的是 **Debug 簽名** (Android Studio 默認 debug.keystore)。
   • 解決：在百度地圖開放平台控制台，為同一個 Key 同時添加 **Debug 簽名 SHA1** 和 **Release 簽名 SHA1**，包名保持一致。
2. 網絡權限缺失：

   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

3. Meta-data 配置錯誤：AndroidManifest.xml 中 <application> 內缺少或 Key 錯誤：

   <meta-data
       android:name="com.baidu.lbsapi.API_KEY"
       android:value="您的AK" />

4. so 庫架構不匹配：項目引入的 libs/armeabi-v7a / arm64-v8a 下的 libBaiduMapSDK_map.so 等與設備 CPU 架構不兼容。建議在 build.gradle 配置 ndk.abiFilters 指定支持架構。
5. 包名不一致：Manifest 包名、build.gradle applicationId、百度 Key 綁定包名三者必須**完全一致** (區分大小寫)。
6. 設備系統/安全策略：部分國產 ROM (華為、小米、OPPO 等) 預設限制應用訪問網絡或讀取存儲，需在設置中手動授權「數據網絡」、「存儲權限」。

「打包運行就有地圖」的深層原因

題主提到「打包運行就有地圖」，這確切證明了 **Debug 簽名未授權**。打包生成的 APK 使用 Release 簽名，其 SHA1 已在百度後台配置，故驗證通過；而直接 Run 使用 Debug 簽名，SHA1 未授權，SDK 拒絕下發瓦片數據，只渲染空白網格。

一鍵獲取 SHA1 命令

# Debug 簽名 (默認密鑼 android)
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

# Release 簽名 (替換路徑/別名/密碼)
keytool -list -v -keystore /path/to/release.jks -alias your_alias -storepass your_store_pass -keypass your_key_pass

Gradle 統一簽名配置 (推薦)

android {
    signingConfigs {
        release {
            storeFile file("release.jks")
            storePassword "store_pass"
            keyAlias "key_alias"
            keyPassword "key_pass"
        }
        debug {
            storeFile file("debug.keystore") // 可選：統一使用自定義 debug 密鑼
            storePassword "android"
            keyAlias "androiddebugkey"
            keyPassword "android"
        }
    }
    buildTypes {
        release { signingConfig signingConfigs.release }
        debug { signingConfig signingConfigs.debug } // 關鍵：讓調試也使用固定簽名
    }
}

總結

真機只顯示網格 99% 是 **SHA1 簽名未授權**。請在百度地圖控制台為該 Key 添加 **Debug 簽名 SHA1**，或在 Gradle 中配置固定 Debug 簽名並授權該 SHA1。同時檢查權限、Meta-data、包名、so 庫架構。