故障排除

解决使用 Capgo Cloud Build 构建原生应用时的常见问题。

构建失败

“上传失败”或“连接超时”

或超时

• 症状：
• 项目上传过程中发生错误

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 key 无效” 或 “未授权”

症状：

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

解决方案：

1. 验证API key 是否正确

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

2. 检查API key 权限

   • Key 必须具有 write 或 all 权限
   • 在Capgo控制台中检查API密钥

3. 确保API密钥正在被读取

   # 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

“应用程序未找到”或“无此应用程序的权限”

症状：

• 认证正常但应用程序特定错误

解决方案：

1. 验证应用程序已注册

   bunx @capgo/cli@latest app list

2. 验证应用程序 ID 匹配

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

3. 验证组织访问权限

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

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

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

症状：

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

Solutions:

1. 下载最新的 Apple 配置文件

   • 前往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 中检查
   • 如果需要则生成新密钥

iOS 27 上的应用程序在启动时会崩溃

症状：

• 使用 Xcode 27 构建的 iOS 27 应用程序（TestFlight 或设备）会立即关闭
• 崩溃报告显示 _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

解决方案： apps built with the iOS 27 SDK must adopt the UIScene lifecycle. Add a SceneDelegate 和一个 UIApplicationSceneManifest 到 ios/App/App/Info.plist或使用 --xcode-version 26。 Capgo 现在在构建开始之前会阻止这些构建（预检查） ios/plist-scene-lifecycle-xcode27).

“Pod 安装失败”

注意事项

Capgo 从 2026 年 12 月开始，Capgo 将停止为 CocoaPods 项目构建。请迁移到 Swift Package Manager：参见 Capacitor SPM 指南.

症状：

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

解决方案：

1. 验证 Podfile.lock 已提交

   git status ios/App/Podfile.lock

2. 测试 pod 安装本地

   cd ios/App
   pod install

3. 检查不兼容的 pod

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

4. 清除 pod 缓存

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

Android 构建问题

密钥库密码错误

症状：

• 签名过程中构建失败
• 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

“找不到密钥别名”

症状：

• 签名失败，出现别名错误

解决方案：

1. 列出密钥库别名

   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构建失败”

症状：

• 常见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上传失败”

问题:

• 构建成功但上传失败
• 服务账户错误

解决方案:

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 DeveloperAPI必须已启用
   • 检查Google Cloud Console

常见问题

“任务未找到”或“构建状态不可用”

症状：

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

解决方案：

1. 请稍等再试

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

2. 检查作业 ID 是否正确

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

3. 检查构建是否过期

   • 构建数据在 24 小时内可用

“项目同步失败”

症状：

• 构建在编译开始之前失败
• 缺失文件错误

Solutions:

1. 在本地运行Capacitor

   bunx cap sync

2. 确保所有本地文件已提交

   git status ios/ android/

3. 检查被git忽略的本地文件

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

“构建成功但我看不到输出”

问题:

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

解决方案:

1. 检查构建配置

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

2. context:页面/区域：集成营销部分。角色：短UI标签或导航项。见于：集成页面。astro。消息键`integrations_partners_freelance_contact`（集成合作伙伴自由职业者联系）

   • 对于iOS TestFlight提交
   • 检查App Store Connect

3. 上传后处理可能需要5-30分钟

   • 对于Android Play Store
   • 检查Play Console → Testing → Internal testing

环境切换后，构建成功但 artifact 错误

症状：

• 构建状态是 success 但 IPA/AAB/APK 与您刚刚构建的 branch 或 flavor 不匹配
• Android AAB 缺失或错误，可能是由于切换 RC 与生产凭证或 --android-flavor
• 构建完成后，似乎在切换签名配置或产品风味后异常快速

原因： Capgo 默认恢复 每个应用的构建缓存 (省略 cache_key 共享的通用缓存)。如果 RC 和生产共享相同的应用 ID，但没有单独的密钥，恢复可以重用之前环境的编译输出

Solutions:

1. 环境使用缓存键 (推荐用于持续的RC/PROD管道):

   # 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 动作：“命令未找到”

症状：

• bunx @capgo/cli@latest … CI 构建失败，提示“命令未找到”

解决方案：

1. 首先设置Bun 所以 bunx 可用:

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

2. 然后运行CLI — bunx 然后运行__CAPGO_KEEP_0__

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

GitHub 动作： “找不到密钥”

Symptoms:

• 症状：

构建环境变量为空

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

联系支持

• Discord: 加入我们的社区
• 电子邮件: 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

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

额外资源

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