如何在云中签名和构建一个 Capacitor 应用

要在云端签名并构建一个 Capacitor 应用，您只需创建一次签名材料（Android.keystore、iOS 分发证书和配置文件），将其提供给云构建服务，然后从终端或 CI 触发构建。该服务会编译本机项目、签名并将其直接上传到 TestFlight 或 Google Play。该指南将涵盖每个签名文件、如何在没有 Mac 的情况下创建它、如何将其设置为 Capgo 构建，并如何安全地自动签名构建。

什么是“云端签名”

两家商店都只接受签名二进制文件。签名证明构建来自您，并且没有人在之后修改它。局部，Xcode 和 Android Studio 隐藏了大部分内容。在云端，所有内容都是显式的，所以您需要知道哪些文件参与其中：

上传到 TestFlight，读取构建号

请勿将这些信息存入 Git。以下所有信息将存储在您的本地凭据文件或 CI 的密钥存储中。

Android 签名信息存储在本地凭据文件或 CI 的密钥存储中。请勿将这些信息存入 Git。以下所有信息将存储在您的本地凭据文件或 CI 的密钥存储中。

如果应用程序已经在Google Play上发布，建议重用现有的keystore。使用不同的密钥签名更新将被拒绝，除非您通过Play Console的上传密钥重置进行。

新应用：

keytool -genkeypair -v \
  -storetype PKCS12 \
  -keystore release.jks \
  -alias upload \
  -keyalg RSA -keysize 2048 \
  -validity 10000

注意：

• Google Play要求密钥至少有效到2033年10月22日。 -validity 10000 即可满足27年要求。
• 使用PKCS12存储类型时，密钥密码与存储密码相同。
• 没有JDK？ Android keystore生成器 在浏览器中生成的文件与本地文件相同。

Play App Signing和上传密钥

新应用程序在Google Play上使用Play App Signing。Google持有应用程序签名密钥 重置Play Console的上传密钥 并重新签署用户下载的内容。您的keystore是 上传密钥。如果您丢失它，Play Console支持可以注册一个新的上传密钥，这就是为什么丢失它不是灾难的原因。无论如何都要备份它。

上传服务帐户

To upload from the cloud, create a service account in Google Cloud, enable the Google Play Android Developer API, download its JSON key, and invite the service account in Play Console under 用户和权限 并为您的应用程序分配发布权限。Capgo的入职流程可以通过Google登录来完成，如下所示。

iOS签名

苹果的三个部分

• 苹果分发证书 每个团队只需一个，有效期一年。苹果限制了您可以创建的数量，因此不要为每个开发者创建一个。
• 配置文件 连接包ID、证书和能力，如推送通知。使用 App Store Connect 用于TestFlight和App Store的 临时性 用于已注册设备上的
• App Store Connect API 密钥。 每个应用扩展（小工具、分享扩展、通知服务）都需要自己的配置文件。 App Store Connect __CAPGO_KEEP_0__密钥。 在 .p8 用户和访问>集成

中创建，具有App Manager访问权限。该

文件仅下载一次。

需要 macOS 的 Keychain Access 流程，但 OpenSSL 可以在任何地方工作：

# 1. Private key and certificate signing request
openssl req -new -newkey rsa:2048 -nodes \
  -keyout dist.key -out dist.csr \
  -subj "/emailAddress=dev@example.com/CN=Example Inc/C=US"

# 2. Upload dist.csr at developer.apple.com > Certificates > + > Apple Distribution
#    and download distribution.cer

# 3. Convert and bundle into a .p12
openssl x509 -inform DER -in distribution.cer -out distribution.pem
openssl pkcs12 -export -legacy \
  -inkey dist.key -in distribution.pem \
  -out distribution.p12 -passout pass:choose-a-password

The -legacy flag matters with OpenSSL 3: without it, macOS build machines may fail to import the .p12 with “MAC verification failed”. The browser-based iOS certificate generator does the same steps if you prefer not to use a terminal.

Then create the provisioning profile in the developer portal (Profiles > + > App Store Connect), select your app ID and the new certificate, and download it.

在云端设置签名与Capgo构建

Capgo 构建 compiles and signs Capacitor apps on Capgo-managed machines, so you can build iOS from Windows or Linux. Start by logging in and registering the app:

bunx @capgo/cli@latest login
bunx @capgo/cli@latest app add

Option A: 指导式入门（推荐)

bunx @capgo/cli@latest build init --platform ios
bunx @capgo/cli@latest build init --platform android

在 iOS 上，入门流程会创建或重用 App Store Connect 的 API 密钥对应的分发证书和 App Store 配置文件。在 macOS 上，它还可以引导您创建 API 密钥。对于 Android，入门流程会创建或导入密钥库，并可以为 Google Cloud 服务帐户和 Play Console 邀请配置 Google 登录。最后，它会提供开始第一个构建的选项。

Option B: 保存现有文件

如果您已经有上一节中的文件:

# iOS
bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --certificate ./distribution.p12 \
  --p12-password "choose-a-password" \
  --ios-provisioning-profile ./AppStore.mobileprovision \
  --apple-key ./AuthKey_ABC1234567.p8 \
  --apple-key-id ABC1234567 \
  --apple-issuer-id 00000000-0000-0000-0000-000000000000 \
  --apple-team-id TEAM123456

# Android
bunx @capgo/cli@latest build credentials save \
  --platform android \
  --keystore ./release.jks \
  --keystore-alias upload \
  --keystore-key-password "store-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-service-account.json

对于有扩展的应用程序，重复 --ios-provisioning-profile 使用一个 bundleId=path 映射每个目标:

  --ios-provisioning-profile com.example.app=./App.mobileprovision \
  --ios-provisioning-profile com.example.app.widget=./Widget.mobileprovision

凭据存储在 ~/.capgo-credentials/credentials.json，以应用程序 ID 和平台为键。添加 --local 将它们存储在 .capgo-credentials.json 中，代替， 并将该文件添加到 .gitignore。检查保存的内容与 bunx @capgo/cli@latest build credentials list.

触发一个签名的构建

准备本地项目，然后请求构建:

bun run build
bunx cap sync

# iOS: sign with the App Store profile and upload to TestFlight
bunx @capgo/cli@latest build request com.example.app --platform ios --build-mode release

# Android: sign the AAB and upload to the internal track
bunx @capgo/cli@latest build request com.example.app --platform android --build-mode release --android-track internal

日志流入您的终端。预构建扫描检查证书过期、密码和配置配对，确保在上传任何内容之前，签名错误在几秒钟内而不是几分钟内就被检测出来。使用它单独的命令 bunx @capgo/cli@latest build prescan --platform ios.

有用的变体:

为了生成adhoc构建，首先使用 iOS UDID 查找器 并将其添加到配置文件中。

在 CI 中自动签署构建

在 CI 中，通过环境变量传递凭据而不是凭据文件。CLI 将导出您需要的所有内容：

bunx @capgo/cli@latest build credentials manage --appId com.example.app
# choose "Export to .env"

在GitHub上，使用一个命令将每行推送到存储库密钥中，然后删除文件：

gh secret set -f .env.capgo.com.example.app
gh secret set CAPGO_TOKEN --body "your-capgo-api-key"
rm .env.capgo.com.example.app

一个发布工作流程，签署并将两种平台发送到标签：

name: Signed release
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        platform: [ios, android]
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
      - run: bun install --frozen-lockfile
      - run: bun run build
      - run: bunx cap sync ${{ matrix.platform }}
      - run: bunx @capgo/cli@latest build request com.example.app --platform ${{ matrix.platform }} --build-mode release
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          CAPGO_IOS_PROVISIONING_MAP_BASE64: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_BASE64 }}
          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 }}
          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 }}

该作业在 Linux 上运行。没有 macOS 运行器，没有 keychain 命令，没有 fastlane。同样的环境变量在任何 CI 中都有效：GitLab CI/CD 变量、Bitbucket 安全变量、Gitea 秘密或 Azure DevOps 变量组。平台特定的教程： Bitbucket Pipelines, Gitea Actions,以及 GitHub Actions 文档.

您的密钥如何处理

在您将签名密钥交给任何云服务之前，一个合理的问题。使用 Capgo 构建:

• 凭据存储在您的机器上（~/.capgo-credentials/）或在您的CI秘密存储中。 Capgo 不保留您的密钥库。
• 对于每个构建， CLI 会通过HTTPS发送它们。它们只在构建期间使用，并在完成时删除。
• 只上传准备好的原生项目。您的网页源文件和 .git文件不会。 .env 构建的应用程序直接上传到App Store Connect或Google Play，或者如果您要求的话，会生成一个有限期的下载链接。
• 交易：旋转凭据意味着您需要更新CI秘密存储本身。重新导出并推送文件。

过期和轮换 build credentials manage 项目

有效期和轮换

将Apple证书的过期日期放入共享日历中。过期的证书不会影响已经安装在用户设备上的应用，但会阻止新建应用。

故障排除

更多修复在 Capgo 构建故障排除指南 和 CI/CD for Capacitor: 常见陷阱.

首次签名构建后

仅当原生code发生变化时才需要签名的原生构建。对于 JavaScript、CSS 和 HTML 的更改，向已安装的应用程序发送一个code，并保留触摸插件或原生配置的发布的存储构建。如果您来自基于 Mac 的设置，请 live update 从 Windows 构建 iOS 应用程序 在 Windows 上使用 Capgo Build 构建 iOS 应用 文章来源