gpc-setup

GPC 设置

适用场景

当任务涉及以下内容时，使用此技能：

• 安装 GPC（npm install -g @gpc-cli/cli 或独立二进制文件）
• 运行统一设置向导（gpc setup，v0.9.68+）
• 使用 Google Play Developer API 进行身份验证（服务账号、OAuth、ADC）
• 管理身份验证配置文件（gpc auth profiles、gpc auth switch）
• 配置 GPC（.gpcrc.json、环境变量、gpc config init）
• 诊断设置问题（gpc doctor）
• 在新项目或 CI 环境中设置 GPC

所需输入

• 这是本地开发设置还是 CI/CD 设置
• 身份验证方法：服务账号 JSON、OAuth 或 Application Default Credentials
• Android 应用的软件包名称（例如，com.example.app）
• 如果是 CI：使用哪个 CI 平台（GitHub Actions、GitLab 等）

流程

0) 安装 GPC

通过 npm 安装（推荐）：

npm install -g @gpc-cli/cli

通过 npx 运行（免安装试用）：

npx @gpc-cli/cli --version

通过独立二进制文件运行（无需 Node.js）：

curl -fsSL https://raw.githubusercontent.com/yasserstudio/gpc/main/scripts/install.sh | bash

1) 统一设置（v0.9.68+，推荐）

从头开始配置 GPC 的最快方式：

gpc setup

gpc setup 是一条命令，可在引导流程中整合身份验证、配置和验证：

1. 检测现有配置（如配置不完整，则从中断处继续）
2. 提示选择身份验证方法（服务账号、OAuth 或 ADC）
3. 验证凭据
4. 设置默认软件包名称
5. 写入 .gpcrc.json
6. 运行 gpc doctor，验证所有功能是否正常

对于 CI/CD 或无头环境，请使用非交互式变体：

gpc setup --auto

--auto 从环境变量（GPC_SERVICE_ACCOUNT、GPC_APP）读取信息，并跳过所有提示。成功时以状态码 0 退出；失败时以非零状态码退出并提供可操作的错误信息。适用于 Docker 镜像、GitHub Actions 设置步骤和新手引导脚本。

如果需要更多控制，请使用下方的单独命令。

1a) 身份验证

以下三种身份验证策略按推荐顺序排列：

A) 服务账号（推荐用于 CI/CD）

刚开始使用 Google Cloud，或首次进行设置？ 使用交互式 GCP 设置指南：

gpc auth setup-gcp

这个全交互式向导会引导你完成将 GPC 连接到 Play Developer API 所需的每个步骤：

1. 在 GCP 项目中启用 Google Play Developer API
2. 在 GCP Console 中创建服务账号
3. 在 Google Play Console 中授予服务账号访问权限（设置 → API 访问权限）
4. 将 JSON 密钥文件下载到你的计算机
5. 使用下载的密钥运行 gpc auth login

无需任何标志，只需运行命令并按照提示操作即可。适合在任何计算机上首次进行设置。

已经有密钥文件？ 使用 --key 跳过向导：

gpc auth setup-gcp --key /path/to/service-account.json

此命令会一步完成 JSON 验证、身份验证和将配置保存到文件。

向导完成后，或如果你已经有密钥文件：

gpc auth login --service-account path/to/key.json

也可以通过环境变量指定（CI 中优先使用）：

export GPC_SERVICE_ACCOUNT=path/to/key.json
# or inline JSON:
export GPC_SERVICE_ACCOUNT='{"type":"service_account","project_id":"..."}'

批量报告所需的额外授权（v0.9.93+）。 上述 API 访问授权不包含 Play 的月度批量报告。这些报告以 CSV 文件形式存储在 Cloud Storage 存储桶中，而不是通过 Publisher API 提供。Play 会自动将该存储桶授权给你自己的用户登录账号，但不会授权给服务账号。如果你计划使用 gpc reports，请打开 Play Console → 用户和权限 → 服务账号 → 账号权限，启用 “查看应用信息并下载批量报告（只读）”，然后等待几分钟，让权限生效。如果未启用，报告命令会失败并显示 REPORT_ACCESS_DENIED。使用 gpc doctor 中的 reports-bucket 检查进行验证。

只有报告命令（以及该 doctor 探测项）会请求额外的 devstorage.read_only 作用域，并且具有存储访问权限的令牌会单独缓存，因此为其他所有命令签发的令牌都不会拥有存储访问权限。

阅读：

• references/service-account.md

B) OAuth（用于本地开发）

交互式 OAuth 设备流程，无需密钥文件：

gpc auth login

令牌会缓存在操作系统密钥链（macOS Keychain、Linux libsecret）中，或在密钥链不可用时回退到文件缓存。

C）应用默认凭据（适用于 GCP 环境）

在 Cloud Build、Cloud Run、GKE 中可自动运行——无需配置：

# ADC is auto-detected when no other auth is configured
gpc apps list

2）配置默认值

交互式设置向导：

gpc config init

引导式向导会：

1. 选择身份验证方式（service-account / adc / skip）
2. 对于服务账号：验证文件是否存在（路径错误时会重试）
3. 提示输入默认软件包名称（格式无效时会发出警告）
4. 写入 .gpcrc.json 并打印初始化后摘要
5. 最后提示：Run \gpc doctor` to verify your setup.`

手动配置文件（项目根目录中的 .gpcrc.json 或 ~/.config/gpc/config.json）：

{
  "app": "com.example.myapp",
  "output": "table",
  "profile": "default"
}

环境变量：

变量	描述
GPC_APP	默认软件包名称
GPC_OUTPUT	默认输出格式（table/json/yaml/markdown/csv/tsv）
GPC_PROFILE	身份验证配置文件名称
GPC_NO_COLOR	禁用彩色输出
GPC_NO_INTERACTIVE	禁用交互式提示
GPC_SKIP_KEYCHAIN	跳过 OS 钥匙串，使用文件存储

配置解析优先级（v0.9.81+）

同一设置通过多个来源提供时，GPC 按以下顺序解析（优先级从高到低）：

优先级	来源	示例
1	CLI 标志	--service-account key.json、--app com.example.app
2	环境变量	GPC_SERVICE_ACCOUNT、GPC_APP
3	活动配置文件	通过 gpc auth switch <name> 设置
4	.gpcrc.json	项目级或全局配置文件
5	默认值	内置回退值

在 v0.9.81 之前，活动配置文件会静默地优先于 GPC_SERVICE_ACCOUNT 和 GPC_APP 环境变量。此错误已修复。现在，环境变量和 CLI 标志都能可靠地覆盖当前活动配置文件，这对运行时注入密钥的 CI 环境尤为重要。

阅读：

• references/configuration.md

3）管理身份验证配置文件

用于管理多个 Google Play 账号：

gpc auth login --service-account key.json --profile production   # Create a profile (v0.9.95+)
gpc auth profiles              # List profiles
gpc auth switch production     # Switch active profile
gpc auth whoami                # Show current identity
gpc auth status                # Show auth state details
gpc auth clear-cache           # Drop cached tokens, keep credentials (v0.9.93+)

重新运行 auth login --profile <name> 会就地更新该配置文件的凭据，并保留其他设置（app、developerId、reports），因此轮换密钥是安全的。gpc auth logout --profile <name> 只会清除该配置文件的凭据。两项功能都需要 GPC v0.9.95+；在较早版本中，login/logout 命令的 --profile 标志会被静默忽略——请改用交互式 gpc auth login 向导创建配置文件。

gpc auth clear-cache 是 gpc auth logout 的轻量级对应操作：它会删除缓存的访问令牌，以便下一条命令重新生成令牌，但不会移除已配置的凭据。在 Play Console 中更改权限后（例如授予 bulk-reports 权限），可使用此命令，避免更改前缓存的令牌影响新权限。

使用 --profile 标志覆盖单条命令的配置：

gpc apps list --profile staging

4）验证设置

gpc doctor

检查项（共 23 项）：

• Node.js 版本（≥ 20）
• 配置已加载
• 已设置默认应用，且 Android 软件包名称格式有效
• 配置和缓存目录权限
• 服务帐号文件存在且权限正确（组和其他用户均不可读）
• 配置文件环境变量指向已知配置文件
• 代理 URL 有效（如果设置了 HTTPS_PROXY）
• CA 证书文件存在（如果设置了 GPC_CA_CERT）
• DNS 解析（androidpublisher + playdeveloperreporting）
• 身份验证有效
• API 连通性（已获取访问令牌）
• 开发者验证截止日期（2026 年 9 月 30 日）
• 缓存过期警告（超过 7 天）
• Shell 补全检测（bash/zsh）
• API 配额接近上限：每日或每分钟用量超过 80% 时发出警告（v0.9.71+）
• 插件运行状况：验证每个已配置插件是否都能无错误加载（v0.9.71+）
• 签名密钥验证：--verify 会获取 Play 签名证书，并与本地密钥库进行比较（v0.9.75+）
• 报告存储桶（reports-bucket）：探测 Play 批量报告存储桶；如果服务帐号缺少“下载批量报告（只读）”授权或存储桶名称有误，则发出警告（v0.9.93+）

使用 gpc doctor --fix 自动修复可修复的问题（版本、身份验证、配置键）。

支持 JSON 输出：gpc doctor --json 或 gpc doctor --output json。

签名密钥验证（v0.9.75+）

# Show Play signing certificate fingerprint
gpc doctor --verify

# Compare against a local keystore
gpc doctor --verify --keystore release.keystore --store-pass $STORE_PASSWORD

环境变量替代方案：GPC_KEYSTORE_PATH 和 GPC_STORE_PASSWORD。

5a）检查开发者验证

gpc verify              # Status, deadlines, resources
gpc verify --open       # Open verification page in browser
gpc verify checklist    # Interactive readiness walkthrough

Google 的 Android 开发者验证强制执行将于 2026 年 9 月在巴西、印度尼西亚、新加坡和泰国开始。gpc doctor 将其列为第 20 项检查。

gpc verify checklist 会对 11 项准备情况进行评分（v0.9.96+）：其中 4 项可从帐号和应用中自动检测（Play Console 帐号已启用、可通过 API 访问应用、至少已上传一个应用包、已加入 Play 应用签名），另外 7 项 GPC 无法检测。截至 v0.9.96，这 7 项均可在提示时作答：

• 已在 Play Console 中完成身份验证
• 已查看 2026 年 9 月 30 日的强制执行时间表（巴西、印度尼西亚、新加坡、泰国）
• 已查看自动注册结果
• 帐号中的每个应用都已在 Play Console 中注册（2026 年 7 月 15 日的强制要求）
• 已查看 2027 年 2 月的内存和 DEX 优化质量要求（v0.9.96 新增）
• 已通过 Android Restore Credentials API 实现 Zero-Tap Sign-In，此项要求于 2027 年 4 月 生效；目前游戏可豁免（v0.9.96 新增）
• 已注册 Play 以外使用的其他签名密钥

每项会显示 ✓（已完成）、✗（需要处理）或 ?（无法自动检测且尚未作答）。手动项目只有在回答提示后才会变为 ✓ 或 ✗，因此在 --no-interactive、--json 或 CI 模式下，这 7 项都会保持为 ?——需要获取真实评分时，请以交互方式运行。

5b）通过 CLI 浏览文档（v0.9.64+ 内嵌文档）

从 v0.9.64 起，GPC 将 108 个文档页面内嵌在二进制文件中。无需联网。

gpc docs list                     # List all 108 embedded topics
gpc docs show authentication      # Render a guide in the terminal (ANSI-formatted)
gpc docs show auth                # Fuzzy slug matching
gpc docs search "staged rollout"  # Full-text search across all pages
gpc docs init                     # Write GPC.md quick-reference into repo (for AI agents)
gpc docs web                      # Open docs site in browser (previous default behavior)

gpc docs show 会通过 $PAGER 显示较长的页面。使用 gpc docs list --json 和 gpc docs search --json 获取机器可读的输出。

5）网络配置（如有需要）

用于企业代理或自定义 CA 证书：

export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,.internal.example.com   # optional: hosts to reach directly
export GPC_CA_CERT=/path/to/ca-bundle.crt

代理只能通过这些环境变量（大小写均可）配置；配置文件中没有代理键。自 v0.9.98 起，如果代理已设置但无法应用（例如 URL 格式错误），命令会在发送任何请求前以 NETWORK_ERROR（退出代码 5）终止，而不是绕过代理直接连接。空的小写变量（例如 https_proxy=）不再会隐藏已设置的 HTTPS_PROXY。

重试配置：

export GPC_MAX_RETRIES=3
export GPC_TIMEOUT=30000
export GPC_BASE_DELAY=1000
export GPC_MAX_DELAY=60000

Shell 补全（v0.9.58+ 支持 walker，v0.9.60+ 支持动态值）

GPC 提供 bash、zsh、fish 和 PowerShell 的 Shell 补全。补全树基于内省（v0.9.58+）——新命令和插件注册的命令无需修改生成器即可自动补全。通过 .choices() 声明的标志会在按下 TAB 时显示候选列表。

# One-time setup (macOS/Linux)
gpc completion bash >> ~/.bash_completion      # or source in ~/.bashrc
gpc completion zsh  >> ~/.zshrc
gpc completion fish > ~/.config/fish/completions/gpc.fish

# Homebrew auto-installs completion files -- no eval step needed
brew install yasserstudio/tap/gpc

动态值（v0.9.60+）

补全脚本会在按下 TAB 时，为多个标志填入实时值；其后端是隐藏的 gpc __complete <ctx> 子命令。不会调用 API——只读取配置和 ~/.cache/gpc/status-*.json 缓存，冷启动时会在 150 毫秒内返回。

标志	来源
--profile	来自 ~/.config/gpc/config.json 的配置文件名称
--app / --apps	来自配置文件和状态缓存的软件包名称
--track	当前应用的轨道名称（来自状态缓存）

如果软件包或轨道补全结果已过时，请运行任何会访问 gpc status 的命令（或直接运行 gpc status）以刷新缓存。

验证

• gpc doctor 显示所有检查均已通过
• gpc auth status 显示已通过身份验证的身份
• gpc apps list 返回真实应用数据
• gpc config show 显示解析后的配置

故障模式 / 调试

症状	可能原因	修复方法
AUTH_EXPIRED	访问令牌已过期	运行 gpc auth login 重新进行身份验证
AUTH_INVALID	服务账号错误或缺少权限	检查 Google Play Console → Settings → API access
NETWORK_ERROR	代理或防火墙阻止了连接	设置 HTTPS_PROXY 和/或 GPC_CA_CERT
CONFIG_NOT_FOUND	没有配置文件	运行 gpc config init 或设置 GPC_APP 环境变量
Doctor 在“API connectivity”检查中失败	服务账号未获授 Play Console 访问权限	在 Play Console API access 设置中添加服务账号

阅读：

• references/troubleshooting.md

升级处理

• 关于 Google Play Console API 访问权限设置，请参阅：https://developers.google.com/android-publisher/getting_started
• 关于创建服务账号，请参阅：https://cloud.google.com/iam/docs/service-accounts-create