跳过主要内容
教程 安卓 CI/CD

在Linux、Windows和CI上使用安卓Studio以外的安卓发布构建

Produce a signed Android AAB for a Capacitor app with only the command line: keytool keystore, Gradle from a terminal, Play Console service account, and a Capgo Build cloud alternative that keeps the keystore off laptops.

文章来源

马丁·多纳迪厄

作者

瓦莱里娅

审稿人

乔丹

编辑

在Linux、Windows和CI上不使用Android Studio生成Android发布版本

Android Studio是一个不错的IDE，但它并不是生成一个商店可用的Android版本所必需的。生成的__CAPGO_KEEP_0__项目文件夹包含一个Gradle包装器，可以从任何终端构建和签名。这对于没有显示器的Linux服务器、Windows机器（Studio很慢）以及CI来说很重要。 android/ folder in a Capacitor project contains a Gradle wrapper that builds and signs from any terminal. That matters for Linux servers without a display, for Windows machines where Studio is slow, and for CI.

本指南使用命令行仅生成一个签名的AAB，然后展示了云变体 Capgo 构建 为不想在笔记本上安装.keystore的团队

前提条件

  • JDK 21 (java -version 打印 21)
  • Android 命令行 SDK platform-tools, build-tools 并且该平台与您的Capacitor版本（API 36 对应 Capacitor 8，API 35 对应 Capacitor 7）匹配。 Linux 指南 Linux 指南 和 Windows 指南
  • ANDROID_HOME 涵盖了安装过程 android/local.properties 与 sdk.dir=....
  • 一个 Capacitor 应用程序 android/ 由 bunx cap add android.

1) 创建签名密钥库

keytool 是每个平台上的 JDK 的一部分：

keytool -genkeypair -v \
  -keystore release.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias release

回答提示并选择一个存储密码和一个密钥密码。现在将文件和两个密码存储在您的密码管理器或秘密保险箱中。永远不要提交 release.jks.

在创建应用程序时在 Play Console 中启用 Play App Signing。Google 将保留最终签名密钥，而您的密钥库将成为一个上传密钥，可以在丢失时重置。

2) 告诉 Gradle 如何签名

将机密信息从 build.gradle创建 android/keystore.properties (忽略 Git):

storeFile=/absolute/path/to/release.jks
storePassword=your-store-password
keyAlias=release
keyPassword=your-key-password

然后在 android/app/build.gradle:

def keystoreProperties = new Properties()
def keystorePropertiesFile = rootProject.file("keystore.properties")
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
}

android {
    signingConfigs {
        release {
            if (keystorePropertiesFile.exists()) {
                storeFile file(keystoreProperties['storeFile'])
                storePassword keystoreProperties['storePassword']
                keyAlias keystoreProperties['keyAlias']
                keyPassword keystoreProperties['keyPassword']
            }
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled false
        }
    }
}

添加 android/keystore.properties 和 *.jks 到 .gitignore.

3) 升级版本

Google Play 拒绝上传包含它之前未见过的内容 versionCode 编辑 android/app/build.gradle:

defaultConfig {
    versionCode 12
    versionName "1.4.0"
}

团队通常从 CI 运行次数或 Git 提交次数中派生 versionCode 4) 从终端构建 AAB

在 Windows 上使用

bun run build
bunx cap sync android
cd android
./gradlew bundleRelease

. 签名的包写入 .\gradlew.bat bundleRelease想要一个直接安装的 APK 以及使用 adb? android/app/build/outputs/bundle/release/app-release.aab.

需要一个可以直接通过adb安装的APK吗？ ./gradlew assembleRelease 生成 app-release.apk 在 outputs/apk/release/. 使用 adb install; adb 安装指南 涵盖了边缘案例。

5) 验证签名

$ANDROID_HOME/build-tools/36.0.0/apksigner verify --print-certs app/build/outputs/apk/release/app-release.apk

对于一个 AAB jarsigner -verify -verbose app-release.aab 确认签名和证书指纹。 比较 SHA-256 与 Play Console 下 App完整性中显示的值。

6) 从命令行上传到 Google Play

通过 Play Console 手动上传可以正常工作。 为了实现自动化，创建一个 Google Cloud 服务账户，在 Play Console 下的用户和权限中授予它访问权限，然后下载其 JSON 密钥。 然后使用 Google Play Developer API 或一个工具，如 fastlane supply:

bundle exec fastlane supply --aab android/app/build/outputs/bundle/release/app-release.aab \
  --track internal --json_key play-service-account.json --package_name com.example.app

新应用的第一次上传必须在 Play Console 中手动完成；API 只接受已经存在的应用的构建。

7) 云端替代方案：Capgo Android构建

Everything above works, but it leaves a keystore on every machine that builds. Capgo Android构建会将keystore存储在加密的安全库中，使用您上传的准备好的项目进行构建，并将AAB推送到Play track。 android/ Save credentials once：

或让

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

指引您。然后每次发布都是： bunx @capgo/cli@latest build init --platform android 日志流向终端。添加

bun run build
bunx cap sync android
bunx @capgo/cli@latest build request com.example.app --platform android --build-mode release

以获取AAB或APK的下载链接，并 --output-upload 获取 AAB 或 APK 的下载链接 --ai-analytics 在 Windows、Linux、macOS 和 CI 中，同一命令可以自动解释失败的构建。同一命令在 Windows、Linux、macOS 和 CI 中都可以运行。一个 GitHub Actions 示例位于 因为__CAPGO_KEEP_0__只接收准备好的本机项目，私有的__CAPGO_KEEP_1__注册表和Web构建密钥将保留在您的环境中。.

Because Capgo receives only the prepared native project, private npm registries and web build secrets stay in your environment.

8) 停止针对 web 变更重建

一个签名的原生构建对于插件、权限、图标和Capacitor升级是必需的。对于所有在 dist/, Capgo 实时更新 直接将新版 Web 包推送到已安装的应用程序：

bunx @capgo/cli@latest bundle upload --channel production

这将从您的周中去除大多数 Gradle 运行。

故障排除

  • SDK location not found: 设置 ANDROID_HOME 或创建 android/local.properties.
  • Keystore was tampered with, or password was incorrect: 错误的商店密码，或者文件被 Git 中的 CRLF 转换损坏。标记 *.jks 为二进制文件在 .gitattributes 如果它必须被版本化，事实上它不应该被。
  • Unsupported class file major version: JDK 版本号大于或小于 21。
  • Play 拒绝 AAB：“使用不同的密钥签名”: Play App Signing 需要您的上传密钥。使用 Play Console 注册的.keystore 文件，或申请重置上传密钥。
  • Windows 构建速度慢: exclude ~/.gradle 并且从 Defender 中排除 SDK，并将项目放在一个短的本地路径上。
  • Gradle 中内存不足: add org.gradle.jvmargs=-Xmx4g 到 android/gradle.properties.

Summary

一个 Capacitor Android release 需要 JDK、SDK 和 Gradle wrapper，而不是 Android Studio。创建密钥库时 keytool一个 __CAPGO_KEEP_0__ Android 发布版需要 JDK、__CAPGO_KEEP_1__ 和 Gradle 包装器，而不需要 Android Studio。使用 keystore.properties签名 bundleRelease使用 生成并签名的 APK，通过 上传到 Play API。当您希望密钥出现在笔记本电脑上并且在每个操作系统上使用相同的命令时，Capgo Build 将从准备好的项目中进行签名和上传。

Capacitor 应用的即时更新

当Web层面的bug出现时，通过Capgo将修复推送给用户，而不是等待几天的应用商店审批。用户在后台接收更新，而原生变化仍然在正常的审批路径中。

最新博客

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

2-Way 通信在Capacitor应用中
开发 移动 +1
2025年4月26日

2-Way 通信在Capacitor应用中

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

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

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

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

查看我们博客中的所有内容