故障排除

解决常见问题：使用 Capgo Cloud Build 构建原生应用时的故障排除。

构建故障

”Upload failed” or “Connection timeout”

症状:

• 项目上传过程中构建失败
• 60秒后超时错误

解决方案:

1. 检查您的网络连接

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

2. 减少项目大小

   • 确保 node_modules/ 无法上传（应自动排除）
   • 检查项目中的大文件：

   find . -type f -size +10M

3. 检查上传 URL 过期

   • 上传 URL 将在 1 小时后过期
   • 如果您收到过期 URL 错误，请重新运行构建命令

提示

非常大的项目可能会超出构建时间限制（请参见 已知限制企业选项，请联系支持。

”10 分钟后超时”

症状：

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

解决方案：

1. 优化依赖项

   • 移除未使用的npm包
   • 在构建前使用 npm prune --production 检查构建过程中的网络问题

2. 一些依赖项在构建过程中可能下载大文件

   • 某些依赖项在构建过程中可能下载大文件
   • 考虑预缓存使用锁文件

3. 检查原生依赖

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

4. 联系支持

   • 如果您的应用程序合法地需要更多时间
   • 我们可以根据特定场景调整限制

身份验证问题

“API密钥无效”或“未授权”

症状：

• 构建立即失败，出现认证错误
• 401 或 403 错误

解决方案：

1. 验证 API 密钥是否正确

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

2. 检查 API 密钥权限

   • 密钥必须具有 write 或 all 检查 __CAPGO_KEEP_0__ 面板中的 __CAPGO_KEEP_1__ 密钥
   • Check in Capgo dashboard under API Keys

3. Ensure API key is being read

   # 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 not found” or “No permission for this app”

症状：

• 验证通过但应用特定错误

解决方案：

1. 验证应用是否已注册

   bunx @capgo/cli@latest app list

2. 检查 app ID 是否匹配

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

3. 验证组织访问权限

   • 检查您是否在正确的组织中
   • API 键必须具有对应用组织的访问权限

iOS 构建问题

”Code signing failed”

问题:

• 在 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 portal 中创建新的凭据
   • 重新编码并更新环境变量

“未包含签名证书的配置文件”

症状：

• xcode 无法在配置文件中找到证书

解决方案：

1. 下载最新的配置文件

   • 前往 Apple Developer → 证书、ID 和配置文件
   • 下载配置文件
   • 确保包含您的证书

2. 验证证书是否在配置文件中

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

3. 使用正确的证书重新创建配置文件

   • 在 Apple Developer 门户中编辑配置文件
   • 确保已选择您的发布证书
   • 下载并重新编码

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 分钟未来的令牌，因此即使是微小的时钟漂移也会使一个原本有效的密钥失败
   • 在 Windows 上打开 设置 > 时区和语言 > 日期和时间 然后点击 立即同步
   • 在 macOS 上，打开 系统设置 > 常规 > 日期和时间 并启用自动时间同步
   • 在 Linux 上，检查 timedatectl status 并如果需要启用 NTP
   • 同步后重新运行 Capgo 构建或凭据命令

   参见 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 键权限

   • 键需要“开发者”角色或更高
   • 在 App Store Connect -> 用户和访问 -> 键中验证

5. 确保键未被撤销

   • 在 App Store Connect 中检查
   • 如果需要，请生成新键

“Pod 安装失败”

症状：

• 构建过程中 CocoaPods 安装失败
• Podfile 错误

解决方案：

1. 验证 Podfile.lock 是否已提交

   git status ios/App/Podfile.lock

2. 在本地测试 pod install

   cd ios/App
   pod install

3. 检查不兼容的 pods

   • 检查 Podfile 中的版本冲突
   • 确保所有 pods 支持您的 iOS 部署目标

4. 清除 Pod 缓存

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

Android 构建问题

”Keystore password incorrect”

症状：

• 签名过程中构建失败
• Gradle 错误关于密钥库

解决方案：

1. 验证密钥库密码

   # 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”

Symptoms:

• Signing fails with alias error

解决方案：

1. 列出密钥库别名

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

2. 确认别名完全匹配

   • 别名区分大小写
   • 检查KEYSTORE_KEY_ALIAS中拼写错误

3. 使用密钥库中的正确别名

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

”Gradle build failed”

问题:

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

解决方案:

1. 先在本地测试构建

   cd android
   ./gradlew clean
   ./gradlew assembleRelease

2. 检查依赖项是否缺失

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

3. 验证Gradle版本兼容性

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

4. 清空Gradle缓存

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

”Play Store upload failed”

Symptoms:

• Build succeeds but upload fails
• Service account errors

Solutions:

1. Verify service account JSON

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

2. 检查服务帐户权限

   • 前往 Google Play Console → 设置 → API 访问
   • 确保服务帐户有权访问您的应用
   • 授予“发布到测试渠道”权限

3. 验证应用已在 Google Play Console 中设置

   • 应用必须先在 Google Play Console 中创建
   • 至少需要手动上传一个 APK

4. 检查 API 是否启用

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

常见问题

”Job not found” or “Build status unavailable”

症状:

• 无法检查构建状态
• Job ID 错误

解决方案:

1. 稍等一下，重新尝试

   • 构建作业可能需要几秒钟才能初始化

2. 检查作业 ID 是否正确

   • 从初始构建响应中验证作业 ID

3. 检查构建是否过期

   • 24 小时内可获取构建数据

”Project sync failed”

Symptoms:

• Build fails before compilation starts
• Missing files errors

Solutions:

1. Run Capacitor sync locally

   bunx cap sync

2. Ensure all native files are committed

   git status ios/ android/

3. 检查被忽略的本机文件

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

“我成功构建了，但无法看到输出”

症状：

• 构建显示成功但无下载链接

解决方案：

1. 检查构建配置

   • 可能未配置的工件存储
   • 如果您的构建无法访问工件，请联系支持

2. For iOS TestFlight 提交

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

3. For Android Play Store

   • 检查 Play Console → Testing → 内部测试
   • 处理可能需要几分钟

CI/CD 特定问题

GitHub 动作：“命令未找到”

症状：

• bunx @capgo/cli@latest … CI 处理过程中出现“命令未找到”错误

解决方案：

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 动作： “找不到密钥”

症状：

• 构建环境变量为空

解决方案：

1. 验证密钥是否已设置

   • 前往仓库设置 → 秘密和变量 → 动作
   • 添加所有必需的密钥

2. 使用正确的语法

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

3. 检查密钥名称是否匹配

   • 名称区分大小写
   • 密钥引用中无拼写错误

获取更多帮助

启用详细日志

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

收集构建信息

与支持人员联系时，请包含：

1. 使用的构建命令

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

2. 错误消息 (完整输出)

3. 作业 ID （来自构建输出）

4. 构建日志 （复制全屏终端输出）

5. 环境信息

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

联系支持

• 加入我们的社区: 电子邮件
• support@__CAPGO_KEEP_0__.app: support@capgo.app
• 文档: Capgo 文档

已知限制

当前限制:

• 最大构建时间：10分钟
• 最大上传大小：约500MB
• iOS构建需要24小时的Mac租赁，构建在Mac上会排队以确保最佳使用
• 构建工件下载可用性取决于构建目的地和工件存储配置

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

预扫描阻止了我的构建

Capgo 运行本地 预扫描 上传之前运行预扫描。修复报告的发现，或者忽略该检查 id:

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

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

额外资源

• 开始 - 初步设置指南
• iOS 构建 - iOS专属配置
• Android构建 - Android专属配置
• 预扫描检查 - 预建检查和忽略标志的完整列表
• CLI参考 - 完整的命令文档