gplay-submission-checks

Name: gplay-submission-checks
Author: tamtom

github.com/tamtom测试与质量52467 次安装13 周前更新

代码仓库

关于 gplay-submission-checks

面向准备向 Google Play 发布应用的 Android 开发者，指导使用 gplay 命令检查构建产物、商店资料、合规性和发布准备情况，涵盖离线预检与试运行。

主要功能

01执行综合发布准备验证
02检查应用包与商店资料
03扫描构建产物中的合规问题
04对比本地资料与 Play Store
05通过试运行验证发布流程

适用场景

01提交前检查 AAB 或 APK
02发现资料与截图问题
03在 CI 流水线中加入合规检查
04不提交更改地测试发布流程

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/tamtom/gplay-cli-skills --skill gplay-submission-checks

安装后在 Claude Code 中输入/gplay-submission-checks确认已加载。

详细介绍

Google Play 提交检查

在向 Google Play 提交版本之前，使用此技能验证所有内容，减少被拒和编辑失败的情况。

前提条件

已配置身份验证（gplay auth login 或 GPLAY_SERVICE_ACCOUNT 环境变量）。
已知包名（--package 或 GPLAY_PACKAGE）。
已构建并签名 AAB/APK。
服务账号至少具有“Release Manager”权限。

优先使用一流命令

CLI 提供了规范的专用命令。应优先使用这些命令，而不是手动编写各个验证器：

gplay validate --package <pkg> — 规范的版本就绪情况报告。汇总本地构建产物、元数据、截图和版本说明检查，以及远程轨道和商店页面状态、仅可在 Console 中完成的后续事项。使用 --bundle、 --listings-dir、--screenshots-dir、--track 和 --strict（将警告视为失败）来指定检查范围。
```
gplay validate \
  --package com.example.app \
  --bundle app-release.aab \
  --track production \
  --strict
```
gplay preflight --file <app.aab> — 离线 AAB/APK 合规性和卫生检查。完整解码 AndroidManifest.xml（APK 使用二进制 AXML，应用包使用 aapt2 protobuf），并运行九个扫描器：manifest、permissions、 native_libs、metadata、secrets、billing、privacy、 policy、size。不会调用 API，也不需要凭据。退出代码：0 表示无问题，1 表示发现达到或超过 --fail-on 阈值的问题。
```
gplay preflight --file app-release.aab --max-size 150M --fail-on warning

# Validate the store listing in the same pass
gplay preflight --file app-release.aab --listings-dir ./metadata --fail-on error

# Narrow the gate
gplay preflight --file app-release.aab --only manifest,permissions,native_libs
```
查看 gplay-preflight 技能，了解各扫描器的检查内容、如何解读发现的问题，以及 CI 门禁模式。
gplay checks upload — 将 Google Checks 合规性分析用作 CI 门禁。使用 --severity-threshold PRIORITY 在发布前因高优先级检查失败而中断流水线。
```
gplay checks upload \
  --account "$CHECKS_ACCOUNT" \
  --app "$CHECKS_APP" \
  --binary app-release.aab \
  --binary-type ANDROID_AAB \
  --severity-threshold PRIORITY
```
gplay publish track --strict — 一步完成预检和发布。生成就绪情况报告，遇到阻塞问题时停止（使用 --strict 时，遇到警告也会停止），仅在预检通过后运行发布工作流。
```
gplay publish track \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --release-notes @release-notes.json \
  --strict
```

以下按构建产物细分的检查仍有助于定位失败原因，或用于逐项设置 CI 门禁。

提交前检查清单

1. 验证应用包完整性

gplay validate bundle --file app-release.aab

检查项：

文件存在且可读取
文件扩展名为 .aab
ZIP 压缩包结构有效
包含必需的应用包组件（清单、资源、dex）

如果使用 APK：

gplay validate bundle --file app-release.apk

2. 验证商店页面元数据

gplay validate listing --dir ./metadata

检查项：

标题：最多 30 个字符
简短说明：最多 80 个字符
完整说明：最多 4000 个字符
必填字段均已填写
UTF-8 编码有效

验证特定语言区域：

gplay validate listing --dir ./metadata --locale en-US

对于 JSON 格式的元数据：

gplay validate listing --dir ./metadata --format json

3. 验证截图

gplay validate screenshots --dir ./metadata

检查项：

每种设备类型至少 2 张截图
每种设备类型最多 8 张截图
图片格式有效（PNG、JPEG）
文件可读取

验证特定语言区域的截图：

gplay validate screenshots --dir ./metadata --locale en-US

4. 验证 Play 商店中的现有商店页面

将本地元数据与线上内容进行比较：

gplay sync diff-listings \
  --package com.example.app \
  --dir ./metadata

检查所有已配置的语言区域：

EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')
gplay listings list --package com.example.app --edit $EDIT_ID --output table

5. 数据安全声明

确保数据安全表单已填写完整。数据安全声明缺失或不准确是常见的拒绝原因。

gplay data-safety update \
  --package com.example.app \
  --json @data-safety.json

6. 版本代码检查

版本代码必须严格高于所有轨道上的历史版本。检查当前轨道状态：

gplay tracks list --package com.example.app --output table

获取特定轨道的详细信息：

EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')
gplay tracks get --package com.example.app --edit $EDIT_ID --track production --output table

7. 反混淆 / 映射文件

上传 ProGuard/R8 映射文件，以便在 Play Console 中查看可读的崩溃报告。此命令作用于 edit（需要 --edit），且版本标志为 --apk-version，而不是 --version-code：

EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')
gplay deobfuscation upload \
  --package com.example.app \
  --edit $EDIT_ID \
  --apk-version 42 \
  --file mapping.txt
gplay edits commit --package com.example.app --edit $EDIT_ID

如果没有映射文件，Android Vitals 中的崩溃堆栈跟踪将会被混淆，无法使用。

8. 试运行发布

这是最安全的提交前检查。它会执行完整发布流程，但不会提交：

gplay release \
  --package com.example.app \
  --track production \
  --bundle app-release.aab \
  --release-notes @release-notes.json \
  --dry-run

执行内容：

创建一个 edit
上传应用包
配置轨道
验证 edit（捕获 API 级别的错误）
丢弃 edit，不进行提交

如果试运行成功，正式发布也会成功。

9. 编辑验证（手动流程）

使用手动编辑工作流时，提交前务必进行验证：

EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')

# ... upload bundle, update tracks, etc. ...

# Validate the edit (catches all server-side issues)
gplay edits validate --package com.example.app --edit $EDIT_ID

# Only commit if validation passes
gplay edits commit --package com.example.app --edit $EDIT_ID

内容政策合规

目标 API 级别

Google Play 要求应用面向较新的 Android API 级别，并且大约每年 8 月将最低要求提高到“最新版本减 1”。新应用和更新都会受到影响；低于最低要求的构建版本会在上传时被拒绝。

无需猜测当前要求的级别，检查构建配置：

# The policy scanner reports targetSdkVersion against Play's floor
gplay preflight --file app-release.aab --only policy

# Override the floor if Google's annual bump landed before a gplay release
gplay preflight --file app-release.aab --only policy --min-target-sdk 36

在 build.gradle / build.gradle.kts 中修复：

android {
    defaultConfig {
        targetSdk = 35  // set to Play's current floor or higher
    }
}

不要凭记忆告知用户所需的具体 API 级别，应从 policy 扫描器输出或 Play 发布的要求中读取。

权限声明

敏感权限需要在 Play Console 中说明理由：

ACCESS_FINE_LOCATION / ACCESS_BACKGROUND_LOCATION
READ_CONTACTS、READ_CALL_LOG、READ_SMS
CAMERA、RECORD_AUDIO
REQUEST_INSTALL_PACKAGES
QUERY_ALL_PACKAGES

移除应用实际上不需要的权限。未使用的敏感权限是导致拒绝的主要原因之一。

数据安全表单

所有应用都必须填写完整的数据安全部分。常见的需声明数据类型：

个人信息（姓名、电子邮件、电话号码）
位置（大致位置、精确位置）
财务信息（购买记录）
应用活动（应用内搜索、其他用户生成的内容）
设备标识符（广告 ID）

应用内容分级

确保已在 Play Console 中完成内容分级问卷。缺少分级会阻止应用发布。

不同设备类型的截图要求

设备类型	图片类型	最少数量	最多数量	最低分辨率
手机	`phoneScreenshots`	2	8	320px（短边）
7 英寸平板电脑	`sevenInchScreenshots`	0	8	320px（短边）
10 英寸平板电脑	`tenInchScreenshots`	0	8	320px（短边）
Android TV	`tvScreenshots`	0	8	1280x720
Wear OS	`wearScreenshots`	0	8	320px（短边）

其他图片素材：

素材	类型	是否必需
功能图片	`featureGraphic`	是（用于展示推荐）
宣传图片	`promoGraphic`	否
图标	`icon`	在 Play Console 中设置
TV 横幅	`tvBanner`	TV 应用必需

常见拒绝原因及修复方法

1. “版本代码已存在”

原因：应用包中的版本代码与现有版本相同。 修复方法：在 build.gradle 中递增 versionCode，然后重新构建。

2. “APK/应用包的目标 SDK 低于要求级别”

原因：targetSdkVersion 过低。 修复方法：将 targetSdkVersion 更新至 34 或更高，然后重新构建。

3. “数据安全表单不完整”

原因：缺少数据安全声明或声明不完整。 修复方法：在 Play Console 中填写数据安全表单，或通过 CLI 更新：

gplay data-safety update --package com.example.app --json @data-safety.json

4. “缺少必需设备类型的截图”

原因：所有应用都必须提供手机截图。 修复方法：至少添加 2 张手机截图：

EDIT_ID=$(gplay edits create --package com.example.app | jq -r '.id')
gplay images upload \
  --package com.example.app \
  --edit $EDIT_ID \
  --locale en-US \
  --type phoneScreenshots \
  --file screenshot1.png

5. “缺少默认语言的版本说明”

原因：默认语言没有“更新内容”文本。 修复方法：在发布命令中加入版本说明：

gplay release \
  --package com.example.app \
  --track production \
  --bundle app.aab \
  --release-notes '{"en-US": "Bug fixes and improvements"}'

6. “签名密钥不匹配”

原因：应用包使用的签名密钥与 Play Console 预期的密钥不同。 修复方法：使用 Play App Signing 中配置的同一上传密钥。检查密钥库配置。

7. “反混淆文件过大”

原因：映射文件超过 300 MB 的限制。 修复方法：移除未使用的映射项，或压缩文件。

发布前报告

Google Play 会在审核应用之前对其进行自动化测试（发布前报告）。报告中常见的问题包括：

启动时崩溃：应用在一个或多个测试设备上崩溃
安全漏洞：依赖项中存在已知 CVE
无障碍问题：缺少内容描述、触控目标过小
性能警告：启动缓慢、唤醒锁过多

上传到任意轨道后，请在 Play Console 中查看发布前报告。在将应用推广到正式版之前，请解决严重问题。

完整的提交前流程

#!/bin/bash
# pre-submission-checks.sh

PACKAGE="com.example.app"
BUNDLE="app-release.aab"
METADATA_DIR="./metadata"
RELEASE_NOTES="release-notes.json"
MAPPING="app/build/outputs/mapping/release/mapping.txt"

echo "=== Step 1: Validate bundle ==="
gplay validate bundle --file "$BUNDLE" --output table

echo "=== Step 2: Validate listings ==="
gplay validate listing --dir "$METADATA_DIR" --output table

echo "=== Step 3: Validate screenshots ==="
gplay validate screenshots --dir "$METADATA_DIR" --output table

echo "=== Step 4: Diff listings against Play Store ==="
gplay sync diff-listings --package "$PACKAGE" --dir "$METADATA_DIR" --output table

echo "=== Step 5: Dry run release ==="
gplay release \
  --package "$PACKAGE" \
  --track production \
  --bundle "$BUNDLE" \
  --release-notes "@$RELEASE_NOTES" \
  --listings-dir "$METADATA_DIR" \
  --screenshots-dir "$METADATA_DIR" \
  --dry-run \
  --output table

echo "=== Step 6: Upload mapping file (edit-scoped) ==="
EDIT_ID=$(gplay edits create --package "$PACKAGE" | jq -r '.id')
gplay deobfuscation upload \
  --package "$PACKAGE" \
  --edit "$EDIT_ID" \
  --apk-version 42 \
  --file "$MAPPING"
gplay edits commit --package "$PACKAGE" --edit "$EDIT_ID"

echo "=== All checks passed. Ready to release. ==="

CI/CD 集成

将这些检查添加到 CI 流水线中，以便在问题到达 Play Console 之前发现它们：

# GitHub Actions example
- name: Offline preflight (compliance + secret scan)
  run: gplay preflight --file app/build/outputs/bundle/release/app-release.aab --fail-on error

- name: Checks compliance gate
  run: |
    gplay checks upload \
      --account ${{ secrets.CHECKS_ACCOUNT }} \
      --app ${{ secrets.CHECKS_APP }} \
      --binary app/build/outputs/bundle/release/app-release.aab \
      --binary-type ANDROID_AAB \
      --severity-threshold PRIORITY

- name: Canonical readiness report
  run: |
    gplay validate \
      --package ${{ secrets.PACKAGE_NAME }} \
      --bundle app/build/outputs/bundle/release/app-release.aab \
      --track internal \
      --strict
  env:
    GPLAY_SERVICE_ACCOUNT: ${{ secrets.GPLAY_SERVICE_ACCOUNT_PATH }}

Agent 行为

优先使用一等命令：gplay validate（就绪情况报告）、 gplay preflight（离线检查）、gplay checks upload（Checks 门禁）以及 gplay publish track --strict（预检 + 发布），而不是手动编写脚本。
尝试发布之前，务必运行 gplay validate。
将 --dry-run（或 publish track --strict）用作正式发布前的最终门禁。
gplay deobfuscation upload 的作用范围限定为 edit：使用 --edit 和 --apk-version （而不是 --version-code），然后提交 edit。
运行命令之前，务必先通过 --help 确认准确的标志。
使用 --output table 输出便于阅读的验证结果。
如果多个验证步骤失败，请汇总报告所有失败项，而不是在首个失败时停止。
发布之前，先列出轨道以检查版本代码冲突。
如果用户尚未提及数据安全声明，请提醒他们。

备注

gplay validate 命令在本地运行，无需调用 API。
gplay release --dry-run 会创建一个真实的 edit 会话，但验证后会将其丢弃。
gplay edits validate 是服务端对应的验证方式，可捕获本地验证无法发现的问题。
务必使用 --help 验证具体命令的标志。
使用 --output table 输出便于阅读的内容；默认格式为 JSON。

支持 Markdown

登录后评论

基本信息

作者: tamtom
仓库: tamtom/gplay-cli-skills
分类: 测试与质量
安装次数: 467
GitHub Stars: 52

报告问题