第一次往 Google Play 管理中心(Play Console)上传 Android App Bundle(.aab)时,很少有人能一把过。哪怕工程在本地打包零报错,Play 管理中心也会额外校验签名密钥、软件包名称、版本代码、原生 .so 库的 16 KB 对齐以及清单权限声明。

留意页面顶部的两个步骤,不同类型的报错会出现在不同位置:
- 步骤 1 — 创建发布版本:把
.aab拖进 app bundle 上传框的瞬间就会校验。未签名、调试模式签名、误传.apk、包名受限或版本代码重复,都会直接在上传框下方报红字。 - 步骤 2 — 预览并确认:填完版本信息点下一步后才会集中拦截。目标 API 级别(
35/36)、16 KB 内存页面大小对齐、64 位原生代码、未完成声明的敏感权限(如AD_ID广告 ID、前台服务、选图权限),以及两条经常吓住新手的黄色警告都在这一步显示。
可以用下面的速查表直接跳到对应章节,或者按 Ctrl+F(Cmd+F)搜索后台显示的报错原话。
| 后台显示的报错 / 警告关键词 | 出现位置 | 快速跳转 |
|---|---|---|
所有上传的软件包都必须签名 / 调试模式下签名 / 可调试的 APK |
步骤 1:上传框 | 第 1 节 |
使用的签名密钥不正确(SHA1)/ 签名证书不久就会过期 / 重置冷却期 |
步骤 1:上传框 | 第 2 节 |
"com.example" is restricted / 软件包名称必须为 / 包名已被占用 |
步骤 1:上传框 | 第 3 节 |
已有版本使用了版本代码 / 不允许任何现有用户升级 |
步骤 1 & 步骤 2 | 第 4 节 |
请重新编译您的应用,使原生库针对 16 KB 对齐 / 不支持 16 KB |
步骤 2:预览并确认 | 第 5 节 |
目标 API 级别必须最低为 35(36)/ 64 位版本 / 200 MB |
步骤 1 & 步骤 2 | 第 6 节 |
com.google.android.gms.permission.AD_ID / 尚未在 Play 管理中心内声明的权限 |
步骤 2:预览并确认 | 第 7 节 |
没有与此 App Bundle 关联的去混淆文件 / 尚未上传调试符号文件 |
步骤 2:黄色警告 | 第 8 节 |
在声明中将硬件功能标记为必需(android.hardware.screen.portrait / Android XR) |
发布概览:送审前 | 第 9 节 |
1未签名、调试模式签名或可调试包
纯新手第一次传包最容易栽在这里——尤其是 Flutter、React Native 和 Unity 项目,本地跑 release 命令打出来的包,默认可能依然带着调试配置。
软件包未签名
所有上传的软件包都必须签名。
(若通过 Fastlane 等 API 工具上传,英文报错为 The Android App Bundle was not signed.)
- 原因:
.aab里没有任何签名信息(比如未配置signingConfig就直接命令行跑./gradlew bundleRelease,或 CI 环境漏掉了key.properties)。 - 解决:Android Studio 用菜单 Build > Generate Signed App Bundle or APK 选择
release导出,或在app/build.gradle的buildTypes.release中绑定signingConfigs.release;Expo 使用eas build --platform android --profile production。
在调试模式下签名(androiddebugkey)
您上传的是在调试模式下签名的 APK 或 Android App Bundle。请在发布模式下为 APK 或 Android App Bundle 签名。
- 原因:Flutter 与 React Native 新手头号大坑。
flutter create新建工程时,默认在android/app/build.gradle(.kts)的release里写了signingConfig = signingConfigs.getByName("debug"),所以跑flutter build appbundle --release本地能顺利出包,但实际用的是系统默认的调试密钥。 - 解决:生成正式的
.jks上传密钥库,配置android/key.properties,并把buildTypes.release下的签名配置从debug改成自己的release配置后重新打包。
开启了可调试属性(android:debuggable="true")
您上传的是可调试的 APK 或 Android App Bundle。出于安全考虑,您需要先停用调试功能,然后才能在 Google Play 中进行发布。
- 原因:误传了
build/outputs/bundle/debug/app-debug.aab,在AndroidManifest.xml里手写了android:debuggable="true",或者在 Unity 的 File > Build Settings 中勾选了 Development Build。 - 解决:确认上传的是
bundle/release/目录下的产物,删掉清单里手写的debuggable属性,Unity 打包前取消勾选 Development Build。
误传了 .apk 文件或未启用 Play 应用签名
- 传了
.apk而非.aab(Upload a valid app bundle/自 2021 年 8 月起,新应用需要使用 Android App Bundle 才能在 Google Play 中发布。):新应用只收.aab。Flutter 请跑flutter build appbundle --release(不要跑build apk);Expo 删掉生产配置里的"buildType": "apk";Unity 勾选 Build App Bundle (Google Play)。 - 未启用应用签名计划(
此软件包未启用 Google Play 应用签名。您必须注册 Google Play 应用签名计划,才能上传 Android App Bundle。):常见于还没在网页后台点过发布向导,就先用 CI / API 推第一个包。先在浏览器打开 Play 管理中心进入一次创建发布版本页面即可自动完成注册。
完整的 keytool 生成命令,以及 Flutter(key.properties)、Android Studio、Expo 和 Unity 的正式签名配置步骤,见 Play 管理中心「在调试模式下签名 / 必须签名」解决办法。
2签名密钥不正确(SHA-1 不匹配)与证书问题
当你上传第一个签好名的 .aab 后,Play 管理中心就会把这张证书的 SHA-1 指纹锁定为该应用的上传密钥,后续所有更新版本都必须用同一个 .jks 签名。
签名密钥指纹不匹配(SHA1)
您的 Android App Bundle 使用的签名密钥不正确。请务必使用正确的签名密钥为您的 App Bundle 签名,然后重试。正常情况下应使用具有如下指纹的证书为该 App Bundle 签名: SHA1: <EXPECTED_SHA1>,但您上传的 App Bundle 所用的签名证书的指纹却是: SHA1: <ACTUAL_SHA1>
- 原因:换电脑弄丢了原
.jks、重新生成过密钥库、选错了密钥别名(alias),或中途从本地签名切换到了 EAS / CI 自动托管密钥。 - 解决:
- 在本地运行
keytool -list -v -keystore your.jks,找回指纹与<EXPECTED_SHA1>一致的原密钥库。 - 如果原上传密钥彻底找不回来了,不用作废应用:新建一个 2048 位的
.jks,导出 PEM 证书(keytool -export -rfc -keystore new.jks -alias upload -file upload_cert.pem),去后台 由 Google Play 提供保护 > Play 商店保护 > 管理 Google Play 应用签名(原「测试和发布 > 应用完整性」已迁至此),在上传密钥区域点击请求重置。
- 在本地运行
重置上传密钥后的 48 小时冷却期
You uploaded an app bundle that is signed with an upload certificate that is not yet valid because it has been recently reset. You will be able to upload app bundles again from <Date/Time> UTC.
- 解决:千万不要再重新生成密钥!重置上传密钥获批后有强制 48 小时安全冷却期,只需等到报错里写的 UTC 时间点过去,再原封不动上传同一个
.aab即可。
其他证书报错
- 证书有效期太短:
您上传的 APK 或 Android App Bundle 所使用的签名证书不久就会过期,请使用有效期更长的证书为 APK 或 Android App Bundle 签名。Google Play 要求证书有效期必须晚于 2033 年 10 月 22 日。命令行跑keytool -genkeypair不加-validity时默认只有 90 天,生成时请务必加上-validity 10000(约 27 年)。 - 证书尚未生效(
…signed with a certificate that is not yet valid…):生成密钥时电脑系统时间比标准 UTC 时间快,开启系统自动同步时间后重新生成新密钥库重签即可。 - 密钥强度太低:
您的 Android App Bundle 所使用的上传证书的密钥强度太低。使用了老旧的 1024 位密钥,请改用-keyalg RSA -keysize 2048重新生成。 - 部分文件签名无效或缺失:
您上传的 APK 或 Android App Bundle 的某些文件的签名信息无效或缺失。签名后又改动了压缩包内容,或误用了国内第三方壳加固工具。Google Play 会对.aab拆包重签分发,严禁对上传 Google Play 的包做第三方壳加固,执行clean重新打包即可。
如何用命令行核对本地密钥指纹、导出 PEM 证书并在后台重置上传密钥,见 Play 管理中心「使用的签名密钥不正确(SHA1)」解决办法。
3软件包名称错误(com.example 受限、不匹配或已被占用)
软件包名称(applicationId)在 Google Play 全局唯一,一旦在创建应用或首次传包时锁定就无法修改。
使用了受限制的默认包名
You need to use a different package name because "com.example" is restricted.
- 解决:到
app/build.gradle(.kts)(Expo 为app.json的expo.android.package,Unity 为 Player Settings > Other Settings > Package Name)把默认的com.example.*改成自己的反写域名包名(如com.yourbrand.app),若用了 Firebase 记得同步重新下载google-services.json。
与当前应用锁定的包名不一致
您的 APK 或 Android App Bundle 的软件包名称必须为“<com.yourcompany.app>”。
- 原因:传错了应用槽位、构建变体多加了
.debug/.staging等applicationIdSuffix后缀,或者后台建应用时填的包名与工程代码不一致。 - 解决:核对后台应用标题下方显示的包名,保证工程
applicationId与之一字不差;如果后台应用还没发布过任何版本但包名填错了,直接新建一个应用重来最快。
包名在 Google Play 上已被占用
You need to use a different package name because "<com.yourcompany.app>" already exists in Google Play.
(若是被自己账号下的另一个草稿应用占用,尾句为 …is already used by one of your other applications.)
- 原因:常见于未修改框架模板包名(如
io.ionic.starter)或起了太普通的包名。Google Play 的包名一旦被占用永久不会释放(哪怕原应用已下架),换一个唯一的新包名重新打包即可。
4版本代码已被使用与升级覆盖异常
Play 管理中心只认整数 versionCode(1、2、3……)来区分新旧构建,不看给用户展示的 versionName(1.0.0、1.0.1)。
版本代码已被使用
已有版本使用了版本代码“<X>”。请尝试改用其他版本代码。
- 原因:只要某个
.aab上传进过后台——哪怕当时点了「舍弃草稿版本」根本没发布,或者之前传在内部测试轨道里——它的versionCode就会在内容库里被永久占用。只把1.0.0改成1.0.1却忘了把整数版本号加 1,重传必报此错。 - 解决(分清两种情况):
- 代码没改,只是想复用刚传过的包(比如把内部测试测好的包发到封闭式测试,或恢复刚舍弃的草稿):不要重新上传本地文件,直接点上传框里的从内容库添加(Add from library),勾选刚才上传过的那个包即可。
- 改了代码重新打的新包:把整数版本号
+1再打包——Android Studio 改versionCode;Flutter 改pubspec.yaml里+号后面的数字(如version: 1.0.1+2);Expo 改android.versionCode;Unity 改 Bundle Version Code。
不允许现有用户升级(Version Shadowing)
您无法推出此版本,因为它不允许任何现有用户升级到新添加的应用程序包
- 原因:从内容库选了一个比当前轨道在架版本
versionCode更低的旧包、没往新版本里添加新包就点了下一步,或新包缩窄了minSdkVersion/ 硬件特性导致老用户无法升级。 - 解决:确保新包的
versionCode严格大于当前轨道在架的最高版本,并移除草稿里低版本的旧包。
「从内容库添加」的具体用法,以及 Flutter、Gradle、Expo、Unity 四种框架递增 versionCode 的配置位置,见 Play 管理中心「已有版本使用了版本代码」原因与解决办法。
516 KB 内存页面大小未对齐
对于目标 API 级别 ≥ 35(Android 15+)的应用,这是 2025–2026 年 Flutter、Unity、React Native、Uni-app 及原生开发者遇到最多的头号拦截:
请重新编译您的应用,使原生库针对 16 KB 对齐
您的应用所使用的原生库未经对齐处理,不支持采用 16 KB 内存页面大小的设备。这些设备可能无法安装或启动您的应用,或者您的应用可能会在启动后崩溃。
(在 App bundle 资源管理器或政策状态中也会显示为 不支持 16 KB 或 您的应用不支持 16 KB 内存页面大小。)
哪怕你一行 C/C++ 代码都没写,跨平台引擎(libflutter.so、libil2cpp.so、libreactnative.so)或相机、扫码、数据库插件里自带的 64 位 .so 原生库只要还是旧的 4 KB 对齐,就会触发此提示。
- 第一步:点开提示卡片下方的这些库不支持 16 KB,看清被点名的具体是引擎库还是某个第三方插件的
.so。 - 第二步(按框架升级构建链与插件):
- Android Studio / 原生:将 AGP 升级至
8.5.1+,NDK 升级至r28+(默认按 16 KB 编译对齐;若用 NDKr27需加链接参数-Wl,-z,max-page-size=16384),并升级被点名的第三方 SDK。 - Flutter:升级至 Flutter
3.27+/3.29+,将android/settings.gradle中的 AGP 升至8.5.1+、NDK 升至r28+,并运行flutter pub upgrade更新含原生代码的插件。 - Expo / React Native:升级至 Expo SDK
52+/53+(对应 React Native0.77+)。 - Unity:升级至带 16 KB 支持补丁的编辑器版本(Unity
6000.0.38f1+、2022.3.56f1+或企业延展支持版2021.3.48f1+)。
- Android Studio / 原生:将 AGP 升级至
如何定位具体违规的 .so 文件、处理尚未适配的第三方 SDK 以及清理旧测试轨道残留包,见 Play 管理中心「使原生库针对 16 KB 对齐」报错解决办法。
6目标 API 级别(35 / 36)、64 位要求与 200 MB 上限
目标 API 级别过低
您的应用目前的目标 API 级别为 <34>,但其目标 API 级别必须最低为 <35>,这样才能确保应用基于最新 API 而构建,让安全性和性能达到最佳状态。请将应用的目标 API 级别至少更改为 <35>。
- 原因:Google Play 每年 8 月 31 日(可申请延期至 11 月 1 日)都会上调最低
targetSdkVersion门槛——2025/2026 要求至少 API 35(Android 15),2026 年 8 月底起新门槛上调至 API 36(Android 16)。 - 解决:在
build.gradle(.kts)中同步调高compileSdk与targetSdk(或升级 Flutter / Expo SDK / Unity Target API Level),并顺手检查 Android 15+ 默认全面屏(Edge-to-Edge)是否遮挡顶部状态栏或底部按钮。
不符合 64 位版本要求
此版本不符合 Google Play 关于提供 64 位版本应用的要求。
- 原因:包里含有 32 位
.so(armeabi-v7a),却缺少对应的 64 位.so(arm64-v8a)。最常见于 Unity 默认停留在Mono脚本后端,或接入了只给 32 位.so的老旧硬件 SDK。 - 解决:Unity 在 Player Settings > Other Settings 将 Scripting Backend 改为
IL2CPP并勾选ARM64;Gradle 检查ndk.abiFilters确保包含"arm64-v8a"。
超出 200 MB 压缩下载大小上限
您的 App Bundle 的部分功能模块超出了压缩后下载大小上限 (200 MB)。请缩减以下模块的大小:base。
- 解决:开启 R8 代码与资源缩减(
isMinifyEnabled = true、isShrinkResources = true),压缩贴图与音视频;大体积游戏资源或端侧模型文件改用 Play Asset Delivery (PAD) 拆成独立资源包,或首次启动后走 CDN 下载。
7广告 ID 与敏感权限声明拦截(含旧轨道残留坑)
进入步骤 2(预览并确认)时,Play 管理中心会把 .aab 合并后的 AndroidManifest.xml 与你在 监控和改进 > 政策和计划 > 应用内容 里填的声明逐项比对。
最隐蔽的多轨道连坐坑:Play 管理中心检查的是所有轨道(正式版、开放式测试、封闭式测试、内部测试)上仍处于生效状态的全部软件包。哪怕你在封闭式测试上传的新包里已经删掉了违规权限,只要内部测试轨道还挂着带该权限的老版本包,点下一步依然会被拦住——必须去对应测试轨道也发个新包把旧包顶掉才行。
广告 ID(com.google.android.gms.permission.AD_ID)声明不匹配
- 后台填了「否」,但包里带了
AD_ID权限:此版本包含 com.google.android.gms.permission.AD_ID 权限,但您在 Play 管理中心的声明中指出您的应用未使用广告ID。
- 原因:接入 Firebase Analytics、Crashlytics、AdMob 或 Unity Ads 时,SDK 会自动往清单里合并注入
AD_ID权限。 - 解决:确实用了统计分析或广告的,去 应用内容 > 广告 ID 改成「是」并勾选对应用途(分析 / 广告或营销);完全不用的,在
AndroidManifest.xml加一行<uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove" />剔除后重打。
- 原因:接入 Firebase Analytics、Crashlytics、AdMob 或 Unity Ads 时,SDK 会自动往清单里合并注入
- 后台填了「是」,但某个在架包缺少
AD_ID权限:您在 Play 管理中心的广告 ID 声明中指出,您的应用会使用广告 ID。但是,您当前使用的某个工件的清单文件不包含 com.google.android.gms.permission.AD_ID 权限。
- 解决:在
AndroidManifest.xml补上AD_ID权限(并顶掉旧测试轨道上缺权限的老包),或把后台声明改为「否」。
- 解决:在
未声明的敏感权限(前台服务、照片和视频、安装未知应用)
此版本包含尚未在 Play 管理中心内声明的权限。请转到‘敏感的应用权限’,更新您的权限声明
READ_MEDIA_IMAGES/READ_MEDIA_VIDEO(照片和视频权限):如果应用只是让用户传头像、发附图或提交反馈截图,千万别去填声明表单碰运气——非相册/修图/文件管理器类应用填表必被拒审(权限的使用与应用的核心目的没有直接关系)。请升级选图插件改用免权限的系统 Android Photo Picker,并用tools:node="remove"彻底移除残留权限。REQUEST_INSTALL_PACKAGES(应用内安装 APK):常由open_file或国内自更新组件带入。Google Play 严禁应用自行下载安装 APK 更新,必须移除该权限。FOREGROUND_SERVICE_*(前台服务权限,API 34+):不需要常驻后台服务的直接用tools:node="remove"移除;确实需要(如音乐播放、计时器、运动记录)的,在 应用内容 > 前台服务权限 如实填写,并附上无需登录即可观看的演示视频链接(拍到用户点击触发 + 下拉通知栏展示常驻通知)。
8两条不拦截发布的黄色警告(去混淆文件与原生调试符号)
几乎每个第一次传包的 Flutter、Unity、React Native 或 Capacitor 开发者,在预览并确认页面看到「警告」栏跳出下面这两条黄字时都会心里一紧,以为不能提审:
没有与此 App Bundle 关联的去混淆文件。如果您使用经过混淆处理的代码(R8/proguard),那么上传去混淆文件会使崩溃和ANR 情况更易于分析和调试。使用R8/proguard 有助于缩减应用大小。
此 App Bundle 包含原生代码,您尚未上传调试符号文件。我们建议您上传调试符号文件,这样会便于针对崩溃和 ANR 问题进行分析和调试。
- 能直接点发布吗?完全可以。黄色警告绝不会阻塞保存、发布测试轨道或通过 Google 审核,赶着先开测时直接点下一步即可。
- 后续正式版怎么顺手消掉:
- 关联去混淆文件(
mapping.txt):在app/build.gradle.kts的buildTypes.release中开启isMinifyEnabled = true与isShrinkResources = true(Groovybuild.gradle写minifyEnabled true/shrinkResources true),现代 Android Gradle Plugin 会自动把mapping.txt嵌进.aab里,不用手动上传(首次开启 R8 记得先在内部测试跑一轮防误删反射类)。 - 上传原生调试符号:在
buildTypes.release中加上ndk { debugSymbolLevel = "SYMBOL_TABLE" }(本地需装好 Android NDK),打包时会自动将符号表塞进.aab;也可以在 App bundle 资源管理器手动上传生成的native-debug-symbols.zip。
- 关联去混淆文件(
9发布概览送审拦截:android.hardware.screen.portrait 与 Android XR
有时 .aab 在创建发布版本和预览并确认两步都顺利通过,到了发布概览准备送审时,右上角的提交 1 项更改以供审核却变灰,下方弹出红色发现了 1 个问题(在声明中将硬件功能标记为必需,导致您的应用分发范围受限 —— `android.hardware.screen.portrait` 会影响 手机、平板电脑、桌面设备和Android XR 用户)。
- 本次已传包直接放行(不浪费
versionCode):点开查看问题 → 仍然继续,在弹出的忽略此问题确认框里勾选原因(如我已计划解决此问题)并点忽略问题,回到页面点提交 1 项更改以供审核即可送审,无需改代码重打包。 - 下个版本永久消除:在
AndroidManifest.xml的<manifest>根节点下加上<uses-feature android:name="android.hardware.screen.portrait" android:required="false" />,既保留手机竖屏锁定,又解除对桌面端与 Android XR 的硬件安装过滤。完整截图与各框架改法见 Play 管理中心 android.hardware.screen.portrait 报错解决。
包传上去了,下一步是什么?
把 .aab 顺利推过「预览并确认」只是个人开发者账号上架的上半场。第一个封闭式测试版本发出去后,紧接着最容易卡住人的还有三件事:
- 只要应用需要登录(哪怕只支持 Google 登录),提审前先填好登录说明,避免审核人员进不去被拒——见 Play 管理中心「登录详细信息」怎么填?。
- 把加入测试链接发给测试人员前,确认 Google 群组、全部国家/地区以及发布概览里的改动都已过审生效,避免点开一片空白——见 封闭式测试、内部测试显示 "Item not found"?原因与解决办法。
- 凑齐至少 12 名测试人员连续参与满 14 天,再去申请正式版发布权限——见 12 名测试人员、14 天:「连续」到底是什么意思。
自己找满 12 名测试人员往往比传包还折腾:找身边朋友帮忙,不是用 iPhone 就是装完两天就忘了打开;去社区发帖互测,又常遇到对方只点选择参与却不安装、中途卸载,或者装上后再也没打开过,14 天跑完却因为活跃度不够被拒。BetaLobby(完全免费,无付费套餐)采用 16 人组队模式并共用同一个 Google 群组,人齐后统一开跑,免截图在真机上验证安装,并通过每日打卡把每天真正打开应用的人数直观记下来,让这 14 天跑得踏实省心。