故障排除

使用 Capgo Cloud Build 构建 Native Build 时常见问题的解决方案。

Build 失败

“Upload failed” 或 “Connection timeout”

常见症状：

• 项目上传时 Build 失败
• 60 秒后出现 Timeout 错误

解决方案：

1. 检查您的网络连接

   # Test connection to Capgo
   curl -I https://api.capgo.app

2. 减小项目体积

   • 确保 node_modules/ 未被上传 (应被自动排除)
   • 检查项目中是否存在大文件：

   find . -type f -size +10M

3. 检查上传 URL 是否过期

   • 上传 URL 在 1 小时后会过期
   • 如果遇到 URL 过期错误，请重新运行 build 命令

提示

超大型项目可能会触发构建时间限制（参见 已知限制）。如需企业级方案，请联系支持团队。

“Build 超时（10 分钟）”

常见症状：

• 构建时间超过允许的最大时长
• 状态显示为 timeout

解决方案：

1. 优化依赖项

   • 移除未使用的 npm 包
   • 使用 npm prune --production 在构建前

2. 检查构建过程中的网络问题

   • 部分依赖项在构建时可能会下载大文件
   • 考虑使用 lock 文件进行预缓存

3. 检查原生依赖项

   # iOS - check Podfile for heavy dependencies
   cat ios/App/Podfile
   
   # Android - check build.gradle
   cat android/app/build.gradle

4. 联系支持

   • 如果您的应用确实需要更多时间
   • 我们可以针对特定场景调整限制

身份验证问题

“API key 无效”或“未授权”

常见症状：

• Build 立即失败并提示身份验证错误
• 401 或 403 错误

解决方案：

1. 验证 API key 是否正确

   # Test with a simple command
   bunx @capgo/cli@latest app list

2. 检查 API key 的权限

   • Key 必须具有 write 或 all 权限
   • 在 Capgo dashboard 的 API Keys 中查看

3. 确保 API key 正在被读取

   # Check environment variable
   echo $CAPGO_TOKEN
   
   # Or check your saved credentials file
   cat ~/.capgo-credentials/credentials.json   # global
   cat .capgo-credentials.json                 # local (--local)

4. 重新认证

   bunx @capgo/cli@latest login

“未找到 App”或“无权访问此 App”

常见症状：

• 认证成功但出现 App 相关错误

解决方案：

1. 确认 App 已注册

   bunx @capgo/cli@latest app list

2. 检查 App ID 是否匹配

   • 验证 capacitor.config.json appId
   • 确保命令使用正确的 App ID

3. 验证组织访问权限

   • 检查是否在正确的组织中
   • API key 必须有权访问该 App 所属组织

iOS 构建问题

“Code 签名失败”

常见症状：

• 构建在 code 签名阶段失败
• Xcode 证书或描述文件报错

解决方案：

1. 确认证书类型与构建类型匹配

   • 开发构建需要开发证书
   • App Store 构建需要发布证书

2. 检查证书与描述文件是否匹配

   # Decode and inspect your certificate
   echo $BUILD_CERTIFICATE_BASE64 | base64 -d > cert.p12
   openssl pkcs12 -in cert.p12 -nokeys -passin pass:$P12_PASSWORD | openssl x509 -noout -subject

3. 确保描述文件有效

   • 检查到期日期
   • 确认其中包含你的 App ID
   • 确认包含证书

4. 重新生成凭据

   • 删除旧证书/描述文件
   • 在 Apple Developer 门户创建新的
   • 重新编码并更新环境变量

“Provisioning profile 不包含签名证书”

常见症状：

• Xcode 在描述文件中找不到证书

解决方案：

1. 从 Apple 下载最新的描述文件

   • 前往 Apple Developer → Certificates, IDs & Profiles
   • 下载 provisioning profile
   • 确保其中包含您的证书

2. 验证 profile 中是否存在证书

   # Extract profile
   echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision
   
   # View profile contents
   security cms -D -i profile.mobileprovision

3. 使用正确的证书重新创建 profile

   • 在 Apple Developer 门户中编辑 profile
   • 确保已选中您的 distribution certificate
   • 下载并重新编码

“App Store Connect 身份验证失败”

常见症状：

• 上传至 TestFlight 失败
• API 密钥错误

解决方案：

1. 验证 API 密钥凭据

   • 检查 APPLE_KEY_ID（应为 10 位字符）
   • 检查 APPLE_ISSUER_ID（应为 UUID 格式）
   • 验证 APPLE_KEY_CONTENT 是否已正确进行 base64 编码

2. 同步您的计算机时钟

   • App Store Connect 身份验证使用基于本地系统时间生成的短期 JWT
   • Apple 会拒绝有效期超过当前时间 20 分钟以上的 Token，因此即使微小的时钟偏差也会导致原本有效的密钥失效
   • 在 Windows 上，打开 设置 > 时间和语言 > 日期和时间 并点击 立即同步
   • 在 macOS 上，打开 系统设置 > 通用 > 日期与时间 并启用自动设置时间
   • 在 Linux 上，检查 timedatectl status 并在需要时启用 NTP
   • 同步完成后，重新运行 Capgo build 或 credential 命令

   请参阅 Apple 的 API 请求令牌生成 文档，了解 App Store Connect 令牌有效期规则。

3. 在本地测试 API 密钥

   # Decode key
   echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8
   
   # Test with fastlane (if installed)
   fastlane pilot list

4. 检查 API key 的权限

   • 密钥需要“Developer”或更高权限
   • 在 App Store Connect -> Users and Access -> Keys 中进行验证

5. 确保密钥未被撤销

   • 在 App Store Connect 中检查
   • 如有需要，请生成新密钥

iOS 27 上 App 启动即崩溃

常见症状：

• 使用 Xcode 27 构建的应用在 iOS 27 上立即关闭 (TestFlight 或真机)
• 崩溃报告显示 _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

解决方案： 使用 iOS 27 SDK 构建的应用必须采用 UIScene 生命周期。添加一个 SceneDelegate 以及 UIApplicationSceneManifest 改为 ios/App/App/Info.plist，或改用 --xcode-version 26。Capgo 现在会在构建开始前拦截此类构建（预扫描检查 ios/plist-scene-lifecycle-xcode27).

“Pod install 失败”

注意

Capgo Build 将于 2026 年 12 月停止构建 CocoaPods 项目。请迁移至 Swift Package Manager：参见 Capacitor SPM 指南.

常见症状：

• CocoaPods 安装期间 Build 失败
• Podfile 错误

解决方案：

1. 确认 Podfile.lock 已提交

   git status ios/App/Podfile.lock

2. 在本地测试 pod install

   cd ios/App
   pod install

3. 检查是否存在不兼容的 pods

   • 检查 Podfile 是否存在版本冲突
   • 确保所有 pods 都支持你的 iOS deployment target

4. 清理 pod 缓存

   cd ios/App
   rm -rf Pods
   rm Podfile.lock
   pod install
   # Then commit new Podfile.lock

Android 构建问题

“Keystore 密码错误”

常见症状：

• 签名阶段构建失败
• 关于 keystore 的 Gradle 错误

解决方案：

1. 验证 keystore 密码

   # Test keystore locally
   keytool -list -keystore my-release-key.keystore
   # Enter password when prompted

2. 检查环境变量

   # Ensure no extra spaces or special characters
   echo "$KEYSTORE_STORE_PASSWORD" | cat -A
   echo "$KEYSTORE_KEY_PASSWORD" | cat -A

3. 验证 base64 编码

   # Decode and test
   echo $ANDROID_KEYSTORE_FILE | base64 -d > test.keystore
   keytool -list -keystore test.keystore

“未找到密钥别名 (Key alias not found)”

常见症状：

• 签名失败，提示别名错误

解决方案：

1. 列出 keystore 别名

   keytool -list -keystore my-release-key.keystore

2. 验证别名是否完全匹配

   • 别名区分大小写
   • 检查 KEYSTORE_KEY_ALIAS 是否有误

3. 使用 keystore 中正确的别名

   # Update environment variable to match
   export KEYSTORE_KEY_ALIAS="the-exact-alias-name"

“Gradle build 失败”

常见症状：

• 通用 Gradle 错误
• 编译或依赖问题

解决方案：

1. 先在本地测试构建

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. 检查是否有缺失的依赖

   • 检查 build.gradle 文件
   • 确保所有插件都列在 dependencies 中

3. 验证 Gradle 版本兼容性

   # Check gradle version
   cat android/gradle/wrapper/gradle-wrapper.properties

4. 清理 Gradle 缓存

   cd android
   ./gradlew clean
   rm -rf .gradle build

“Play Store 上传失败”

常见症状：

• Build 成功但 upload 失败
• Service account 错误

解决方案：

1. 验证服务账号 JSON

   # Decode and check format
   echo $PLAY_CONFIG_JSON | base64 -d | jq .

2. 检查服务账号权限

   • 前往 Play Console → 设置 → API 访问权限
   • 确保服务账号有权访问你的应用
   • 授予“发布到测试轨道”权限

3. 验证应用是否已在 Play Console 中配置

   • 必须先在 Play Console 中创建应用
   • 初始阶段必须手动上传至少一个 APK

4. 检查 API 是否已启用

   • 必须启用 Google Play Developer API
   • 在 Google Cloud Console 中检查

常见问题

“Job not found” 或 “Build status unavailable”

常见症状：

• 无法检查 Build 状态
• Job ID 错误

解决方案：

1. 稍等片刻并重试

   • Build job 可能需要几秒钟进行初始化

2. 检查 Job ID 是否正确

   • 验证初始 build 响应中的 job ID

3. 检查 build 是否已过期

   • Build 数据有效期为 24 小时

“项目同步失败”

常见症状：

• 在编译开始前 build 失败
• 文件缺失错误

解决方案：

1. 在本地运行 Capacitor sync

   bunx cap sync

2. 确保所有原生文件都已提交

   git status ios/ android/

3. 检查被 gitignore 忽略的原生文件

   • 检查 .gitignore
   • 确保重要的配置文件未被忽略

“Build 成功但未看到输出”

常见症状：

• 构建显示成功，但没有下载链接

解决方案：

1. 检查构建配置

   • 可能未配置 Artifact 存储
   • 如果构建无法访问 Artifact，请联系支持团队

2. 针对 iOS TestFlight 提交

   • 请检查 App Store Connect
   • 上传后处理可能需要 5-30 分钟

3. 针对 Android Play Store

   • 请检查 Play Console → Testing → Internal testing
   • 处理可能需要几分钟

构建成功但切换环境后 artifact 不对

常见症状：

• 构建状态为 success 但 IPA/AAB/APK 与你刚刚构建的分支或 flavor 不匹配
• 切换 RC 与 production 凭据后，Android AAB 缺失或错误，或者 --android-flavor
• 修改 signing config 或 product flavor 后，Build 完成速度快得异常

原因： Capgo 会恢复 每个 App 的 build cache 默认情况下（省略 cache_key 用于共享的通用 cache）。如果 RC 和 production 使用相同的 app ID 且没有独立的 key，恢复时可能会复用之前环境的编译输出。

解决方案：

1. 为每个环境使用独立的 cache key （推荐用于持续的 RC/PROD pipeline）：

   # Production
   bunx @capgo/cli@latest build request com.example.app --platform android \
     --cache-key=prod \
     --android-flavor production
   
   # Staging / RC
   bunx @capgo/cli@latest build request com.example.app --platform android \
     --cache-key=staging \
     --android-flavor staging

2. 强制进行一次干净构建 调试时：

   bunx @capgo/cli@latest build request com.example.app --platform android --no-cache

3. 在 API 或 webhook 集成中，传入 cache_key （例如 "prod"）或设置 cache_enabled: false 以执行一次干净运行。

查看 构建缓存 查看完整的选项参考。

CI/CD 相关问题

GitHub Actions：“Command not found”

常见症状：

• bunx @capgo/cli@latest … 在 CI 中因 “command not found” 而失败

解决方案：

1. 请先配置 Bun 以便 bunx 可用：

   - uses: oven-sh/setup-bun@v2

2. 然后运行 CLI — bunx 按需获取，无需全局安装：

   - run: bunx @capgo/cli@latest build request com.example.app --platform android

GitHub Actions：“Secrets not found”

常见症状：

• 构建时环境变量为空

解决方案：

1. 验证 Secrets 是否已设置

   • 前往仓库 Settings → Secrets and variables → Actions
   • 添加所有必需的 Secrets

2. 使用正确的语法

   env:
     CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

3. 检查 Secret 名称是否匹配

   • 名称区分大小写
   • Secret 引用无拼写错误

获取更多帮助

启用详细日志

# Add debug flag (when available)
bunx @capgo/cli@latest build request com.example.app --verbose

收集构建信息

联系技术支持时，请提供：

1. 使用的 Build 命令

   bunx @capgo/cli@latest build request com.example.app --platform ios

2. 错误信息 （完整输出内容）

3. 任务 ID （来自 build 输出）

4. 构建日志 （复制完整的终端输出）

5. 环境信息

   node --version
   npm --version
   bunx @capgo/cli@latest --version

联系支持

• Discord: 加入我们的社区
• 邮箱: support@capgo.app
• 文档: Capgo 文档

已知限制

当前限制：

• 最长构建时间：10 分钟
• 最大上传大小：约 500MB
• iOS 构建需要 24 小时的 Mac 租期，Mac 构建会排队以确保最优使用率
• 构建产物的可下载性取决于构建目标和产物存储配置

这些限制可能会根据反馈进行调整。

Prescan 阻止了我的构建

Capgo 会在上传前运行本地 预扫描 检查。请修复报告的问题，或仅忽略该 check id：

npx @capgo/cli@latest build request <appId> --platform ios \
  --prescan-skip ios/capacitor-server-url-shipped

查看完整目录： 预扫描检查.

更多资源

• 快速入门 - 初始设置指南
• 配置选项 - CLI 标志，包括 --cache-key 以及 --no-cache
• iOS 构建 - iOS 端特定配置
• Android 构建 - Android 端特定配置
• 预扫描检查 - 构建前检查与忽略标志的完整列表
• CLI 参考文档 - 完整的命令文档