跳过主要内容
CapgoLogo
CI/CD

自动Capacitor Android构建与GitHub动作

如何在5分钟内使用fastlane和GitHub Actions为您的AndroidCapacitor应用设置CI/CD管道

马丁·多纳迪尤

马丁·多纳迪尤

内容营销人员
自动Capacitor Android构建与GitHub动作

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

我们现在建议使用 Capgo Build与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 for CI/CD by Capgo

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

  • 与您的管道兼容: 在您的Web构建之后，通过GitHub Actions、GitLab CI、Jenkins或本地脚本触发Capgo Build npx cap sync.
  • 从CI密钥中签名: 在您的CI密钥中保留Android密钥库、密钥别名、密码和Play Console服务账户JSON。
  • 无原生运行器维护: Capgo Build提供维护的Android构建环境，因此您不需要管理SDK镜像、Gradle缓存问题或Fastlane通道。
  • 工件和提交: 下载签名工件进行QA或通过Capgo CLI提交发布构建。

定价

  • Capgo 计划从每月 12 美元开始
  • 包括 OTA 更新和每月约 15 个本机构建
  • 额外的构建分钟通过信用额度按分钟计费

在 CI/CD 中设置 Capgo 构建

手动设置指南

以下是您需要做的事情：

GitHub 动作定价

GitHub 动作价格

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

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

For private projects, costs are approximately ¥0.008/minute. A typical build takes 3-5 minutes.

手动设置步骤

  1. 创建 Android Keystore
  2. 设置 Google Play 服务帐号
  3. 设置 Fastlane
  4. 配置 GitHub 秘密
  5. 创建 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_STORE_PASSWORD)
  • 密钥密码: 选择一个强大的密码（你将需要这个作为 KEYSTORE_KEY_PASSWORD)
  • 你的名字、组织等: 填写你的详细信息

重要注意事项

  • 保存这些值安全:

    • 密钥库文件位置（例如 my-release-key.keystore)
    • 密钥别名（例如 my-key-alias) - 你将需要这个作为 KEYSTORE_KEY_ALIAS
    • 密钥库密码 - 你将需要这个作为 KEYSTORE_STORE_PASSWORD
    • 密钥密码 - 你需要这个 KEYSTORE_KEY_PASSWORD

  • 备份密钥库文件: 如果你丢失了它，你就无法更新你的发布应用

  • 保密: 不要将密钥库文件提交到git

  • 安全存储: 在安全的位置保留多个备份

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

如果你已经发布了你的应用，你必须使用最初使用的同一个密钥库。你可以在以下位置找到它：

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

2. 设置Google Play Service Account

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

步骤 2.1：创建 Google Cloud 项目

  1. 前往 Google Cloud 控制台
  2. 创建新项目或选择现有项目
  3. 注意项目 ID

步骤 2.2：启用 Google Play Developer API

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

步骤 2.3: 创建服务账号

  1. 前往 IAM & Admin → 服务账号
  2. 点击 创建服务账号
  3. 输入详细信息：
    • 名称： github-actions-uploader
    • 描述： “GitHub 的服务账号，用于上传构建”
  4. 点击 创建并继续
  5. 暂时跳过角色赋权（点击 继续, 然后 完成)

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

  1. 点击新创建的服务帐户
  2. 前往 密钥 选项卡
  3. 点击 添加密钥 → 创建新密钥
  4. 选择 JSON 格式
  5. 点击 创建
  6. 将下载一个 JSON 文件 - 请安全保存这个文件，因为你以后会需要它步骤 2.5: 在 Play Console 中授权

前往

  1. Google Play 控制台 前往
  2. 步骤 2.5 配置 → API访问
  3. 在 服务帐号, 点击 授权访问 为您的服务帐号
  4. 在 应用权限 选项卡中添加您的应用
  5. 在 帐号权限 点击允许这些权限：
    • 查看应用信息和下载批量报告（只读）
    • 创建、编辑和删除草稿应用
    • 将应用发布到测试轨道
    • 将应用发布到生产、排除和其他轨道
  6. 点击 邀请用户
  7. 点击 发送邀请

步骤 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

创建一个 fastlane 项目根目录下的文件夹并添加一个 Fastfile 包含以下内容:

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. 配置 GitHub 秘密

现在您已经拥有您的密钥库和服务帐户 JSON，您需要安全地将它们存储在 GitHub 中。

步骤 4.1: 访问 GitHub 秘密

  1. 前往您的仓库在 GitHub
  2. 点击 设置 → 秘密和变量 → 动作
  3. 点击 新建仓库密钥

步骤 4.2: 添加必需密钥

逐一添加这些密钥:

__CAPGO_KEEP_0__

  1. 取出步骤 2.4 下载的服务帐号 JSON 文件
  2. 将其转换为 base64:

在 macOS/Linux 上:

base64 service_account_key.json | pbcopy

在 Windows (PowerShell) 上:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("service_account_key.json")) | Set-Clipboard
  1. 创建一个名为 __CAPGO_KEEP_0__ 的新密钥 PLAY_CONFIG_JSON 并粘贴 base64 字符串

Android.keystore 文件

  1. 将您的keystore转换为base64：

在macOS/Linux上：

base64 my-release-key.keystore | pbcopy

在Windows (PowerShell)上：

[Convert]::ToBase64String([IO.File]::ReadAllBytes("my-release-key.keystore")) | Set-Clipboard
  1. 创建一个名为"__CAPGO_KEEP_0__"的新密钥 ANDROID_KEYSTORE_FILE 并粘贴base64字符串

KEYSTORE_KEY_ALIAS

创建一个新密钥，使用生成keystore时使用的别名（例如，"__CAPGO_KEEP_1__"） my-key-alias)

KEYSTORE_KEY_PASSWORD

创建一个新密钥，使用生成keystore时设置的密钥密码

KEYSTORE_STORE_PASSWORD

创建一个新密钥，使用生成keystore时设置的keystore密码

DEVELOPER_PACKAGE_NAME

创建一个新的密钥与您的应用程序包名（例如， com.example.app)

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

步骤 4.3：验证所有密钥

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

  • ✅ PLAY_CONFIG_JSON
  • ✅ ANDROID_KEYSTORE_FILE
  • ✅ KEYSTORE_KEY_ALIAS
  • ✅ KEYSTORE_KEY_PASSWORD
  • ✅ KEYSTORE_STORE_PASSWORD
  • ✅ DEVELOPER_PACKAGE_NAME

5. 创建GitHub Actions 工作流

创建 .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

如何工作

  1. 创建一个 Git 标签来触发工作流
  2. GitHub Capgo 构建您的应用
  3. Fastlane 将其上传到 Google Play beta 频道
  4. 您的应用将自动更新

构建时间和成本

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

CI/CD 设置指南

替代 CI/CD 平台

实时更新和部署

资源

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

如果您正在使用 Automatic Capacitor Android build with GitHub actions 来规划 CI/CD 自动化,将其连接到 Capgo CI/CD 集成 为产品工作流程在Capgo CI/CD中 Capgo 本机构建 为产品工作流程在Capgo 本机构建中 Capgo 集成 为产品工作流程在Capgo 集成中 CI/CD 集成 CI/CD 集成的实现细节， GitHub 动作集成 为GitHub 动作集成的实现细节

实时更新 Capacitor 应用

当 web 层 bug 活跃时，通过 Capgo 将修复推送，而不是等待几天的应用商店批准。用户在后台接收更新，而本机更改保持在正常审查路径中。

立即开始

最新博客文章

Capgo 为您提供创建真正专业的移动应用所需的最佳见解。

双向通信 Capacitor 应用
开发 Mobile +1
2025年4月26日

Capacitor应用的双向通信

避免的5种OTA更新常见错误
开发 安全 +1
2025年4月13日

避免的5种OTA更新常见错误

移动应用实时更新的5种安全最佳实践
开发 移动 +1
2025年1月14日

5条关于移动应用实时更新的安全最佳实践

查看所有博客文章