为何Maps API仅在模拟器可用却无法在真实设备正常运行？

一、API密钥重复输入的原因 #

你的local.properties应该是被加入了.gitignore文件，所以GitHub不会同步这个文件，每次拉取项目都得重新填写。这是常规的安全操作，防止密钥泄露，但确实会带来重复输入的麻烦。

二、真实设备地图空白的原因及解决 #

这两个问题直接相关，真实设备上地图空白很大概率是因为APP没正确读取到local.properties里的API密钥，导致Maps API鉴权失败。另外还有其他排查方向：

1. 验证API密钥的配置逻辑 #

检查项目是否正确从local.properties读取密钥并注入到Manifest或build.gradle：

• 在模块级build.gradle中，确保有读取逻辑：

def localProperties = new Properties()
def localPropertiesFile = rootProject.file('local.properties')
if (localPropertiesFile.exists()) {
    localPropertiesFile.withReader('UTF-8') { reader ->
        localProperties.load(reader)
    }
}

android {
    defaultConfig {
        manifestPlaceholders = [
                MAPS_API_KEY: localProperties.getProperty('MAPS_API_KEY') ?: ''
        ]
    }
}

• 然后在AndroidManifest.xml中引用占位符：

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

配置错误的话，真实设备上APP拿不到密钥，地图自然空白。

2. 检查API密钥的权限限制 #

登录Google Cloud控制台，确认密钥的应用限制是否正确：

• 模拟器和真实设备的签名可能不同（比如模拟器用debug签名，真实设备如果打release包用正式签名），如果密钥只允许debug签名的应用访问，真实设备的release包就会被拒绝。
• 务必添加真实设备对应的签名证书SHA-1和应用包名到密钥的允许列表中。

3. 确认Maps SDK已启用 #

在Google Cloud控制台，检查Maps SDK for Android是否已经启用，没启用的话，不管密钥对不对，地图都会空白。

4. 检查网络权限 #

确保AndroidManifest.xml里加了必要的网络权限：

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

真实设备没网络或者权限没开，也会加载空白地图。

三、优化密钥管理，避免重复输入 #

• 复制local.properties为local.properties.example，里面写上占位符（比如MAPS_API_KEY=your_api_key_here），把这个示例文件提交到GitHub。之后每次拉取项目，只需要复制示例文件重命名为local.properties，再填入密钥即可。
• 永远不要把真实的local.properties提交到Git，保持它在.gitignore中，防止密钥泄露。

内容的提问来源于stack exchange，提问作者Quaresma