原生移动开发 / 系统课时
在 Gradle 配置 Release 签名
在 Gradle 配置 Release 签名
Release 构建只有绑定正确签名配置,才能产出可安装、可升级并可提交商店的正式包。本节用 Gradle Kotlin DSL 配置 signingConfig,同时把密钥路径、别名和密码移出源码,避免凭据随仓库泄露。
学习目标
- 为
release构建类型绑定独立的签名配置。 - 使用环境变量保存密钥路径、别名和密码,避免硬编码敏感信息。
- 通过 Release 构建验证签名配置是否真正生效。
准备密钥与环境变量
假设已经有用于发布的 keystore,并知道别名。不要把 .jks、.keystore 或密码提交到 Git;CI 中也应通过密钥管理或受保护变量注入。
下面是本地终端的配置示例,变量值请替换为自己的真实值。它只影响当前 Shell 会话。
export ANDROID_KEYSTORE_PATH="/secure/path/upload-key.jks"
export ANDROID_KEY_ALIAS="upload"
export ANDROID_KEYSTORE_PASSWORD="<PASSWORD>"
export ANDROID_KEY_PASSWORD="<PASSWORD>"预期结果:这些命令本身通常没有输出。可用下面的检查确认四个变量已设置;密码变量只检查是否为空,不回显内容。
test -n "$ANDROID_KEYSTORE_PATH" && test -n "$ANDROID_KEY_ALIAS" && test -n "$ANDROID_KEYSTORE_PASSWORD" && test -n "$ANDROID_KEY_PASSWORD" && echo "signing env ready"预期输出
signing env ready配置 signingConfig
在应用模块的 build.gradle.kts 中读取环境变量,并在 signingConfigs 中创建 Release 配置。下面是片段示例,依赖现有 Android 应用模块中的 android {} 配置。
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 项目可执行:
./gradlew assembleRelease预期输出的具体任务列表和耗时会随 Gradle、AGP 与项目配置变化,但成功构建应以类似下面的结果结束:
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 没有被其他构建步骤重新签名。