gpc-troubleshooting 是 GPC CLI 的统一调试指南，用于排查所有 GPC 错误、退出码和常见问题。
用途 当 GPC 命令因错误码失败、gpc doctor 报告问题、CI 流水线在 GPC 步骤失败、出现意外行为或输出、需要解读退出码、或需要开启详细/调试输出时使用。
所需输入 错误消息或退出码（GPC 报告的内容）、失败的命令（完整命令）、环境信息（本地还是 CI、操作系统、Node.js 版本）。
快速诊断 可运行 gpc doctor 检查 GPC 健康状况，gpc --version 查看版本，用 GPC_DEBUG=1 gpc <failing-command> 以详细输出运行失败命令，用 gpc <failing-command> --json 获取 JSON 格式错误（自 v0.9.68 起也支持 --output csv、--output tsv）。
退出码 0 表示成功；1 表示配置错误（缺少 .gpcrc.json、字段无效）；2 表示用法错误（参数或标志无效）；3 表示认证失败（令牌过期、密钥无效、无凭据）；4 表示 Google Play API 错误（403、404、408、409、限流）；5 表示网络失败、DNS 错误、超时；6 表示 Vitals 阈值被突破或没有可比较的值（用于 CI 门禁）；10 表示插件权限校验错误。v1.0.0-rc.1 有变更：用法错误现在退出 2（此前为 1）；vitals 或 anomalies 的 403 现在退出 4（此前打印“无数据”并退出 0）；无终端且无 --yes 的退款或撤销操作退出 2 并返回 CONFIRMATION_REQUIRED。
认证错误（退出码 3） 包括 AUTH_FAILED（凭据无效或损坏，重新运行 gpc auth login --service-account <key.json>）、AUTH_EXPIRED（令牌过期且刷新失败，重新认证并检查网络/代理）、AUTH_NO_CREDENTIALS（未配置认证，运行 gpc auth login 或设置 GPC_SERVICE_ACCOUNT）、AUTH_INVALID_KEY（服务账号 JSON 格式错误，从 Google Cloud Console 重新下载密钥）、AUTH_KEYCHAIN_ERROR（操作系统钥匙串访问被拒，授予访问权限或使用环境变量认证）。可用 gpc auth status 检查状态，用 export GPC_SERVICE_ACCOUNT=$(cat ~/path/to/key.json) 绕过钥匙串。
API 错误（退出码 4） 涵盖 API_FORBIDDEN（403，权限不足）、API_NOT_FOUND（404，应用/轨道/资源不存在）、API_CONFLICT（409，已有编辑进行中）、API_RATE_LIMITED（429，请求过多，GPC 自动重试，可增大 GPC_BASE_DELAY）、API_REQUEST_TIMEOUT（408，自动指数退避重试）、API_SERVER_ERROR（5xx，稍后重试）、EDIT_CONFLICT（409，其他工具或用户并发编辑）、API_DUPLICATE_VERSION_CODE（409，版本号已上传）、API_VERSION_CODE_TOO_LOW（400）、API_PACKAGE_NAME_MISMATCH（400）、API_APP_NOT_FOUND（404）、API_INSUFFICIENT_PERMISSIONS（403）、API_DECLARATION_REQUIRED（403，Play Console 的“应用内容”声明未完成）、API_ALREADY_EXISTS（409，改用对应更新命令）、API_ENDPOINT_RETIRED（404，Google 已移除该端点，目前影响 gpc games ... set-icon）、API_CHANGES_NOT_SENT_FOR_REVIEW（400/403，需加 --changes-not-sent-for-review）、API_CHANGES_ALREADY_IN_REVIEW（400，可用 --error-if-in-review 防止静默取消）、API_EDIT_EXPIRED（410，编辑会话约 30 分钟无活动后过期，重试会自动创建新编辑）、API_ROLLOUT_DECREASE_FORBIDDEN（400，分阶段发布百分比只能增加，停止发布用 gpc releases rollout halt --track production）。
网络错误（退出码 5） 包括 NETWORK_ERROR（连接失败，检查网络和代理）、NETWORK_TIMEOUT（增大 GPC_TIMEOUT，默认 30000ms）、NETWORK_DNS（检查 DNS，可试 8.8.8.8）、NETWORK_SSL（设置 GPC_CA_CERT 自定义 CA，检查代理）。可配置 GPC_MAX_RETRIES、GPC_BASE_DELAY、GPC_MAX_DELAY、HTTPS_PROXY、GPC_CA_CERT。
配置错误（退出码 1） 包括 CONFIG_MISSING（运行 gpc setup 或 gpc config init）、CONFIG_INVALID、CONFIG_INVALID_JSON（用 python3 -m json.tool 定位）、CONFIG_INVALID_KEY、CONFIG_APP_MISSING。v0.9.81+ 修复了配置优先级：标志覆盖环境变量，环境变量覆盖活动 profile，活动 profile 覆盖默认值。
上传与发布错误 包括 INVALID_BUNDLE、VERSION_CODE_CONFLICT、RELEASE_NOT_FOUND、RELEASES_USAGE_ERROR / PUBLISH_USAGE_ERROR（退出 2，--rollout 和 --to 是百分比，如 --rollout 10）、PROMOTE_NO_SOURCE、UPLOAD_CHUNK_FAILED、UPLOAD_NO_COMPLETION、UPLOAD_INITIATE_FAILED、UPLOAD_NO_SESSION_URI、UPLOAD_SESSION_NOT_FOUND、UPLOAD_SESSION_EXPIRED、UPLOAD_INVALID_CHUNK_SIZE（块大小须为 256 KB 的倍数，即 262144）、EDIT_VALIDATE_FAILED（自 v0.9.77 起自动多重试）、REVIEW_SKIPPED（内部轨道无需审核，属预期行为）。提交被拒需审核时，--json 输出包含 reviewPending 和 nextStep 结构化结果。
Vitals 阈值（退出码 6） 退出码 6 不是错误，而是 Vitals 指标超过阈值的信号，用于 CI 门禁。例如 gpc vitals crashes --threshold 0.02 在崩溃率超过 2% 时退出 6。
订单退款审核错误（退出码 2，v0.9.96+） ORDER_REVIEW_REFUND_INVALID 表示 gpc purchases orders review-refund 输入无效，需正确提供 --sample-content-provided / --no-sample-content-provided、--consumption-percent 在 0-100 之间、--usage-events-file 为 JSON 对象数组。
插件错误（退出码 10） 包括 PLUGIN_INVALID_PERMISSION、PLUGIN_PERMISSIONS_REQUIRED、PLUGIN_IDENTITY_MISMATCH，以及插件未加载或钩子报错。
变更日志生成错误（v0.9.61+） 包括 CHANGELOG_NO_TAG、CHANGELOG_BAD_REF、CHANGELOG_LOCALES_REQUIRED、CHANGELOG_LOCALES_INVALID、CHANGELOG_LOCALES_AUTO_NO_APP、CHANGELOG_FETCH_FAILED、CHANGELOG_VERSION_NOT_FOUND、WATCH_WEBHOOK_FAILED、CHANGELOG_LOCALES_EMPTY、RELEASE_NO_DRAFT、BUNDLE_PROCESSING_TIMEOUT。
批量报告错误（v0.9.93+） gpc reports list 和 gpc reports download stats|financial 从开发者账号关联的 Cloud Storage 桶（pubsite_prod_<developerId>）读取 Play 月度批量报告 CSV。错误码包括 REPORT_ACCESS_DENIED（4）、REPORT_AUTH_REJECTED（3）、REPORT_BUCKET_UNKNOWN（2）、REPORT_BUCKET_INVALID（2）、REPORT_BUCKET_NOT_FOUND（4）、REPORT_OBJECT_NOT_FOUND（4）、REPORT_LIST_FAILED（4）、REPORT_DOWNLOAD_FAILED（4）、REPORT_DECODE_FAILED（4）、REPORT_ARCHIVE_UNREADABLE（4）、REPORT_MULTIPLE_ENTRIES（2）等。
适用场景与限制 该技能适用于本地调试和 CI 流水线中定位 GPC 失败原因，提供退出码解读与修复建议。部分错误（如 API_ENDPOINT_RETIRED）无法通过 CLI 修复，需在 Play Console 操作。具体平台支持、收费与价格信息暂未提供。