游戏引擎 / 系统课时

Android 签名配置卡在哪里

Android 签名配置卡在哪里

Cocos Creator 的 Android 调试包能够运行,并不代表正式包已使用正确证书。发布时常见的失败集中在密钥库路径、口令、别名和历史签名不一致。本课先厘清这些输入的关系,再按构建、验签、覆盖安装的顺序定位问题。

学习目标

  • 理解密钥库、密钥别名和两种口令各自负责什么。
  • 在 Cocos Creator 的 Android 构建选项中切换正式签名。
  • 用标准工具检查密钥条目和 APK 签名,区分构建失败与升级失败。

密钥库与别名为什么不能混用

一个 .jks 密钥库可以包含多个密钥条目,每个条目用别名定位。密钥库口令负责访问文件,密钥口令用于解锁相应的私钥;两者可能相同,但不能想当然地互换。签名使用私钥,APK 内携带可供验证的签名及证书信息,而不是把私钥打进安装包。

Android 密钥库、别名、口令与正式包签名关系图

这里最容易误判的是“别名写对了就说明证书没变”:别名只在当前密钥库内有意义。两份不同密钥库即使都叫 release,证书也可能完全不同;旧版本升级要核对证书身份,而不只是核对名字。

把正式密钥接入 Android 构建

  1. 先确认应用是否已经对外发布。若已发布,优先取回该应用原有的密钥与签名规则;不要因为忘记口令就生成一份新密钥直接替换。
  2. 对首次发布的新应用,可在 Android Studio 的“Build → Generate Signed Bundle / APK → Create new”生成密钥库,并妥善记录文件路径、别名及两类口令。
  3. 返回 Cocos Creator 3.8 的“项目 → 构建发布”,选择 Android,取消“使用调试密钥库”,填写自有密钥库路径、密钥库口令、密钥别名和别名口令。
  4. 重新“构建”并“生成”正式包。若打开 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 验签通过,所用证书符合既有发布链,并且在保留用户数据的测试设备上能够完成预期的升级安装。

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

目录与阅读设置

阅读设置

17

记录一个想法

Android 签名配置卡在哪里

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

登录哪都通