游戏引擎 / 系统课时
处理 Android 签名与版本号
处理 Android 签名与版本号
首个包能安装不代表下个版本能覆盖升级,签名身份和版本编号都必须保持一致。本课建立 Android 发布密钥与版本记录,区分上传签名和设备安装签名,再用保留存档的升级测试检查发布链。
学习目标
- 能区分应用签名密钥与上传密钥
- 能设置可持续递增的版本编号并验证升级
先确定应用的长期身份
Android 升级依赖包名与签名身份,调试包和正式包通常不同。首次发布前确定包名和签名方案,保存证书指纹与密钥归属,不要每次构建重新生成密钥。已有玩家安装时,更换身份可能导致覆盖失败或需要平台支持的密钥升级流程。
采用 Play App Signing 时,开发者用上传密钥签名提交产物,Google Play 使用应用签名密钥签署分发到设备的 APK。上传密钥与设备最终签名并非一定相同;本地 APK 与商店安装包的升级兼容性要按实际证书检查,不能仅看同一个包名。

在受控位置创建密钥
保存下面的 PowerShell 入口为 create-key.ps1,传入 JDK 的 keytool 路径和新的密钥文件路径。它会交互询问密码与证书信息,不把秘密写入脚本;本课未执行密钥生成或签名。
param(
[Parameter(Mandatory)][string]$KeytoolExe,
[Parameter(Mandatory)][string]$Keystore
)
$ErrorActionPreference = 'Stop'
if (-not (Test-Path -LiteralPath $KeytoolExe -PathType Leaf)) { throw 'keytool missing' }
if (Test-Path -LiteralPath $Keystore) { throw 'Refuse to replace an existing keystore' }
# 使用交互输入密码;发布前核对所选签名方案与备份流程。
& $KeytoolExe -genkeypair -keystore $Keystore -alias release -keyalg RSA -keysize 2048 -validity 10000
if ($LASTEXITCODE -ne 0) { throw 'Key generation failed' }
if (-not (Test-Path -LiteralPath $Keystore -PathType Leaf)) { throw 'Keystore missing' }
Write-Output 'keystore_created=true'预期输出(完成交互并成功创建时,省略 keytool 自己的提示):
keystore_created=true目录必须已经存在且可写。密钥创建成功不是包签名成功,应另行验证产物。按组织方案备份密钥与口令并限制访问;演示别名可用,已有应用必须使用登记的别名和密钥,不能覆盖旧文件来“修复”密码错误。
配置发布签名和版本
在 Android 导出预设的 Keystore 中填写 Release 路径、Release User 别名和 Release Password,正式导出取消 Export With Debug。当前 Godot Android 文档要求密钥库与密钥口令一致,按当前版本操作;凭据应放在受控配置或环境,避免公开存入仓库。
预设的 Version Name 是展示给用户的版本,Version Code 是安装与商店更新判断使用的整数,发布更新需要比前一版更高。它们可以采用不同规则,例如展示语义版本而使用持续递增构建编号,不能将展示名变化当成编号已经升级。
保留每个平台渠道最后使用的编号,包含内部测试和正式提交,避免同一编号被复用。回滚通常需要用更高编号发布恢复内容的构建,而不是给玩家安装更低 Version Code 的旧包。用户数据格式也应同时考虑兼容。
用实际产物验证升级链
对 APK 用 apksigner 检查签名,对版本、包名和 SDK 用 apkanalyzer 核对;AAB 与 Play 分发包采用对应工具和平台证书信息。不要用 APK 工具声称验证所有 AAB 分发行为,也不要将上传证书指纹直接当成设备最终签名。
先安装旧版并创建存档,再在相同渠道覆盖新版,启动读取存档并保存。卸载重装能绕过签名与数据问题,不能替代升级验收。同包名不同签名安装失败时先保存数据并核对证书,确认是测试身份冲突还是发布链错误。
签名分工见 Sign your app,版本规则见 Version your app,Godot字段见 Android export。