Android Studio 是一款不错的 IDE,但生成可上架的 Android 构建包并不需要它。生成的 android/ Capacitor 项目中的文件夹包含 Gradle wrapper,可从任意终端构建并签名。这对没有显示器的 Linux 服务器、Studio 运行缓慢的 Windows 机器以及 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 指南 以及 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 会成为上传密钥,丢失后可重置。
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 需要签名的原生构建。至于 dist/, Capgo Live Update 把新的 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以及来自 Defender 的 SDK,并将项目放在较短的本地路径下。 - Gradle 内存不足:添加
org.gradle.jvmargs=-Xmx4g改为android/gradle.properties.
总结
构建 Capacitor Android 发布版需要 JDK、SDK 和 Gradle wrapper,而不是 Android Studio。使用以下命令创建 keystore: keytool,通过 keystore.properties进行签名,构建使用 bundleRelease,并使用 Play API 上传。如果你想让 keystore 不再放在个人电脑上,并在所有操作系统上使用同一条命令,Capgo Build 会直接从准备好的项目完成签名和上传。