游戏引擎 / 系统课时
Android 签名配置卡在哪里
Android 签名配置卡在哪里
Cocos Creator 的 Android 调试包能够运行,并不代表正式包已使用正确证书。发布时常见的失败集中在密钥库路径、口令、别名和历史签名不一致。本课先厘清这些输入的关系,再按构建、验签、覆盖安装的顺序定位问题。
学习目标
- 理解密钥库、密钥别名和两种口令各自负责什么。
- 在 Cocos Creator 的 Android 构建选项中切换正式签名。
- 用标准工具检查密钥条目和 APK 签名,区分构建失败与升级失败。
密钥库与别名为什么不能混用
一个 .jks 密钥库可以包含多个密钥条目,每个条目用别名定位。密钥库口令负责访问文件,密钥口令用于解锁相应的私钥;两者可能相同,但不能想当然地互换。签名使用私钥,APK 内携带可供验证的签名及证书信息,而不是把私钥打进安装包。

这里最容易误判的是“别名写对了就说明证书没变”:别名只在当前密钥库内有意义。两份不同密钥库即使都叫 release,证书也可能完全不同;旧版本升级要核对证书身份,而不只是核对名字。
把正式密钥接入 Android 构建
- 先确认应用是否已经对外发布。若已发布,优先取回该应用原有的密钥与签名规则;不要因为忘记口令就生成一份新密钥直接替换。
- 对首次发布的新应用,可在 Android Studio 的“Build → Generate Signed Bundle / APK → Create new”生成密钥库,并妥善记录文件路径、别名及两类口令。
- 返回 Cocos Creator 3.8 的“项目 → 构建发布”,选择 Android,取消“使用调试密钥库”,填写自有密钥库路径、密钥库口令、密钥别名和别名口令。
- 重新“构建”并“生成”正式包。若打开 Android Studio 重新打包,也要检查它的实际签名配置,不能因为 Creator 面板已填写就假定 Android Studio 一定复用了相同证书。
用命令分别验证密钥和产物
先确认电脑已安装 JDK 和 Android SDK Build Tools,并能从终端调用 keytool 与 apksigner。下面命令以 Bash 为例,将两处 <PATH> 分别替换为 .jks 和最终 .apk 的真实路径,将 <ID> 替换为实际别名;keytool 会交互请求密钥库口令。
bash
set -e
# 验证指定密钥库中存在目标别名;不在命令里明文传密码
KEYSTORE_PATH="<PATH>"
APK_PATH="<PATH>"
ALIAS="<ID>"
keytool -list -keystore "$KEYSTORE_PATH" -alias "$ALIAS" >/dev/null
printf '密钥别名可访问\n'
# 对最终 APK 验签,并摘取签名证书的 SHA-256 摘要
certs="$(apksigner verify --print-certs "$APK_PATH")"
printf '%s\n' "$certs" | grep 'certificate SHA-256 digest'
printf 'APK 签名有效\n'预期输出(省略口令提示,证书摘要因项目而异):
text
密钥别名可访问
Signer #1 certificate SHA-256 digest: <SHA256>
APK 签名有效keytool 成功只能说明指定别名可被查询,不能证明 Creator 实际使用了它。apksigner 校验的则是最终 APK;再用同样的检查方式获取上一正式 APK 的 SHA-256 证书指纹,才能判断两版证书是否一致。这些命令不直接适用于 AAB 文件。
按失败发生的环节排查
| 故障阶段或提示 | 更可能的原因 | 优先处理 |
|---|---|---|
| 找不到密钥库文件 | 路径错、文件未同步到构建机器 | 检查文件是否存在及构建进程的读取权限 |
Keystore was tampered with, or password was incorrect |
密钥库口令错误,也可能文件损坏 | 核实所用文件与口令,不反复生成新密钥 |
Alias ... does not exist 或无法恢复密钥 |
别名错误或密钥口令不匹配 | 用 keytool 查询条目,再核对密钥口令 |
| APK 可以验签却不能覆盖旧包 | 应用 ID 相同但签名身份不兼容 | 比对新旧 APK 的签名证书及平台签名规则 |
| 调试版能装,正式包无法通过商店检查 | 仍使用调试密钥、版本码不合规或渠道要求未满足 | 核对正式签名、版本与平台规定 |
签名问题的验收标准不是“Gradle 没报错”,而是最终 APK 验签通过,所用证书符合既有发布链,并且在保留用户数据的测试设备上能够完成预期的升级安装。
按自己的节奏,确认真正理解。