博客

Play 管理中心「在调试模式下签名 / 必须签名」解决办法

解决 Play 管理中心上传 .aab 报错「在调试模式下签名」「所有上传的软件包都必须签名」与「可调试」,附 Flutter、原生、Expo 与 Unity 解法。

在本地用 release 模式顺利打出 Android App Bundle(.aab),并不代表它已经符合 Google Play 的签名要求。不少框架新建工程时,要么完全没给 release 配置签名,要么为了方便本地直接运行,默认把 release 绑在了系统自带的 debug.keystore 上——直到你进入 Google Play 管理中心(Play Console)的创建发布版本页面,把 .aab 拖进 app bundle 上传框,下方立刻弹出一行红字拦截。

Play 管理中心「创建封闭式测试版本」页面:上传 app-debug.aab 时提示「所有上传的软件包都必须签名。」

上传框下方最常出现的其实是三条长得很像的姊妹报错,对应三种不同原因:

  • 使用了默认调试密钥签名(androiddebugkey):

    您上传的是在调试模式下签名的 APK 或 Android App Bundle。请在发布模式下为 APK 或 Android App Bundle 签名。

  • 软件包完全没有签名:

    所有上传的软件包都必须签名。

    (若通过 Fastlane 或 CI 调用 API 上传,英文原文为 The Android App Bundle was not signed.)

  • 清单开启了可调试属性(android:debuggable="true"):

    您上传的是可调试的 APK 或 Android App Bundle。出于安全考虑,您需要先停用调试功能,然后才能在 Google Play 中进行发布。

下面按步骤生成一个合规的 .jks 上传密钥库,并分别给出 Flutter、Android Studio、Expo / React Native 与 Unity 的标准配置。

1生成合规的上传密钥库(.jks)

除非你使用云端打包的 Expo EAS(会自动在云端生成并托管密钥),否则先用 Android Studio 自带 JDK 里的 keytool 生成独立的上传密钥库:

keytool -genkeypair -v -keystore upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload

跑这条命令时有两个细节最容易踩坑:

  • 切勿漏写 -validity 10000:如果不加 -validity 参数,keytool 默认生成的证书有效期只有 90 天。而 Google Play 强制要求签名证书有效期必须持续到 2033 年 10 月 22 日之后,否则重传会立刻报第二条错:

    您上传的 APK 或 Android App Bundle 所使用的签名证书不久就会过期,请使用有效期更长的证书为 APK 或 Android App Bundle 签名。

    显式加上 -validity 10000(约 27 年)和 -keyalg RSA -keysize 2048,就能一次通过有效期和密钥强度检查。

  • 立刻备份 upload-keystore.jks 与密码:当你上传第一个签好名的 .aab 后,Play 应用签名计划就会把这张证书的 SHA-1 指纹永久绑定为该应用的上传密钥。日后换电脑弄丢文件或不小心重生成新 .jks,更新版本时就会被拒——详见签名密钥不正确(SHA-1 不匹配)与 48 小时重置指南。

2Flutter:替换默认的 debug 签名配置

Flutter 新手遇到「在调试模式下签名」的概率最高——因为 flutter create 初始化工程时,故意在 buildTypes.release 里写了一行 signingConfig = signingConfigs.getByName("debug"),好让开发者不配密钥也能跑通 flutter run --release。结果执行 flutter build appbundle --release 时本地零报错出包,里面签的却是 debug.keystore。

第一步 — 放置密钥库并新建 android/key.properties

把 upload-keystore.jks 放进 android/app/upload-keystore.jks(或者放在代码仓库外的安全目录,写完整路径时即使在 Windows 上也要用正斜杠 /),然后在 android/ 目录下新建 android/key.properties:

storePassword=你的密钥库密码
keyPassword=你的密钥密码
keyAlias=upload
storeFile=upload-keystore.jks

(注意:android/app/build.gradle.kts 里的相对路径 storeFile 是相对于 android/app/ 目录解析的,不是 android/。)

第二步 — 把密钥配置加入 .gitignore

提交代码前,先把敏感文件排除在 Git 之外:

**/android/key.properties
**/*.jks
**/*.keystore

第三步 — 修改 android/app/build.gradle.kts

打开 android/app/build.gradle.kts,在顶部读取 key.properties,并把 buildTypes.release 的签名从 "debug" 改成 "release":

import java.util.Properties

val keystoreProperties = Properties()
val keystorePropertiesFile = rootProject.file("key.properties")
if (keystorePropertiesFile.exists()) {
    keystorePropertiesFile.inputStream().use { keystoreProperties.load(it) }
}

android {
    // ...
    signingConfigs {
        create("release") {
            keyAlias = keystoreProperties.getProperty("keyAlias")
            keyPassword = keystoreProperties.getProperty("keyPassword")
            storeFile = keystoreProperties.getProperty("storeFile")?.let { file(it) }
            storePassword = keystoreProperties.getProperty("storePassword")
        }
    }

    buildTypes {
        getByName("release") {
            signingConfig = signingConfigs.getByName("release")
        }
    }
}

(如果老项目用的是 Groovy 语法的 android/app/build.gradle,则在 signingConfigs 中定义 release 块后,把 buildTypes.release 里的 signingConfig signingConfigs.debug 改为 signingConfig signingConfigs.release。)

第四步 — 清理缓存并重新打包

flutter clean
flutter build appbundle --release

打包完成后,上传 build/app/outputs/bundle/release/app-release.aab。

3Android Studio、Expo 与 React Native

Android Studio(原生 Kotlin / Java)

在未配置 signingConfig 的情况下直接点菜单 Build > Generate App Bundles or APKs > Generate App Bundle(s)(旧版为 Build Bundle(s) / APK(s) > Build Bundle(s)),打出来的 app-release.aab 是未签名状态(触发 所有上传的软件包都必须签名。)。任选以下一种方式即可:

  • 图形向导导出:点击 Build > Generate Signed App Bundle or APK → 选择 Android App Bundle → 选中 upload-keystore.jks 与 upload 别名 → 选择 release 构建变体。
  • Gradle 命令行 / CI 自动签名:参照上一节把 signingConfigs 和 buildTypes.release 写进 app/build.gradle.kts,之后每次执行 ./gradlew bundleRelease 都会在 app/build/outputs/bundle/release/ 下生成已签名的包。

Expo(EAS Build)

使用 production 配置打包,EAS 会在云端自动生成并托管 2048 位的上传密钥:

eas build --platform android --profile production

切勿上传用 --profile development 或本地 npx expo run:android 打出的开发包(这类包自带调试客户端与 debug.keystore),同时检查 eas.json 的 production 里没有写 "buildType": "apk"。

纯 React Native(不使用 EAS)

和 Flutter 一样,React Native 模板默认在 android/app/build.gradle 的 buildTypes.release 里写了 signingConfig signingConfigs.debug。在 gradle.properties 中配置密钥信息、在 signingConfigs 新增 release 并将 buildTypes.release.signingConfig 指向 signingConfigs.release,再进入 android/ 目录运行 ./gradlew bundleRelease 即可。

4Unity:配置 Custom Keystore 并关闭 Development Build

Unity 把正式签名和调试开关放在两个不同的窗口里,漏掉任意一处都会被后台拒收:

  1. 开启正式密钥库签名:打开 Edit > Project Settings > Player(切到 Android 标签页)> Publishing Settings,勾选 Custom Keystore,选择刚才生成的 upload-keystore.jks(或通过 Keystore Manager 创建),选定 upload 别名并填入密码。
  2. 关闭开发构建并输出 .aab:打开 File > Build Settings(Unity 6 为 Build Profiles),勾选 Build App Bundle (Google Play),并取消勾选 Development Build(以及 Script Debugging)。

5还是提示「可调试的 APK 或 Android App Bundle」?查这 3 处

明明已经换上了正式 .jks 签名,上传时却依然弹出 您上传的是可调试的 APK 或 Android App Bundle……,逐一核对下面三处:

  1. 传错了构建目录:同时跑过调试包和正式包时,硬盘上会并存两个 .aab。确认你在上传框里选的是 bundle/release/app-release.aab,而不是 bundle/debug/app-debug.aab。
  2. AndroidManifest.xml 里写死了 debuggable:打开 android/app/src/main/AndroidManifest.xml,删掉 <application> 标签上手写的 android:debuggable="true",并确认 buildTypes.release 里没有设置 isDebuggable = true(debuggable true)。
  3. 残留开发构建开关:确认 Unity 已取消勾选 Development Build,或者 Expo 的 eas.json 打包配置里没有带 "developmentClient": true。

上传前 2 秒本地自检:在终端运行 jarsigner -verify -verbose -certs app-release.aab。如果输出里出现 CN=Android Debug,说明打包脚本拿到的还是默认调试密钥;看到你自己的证书信息且末尾显示 jar verified.(中文 JDK 为 jar 已验证。),就可以放心上传了。

签名通过了,下一步是什么?

当 .aab 顺利通过步骤 1(创建发布版本)后,点下一步进入预览并确认。如果又被其他规则拦住——例如版本代码已被使用、16 KB 内存页面大小对齐、AD_ID 广告 ID 权限冲突,或是看到缺少去混淆文件与原生调试符号的黄色警告——可以直接对照总表 Play 管理中心上传 AAB 报错汇总:常见原因与解决办法 逐项排查;后续换电脑发更新前也建议先收藏签名密钥不正确(SHA-1 不匹配)指南。

对于个人开发者账号,把第一个封闭式测试版本发出去后,真正的硬仗才刚开始:招募至少 12 名测试人员连续参与满 14 天,才能申请正式版发布权限——具体判定规则见 12 名测试人员、14 天:「连续」到底是什么意思。

与其到处发帖拉人、挨个维护群组名单,不如在 BetaLobby(完全免费,无付费套餐)加入 16 人组队模式:全员共用同一个 Google 群组,人齐统一开测,在 Android 真机上免截图验证互装,并完成 14 天每日打卡。