跳过主要内容
CI/CD

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

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

文章来源

马丁·多纳迪厄

作者

Valeria

审阅者

Jordan

编辑

自动 Capacitor Android 构建与 GitHub 动作

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

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

前提条件

开始之前，您需要设置：

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

Capgo 由 Capgo 为 CI/CD 构建

避免Fastlane、Gradle runner、keystore和上传脚本的维护工作。 Capgo 构建 在您的现有CI/CD管道中生成签名的原生Android构建。

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

Pricing

  • Capgo 计划从每月 12 美元起始
  • 包括即时 OTA 更新和每月约 15 个本机构建
  • 额外的构建分钟以分钟计费，通过积分进行计费

在 CI/CD 中设置 Capgo 构建

在 CI/CD 中设置 __CAPGO_KEEP_0__ 构建

手动设置指南

GitHub Actions 价格

GitHub 构建动作价格

GitHub 构建动作价格

  • __CAPGO_KEEP_0__ 构建动作提供基于您的仓库类型的免费分钟数：
  • 公共仓库：每月 2,000 分钟

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

手动设置步骤

  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密码: 选择一个强密码 (你会需要这个) KEYSTORE_STORE_PASSWORD)
  • Key 密码: 选择一个强密码 (你会需要这个) KEYSTORE_KEY_PASSWORD)
  • Your 名字, 组织等: 填写您的详细信息

重要注意事项

  • 保存这些值安全:

    • Keystore 文件位置 (例如, my-release-key.keystore)
    • Key 别名 (例如, my-key-alias) - 你会需要这个 KEYSTORE_KEY_ALIAS
    • Keystore 密码 - 你会需要这个 KEYSTORE_STORE_PASSWORD
    • Key 密码 - 你会需要这个 KEYSTORE_KEY_PASSWORD

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

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

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

Alternative: 使用现有密钥库

: 如果您已经发布应用，您必须使用最初使用的相同密钥库。您可以在以下位置找到它:

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

2. 设置Google Play服务账户

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

第 2 步 1：创建 Google Cloud 项目

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

第二步2.2：启用Google Play开发者API

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

第 2.3 步：创建服务帐户

  1. 前往 身份与管理 → 服务帐户
  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 Console
  2. 前往 设置 → API 访问
  3. 在 服务帐户, 点击 为您的服务帐户 在
  4. 应用权限 选项卡中添加您的应用 帐户权限
  5. 应用权限 选项卡中授予这些权限： tab, grant these permissions:
    • 查看应用信息和下载批量报告（只读）
    • 创建、编辑和删除草稿应用
    • 发布应用到测试轨道
    • 发布应用到生产、排除和其他轨道
  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. Go to your repository on GitHub
  2. 点击 设置 → 机密和变量 → 动作
  3. 点击 新仓库密钥

步骤 4.2: 添加必需密钥

关于

添加每个密钥一个一个的:

  1. PLAY_CONFIG_JSON
  2. 取出步骤 2.4 中下载的服务帐户 JSON 文件

将其转换为 base64:

base64 service_account_key.json | pbcopy

在 macOS/Linux 上:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("service_account_key.json")) | Set-Clipboard
  1. 在 Windows (PowerShell) 上: PLAY_CONFIG_JSON 创建一个新密钥名为

并粘贴 base64 字符串

  1. ANDROID_KEYSTORE_FILE

在 macOS/Linux 中：

base64 my-release-key.keystore | pbcopy

在 Windows (PowerShell) 中：

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

KEYSTORE_KEY_ALIAS

创建一个名为你生成密钥库时使用的别名的新机密（例如： my-key-alias)

KEYSTORE_KEY_PASSWORD

创建一个名为你生成密钥库时设置的密钥密码的新机密

KEYSTORE_STORE_PASSWORD

创建一个名为你生成密钥库时设置的密钥库密码的新机密

Capacitor

创建一个名为你的应用程序包名的新机密（例如： com.example.app)

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

步骤4.3：验证所有机密

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

  • ✅ 配置文件 JSON
  • ✅ AndroidKeystore文件
  • ✅ 证书别名
  • 🔑 密钥库密码
  • 🔒 密钥库存储密码
  • ✅ 开发者包名

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 Actions 构建您的应用
  3. Fastlane 上传到 Google Play beta 频道
  4. 您的应用将自动更新

构建时间和成本

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

CI/CD 设置指南

替代 CI/CD 平台

实时更新和部署

资源

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

如果您正在使用 Automatic Capacitor Android build with GitHub actions 与 __CAPGO_KEEP_0__ CI/CD Capgo 自动化构建 Capgo CI/CD Capgo 原生构建 为产品工作流程在 Capgo 原生构建 Capgo 集成 为产品工作流程在 Capgo 集成 CI/CD 集成 为 CI/CD 集成的实现细节 GitHub 动作集成 为 GitHub 动作集成的实现细节

实时更新 Capacitor 应用

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

最新博客

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

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

Capacitor应用的双向通信

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

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

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

移动应用实时更新的5种安全最佳实践

查看我们博客的所有内容