凭据管理

复制包含安装步骤和该插件完整 Markdown 指南的配置 prompt。

在本地管理您的 iOS 和 Android 构建凭据，实现便捷的云端构建。

概览

Capgo CLI 会把你的构建凭据保存在 你的机器上 ——绝不会存放在 Capgo 的服务器上。默认情况下，它们存放在一个全局文件中， ~/.capgo-credentials/credentials.json供所有项目共用。传入参数 --local 可将它们 按项目 中的 .capgo-credentials.json 分别保存。运行构建时，会自动使用已保存的凭据并安全发送到 Capgo，构建完成后再将其删除。

命令

交互式管理凭据

使用已保存的凭据最快的方式是交互式管理器。它会打开一个 TUI（与 build init 使用的是同一个），你可以在其中浏览已存储的内容，查看每个 App 和平台配置了什么，导出可直接用于 CI/CD 的 .env 文件，或删除某个平台的凭据：

bunx @capgo/cli@latest build credentials manage

选项	描述
`--appId <appId>`	要管理的 App（若未指定会提示选择）
`--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 命令用于 增量合并 用于描述文件 (provisioning profiles) —— 新文件将与现有文件合并。若要替换整个描述文件映射，请添加 --overwrite-ios-provisioning-map.

示例 —— 为现有凭据添加扩展描述文件：

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

update 命令接受与以下相同的选项 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

migrate 命令会检测旧的 BUILD_PROVISION_PROFILE_BASE64 凭据，将其转换为新格式， CAPGO_IOS_PROVISIONING_MAP并移除旧版密钥。请参阅从单一 Profile 迁移详情。

保存 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 证书文件路径	是（release）
`--p12-password <password>`	.p12 证书密码	是（release）
`--ios-provisioning-profile <mapping>`	Provisioning profile 映射 (`bundleId=path`)。适用于多 target 应用。若仅有一个 profile 且无 bundleId 前缀，CLI 会根据 profile 自动推断。	是（release）
`--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>`	使用 App 专用密码上传时用的 Apple ID 邮箱（API 密钥的替代方案）	参见注²
`--apple-app-specific-password <password>`	App 专用密码 (`xxxx-xxxx-xxxx-xxxx`)	参见注²
`--apple-app-id <id>`	App Store Connect 的数字 App ID (例如 `1234567890`)	参见注²
`--ios-distribution <mode>`	分发模式： `app_store` (默认) 或 `ad_hoc`	否
`--output-upload`	为构建产物启用限时 Capgo 下载链接	否 (默认： `false`)
`--output-retention <seconds>`	构建输出文件的保留时长（例如 `3600s`)	否 (默认： `3600s`)
`--skip-build-number-bump`	跳过自动构建版本号递增	否

存储内容

当您保存 iOS 凭据时，CLI 会：

读取证书和 provisioning profile 文件
将其转换为 base64 编码
并将其保存到 ~/.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 文件的路径	是（release）
`--keystore-alias <alias>`	keystore 中的 Key alias	是（release）
`--keystore-key-password <password>`	Key alias 的密码	是（release）
`--keystore-store-password <password>`	Keystore 密码	是（release）
`--play-config <path>`	Play Store 服务账号 JSON 路径	是（用于提交）

存储内容

保存 Android 凭据时，CLI 会：

读取 keystore 和服务账号 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

全局文件位于您的主目录中，不在代码仓库内。

隔离凭据
- 为本地开发与 CI/CD 使用不同的凭据
- 定期轮换凭据
- 切勿在团队成员间共享凭据

CI/CD 用法

对于 CI/CD 环境， 优先使用环境变量 而非保存的凭据。

导出即插即用的 `.env` （推荐）

与其手动对每个凭据文件进行 base64 编码（参见下方), let 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	是（release）
`CAPGO_IOS_PROVISIONING_MAP`	Bundle ID 与 Provisioning Profile 数据的 JSON 映射	JSON 字符串	是（release）
`P12_PASSWORD`	P12 证书密码	明文	可选
`APPLE_KEY_ID`	App Store Connect API Key ID	字符串 (例如 “ABC1234567”)	查看备注¹
`APPLE_ISSUER_ID`	App Store Connect API Issuer ID	UUID 字符串	查看备注¹
`APPLE_KEY_CONTENT`	App Store Connect API 密钥（.p8 文件内容）	Base64	查看备注¹
`APP_STORE_CONNECT_TEAM_ID`	Apple Developer Team ID	字符串（例如 “XXXXXXXXXX”）	是
`CAPGO_IOS_DISTRIBUTION`	分发模式： `app_store` (默认) 或 `ad_hoc`	字符串	否

Android 凭据：

变量	描述	格式	必填
`ANDROID_KEYSTORE_FILE`	用于签名 APK/AAB 的 Keystore 文件	Base64	是（release）
`KEYSTORE_KEY_ALIAS`	Keystore 中的 Key alias	字符串	是（release）
`KEYSTORE_KEY_PASSWORD`	Key alias 的密码	明文	是*
`KEYSTORE_STORE_PASSWORD`	Keystore 文件的密码	明文	是*
`PLAY_CONFIG_JSON`	Google Play 服务账号 JSON	Base64	是（用于提交）

*如果只提供一个密码，将同时用于两者 KEYSTORE_KEY_PASSWORD 以及 KEYSTORE_STORE_PASSWORD.

GitHub Actions 示例

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 值

若要将凭据文件转换为 base64 以用于 CI/CD secrets：

# 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 平台管理密钥
Runner 上不留凭据文件
便捷的轮换与访问控制
密钥使用审计日志

凭据轮换

定期轮换您的凭据：

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 密钥。

测试 build

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 专用构建配置
故障排除 - 常见问题与解决方案

需要帮助？

继续阅读：管理凭据

如果你正在使用 凭据管理 规划 CI/CD 自动化，并将其与 Capgo CI/CD 集成用于 Capgo CI/CD 中的产品工作流， Capgo Native Build 用于 Capgo Native Builds 中的产品工作流， Capgo 集成用于 Capgo 集成中的产品工作流， CI/CD 集成了解 CI/CD 集成的实现细节，以及 GitHub Actions 集成有关 GitHub Actions 集成的实现细节。

凭据管理

概览

命令

交互式管理凭据

保存凭据

更新凭据

列出凭据

清除凭据

迁移凭据

保存 iOS 凭据

完整示例

iOS 选项

存储内容

保存 Android 凭据

完整示例

Android 选项

存储内容

使用已保存的凭据

查看已保存的凭据

安全最佳实践

本地存储安全

CI/CD 用法

导出即插即用的 .env （推荐）

环境变量完整参考指南

GitHub Actions 示例

准备 Base64 值

为什么环境变量更安全

凭据轮换

故障排除

“未找到凭据”

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

凭据未被使用

清除并重新保存凭据

从环境变量迁移

文件位置

下一步

需要帮助？

继续阅读：管理凭据

导出即插即用的 `.env` （推荐）