使用GitHub自动构建Capacitor

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

推荐新建构建：使用 Capgo 构建

我们现在建议使用 Capgo 构建与 Capgo CLI 用于本机 Capacitor 构建。 本 Fastlane 指南保留用于维护现有 GitHub Actions pipeline 的团队，但新 Android 构建应使用 Capgo CLI 以免自己维护 Fastlane、Gradle 运行器、密钥库和上传脚本。

前提条件

开始之前，您需要设置:

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

Capgo Build通过Capgo

跳过Fastlane、Gradle runner、keystore和上传脚本的维护 Capgo Build 从您的CI/CD管道中运行已有的签名原生Android构建:

与您的管道兼容: Trigger Capgo Build from GitHub Actions, GitLab CI, Jenkins, or local scripts after your web build and npx cap sync.
从CI密钥中签名: 在您的CI密钥中保留Android密钥库、密钥别名、密码和Play Console服务帐户JSON
No native runner upkeep: Capgo Build 提供维护的 Android 构建环境，因此您不需要管理 SDK 图像、Gradle 缓存问题或 Fastlane 通道。
Artifacts and submission: 下载 QA 或提交发布构建的签名 artifact 通过 Capgo CLI。

Pricing

Capgo plans start at $12/month
Capgo 计划从每月 $12 开始
Capgo 计划从每月 $12 开始

Set up Capgo Build in CI/CD

Set up __CAPGO_KEEP_0__ Build in CI/CD

手动设置指南

GitHub Actions Pricing

价格GitHub动作

GitHub动作提供基于您的仓库类型的免费分钟数:

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

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

手动设置步骤

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

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
安全存储: 在安全位置保留多个备份

备选方案：使用现有密钥库

如果您已经发布了您的应用程序，则必须使用最初使用的同一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开发者API

在Google Cloud控制台中，前往 APIs & Services → Library
在 “Google Play Android Developer API” 中搜索
点击启用

步骤 2.3：创建服务帐户

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

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

点击新创建的服务帐户
转到密钥标签
点击 添加密钥 → 创建新密钥
选择 JSON格式 点击
创建 将下载一个JSON文件 -
请安全保存它 稍后您将需要它tab

第 2.5 步：在 Play Console 中授权访问

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

第 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.1 步：访问 GitHub 秘密

前往您的仓库于 GitHub

Step 4.1: Access GitHub Secrets

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

创建一个名为您在生成 keystore 时使用的密钥别名的新密钥 (例如： my-key-alias)

KEYSTORE_KEY_PASSWORD

创建一个新的密钥,使用您在生成密钥库时设置的密码

KEYSTORE_STORE_PASSWORD

创建一个新的密钥,使用您在生成密钥库时设置的密钥库密码

DEVELOPER_PACKAGE_NAME

创建一个新的密钥,使用您的应用程序包名(例如, com.example.app)

您可以在 android/app/build.gradle 下找到 applicationId

步骤4.3：验证所有密钥

确保您已配置以下6个密钥:

✅ PLAY_CONFIG_JSON
✅ ANDROID_KEYSTORE_FILE
✅ KEYSTORE_KEY_ALIAS
✅ 密钥库密码
✅ 密钥库存储密码
✅ 开发者包名

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 alternative for Android
使用 CodeMagic 构建 - CodeMagic 设置指南

实时更新 & 部署

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

资源

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

If you are using Automatic Capacitor Android build with GitHub actions 来规划 CI/CD 自动化,连接它与 Capgo CI/CD 为产品工作流程在 Capgo CI/CD 中 Capgo 原生构建为产品工作流程在 Capgo 原生构建中 Capgo 集成为产品工作流程在 Capgo 集成中 CI/CD 集成 CI/CD 集成 GitHub Actions Integration 为 GitHub Actions Integration 的实现细节。

自动Capacitor Android构建与GitHub动作