在 Linux、Windows 和 CI 上无需 Android Studio 即可构建 Android Release 版本

Android Studio 是一款优秀的 IDE，但并非生成上架版 Android build 的必需品。生成的 android/ 在 Capacitor 项目中的文件夹包含一个 Gradle wrapper，可以在任何终端进行 build 和签名。这对于没有显示器的 Linux 服务器、运行 Studio 较慢的 Windows 机器以及 CI 环境都至关重要。

本指南将演示如何仅通过命令行构建签名 AAB，并介绍使用 Capgo 构建 适用于不希望在笔记本电脑上存放 keystore 的团队。

前提条件

• JDK 21 (java -version 显示为 21)。
• Android 命令行 SDK 配合 platform-tools, build-tools 以及与您的 Capacitor 版本相匹配的平台（Capacitor 8 对应 API 36，Capacitor 7 对应 API 35）。 Linux 指南 以及 Windows 指南 涵盖安装步骤。
• ANDROID_HOME 导出的，或 android/local.properties 配合 sdk.dir=....
• 带有 Capacitor 的应用 android/ 由...生成 bunx cap add android.

1) 创建签名 keystore

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

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

根据提示操作，并设置 store 密码和 key 密码。请立即将文件及两个密码存入密码管理器或密钥库中。切勿提交 release.jks.

在 Play Console 创建应用时启用 Play App Signing。Google 会保存最终签名密钥，而你的 keystore 将变为上传密钥 (upload key)，即使丢失也可以重置。

2) 配置 Gradle 签名方式

避免将密钥泄露到 build.gradle. 创建 android/keystore.properties (已加入 gitignore):

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"
}

团队通常根据 versionCode CI 运行编号或 git commit 次数来生成，以避免手动修改。

4) 通过终端构建 AAB

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

在 Windows 上使用 .\gradlew.bat bundleRelease。签名后的 bundle 将写入 android/app/build/outputs/bundle/release/app-release.aab.

想要通过 adb 直接安装 APK 吗？ ./gradlew assembleRelease 生成 app-release.apk 在……下 outputs/apk/release/。使用以下命令安装： adb install； adb install 指南 涵盖了各种边缘情况。

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 中“应用完整性”下显示的值进行对比。

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

新 App 的首次上传必须在 Play Console 中手动完成；API 只接受已存在 App 的构建。

7) 云端替代方案：Android 版 Capgo Build

上述方法虽然可行，但会在每台构建机器上留下 keystore。Capgo Build 将 keystore 保存在加密保险库中，并基于你上传的已准备好的 android/ 项目进行构建，还能将 AAB 推送到 Play track。

只需保存一次凭据：

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

日志会流式输出到终端。添加 --output-upload 即可获取 AAB 或 APK 的下载链接，并 --ai-analytics 自动解释构建失败的原因。同一命令可在 Windows、Linux、macOS 和 CI 上运行。GitHub Actions 示例位于 Android 构建指南中.

因为 Capgo 只接收准备好的原生项目，所以私有 npm 注册表和 Web 构建密钥仍留在你的环境中。

8) 停止为 Web 变更重复构建

若涉及插件、权限、图标及 Capacitor 升级，则需要进行签名后的 Native Build。对于其他所有内容，只需 dist/, Capgo Live Updates 将新的 Web bundle 直接推送到已安装的应用中：

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 上的构建速度慢：排除 ~/.gradle 并将 SDK 从 Defender 中排除，同时将项目放在较短的本地路径下。
• Gradle 内存不足 (Out of memory)：添加 org.gradle.jvmargs=-Xmx4g 改为 android/gradle.properties.

总结

一个 Capacitor Android release 不需要 Android Studio，而是需要 JDK、SDK 和 Gradle wrapper。使用以下命令创建 keystore： keytool，通过以下方式签名： keystore.properties，使用以下命令构建： bundleRelease，并使用 Play API 上传。如果你想让 keystore 不再放在个人电脑上，并在所有操作系统上使用同一条命令，Capgo Build 会直接从准备好的项目完成签名和上传。