Android 构建

使用 Capgo 的专用基础设施构建并提交 Android 应用至 Google Play Store。

学习内容

• 你将学习如何通过 Capgo Native Build 上传你的 App
• 您将学习如何配置 Capgo Native Build 的凭据

前提条件

• 您需要一个有效的 Google 开发者账号
• 您需要安装 Android Studio
• 您的应用必须能够通过 Android Studio 成功构建

注意

在本教程中，我将使用以下 App： https://github.com/Cap-go/capgo-native-build-tutorial-app

推荐方案：自动化 onboarding

您无需手动完成这些步骤。Capgo 的 onboarding 会为您创建并配置 Android 签名凭据（keystore + Google Play 服务账号）——这是推荐的方式：

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

以下手动操作指南仅适用于希望自行配置凭据，或想深入了解 Capgo 底层机制的用户。

首次手动构建

在开始使用 Capgo 构建应用之前，我们应先完成初始配置，并手动执行一次 Android 构建。 先进行手动构建有以下优势：

• 为后续的 Capgo 构建准备好凭据
• 在 Play Store Console 中创建应用记录

使用 Android Studio 手动构建应用

在开始使用 Capgo 构建应用之前，我们需要先使用 Android Studio 手动构建应用。

1. 打开 Android Studio

   运行 bunx cap open android 以打开 Android Studio 项目。

2. 点击 Build -> Generate Signed App Bundles / APKs

3. 选择 Android App Bundle 并点击 Next

创建 Keystore

目前你缺少 keystore 文件。该文件用于为你的 App 签名，以便 Google 确认该 App 是由你构建的。 我们将使用 Android Studio 提供的 GUI 方法来生成它。 虽然也可以通过命令行完成，但本教程暂不涉及。

1. 点击 Create new

2. 填写 Key Store 路径

   注意

   此项 需要保存 - 后续会用到

3. 设置 Key Store 密码

   注意

   建议 Key Store 和 Key Alias 使用相同的密码。

   注意

   此项 需要保存 - 后续会用到

4. 填写表单的其余部分

   1. Key Alias 保持不变 (key0)
   2. 填写证书详情。我填的是假信息，但你需要填写自己的信息。

   

5. 点击 OK

完成手动构建

1. 请确保已正确填写所有 keystore 详细信息，然后单击 Next

2. 选择 release 构建变体，然后单击 Create

3. 构建成功后，您应看到以下界面

   1. 此弹窗表示构建已成功。
   2. 点击 locate 按钮 - 这将打开文件资源管理器，你应该能在其中看到构建产物。

4. 确保你能在文件资源管理器中看到构建产物

在 Play Store Console 中创建应用

1. 前往 Google Play 控制台

2. 选择正确的开发者账户

3. 点击 Create app

4. 选择应用名称和语言

5. 选择应用类别，并确定应用是付费还是免费

6. 接受条款和条件

   注意

   请在接受前务必阅读条款和条件。

7. 点击 Create

创建内部测试组

应用创建完成后，您可以创建一个内部测试组。由于我不会将应用正式发布到 Play Store 供所有人使用，因此需要创建一个内部测试组。

注意

在正式发布前，内部测试仍然是对通过 Play 分发的 build 进行冒烟测试最快的方式。

如果你的开发者账号是 2023 年 11 月 13 日之后创建的个人账号，内部测试 不会 不能替代生产环境访问所需的封闭测试要求。在申请生产环境权限前，你仍需进行持续 14 天、至少 12 名已选择加入的测试人员参与的封闭测试。

1. 前往 internal testing 点击 Test and release -> Testing -> Internal testing

   

2. 点击 Testers

3. 点击 Create email list

4. 给邮件列表命名

5. 添加测试人员的邮箱地址

6. 按下 Enter 并点击 Save

7. 点击 Create group

8. 确保已选中新列表并点击 Save

将应用上传到内部测试组

既然你已创建内部测试组，现在就可以将 App 上传到该测试组。

1. 前往 Test and release -> Testing -> Internal testing

2. 点击 Releases 按钮

3. 点击 Create new release

4. 点击 Upload

5. 选择 AAB 文件

   注意

   请确保选择你通过 Android Studio 手动构建的 AAB 文件。如果这个文件使用的 keystore 与你用于 Capgo 构建的 keystore 不同，Capgo Native Build 就会失败。

6. 等待 AAB 文件上传完成

7. 点击 Next

8. 修复错误

   我个人在这个阶段看到的是这个错误

   

   这是因为我还没有验证手机号码。我先完成验证，然后继续本教程。

9. 点击 Save and publish 这将把应用发布到内部测试组。

10. 确认发布

11. 确保应用已发布

12. 获取您的临时应用名称

接受内部测试组邀请

现在，你已将应用上传到内部测试组，可以接受内部测试组的邀请了。

1. 前往 Test and release -> Testing -> Internal testing

2. 点击 Testers

3. 点击 Copy link

4. 把链接发送到手机上，在浏览器中打开并点击 Accept

5. 确认已接受邀请，然后点击“在 Play Store 中下载”

6. 安装应用

   1. 如果你之前用 Android Studio 安装过该应用，请点击 uninstall 按钮
   2. 点击 install 按钮
   3. 打开应用并确认已成功下载

   注意

   如果在 Play Store 中没看到应用，请确保在 Play Store 中选择了正确的账号。

配置 Capgo Native Build (Android)

现在，您可以开始配置 Capgo Native Build 了。恭喜 🎉！

要求	参数	描述	必填
Keystore 文件	--keystore <path>	您的 .jks/.keystore 文件路径，用于对 APK/AAB 进行签名。	是
Keystore 别名	--keystore-alias <alias>	密钥库中密钥的别名。	是
Keystore 密钥密码	--keystore-key-password <password>	密钥的密码。如果密钥密码与 keystore 密码相同，只需提供一个。	请查看下方说明
Keystore 存储密码	--keystore-store-password <password>	Keystore 的密码。如果密钥密码与 keystore 密码相同，只需提供一个。	请查看下方说明
Google Play 服务账号	--play-config <path>	用于上传到 Play Store 的 JSON 服务账号文件。	是

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

注意

如果密钥和存储密码相同，只需提供其中一个 --keystore-key-password 或 --keystore-store-password.

Keystore、keystore 密码、key 密码、keystore alias

如果您已遵循 手动构建说明，您应该已经生成了 keystore。 如果您尚未遵循说明，请按照说明生成 keystore。

Google Play 服务账号

生成 Google Play 服务账号是一个手动且复杂的过程。 但要将应用上传到 Google Play，这一步必不可少。请注意以下几点：

• 您 需要 成为 开发者账号的所有者。否则，你将无法配置服务账号。
• 你需要创建一个新的 Google Cloud Project（需与你的 Google Play 账号分开）

我们开始吧。

1. 前往 Google Cloud Console

2. 点击项目选择器

3. 如果你已有项目，请直接选择。否则，请创建一个新项目：

   注意

   以下截图仅为示例，请使用适合你项目的名称。

   1. 点击 New project
   2. 输入项目名称并点击 Create
   3. 确保你在正确的项目中

4. 点击搜索栏并搜索 service accounts 并点击它

5. 点击 Create service account

6. 填写服务账号表单并点击 Done

   1. 建议将名称设置为 Capgo Native Build Service Account
   2. 对于 Service Account ID，建议设置为 capgo-native-build-service-acc
   3. 描述可以不填，但我建议填写 Allows Capgo Native Build to build and submit the app to the Play Store

   

7. 点击新创建的服务账号 你现在应该能在列表中看到新创建的服务账号。点击它。

   注意

   也复制这个邮箱地址，稍后会用到。

8. 点击 Keys 选项卡

9. 点击 Add Key 以及 Create new key

10. 点击 JSON 以及 Create

    注意

    点击 Create 将创建一个新密钥，并把 JSON 文件下载到你的本地机器。

    请将 JSON 文件保存在安全的位置。它 将会 稍后会用到。

11. 下载 JSON 文件 JSON 文件应已自动下载。您可以点击 close 关闭窗口。

授予服务账号 Play Store API 权限

新创建的服务账号尚无权访问 Play Store API。要授予权限，请前往 Play Store Console。

1. 前往 Google Play 控制台
2. 选择正确的开发者账号
3. 点击 Users and permissions
4. 点击 Invite new users
5. 复制服务账号的邮箱地址
6. 前往 Account permissions 并授予所需的最低权限：
   • 在 App permissions，授予其访问您应用的权限。
   • 在 Releases，启用 Create, edit, and roll out releases.
   • 如果工作流使用 Play App Signing，请启用相应的签名权限。
   • 如果不确定，请使用 Admin 仅在设置期间使用，之后减少权限。
7. 点击 Invite user
8. 确认邀请
9. 确认用户已被邀请

保存凭据

现在您可以保存凭据并运行首次 build。 您可以使用以下命令保存凭据：

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

CI/CD 配置 (GitHub Actions)

如果您已完成 Keystore、keystore 密码、key 密码、keystore alias 以及 Google Play 服务账号，您已具备 CI/CD 所需的一切。 本节仅介绍如何将这些值作为 GitHub Actions 密钥和环境变量传递。

1) 将凭据文件转换为单行 base64

# Android keystore (.jks or .keystore)
base64 -i ./path/to/keystore.jks | 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

提示

GitHub 密钥应为单行值。 tr -d '\n' 用于移除 base64 输出中的换行符。

2) 创建仓库密钥

在 GitHub > Repository > Settings > Secrets and variables > Actions，添加：

密钥名称	值
CAPGO_TOKEN	你的 Capgo API token
APP_ID	你的 Capgo 应用 ID（示例： com.example.app)
ANDROID_KEYSTORE_FILE	内容 keystore_base64.txt
KEYSTORE_KEY_ALIAS	Keystore 别名来源 Keystore、keystore 密码、key 密码、keystore alias
KEYSTORE_KEY_PASSWORD	Keystore 密钥密码
KEYSTORE_STORE_PASSWORD	Keystore 存储密码
PLAY_CONFIG_JSON	内容 play_config_base64.txt

注意

如果密钥密码和存储密码相同，只需提供其中一个即可 KEYSTORE_KEY_PASSWORD 或 KEYSTORE_STORE_PASSWORD.

3) 在 GitHub Actions 工作流中使用环境变量

.github/workflows/android-build.yml

name: Android Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  android-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request Android build with Capgo
        run: bunx @capgo/cli@latest build request ${{ secrets.APP_ID }} --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 }}

提示

这样配置后，CI 只通过环境变量传递凭据。无需提交签名文件，也无需将其作为 workflow artifacts 上传。

运行构建

恭喜 🎉！现在你可以运行第一次 build 了。

运行：

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

这将启动构建流程 🍾🥂

提交 Play 版本进行审核

默认情况下，Android release build 会上传到 Google Play，并会保持未激活状态，直到你在 Play Console 中完成发布。如果你的 CI 发布流程需要自动提交 Play 版本，请传入 --submit-to-store-review 配合 release build 使用：

npx @capgo/cli@latest build request com.example.app \
  --platform android \
  --build-mode release \
  --submit-to-store-review \
  --android-track production \
  --store-release-name "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales"

注意

在 Android 上， --submit-to-store-review 默认为 生产环境 track，并使用 release_status: completed 未设置 track 时。这可能会向 100% 的用户上线。请传入 --android-track internal (或 alpha / beta）— 或设置 PLAY_STORE_TRACK 在 CI 中 — 以将已完成的发布保留在非生产 track 上。使用 --android-release-status / PLAY_STORE_RELEASE_STATUS 当需要不同于 completed.

这需要与常规上传路径相同的 Google Play 服务账号配置（PLAY_CONFIG_JSON 在 CI 中或本地保存的 Android 凭据）。 --store-release-name 用作 Google Play 的 version_name. --store-release-notes 是后备 Play 更新日志，并且每个 --store-release-notes-locale "locale=notes" 条目都会为该语言区域写入本地化的 Play 更新日志。Capgo 会把 Play 发布作为 completed ，除非你覆盖 --android-release-status；如果在 Play Console 中启用了托管发布，Google 在审批通过后仍可能等待你手动发布。

从 Android Builds 继续

如果你正在使用 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 集成的实现细节。