管理凭据

复制一个包含安装步骤和本插件的完整Markdown指南的配置提示。

管理您的 iOS 和 Android 构建凭据本地，方便云构建。

概述

Capgo CLI 在您的机器上存储您的构建凭据 — 从不在 __CAPGO_KEEP_0__ 的服务器上。默认情况下，它们存储在一个 — never on Capgo’s servers. By default they live in one 文件中 , ~/.capgo-credentials/credentials.json所有项目共享。 --local 保留它们 每个项目 在 .capgo-credentials.json 而不是。当您运行构建时，保存的凭据将自动使用并安全地发送到 Capgo, 然后在构建完成后删除。

命令

交互式管理凭据

与保存的凭据一起工作的最快方法是交互式管理器。它打开一个 TUI（同样使用的）界面，允许您浏览存储的内容，查看每个应用程序和平台的配置，导出一个 CI/CD-ready 文件，或者删除一个平台的凭据： build init 终端窗口 .env 复制到剪贴板

bunx @capgo/cli@latest build credentials manage

选项	描述
`--appId <appId>`	用于管理的应用程序（如果省略则会提示您选择）
`--platform <ios\|android>`	用于管理的平台（如果省略则会提示您选择）
`--local`	使用项目级别的 `.capgo-credentials.json` 而不是全局文件

是否希望使用一次性、可脚本化的命令？请使用以下单个命令。

保存凭据

本地存储您的构建凭据以便自动使用：

bunx @capgo/cli@latest build credentials save --platform <ios|android> [options]

更新凭据

部分更新现有凭据而不需要重新提供所有内容：

bunx @capgo/cli@latest build credentials update --platform <ios|android> [options]

这个 update 命令使用 累积合并 用于配置文件 — 新配置文件与现有配置文件合并。要替换整个配置映射而不是，请添加 --overwrite-ios-provisioning-map.

示例 — 将扩展配置文件添加到现有凭据：

bunx @capgo/cli@latest build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.widget=./widget_profile.mobileprovision"

更新命令接受的选项与 save 但所有选项都是可选的 — 只有您提供的字段会被更新。

列表凭据

查看当前保存的凭据（密码会被掩码）：

bunx @capgo/cli@latest build credentials list

# List credentials for a specific app
bunx @capgo/cli@latest build credentials list --appId com.example.app

清除凭据

从本地机器中删除保存的凭据：

# Clear all credentials
bunx @capgo/cli@latest build credentials clear

# Clear credentials for a specific app + platform
bunx @capgo/cli@latest build credentials clear --appId com.example.app --platform ios

迁移凭据

将遗留的单一配置格式转换为新的多目标格式：

bunx @capgo/cli@latest build credentials migrate --platform ios

迁移命令检测旧的 BUILD_PROVISION_PROFILE_BASE64 凭据，转换为 CAPGO_IOS_PROVISIONING_MAP，并删除遗留的键。请参阅单一配置迁移详细信息。

保存 iOS 凭据

完整示例

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --p12-password "YourP12Password" \
  --ios-provisioning-profile "com.example.app=./profile.mobileprovision" \
  --apple-key ./AuthKey_ABC1234567.p8 \
  --apple-key-id "ABC1234567" \
  --apple-issuer-id "00000000-0000-0000-0000-000000000000" \
  --apple-team-id "TEAM123456"

iOS 选项

选项	描述	必填
`--certificate <path>`	p12证书文件路径	是 (发布)
`--p12-password <password>`	p12证书密码	是 (发布)
`--ios-provisioning-profile <mapping>`	配置文件映射 (`bundleId=path`可重复使用，适用于多目标应用。如果只有一个配置文件且没有 bundleId 前缀，CLI 会自动从配置文件中推断。	是 (发布)
`--apple-key <path>`	App Store Connect API .p8 密钥路径	请参见注释¹
`--apple-key-id <id>`	App Store Connect API Key ID	查看说明¹
`--apple-issuer-id <id>`	App Store Connect API Issuer ID (UUID)	查看说明¹
`--apple-team-id <id>`	App Store Connect Team ID	是
`--apple-id <email>`	用于上传应用特定密码的苹果 ID 邮箱（替代 API 密钥）	查看说明²
`--apple-app-specific-password <password>`	应用特定密码（`xxxx-xxxx-xxxx-xxxx`)	查看说明²
`--apple-app-id <id>`	数字 App Store Connect 应用 ID（例如 `1234567890`)	查看说明²
`--ios-distribution <mode>`	发布模式: `app_store` (默认) 或 `ad_hoc`	无
`--output-upload`	启用一个时间限制的Capgo下载链接	无 (默认: `false`)
`--output-retention <seconds>`	保留构建输出的时间长度（例如 `3600s`)	无 (默认: `3600s`)
`--skip-build-number-bump`	跳过自动构建编号递增	无

标题：什么被存储了

When you save iOS credentials, the CLI:

将它们转换为 base64 编码
Converts them to base64 encoding
保存到 ~/.capgo-credentials/credentials.json （或” .capgo-credentials.json 使用 --local)
存储密码和 ID 为纯文本（仅限本地文件）

存储的文件结构：

{
  "ios": {
    "BUILD_CERTIFICATE_BASE64": "...",
    "CAPGO_IOS_PROVISIONING_MAP": "{\"com.example.app\":{\"profile\":\"...\",\"name\":\"match AppStore com.example.app\"}}",
    "APPLE_KEY_CONTENT": "...",
    "P12_PASSWORD": "...",
    "APPLE_KEY_ID": "ABC1234567",
    "APPLE_ISSUER_ID": "...",
    "APP_STORE_CONNECT_TEAM_ID": "TEAM123456",
    "CAPGO_IOS_DISTRIBUTION": "app_store"
  }
}

保存 Android 凭据

完整示例

bunx @capgo/cli@latest build credentials save \
  --platform android \
  --keystore ./release.keystore \
  --keystore-alias "my-key-alias" \
  --keystore-key-password "KeyPassword123" \
  --keystore-store-password "StorePassword123" \
  --play-config ./play-store-service-account.json

Android 选项

选项	描述	必填
`--keystore <path>`	keystore或.jks文件的路径	是 (发布)
`--keystore-alias <alias>`	密钥库中的别名	是 (发布)
`--keystore-key-password <password>`	密钥别名的密码	是 (发布)
`--keystore-store-password <password>`	密钥库的密码	是 (发布)
`--play-config <path>`	Play Store 服务账户 JSON 文件路径	是 (提交)

存储的内容

当您保存 Android 凭据时，CLI:

读取密钥库和服务帐户 JSON 文件
将它们转换为 base64 编码
保存到 ~/.capgo-credentials/credentials.json （或 .capgo-credentials.json 使用 --local)
存储密码和别名为纯文本（仅限本地文件）

存储的文件结构：

{
  "android": {
    "ANDROID_KEYSTORE_FILE": "...",
    "PLAY_CONFIG_JSON": "...",
    "KEYSTORE_KEY_ALIAS": "my-key-alias",
    "KEYSTORE_KEY_PASSWORD": "...",
    "KEYSTORE_STORE_PASSWORD": "..."
  }
}

使用保存的凭据

您保存凭据后，它们将自动在您构建时使用：

# Credentials automatically loaded from ~/.capgo-credentials/credentials.json
bunx @capgo/cli@latest build request com.example.app --platform ios

您也可以使用环境变量覆盖保存的凭据:

# Environment variables take precedence over saved credentials
BUILD_CERTIFICATE_BASE64="..." \
P12_PASSWORD="different-password" \
bunx @capgo/cli@latest build request com.example.app --platform ios

优先顺序:

环境变量（最高优先级）
保存的凭据（~/.capgo-credentials/credentials.json,或本地 .capgo-credentials.json)
无凭据（最低优先级）

查看保存的凭据

列出您保存的凭据：

bunx @capgo/cli@latest build credentials list

示例输出：

📋 Saved Build Credentials:

iOS Credentials:
  ✓ Certificate (base64)
  ✓ Provisioning Map (JSON)
  ✓ Apple Key Content (base64)
  ✓ P12 Password: ********
  ✓ Apple Key ID: ABC1234567
  ✓ Apple Issuer ID: 00000000-0000-0000-0000-000000000000
  ✓ Team ID: TEAM123456

Android Credentials:
  ✓ Keystore (base64)
  ✓ Play Store Config (base64)
  ✓ Keystore Alias: my-key-alias
  ✓ Key Password: ********
  ✓ Store Password: ********

Location: ~/.capgo-credentials/credentials.json

🔒 These credentials are stored locally on your machine only.
   When building, they are sent to Capgo but NEVER stored there.
   They are auto-deleted after build completion.

安全最佳实践

本地存储安全

文件权限

# Global credentials directory + file
chmod 700 ~/.capgo-credentials
chmod 600 ~/.capgo-credentials/credentials.json
# Local (per-project) credentials, if you use --local
chmod 600 .capgo-credentials.json

不要提交凭证

# Ignore the per-project credentials file (used with --local)
echo ".capgo-credentials.json" >> .gitignore

__CAPGO_KEEP_0__

独立凭据
- 为本地开发和 CI/CD 使用不同的凭据
- 定期轮换凭据
- 不要在团队成员之间共享凭据

CI/CD 使用

对于 CI/CD 环境来说， 优先使用环境变量 而不是保存的凭据

导出一个可用的 `.env` (推荐)

而不是手动将每个凭据文件进行 base64 编码（见下面），让 build credentials manage 它为您生成文件：

bunx @capgo/cli@latest build credentials manage
# pick your app → choose "Export to .env"

它写入一个 .env.capgo.<appId>.<platform> 文件（权限 0600)，包含所有保存的凭据作为环境变量 — 每行都是要添加到您的 CI/CD 提供商中的一个秘密。两种平台默认组合；添加 --platform ios 或 --platform android 将其限制在一个。

环境变量参考文档

CLI 读取以下环境变量以获取凭据：

iOS 凭据：

变量	描述	格式	必填
`BUILD_CERTIFICATE_BASE64`	code 签名的 P12/PKCS12 证书	Base64	是 (发布)
`CAPGO_IOS_PROVISIONING_MAP`	应用 ID 到配置文件数据的 JSON 映射	JSON 字符串	是 (发布)
`P12_PASSWORD`	P12 证书的密码	纯文本	可选
`APPLE_KEY_ID`	API Key ID	String (例如，“ABC1234567”)	参见注释¹
`APPLE_ISSUER_ID`	App Store Connect API 发行者 ID	UUID 字符串	参见注释¹
`APPLE_KEY_CONTENT`	App Store Connect API 密钥 (.p8 文件内容)	Base64	参见注释¹
`APP_STORE_CONNECT_TEAM_ID`	Apple 开发者团队 ID	字符串 (例如，“XXXXXXXXXX”)	是
`CAPGO_IOS_DISTRIBUTION`	发布模式： `app_store` (默认) 或 `ad_hoc`	字符串	否

Android凭据:

变量	描述	格式	必填
`ANDROID_KEYSTORE_FILE`	用于签名 APK/AAB 的.keystore文件	Base64	是 (发布)
`KEYSTORE_KEY_ALIAS`	keystore 中的密钥别名	字符串	是 (发布)
`KEYSTORE_KEY_PASSWORD`	密钥别名的密码	明文	是*
`KEYSTORE_STORE_PASSWORD`	密钥库文件的密码	明文	是*
`PLAY_CONFIG_JSON`	Google Play 服务账户 JSON	Base64	是 (提交)

*如果只提供一个密码，它将用于两个 KEYSTORE_KEY_PASSWORD 和 KEYSTORE_STORE_PASSWORD.

GitHub Actions Example

name: Cloud Build

on:
  push:
    branches: [main]

jobs:
  build-ios:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bunx @capgo/cli@latest build request com.example.app --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}

  build-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bunx @capgo/cli@latest build request com.example.app --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

准备 Base64 值

终端窗口

# iOS Certificate (.p12)
base64 -i certificate.p12 | tr -d '\n' > certificate_base64.txt

# iOS Provisioning Profiles — use the CLI to generate CAPGO_IOS_PROVISIONING_MAP:
bunx @capgo/cli@latest build credentials save --platform ios \
  --ios-provisioning-profile "com.example.app=./profile.mobileprovision" \
  # ... other options
# Then copy CAPGO_IOS_PROVISIONING_MAP from ~/.capgo-credentials/credentials.json to your CI secrets

# iOS App Store Connect Key (.p8)
base64 -i AuthKey_XXXXXX.p8 | tr -d '\n' > apple_key_base64.txt

# Android Keystore (.keystore or .jks)
base64 -i release.keystore | tr -d '\n' > keystore_base64.txt

# Google Play Service Account JSON
base64 -i play-store-service-account.json | tr -d '\n' > play_config_base64.txt

为什么环境变量更安全

这种方法更安全，因为：

密钥由您的CI/CD平台管理
没有在运行器上存储凭据
易于轮换和访问控制
密钥使用的审计记录

密钥轮换

定期轮换您的凭据：

iOS: 每年生成新证书和API密钥
Android: 每年更改keystore密码
团队成员变更后: 当团队成员离开时旋转

更新保存的凭据:

# Re-run save command with new credentials
bunx @capgo/cli@latest build credentials save --platform ios --certificate ./new-cert.p12 ...

故障排除

找不到凭据

如果构建显示没有找到凭据:

检查是否已保存凭据:

bunx @capgo/cli@latest build credentials list

如果缺少凭据，请保存:

bunx @capgo/cli@latest build credentials save --platform ios ...

验证凭据文件是否存在:

ls -la ~/.capgo-credentials/credentials.json   # global
ls -la .capgo-credentials.json                 # local (--local)

读取凭据时出现“权限被拒绝”

修复文件权限：

chmod 600 ~/.capgo-credentials/credentials.json   # global
chmod 600 .capgo-credentials.json                 # local

凭证未被使用

检查是否指定了正确的平台：

# Make sure --platform matches saved credentials
bunx @capgo/cli@latest build request com.example.app --platform ios  # Uses ios credentials
bunx @capgo/cli@latest build request com.example.app --platform android  # Uses android credentials

清除并重新保存凭证

如果凭证看起来被损坏：

# Clear all credentials
bunx @capgo/cli@latest build credentials clear

# Save again
bunx @capgo/cli@latest build credentials save --platform ios ...

从环境变量迁移

如果您当前正在使用环境变量，可以迁移到保存的凭据:

提取您的当前环境变量

echo $BUILD_CERTIFICATE_BASE64  # Verify they exist

解码base64文件回原始文件 (如果需要)

echo "$BUILD_CERTIFICATE_BASE64" | base64 -d > cert.p12
echo "$BUILD_PROVISION_PROFILE_BASE64" | base64 -d > profile.mobileprovision

使用CLI保存

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./cert.p12 \
  --ios-provisioning-profile ./profile.mobileprovision \
  --p12-password "$P12_PASSWORD" \
  --apple-key-id "$APPLE_KEY_ID" \
  --apple-issuer-id "$APPLE_ISSUER_ID" \
  --apple-team-id "$APP_STORE_CONNECT_TEAM_ID"

如果您在旧格式中已保存的凭据（单个），请运行： BUILD_PROVISION_PROFILE_BASE64终端窗口

bunx @capgo/cli@latest build credentials migrate --platform ios

并删除旧的 CAPGO_IOS_PROVISIONING_MAP 和 BUILD_PROVISION_PROFILE_BASE64 测试构建 APPLE_PROFILE_NAME 测试构建

和

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

移除环境变量 (可选)

unset BUILD_CERTIFICATE_BASE64 BUILD_PROVISION_PROFILE_BASE64

文件位置

凭据存储在一个单独的 JSON 文件中：

全局 (默认): ~/.capgo-credentials/credentials.json — 在所有项目中共享
本地 (在 --local): .capgo-credentials.json 项目根目录中 — 覆盖全局文件

文件会自动创建在您第一次保存凭据时。添加 .capgo-credentials.json 到您的 .gitignore 以便项目凭据从不被提交。

下一步

开始 - 创建您的第一个构建
iOS构建 - iOS特定的构建配置
Android 构建 - Android 特有的构建配置
故障排除上下文:支持/高级支持页面或底部支持部分。角色:部分或页面标题。见于:页面 support-policy.astro。消息键 `support_policy_troubleshooting_title` (支持政策故障排除标题)。

- 常见问题和解决方案

support@__CAPGO_KEEP_0__.app

如果您正在使用 管理凭据 为CI/CD自动化规划,连接它 Capgo CI/CD 在Capgo CI/CD中为产品工作流程 Capgo 原生构建在Capgo 原生构建中为产品工作流程 Capgo 集成在Capgo 集成中为产品工作流程 CI/CD集成为CI/CD集成的实现细节 GitHub 动作集成为GitHub Actions Integration的实现细节。

管理凭据

概述

命令

交互式管理凭据

保存凭据

更新凭据

列表凭据

清除凭据

迁移凭据

保存 iOS 凭据

完整示例

iOS 选项

标题：什么被存储了

保存 Android 凭据

完整示例

Android 选项

存储的内容

使用保存的凭据

查看保存的凭据

安全最佳实践

本地存储安全

CI/CD 使用

导出一个可用的 .env (推荐)

环境变量参考文档

GitHub Actions Example

准备 Base64 值

为什么环境变量更安全

密钥轮换

故障排除

找不到凭据

读取凭据时出现“权限被拒绝”

凭证未被使用

清除并重新保存凭证

从环境变量迁移

文件位置

下一步

- 常见问题和解决方案

support@__CAPGO_KEEP_0__.app

导出一个可用的 `.env` (推荐)