使用GitHub动作进行自动Capacitor Android构建

设置Capacitor应用的CI/CD流程可能会很复杂和耗时。以下是您需要了解的内容:

推荐新建项目：使用Capgo Build

我们现在推荐使用 Capgo Build与Capgo CLI 来进行原生Capacitor构建。 本Fastlane指南保留用于维护现有GitHub Actions管道的团队，但新Android应用应该使用Capgo CLI，这样您就不需要维护Fastlane、Gradle运行器、keystore和上传脚本。

前提条件

开始之前，您需要设置:

一个GitHub账户，具有管理员权限
您的应用已经在Google Play Store中发布，并且签名正确
Android签名密钥和keystore文件
Google Cloud Console项目，Play StoreAPI已启用
具有适当权限的服务帐户
了解GitHub Actions工作流
了解Fastlane配置
维护和调试管道所需的时间

Capgo Build for CI/CD by Capgo

通过__CAPGO_KEEP_1__ Build CI/CD Capgo Build __CAPGO_KEEP_0__ Build

从您的CI/CD管道中运行已有的签名原生Android构建:与您的管道兼容：触发Capgo Build从GitHub Actions、GitLab CI、Jenkins或本地脚本后您的Web构建和 npx cap sync.
从 CI 秘密中签名: 在自己的 CI 秘密中保留 Android 密钥库、密钥别名、密码和 Play Console 服务账户 JSON。
: 不需要本地运行器维护: Capgo Build 提供维护的 Android 构建环境，因此您不需要管理 SDK 图像、Gradle 缓存问题或 Fastlane 通道。
: 下载签名的 artifact 用于 QA 或通过 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ 提交发布版本。: Download signed artifacts for QA or submit release builds through the Capgo CLI.

: Capgo Builder 本地云构建产品页面的定价信息。

Capgo plans start at $12/month
: 包括 OTA 更新和约 15 个本地构建每月
: 额外的构建分钟通过信用额度按分钟计费

: 在 CI/CD 中设置 Capgo Build

: 手动设置指南

您需要做的就是：

GitHub Actions 价格

设置 GitHub Action

GitHub Actions 提供基于您的仓库类型的免费分钟数：

公共仓库：每月 2,000 分钟
私有仓库：每月 2,000 分钟（Linux 运行器）

对于私有项目，成本约为每分钟 $0.008。典型的构建时间为 3-5 分钟。

手动设置步骤

创建 Android Keystore
设置 Google Play 服务帐户
设置 Fastlane
配置 GitHub 秘密
创建 GitHub Actions 工作流

1. 创建 Android Keystore

在发布 Android 应用之前，您需要创建一个 keystore 文件。这是一个一次性的设置。

使用 keytool 生成 Keystore

在您的终端中运行以下命令：

keytool -genkey -v -keystore my-release-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

您将会被要求输入：

Keystore 密码: 选择一个强大的密码（您将需要它作为 KEYSTORE_STORE_PASSWORD)
Key 密码: 选择一个强大的密码（您将需要它作为 KEYSTORE_KEY_PASSWORD)
您的姓名、组织等: 填写您的详细信息

重要说明

请妥善保存这些值:
- 密钥库文件位置（例如， my-release-key.keystore)
- 密钥别名（例如， my-key-alias) - 您需要此项作为 KEYSTORE_KEY_ALIAS
- 密钥库密码 - 您需要此项作为 KEYSTORE_STORE_PASSWORD
- 密钥密码 - 您需要此项作为 KEYSTORE_KEY_PASSWORD
备份密钥库文件: 如果您丢失它，您无法更新您的发布应用
保密: 不要将密钥库文件提交到git
妥善存储: 保持多个备份在安全的位置

Alternative: 使用现有的Keystore

如果您已经发布了您的应用程序，则必须使用您最初使用的同一个Keystore。您可以在以下位置找到它:

在您第一次构建应用程序的本地机器上
在您的Play Console → 设置 → 应用签名（如果使用Google Play App Signing）

2. 设置Google Play服务帐户

为了允许GitHub Actions 将构建上传到Google Play，您需要一个服务帐户。

步骤2.1：创建Google Cloud项目

前往 Google Cloud控制台
创建一个新项目或选择现有的一个
注意项目ID

步骤 2.2：启用 Google Play Developer API

在 Google Cloud Console 中，前往 APIs & Services → Library
在 "Google Play Android Developer API" 中搜索
点击启用

步骤 2.3：创建服务帐户

前往 IAM & Admin → 服务帐户
点击 创建服务账户
输入详细信息：
- 名称： github-actions-uploader
- 描述： “GitHub Actions 上传构建的服务账户”
点击 创建并继续
跳过角色赋予（点击继续然后完成)

步骤 2.4：创建服务账户密钥

点击新创建的服务账户
前往密钥选项卡
点击 添加密钥 → 创建新密钥
选择 JSON 格式
点击创建
一个JSON文件将下载 - 安全地保存此信息您将需要它

步骤 2.5：在 Play Console 中授予访问权限

前往 Google Play Console
前往设置 → API access
__CAPGO_KEEP_0__ 访问在服务帐户 , 点击 为您的服务帐户
在 应用权限 标签中，添加您的应用
在 帐户权限 标签中，授予这些权限：
- 查看应用信息和下载大批量报告（只读）
- 创建、编辑和删除草稿应用
- 将应用发布到测试跟踪
- 将应用发布到生产、排除和其他跟踪
点击 邀请用户
点击 发送邀请

步骤 2.6：验证 JSON 密钥

下载的 JSON 文件应如下所示：

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "github-actions-uploader@your-project-id.iam.gserviceaccount.com",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "..."
}

您将在 GitHub 秘密设置步骤中将其转换为 base64。

3. 设置 Fastlane

在项目根目录创建一个文件夹并添加一个名为 __CAPGO_KEEP_0__ 的文件，内容如下： fastlane 4. 配置 __CAPGO_KEEP_0__ 秘密 Fastfile 现在您已经拥有您的.keystore 和服务帐户 JSON 文件，需要安全地将它们存储在 __CAPGO_KEEP_0__ 中。

default_platform(:android)

KEYSTORE_KEY_ALIAS = ENV["KEYSTORE_KEY_ALIAS"]
KEYSTORE_KEY_PASSWORD = ENV["KEYSTORE_KEY_PASSWORD"]
KEYSTORE_STORE_PASSWORD = ENV["KEYSTORE_STORE_PASSWORD"]

platform :android do
    desc "Deploy a beta version to the Google Play"
    private_lane :verify_changelog_exists do |version_code: |
      changelog_path = "android/metadata/en-US/changelogs/#{version_code}.txt"
      UI.user_error!("Missing changelog file at #{changelog_path}") unless File.exist?(changelog_path)
      UI.message("Changelog exists for version code #{version_code}")
    end

    private_lane :verify_upload_to_staging do |version_name: |
      UI.message "Skipping staging verification step"
    end
    
    lane :beta do
        keystore_path = "#{Dir.tmpdir}/build_keystore.keystore"
        File.write(keystore_path, Base64.decode64(ENV['ANDROID_KEYSTORE_FILE']))
        json_key_data = Base64.decode64(ENV['PLAY_CONFIG_JSON'])
        
        # Get previous build number and increment
        previous_build_number = google_play_track_version_codes(
            package_name: ENV['DEVELOPER_PACKAGE_NAME'],
            track: "internal",
            json_key_data: json_key_data,
        )[0]
        current_build_number = previous_build_number + 1
        sh("export NEW_BUILD_NUMBER=#{current_build_number}")
        
        # Build the app
        gradle(
          task: "clean bundleRelease",
          project_dir: 'android/',
          print_command: false,
          properties: {
            "android.injected.signing.store.file" => "#{keystore_path}",
            "android.injected.signing.store.password" => "#{KEYSTORE_STORE_PASSWORD}",
            "android.injected.signing.key.alias" => "#{KEYSTORE_KEY_ALIAS}",
            "android.injected.signing.key.password" => "#{KEYSTORE_KEY_PASSWORD}",
            'versionCode' => current_build_number
          })
        
        # Upload to Play Store
        upload_to_play_store(
            package_name: ENV['DEVELOPER_PACKAGE_NAME'],
            json_key_data: json_key_data,
            track: 'internal',
            release_status: 'completed',
            skip_upload_metadata: true,
            skip_upload_changelogs: true,
            skip_upload_images: true,
            skip_upload_screenshots: true,
        )
    end
end

4. Configure GitHub Secrets

Now that you have your keystore and service account JSON, you need to store them securely in GitHub.

步骤 4.1: 访问 GitHub 秘密

Go to your repository on GitHub
点击设置 → 机密和变量 → 动作
点击 新建仓库秘密

步骤 4.2: 添加必需的秘密

逐一添加这些秘密:

PLAY_CONFIG_JSON

添加您在步骤 2.4 下载的服务帐户 JSON 文件
转换为base64：

在macOS/Linux上：

base64 service_account_key.json | pbcopy

在Windows (PowerShell)上：

[Convert]::ToBase64String([IO.File]::ReadAllBytes("service_account_key.json")) | Set-Clipboard

创建一个名为 PLAY_CONFIG_JSON 并粘贴base64字符串

ANDROID_KEYSTORE_FILE

将您的keystore转换为base64：

在macOS/Linux上：

base64 my-release-key.keystore | pbcopy

在Windows (PowerShell)上：

[Convert]::ToBase64String([IO.File]::ReadAllBytes("my-release-key.keystore")) | Set-Clipboard

创建一个名为 ANDROID_KEYSTORE_FILE 并粘贴base64字符串

KEYSTORE_KEY_ALIAS

创建一个新的密钥别名（例如， my-key-alias)

KEYSTORE_KEY_PASSWORD

创建一个新的密钥密码（例如，

KEYSTORE_STORE_PASSWORD

创建一个新的密钥库密码（例如，

DEVELOPER_PACKAGE_NAME

创建一个新的密钥别名（例如， com.example.app)

您可以在 android/app/build.gradle 步骤4.3：验证所有密钥 applicationId

确保您已配置这6个密钥：

✅ PLAY_CONFIG_JSON

✅
✅ 安卓密钥库文件
✅ 密钥库密钥别名
✅ 密钥库密钥密码
✅ 密钥库存储密码
✅ 开发者包名

5. 创建GitHub Actions Workflow

创建 .github/workflows/build-upload-android.yml:

name: Build and Deploy Android App

on:
  push:
    tags:
      - '*'

jobs:
  build_android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      
      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
          
      - name: Install dependencies
        run: npm ci
        
      - name: Cache Gradle
        uses: actions/cache@v5
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
          restore-keys: |
            ${{ runner.os }}-gradle-
            
      - name: Build app
        run: npm run build
        
      - name: Sync Capacitor
        run: npx cap sync
        
      - name: Setup Java
        uses: actions/setup-node@v5
        with:
            distribution: 'zulu'
            java-version: '17'
            
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.0'
          bundler-cache: true
          
      - name: Run Fastlane
        uses: maierj/fastlane-action@v3.1.0
        env:
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          DEVELOPER_PACKAGE_NAME: ${{ secrets.DEVELOPER_PACKAGE_NAME }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
        with:
          lane: android beta
          
      - name: Upload artifact
        uses: actions/upload-artifact@v2
        with:
          name: android-release
          path: ./android/app/build/outputs/bundle/release/app-release.aab
          retention-days: 10

如何工作

创建一个 Git 标签来触发工作流
GitHub Actions 构建您的应用
Fastlane 将其上传到 Google Play 测试版频道
您的应用将自动更新

构建时间和成本

构建时间：3-5分钟
私有仓库的成本：约每次构建 $0.04
开源项目免费

CI/CD 设置指南

自动 Capacitor iOS 构建与 GitHub 动作 - 完整的 iOS CI/CD 设置
自动构建和发布与 GitHub 动作 - 全面的 CI/CD pipeline 教程
使用 GitHub 动作管理开发和生产构建 - 环境管理

其他CI/CD平台

使用GitLab CI构建 - GitLab替代方案
使用CodeMagic构建 - CodeMagic设置指南

实时更新和部署

Capgo 实时更新文档 - 为您的应用程序添加OTA更新
与Capgo集成的CI/CD - 在管道中集成实时更新

资源

从自动 Capacitor Android 构建中继续使用 GitHub 动作

如果您正在使用 自动 Capacitor Android 构建中使用 GitHub 动作 计划 CI/CD 自动化时,将其与 Capgo CI/CD 在 Capgo CI/CD 中的产品工作流 Capgo 原生构建在 Capgo 原生构建中 Capgo 集成在 Capgo 集成中 CI/CD 集成为 CI/CD 集成的实现细节，和 GitHub Actions 集成为 GitHub Actions 集成的实现细节，和

自动化Capacitor Android构建与GitHub动作