gpc-multi-app

gpc-multi-app

使用配置文件、脚本和自动化模式，通过 GPC 管理多个 Google Play 应用。

适用场景

• 管理多个 Android 应用（产品组合、白标应用、变体）
• 在多个应用上运行相同的 GPC 命令
• 为每个应用设置配置和凭据
• 包含多个 Android 模块的单体仓库
• 不同应用使用不同的服务账号

所需输入

• 已通过身份验证的 GPC — gpc auth status 必须显示有效凭据
• 包名 — 所有要管理的应用的包名
• 服务账号密钥 — 不同应用或开发者账号可能使用不同的密钥

操作步骤

0. 了解应用解析方式

GPC 按以下顺序解析目标应用：

1. --app CLI 标志（优先级最高）
2. GPC_APP 环境变量
3. 项目目录中的 .gpcrc.json
4. 用户配置文件 ~/.config/gpc/config.json
5. 活动配置文件覆盖项

1. 快速检查所有应用的运行状况

使用 gpc status --all-apps 一次性检查所有已配置应用的运行状况：

gpc status --all-apps

此命令会报告配置文件或配置中定义的每个应用的状态，无需切换配置文件，也无需为每个应用传入 --app。

2. 使用配置文件为每个应用单独配置

为每个应用创建一个配置文件（GPC v0.9.95+；旧版本会静默忽略此处的 --profile，请改用交互式向导）：

gpc auth login --service-account /keys/main-sa.json --profile main
gpc auth login --service-account /keys/main-sa.json --profile lite
gpc auth login --service-account /keys/enterprise-sa.json --profile enterprise

然后在 ~/.config/gpc/config.json 中为每个配置文件添加 app（以及任何每个应用单独设置的项）——之后重新运行 auth login --profile 只会更新凭据，并保留这些字段：

{
  "app": "com.example.main",
  "profiles": {
    "main": {
      "app": "com.example.main",
      "auth": { "serviceAccount": "/keys/main-sa.json" }
    },
    "lite": {
      "app": "com.example.lite",
      "auth": { "serviceAccount": "/keys/main-sa.json" }
    },
    "enterprise": {
      "app": "com.example.enterprise",
      "auth": { "serviceAccount": "/keys/enterprise-sa.json" }
    }
  }
}

在每条命令中使用配置文件：

gpc releases list --profile main
gpc releases list --profile lite
gpc releases list --profile enterprise

或者通过环境变量设置：

export GPC_PROFILE=enterprise
gpc releases list  # uses enterprise profile

Read: references/profile-patterns.md 了解高级配置文件配置。

3. 项目级 .gpcrc.json

对于单体仓库，请将 .gpcrc.json 放在每个应用的目录中：

monorepo/
├── apps/
│   ├── main/
│   │   ├── .gpcrc.json          # { "app": "com.example.main" }
│   │   └── build.gradle
│   ├── lite/
│   │   ├── .gpcrc.json          # { "app": "com.example.lite" }
│   │   └── build.gradle
│   └── enterprise/
│       ├── .gpcrc.json          # { "app": "com.example.enterprise" }
│       └── build.gradle
└── .gpcrc.json                  # shared defaults

GPC 会从当前目录向上查找 .gpcrc.json，因此从每个应用的目录运行命令时，会自动使用正确的包名。

4. 使用 shell 脚本执行批量操作

在所有应用上运行相同的命令：

#!/bin/bash
# deploy-all.sh — upload to internal track for all apps

APPS=(
  "com.example.main"
  "com.example.lite"
  "com.example.enterprise"
)

for app in "${APPS[@]}"; do
  echo "Uploading $app..."
  gpc releases upload "build/$app/app-release.aab" --track internal --app "$app"
done

5. 批量检查运行状况

#!/bin/bash
# check-vitals.sh — check crash rate across all apps

APPS=("com.example.main" "com.example.lite" "com.example.enterprise")
THRESHOLD=2.0
FAILED=0

for app in "${APPS[@]}"; do
  echo "Checking $app..."
  if ! gpc vitals crashes --threshold "$THRESHOLD" --app "$app"; then
    echo "FAIL: $app crash rate exceeds ${THRESHOLD}%"
    FAILED=1
  fi
done

exit $FAILED

6. 多应用 CI/CD

Read: references/ci-multi-app.md 了解特定 CI 平台的多应用工作流。

GitHub Actions 矩阵策略

name: Deploy All Apps
on:
  push:
    tags: ['v*']

jobs:
  deploy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        app:
          - { package: "com.example.main", aab: "main/app-release.aab" }
          - { package: "com.example.lite", aab: "lite/app-release.aab" }
          - { package: "com.example.enterprise", aab: "enterprise/app-release.aab" }
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Upload to internal
        env:
          GPC_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_KEY }}
          GPC_APP: ${{ matrix.app.package }}
        run: npx @gpc-cli/cli releases upload ${{ matrix.app.aab }} --track internal

7. 为每个应用使用不同的服务账号

当应用属于不同的开发者账号时：

# Use different env vars per command
GPC_SERVICE_ACCOUNT=$(cat keys/main.json) gpc releases list --app com.example.main
GPC_SERVICE_ACCOUNT=$(cat keys/client.json) gpc releases list --app com.client.app

或者使用配置文件（推荐）：

{
  "profiles": {
    "main": {
      "app": "com.example.main",
      "auth": { "serviceAccount": "/keys/main-sa.json" }
    },
    "client": {
      "app": "com.client.app",
      "auth": { "serviceAccount": "/keys/client-sa.json" }
    }
  }
}

8. 批量同步元数据

从共享的元数据结构同步所有应用的商品详情：

# metadata/
# ├── com.example.main/
# │   └── en-US/
# ├── com.example.lite/
# │   └── en-US/

for dir in metadata/*/; do
  app=$(basename "$dir")
  echo "Syncing $app..."
  gpc listings push --dir "$dir" --app "$app" --dry-run
done

验证

• gpc config list --profile <name> 显示每个配置文件对应的应用和身份验证信息正确
• 使用 --app 或 --profile 的命令会指向正确的应用
• 所有应用均成功时，批处理脚本以 0 退出
• CI 矩阵会为每个应用独立运行部署
• 子目录中的 .gpcrc.json 能正确覆盖默认应用

故障模式 / 调试

症状	可能原因	修复方法
目标应用错误	未设置 --app，使用了默认应用	始终传入 --app 或明确使用配置文件
某个应用出现 API_FORBIDDEN	服务账号无权访问该应用	在 Play Console 中检查每个应用的权限
批处理脚本静默失败	循环中缺少错误处理	使用 set -e，或在每条命令后检查 $?
找不到配置文件	配置文件名称拼写错误	使用 gpc config list 检查可用配置文件
CI 矩阵任务中某个应用失败	独立故障	矩阵任务会独立运行——检查每个应用的日志
未读取 .gpcrc.json	运行目录错误	GPC 会从 cwd 向上查找；请确保当前目录正确

相关技能

• gpc-setup — 初始身份验证和配置文件设置
• gpc-ci-integration — 单个应用的 CI 流水线设置
• gpc-sdk-usage — 使用 TypeScript SDK 以编程方式管理多个应用
• gpc-user-management — 管理团队成员对各应用的权限