Android发布APK无法使用Google API及显示地图，调试版正常如何解决？

API 探路者

2026-5-15

这种情况我在开发中碰到过好多次，十有八九是发布版的签名配置或者Google API密钥的设置出了问题，下面给你一步步拆解排查：

1. 给发布版的SHA-1指纹授权Google API密钥

调试版和发布版用的是完全不同的签名密钥，所以它们的SHA-1指纹也不一样。你之前能正常用调试版，说明调试版的SHA-1已经加到API密钥的允许列表里了，但发布版的还没加。

获取发布版SHA-1的方法：打开终端，执行keytool -list -v -keystore 你的发布密钥库路径.jks -alias 你的密钥别名，输入密钥库密码后就能看到SHA-1值。

然后去Google Cloud控制台找到你的API密钥，在「应用限制」里选择「Android应用」，添加发布版的包名和刚才获取的SHA-1指纹，保存更改。

2. 确认build.gradle中发布版的签名配置正确

很多开发者会在debug块里配置签名，但忽略了release块，导致发布版用的是默认的调试签名（或者干脆没签名）。检查app模块的build.gradle，确保release类型指向了正确的签名配置：

android {
    signingConfigs {
        release {
            storeFile file("your-release-keystore.jks") // 你的发布密钥库路径
            storePassword "your-store-password"
            keyAlias "your-key-alias"
            keyPassword "your-key-password"
        }
    }

    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled true // 如果开启了混淆，下面要配置规则
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

如果是用Android Studio的「Generate Signed Bundle/APK」向导生成的APK，要确认向导里选的是正确的密钥库和别名。

3. 检查API密钥的应用限制是否准确

除了SHA-1，还要确认包名有没有写错——有时候发布版的包名和调试版不一样（比如加了后缀），这也会导致API密钥验证失败。另外，API密钥的限制类型一定要选「Android应用」，不能选其他类型（比如HTTP限制），否则Android应用无法正常调用。

4. 确保发布版启用了所需的Google API

虽然调试版能正常用，但要确认你的Google Cloud项目里，Maps SDK for Android、Geocoding API（如果用到的话）等相关API都是「已启用」状态。去Google Cloud的API库搜索对应的API，检查状态，没启用的话点击「启用」即可。

5. 配置ProGuard/R8混淆规则避免破坏Google API类

发布版开启混淆后，如果没有正确配置规则，Google Maps的核心类可能会被混淆，导致运行时崩溃或功能失效。在proguard-rules.pro里添加以下规则：

# Google Maps相关混淆规则
-keep class com.google.android.gms.** { *; }
-keep interface com.google.android.gms.** { *; }
-dontwarn com.google.android.gms.**

# 针对Maps SDK的额外保护
-keep class com.google.android.gms.maps.** { *; }
-keep interface com.google.android.gms.maps.** { *; }
-keep class com.google.maps.android.** { *; }

R8默认会兼容大部分Google库，但手动加上这些规则更保险。

6. 查看发布版日志定位具体错误

如果上面的步骤都试过还是不行，那就得看发布版的错误日志。用USB连接设备，执行adb logcat *:E过滤错误信息，重点找包含「GoogleMaps」「API key」「Signature」的日志，比如“API key not valid. Please pass a valid API key.”或者“Invalid signature.”，这些提示会直接告诉你问题所在。

按照这些步骤一步步排查，基本都能解决发布版无法使用Google API和地图的问题，我之前帮好几个开发者搞定过类似的情况，你试试吧！

内容的提问来源于stack exchange，提问作者marwa ben ali