Android 应用签名终极教程
什么是签名？为什么必须签名？
在 Android 系统中，签名 是一个强制性的步骤，每个 APK 文件都必须经过数字签名才能被安装和运行。
为什么必须签名？
- 身份验证：签名可以验证应用的来源，它确保用户安装的应用确实是你发布的，而不是别人冒充的，这就像一个“数字身份证”。
- 完整性校验：签名可以确保应用在发布后没有被篡改，APK 文件在签名之后被任何第三方修改过，系统在安装时会检测到签名不匹配，从而拒绝安装,这保证了应用代码的完整性。
- 升级机制：Android 系统通过签名来决定一个新安装的应用是否可以覆盖旧版本，只有当新应用的签名与旧版本完全相同时，系统才允许它进行升级，否则,系统会将其视为一个全新的应用。
签名是如何工作的？
它使用非对称加密技术：
- 你拥有一对密钥：私钥 和 公钥。
- 你使用 私钥 对你的应用进行签名（这个过程是保密的，只有你有）。
- 你将 公钥 打包进 APK 文件中。
- 安装时，Android 系统使用公钥来验证签名是否由对应的私钥生成，由于私钥只有你持有，所以可以证明 APK 是你发布的。
签名的两种方式：调试签名与发布签名
Android 开发中有两种主要的签名模式：
| 特性 | 调试签名 | 发布签名 |
|---|---|---|
| 用途 | 开发和测试阶段 | 发布到应用商店（Google Play, 华为应用市场等） |
| 生成方式 | Android Studio / Gradle 自动生成 | 必须由开发者自己创建 |
| 密钥库 | debug.keystore (位于 ~/.android/ 目录) |
自定义的 .jks 或 .keystore 文件 |
| 别名 | androiddebugkey |
自定义别名 |
| 密码 | android |
自定义密码 |
| 有效期 | 36500 年 (有效期很长) | 推荐至少 25 年，以确保应用升级顺畅 |
重要提示：永远不要将 debug.keystore 用于发布应用！ 它是公开的，任何人都可以用它来签名一个冒充你应用的应用,这会带来巨大的安全风险。
如何创建发布签名密钥库？
在发布应用之前，你必须创建自己的签名密钥，最常用的工具是 Java 的 keytool（它随 JDK 一起安装）。
打开命令行工具
- Windows: 打开
cmd或PowerShell。 - macOS / Linux: 打开
Terminal。
执行 keytool 命令
运行以下命令来创建密钥库文件（通常以 .jks 或 .keystore 为后缀）。
keytool -genkeypair -v -keystore my-release-key.jks -alias my-alias -keyalg RSA -keysize 2048 -validity 10000 -storepass YOUR_STORE_PASSWORD -keypass YOUR_KEY_PASSWORD -dname "CN=Your Name, OU=Your Unit, O=Your Organization, L=Your City, ST=Your State, C=Your Country"
命令参数详解：
-genkeypair: 生成密钥对（包含公钥和私钥）。-keystore my-release-key.jks: 指定密钥库文件的名称和路径，这里我们创建了一个名为my-release-key.jks的文件。请妥善保管此文件，不要丢失或泄露！-alias my-alias: 指定密钥的别名,这个别名用于在密钥库中唯一标识你的密钥。-keyalg RSA: 指定密钥算法，RSA 是标准且安全的算法。-keysize 2048: 指定密钥大小，2048 位是当前推荐的安全级别。-validity 10000: 指定密钥的有效期，单位是天，这里设置为 10000（约 27 年）,确保在应用生命周期内无需重新签名。-storepass YOUR_STORE_PASSWORD: 设置密钥库的访问密码。请替换为强密码。-keypass YOUR_KEY_PASSWORD: 设置别名的私钥密码。请替换为强密码。 （可以和-storepass相同,但建议不同）-dname: 设置“可分辨名称”，包含你的身份信息，格式为"CN=姓名, OU=部门, O=组织, L=城市, ST=省份, C=国家代码"。CN(Common Name): 通常是你的姓名或公司名。C: 国家代码，CN代表中国。
执行后，keytool 会在你当前所在的目录下生成 my-release-key.jks 文件。
安全提示：
- 将
.jks文件保存在安全的地方，最好加入版本控制系统（如 Git）的.gitignore文件中,或者使用专门的密钥管理服务。 - 不要将密码硬编码在你的代码或配置文件中。
如何在 Android Studio 中配置签名？
创建好密钥后，你需要告诉 Android Studio 在构建发布版本时使用它。
使用 UI 界面（推荐新手）
-
打开你的 Android 项目。
-
进入
File->Project Structure...。 -
在左侧选择
Modules，然后选择你的app模块。 -
切换到
Signing标签页。 -
点击右上角的 号，创建一个新的签名配置，例如命名为
release。 -
填写以下信息：
- Key store path: 点击 按钮，选择你刚刚创建的
my-release-key.jks文件。 - Key store password: 输入你在
keytool中设置的-storepass。 - Key alias: 输入你在
keytool中设置的-alias(my-alias)。 - Key password: 输入你在
keytool中设置的-keypass。
- Key store path: 点击 按钮，选择你刚刚创建的
-
点击
OK保存签名配置。 -
切换到
Build Types标签页。 -
选择
release构建类型。 -
在
Signing Config下拉菜单中，选择你刚刚创建的release签名配置。 -
点击
OK保存所有更改。
直接修改 build.gradle 文件
这种方法更灵活，适合 CI/CD 流程。
- 打开
app目录下的build.gradle.kts(或build.gradle) 文件。 - 在
android { ... }代码块中，添加一个signingConfigs配置：
// build.gradle.kts (Kotlin DSL)
android {
// ... 其他配置
signingConfigs {
create("release") {
storeFile = file("my-release-key.jks") // 密钥库文件路径
storePassword = "YOUR_STORE_PASSWORD" // 密钥库密码
keyAlias = "my-alias" // 别名
keyPassword = "YOUR_KEY_PASSWORD" // 别名密码
}
}
buildTypes {
release {
isMinifyEnabled = true // 启用代码混淆
proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
// 应用签名配置
signingConfig = signingConfigs.getByName("release")
}
}
}
// build.gradle (Groovy DSL)
android {
// ... other configurations
signingConfigs {
release {
storeFile file("my-release-key.jks") // 密钥库文件路径
storePassword "YOUR_STORE_PASSWORD" // 密钥库密码
keyAlias "my-alias" // 别名
keyPassword "YOUR_KEY_PASSWORD" // 别名密码
}
}
buildTypes {
release {
minifyEnabled true // 启用代码混淆
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
// 应用签名配置
signingConfig signingConfigs.release
}
}
}
如何生成已签名的 APK / AAB？
配置好签名后,就可以构建发布版本了。
生成 APK (Android Package Kit)
- 在 Android Studio 顶部工具栏中，将构建变体从
debug切换到release。 - 点击旁边的
Build->Generate Signed Bundle / APK...。 - 选择 APK，然后点击
Next。 - 如果之前通过 UI 配置，系统会自动找到你的
release签名配置，如果没有，你需要点击Choose existing...来选择你的.jks文件并填写密码。 - 选择你想包含的
release变体（通常是release）。 - 点击
Finish，Android Studio 会在app/build/outputs/apk/release/目录下生成已签名的 APK 文件。
生成 AAB (Android App Bundle) - 推荐方式
Google Play 商店现在推荐使用 AAB 格式，它会根据用户的设备自动生成和优化 APK。
- 在 Android Studio 顶部工具栏中，确保是
release变体。 - 点击
Build->Generate Signed Bundle / APK...。 - 选择 Android App Bundle，然后点击
Next。 - 同样，选择你的
release签名配置。 - 选择
release变体。 - 点击
Finish，已签名的 AAB 文件会生成在app/build/outputs/bundle/release/目录下。
常见问题与解决方案
问题1：升级应用时提示“签名不匹配”
- 原因：你尝试用一个新的、不同的密钥去签名一个已安装的应用。
- 解决方案：必须使用与首次发布时完全相同的
.jks文件和密码，这就是为什么密钥的有效期要设置得足够长，如果你不小心丢失了原始密钥，那么用户将无法通过正常渠道升级,只能卸载后重新安装。
问题2：如何检查 APK 的签名信息？
可以使用 keytool 或 apksigner 命令行工具。
# 查看 APK 的签名信息 keytool -printcert -jarpath your-app.apk # 或者使用 apksigner (在 Android SDK 的 build-tools 目录下) ./apksigner verify -print-certs your-app.apk
问题3：我应该将签名信息保存在哪里？
.jks文件：这是最重要的资产，应该：- 备份到多个安全位置（如加密硬盘、云存储）。
- 不要提交到公共的代码仓库（如 GitHub）。
- 可以使用 GitHub Secrets 或其他 CI/CD 密钥管理服务来管理。
- 密码：不要硬编码在代码里，同样,使用安全的环境变量或密钥管理服务。
- 理解签名：它是应用的身份证明和完整性保证。
- 区分调试和发布：开发用
debug.keystore,发布必须用自己创建的密钥。 - 创建密钥：使用
keytool生成一个安全的.jks文件,并妥善保管。 - 配置签名：在 Android Studio 的
Project Structure或build.gradle中配置你的发布签名。 - 构建发布包：生成已签名的 APK 或 AAB 文件,准备上传到应用商店。
- 安全第一：永远不要泄露你的
.jks文件和密码,否则你的应用将面临被仿冒的风险。
遵循以上步骤，你就可以安全、正确地为你的 Android 应用进行签名和发布了。
