原生移动开发 / 系统课时

在 Gradle 配置 Release 签名

在 Gradle 配置 Release 签名

Release 构建只有绑定正确签名配置,才能产出可安装、可升级并可提交商店的正式包。本节用 Gradle Kotlin DSL 配置 signingConfig,同时把密钥路径、别名和密码移出源码,避免凭据随仓库泄露。

学习目标

  • 为 release 构建类型绑定独立的签名配置。
  • 使用环境变量保存密钥路径、别名和密码,避免硬编码敏感信息。
  • 通过 Release 构建验证签名配置是否真正生效。

准备密钥与环境变量

假设已经有用于发布的 keystore,并知道别名。不要把 .jks、.keystore 或密码提交到 Git;CI 中也应通过密钥管理或受保护变量注入。

下面是本地终端的配置示例,变量值请替换为自己的真实值。它只影响当前 Shell 会话。

bash
export ANDROID_KEYSTORE_PATH="/secure/path/upload-key.jks"
export ANDROID_KEY_ALIAS="upload"
export ANDROID_KEYSTORE_PASSWORD="<PASSWORD>"
export ANDROID_KEY_PASSWORD="<PASSWORD>"

预期结果:这些命令本身通常没有输出。可用下面的检查确认四个变量已设置;密码变量只检查是否为空,不回显内容。

bash
test -n "$ANDROID_KEYSTORE_PATH" && test -n "$ANDROID_KEY_ALIAS" && test -n "$ANDROID_KEYSTORE_PASSWORD" && test -n "$ANDROID_KEY_PASSWORD" && echo "signing env ready"

预期输出

text
signing env ready

配置 signingConfig

在应用模块的 build.gradle.kts 中读取环境变量,并在 signingConfigs 中创建 Release 配置。下面是片段示例,依赖现有 Android 应用模块中的 android {} 配置。

kotlin
android {
    signingConfigs {
        create("release") {
            val storePath = System.getenv("ANDROID_KEYSTORE_PATH")
                ?: error("ANDROID_KEYSTORE_PATH is not set")
            storeFile = file(storePath)
            storePassword = System.getenv("ANDROID_KEYSTORE_PASSWORD")
                ?: error("ANDROID_KEYSTORE_PASSWORD is not set")
            keyAlias = System.getenv("ANDROID_KEY_ALIAS")
                ?: error("ANDROID_KEY_ALIAS is not set")
            keyPassword = System.getenv("ANDROID_KEY_PASSWORD")
                ?: error("ANDROID_KEY_PASSWORD is not set")
        }
    }

    buildTypes {
        getByName("release") {
            signingConfig = signingConfigs.getByName("release")
            isMinifyEnabled = false
        }
    }
}

这里的关键不是变量名本身,而是Release 构建类型显式引用 Release 签名配置。如果只定义了 signingConfigs.release,却没有赋给 buildTypes.release.signingConfig,正式构建仍不会使用它。

执行 Release 构建

从项目根目录运行 Release 构建。APK 项目可执行:

bash
./gradlew assembleRelease

预期输出的具体任务列表和耗时会随 Gradle、AGP 与项目配置变化,但成功构建应以类似下面的结果结束:

text
BUILD SUCCESSFUL in <TIME>

实际耗时会替换 <TIME>。生成文件通常位于应用模块的 build/outputs/apk/release/ 目录;如果模块名不是 app,路径前缀也会相应变化。

处理常见失败

如果构建在配置阶段报 ANDROID_KEYSTORE_PATH is not set,说明当前 Gradle 进程没有拿到环境变量,先确认变量是在启动 Gradle 的同一终端或 CI 任务中设置的。若报 keystore 不存在,应检查 storeFile 指向的实际路径,而不是继续修改密码。

如果出现“别名不存在”或“密码不正确”,应回到 keystore 本身核对别名、store password 与 key password。不要用 Debug keystore 临时顶替 Release 密钥,否则虽然可能构建成功,但后续升级签名会不一致。

Release 构建成功只说明 Gradle 已能使用这套配置;真正发布前,还应再检查产物中的证书指纹与签名方案,确认最终 APK 没有被其他构建步骤重新签名。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

在 Gradle 配置 Release 签名

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通