android-deploy

android-deploy

用途

此技能可自动完成 Android 应用部署，涵盖基于 Gradle 的构建、APK/AAB 签名、上传到 Google Play Console、通过 Firebase 分发，以及使用 Fastlane 和 bundletool 等工具来简化 CI/CD。

使用时机

在生产环境部署 Android 应用、测试不同变体或自动化发布时使用此技能；适用于 CI 流水线、Google Play 应用更新或通过 Firebase 进行内部分发；不适用于非 Android 项目或无需部署的基础构建。

主要功能

• 使用 build.gradle 配置构建并选择 Gradle 变体（例如 debug、release）。
• 使用密钥库为 APK 或 AAB 签名，支持 v1 和 v2 签名方案。
• 通过 API 将应用上传到 Google Play Console，包括管理编辑内容和轨道。
• 通过 Firebase App Distribution 分发构建版本以进行 Beta 测试。
• 使用 Fastlane 自动化工作流，包括构建和部署的 lane 定义。
• 使用 bundletool 从 AAB 生成 APK，并进行测试，以针对特定设备进行优化。

使用模式

要部署 Android 应用，先在 build.gradle 中配置变体（例如，设置 buildTypes { release { ... } }），然后使用 Fastlane 串联构建、签名和上传等任务。要集成到 CI 中，可通过脚本调用 Gradle 任务，传入密钥所需的环境变量，并处理输出以供后续步骤使用。运行前务必确认密钥库路径和 API 凭据；例如，运行一个先调用 ./gradlew assembleRelease、再调用 bundletool 提取内容的 Fastlane lane。

常用命令/API

• 构建指定 Gradle 变体：./gradlew assembleRelease --stacktrace（使用 --stacktrace 进行调试）。
• 为 APK 签名：apksigner sign --ks my.keystore --ks-key-alias myalias myapp.apk（需要密钥库文件和别名）。
• 上传到 Google Play：使用 Google Play API 端点 POST https://www.googleapis.com/androidpublisher/v3/applications/{packageName}/edits，并使用来自 $GOOGLE_PLAY_API_KEY 的 OAuth 令牌；curl 示例：curl -H "Authorization: Bearer $GOOGLE_PLAY_API_KEY" -d '{"title": "Edit"}' https://...。
• Firebase App Distribution：firebase appdistribution:distribute myapp.apk --app <APP_ID> --groups my-testers（设置 $FIREBASE_TOKEN 以进行身份验证）。
• Fastlane lane：在 Fastfile 中定义：lane :deploy do |options| sh("./gradlew assembleRelease") end；运行 fastlane android deploy。
• 用于 AAB 的 Bundletool：bundletool build-apks --bundle=myapp.aab --output=myapp.apks --ks=my.keystore（通过环境变量（如 $KEYSTORE_PASS）设置密码时，添加 --ks-pass）。
• build.gradle 中的 Gradle 构建代码片段：android { buildTypes { release { signingConfig signingConfigs.release } } }（2 行）。
• 脚本中的 API 调用：response = requests.post('https://www.googleapis.com/androidpublisher/v3/...', headers={'Authorization': f'Bearer {os.environ["GOOGLE_PLAY_API_KEY"]}'} )（2 行）。

集成说明

通过设置环境变量来保存敏感数据，例如，设置 export GOOGLE_PLAY_API_KEY=$SERVICE_API_KEY 以用于 OAuth；在项目根目录中配置 Fastlane 的 Fastfile，其中包含引用 Gradle 任务的 lane。对于 Firebase，添加 Firebase CLI，并通过服务账号 JSON 设置 $FIREBASE_TOKEN。在构建流水线中将 bundletool 用作 JAR，确保其版本兼容（例如，1.14.0+）。通过在工作流 YAML 中添加步骤（如 run: fastlane android deploy），将其与 GitHub Actions 等 CI 工具集成。

错误处理

处理签名错误时，请检查密钥库路径和密码（例如，如果 apksigner 报错“Keystore not found”，请确认文件是否存在）；对于 API 上传，请确保 $GOOGLE_PLAY_API_KEY 有效且未过期，以处理 401 错误。Gradle 构建失败通常源于变体不匹配，可使用 ./gradlew tasks 列出可用任务。对于 Fastlane，请使用 fastlane --verbose 进行调试；如果 bundletool 报告“Invalid bundle”，请使用 bundletool validate --bundle=myapp.aab 验证 AAB。始终在脚本中使用 try-catch 块封装命令，例如：try { sh("./gradlew assembleRelease") } catch { echo "Build failed: $error" }。

具体使用示例

示例 1：构建并签署用于发布的 APK
首先，确保 build.gradle 中包含：signingConfigs { release { storeFile file("my.keystore") keyAlias "myalias" } }。然后运行：./gradlew assembleRelease。最后，进行签名：apksigner sign --ks my.keystore --ks-key-alias myalias app/build/outputs/apk/release/app-release-unsigned.apk。这会生成可供分发的已签名 APK。

示例 2：通过 Fastlane 上传到 Google Play
创建一个 Fastfile，其中包含：lane :upload do upload_to_play_store track: 'internal' apk_path: 'app/build/outputs/apk/release/app-release.apk' end。设置环境变量：export SUPPLY_JSON_KEY_FILE=$GOOGLE_PLAY_SERVICE_ACCOUNT。运行：fastlane upload。这会自动完成构建、签名，并上传到 Google Play Console 的内部测试轨道。

图关系

• 相关：移动端集群（例如，与 iOS 部署技能共享依赖项）。
• 集成：ci-cd 流水线（例如，连接 Gradle 等构建工具）。
• 依赖：身份验证服务（例如，Google Play API 密钥）。
• 冲突：非移动端技能（例如，Web 部署）。