本文参考 DCloud 官方文档《Android平台签名证书(.keystore)生成指南》（ask.dcloud.net.cn/article/357… Oracle 官方 keytool 文档与 Android 签名机制原理整理而成。
一、核心前提：Android 只需要一套自有证书
在 Android 平台，签名的规则非常明确：同一个包名（Package Name）的应用，必须使用同一个证书签名，才能覆盖安装和更新。如果包名相同但签名不同，Android 系统会在安装时报错，用户必须先卸载旧版本才能安装新版本。
因此，在 uni-app 的 Android 云打包流程中，不存在“开发证书”与“发布证书”的类型区分。你只需要生成一个 .keystore 文件，它同时用于制作自定义调试基座和正式云打包发布。真正严格区分开发证书与发布证书的是 iOS 平台，这一概念被许多教程不加区分地套用到了 Android 上，造成了广泛的误解。
补充说明：Android SDK 本地编译时确实会使用一个默认的
debug.keystore，但那是 Android 工具链的便利机制，uni-app 云打包并不要求你生成两个证书。
二、uni-app 三种证书的权威对比
HBuilderX 打包界面提供三种 Android 证书类型，理解它们的差异是正确选择的前提。以下对比依据 DCloud 官方说明整理。
2.1 自有证书（推荐用于正式发布）
定义：由开发者自己使用 Java keytool 工具生成，证书文件（.keystore）、密码、别名完全由开发者掌控。
核心优势：
- 所有权完全独立：不依赖任何第三方平台，证书文件始终在你自己手中。
- 长期有效性：有效期可自行设定为 100 年（36500 天），不存在到期风险。
- 可复用：同一个证书可签署多个应用，适合拥有多个 uni-app 项目的团队。
- 上架必需：Google Play 强制要求自有证书，国内主流应用商店也推荐使用。
注意事项：证书一旦丢失，已上架应用将永远无法更新。必须将 .keystore 文件、别名、密码一起备份到至少两个安全位置。
DCloud 官方定位：正式发布应用时推荐使用此类型证书。
2.2 云端证书（适用于开发阶段）
定义：从 HBuilderX 3.2.0 及以上版本开始，DCloud 服务器为开发者自动生成并托管的证书。在打包界面直接勾选“使用云端证书”即可，无需配置 JRE 环境。
技术特性：
- 与 AppID 强绑定：服务器为每个 AppID 生成独立的证书，无法跨 AppID 共享。
- 信息不可自定义：证书信息由服务器自动填写，开发者无法修改。
- 有效期 100 年：由 DCloud 服务器统一管理。
- 可查看和下载：登录 DCloud 开发者中心可查看或下载证书文件。
DCloud 官方定位与建议：云证书的优势是开发方便。DCloud 建议开发阶段使用云证书，开发者打包出 APK 后，交给掌管自有发布证书的人员使用自有证书自行重签，再上架应用商店。这种工作流实现了开发权限与发布权限的分离。
2.3 公共测试证书（已下线，不可使用）
定义：DCloud 提供的共享测试证书，所有开发者均可使用，证书信息为 “Test”。
关键限制：
- 无法上架任何正规应用商店。
- 证书信息为 Test，不包含真实开发者信息。
- 已正式下线，DCloud 官方明确标注“此模式已下线，请勿使用”。
结论：公共测试证书已不具备使用价值，任何正式或测试打包都不应选择此项。
2.4 三种证书对比一览
| 维度 | 自有证书 | 云端证书 | 公共测试证书 |
|---|---|---|---|
| 私钥保管方 | 开发者自己 | DCloud 托管 | DCloud 共享 |
| 创建方式 | keytool 命令生成，需 5–10 分钟 | HBuilderX 勾选即可，即时生成 | 已下线 |
| 信息自定义 | 完全可自定义 | 不支持 | 固定为 Test |
| 与 AppID 关系 | 无绑定，可跨项目使用 | 强绑定，每个 AppID 独立 | 无 |
| 有效期 | 自行设定（建议 36500 天） | 100 年 | 短 |
| 能否上架商店 | 可以 | 可下载后自行重签上架 | 不可以 |
| 官方推荐场景 | 正式发布 | 开发阶段 | 已下线 |
三、自有证书生成：Windows 与 macOS 完整实操
3.1 关于 -genkey 与 -genkeypair 的准确说明
首先纠正一个常见误解：-genkey 和 -genkeypair 功能完全等价。根据 Oracle 官方文档，-genkey 是早期版本的命令名称，旧名称仍然受支持，但新名称 -genkeypair 是今后的首选名称。两者生成的 keystore 文件在结构上没有任何区别。
真正需要关注的是 -keyalg 参数。如果在命令中不显式指定 -keyalg，keytool 会使用遗留的默认算法并打印警告，未来的 JDK 版本中不指定 -keyalg 将直接报错。因此，必须在命令中显式加上 -keyalg RSA，无论使用 -genkey 还是 -genkeypair。
本文统一使用 -genkeypair，以与未来 JDK 版本保持一致。
3.2 环境准备
生成证书使用的工具是 keytool，它随 JDK 或 JRE 一同发布。推荐安装 JDK 8、11 或 17 的 LTS 版本。
Windows 环境验证：
java -version
keytool -help
如果提示“不是内部或外部命令”，需要将 JDK 的 bin 目录添加到系统 PATH 环境变量中。临时配置方式（仅当前命令行窗口有效）：
set PATH=%PATH%;"C:\Program Files\Java\jdk-17\bin"
macOS 环境验证：
java -version
keytool -help
macOS 上如果安装了多个 Java 版本，可以用 /usr/libexec/java_home -V 查看已安装版本，然后临时指定：
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PATH="$JAVA_HOME/bin:$PATH"
3.3 生成自有证书
Windows：
mkdir D:\android-keys
cd /d D:\android-keys
keytool -genkeypair -v -keystore myapp.keystore -keyalg RSA -keysize 2048 -validity 36500 -alias myapp
macOS：
mkdir -p ~/android-keys
cd ~/android-keys
keytool -genkeypair -v -keystore myapp.keystore -keyalg RSA -keysize 2048 -validity 36500 -alias myapp
参数逐一说明：
| 参数 | 含义 | 建议值 |
|---|---|---|
-genkeypair | 生成密钥对（推荐写法） | 等价于 -genkey |
-keystore | 证书文件名 | 建议用项目名，如 myapp.keystore |
-keyalg RSA | 加密算法 | 必须用 RSA，不要用 DSA |
-keysize 2048 | 密钥长度 | 2048 |
-validity 36500 | 有效期（天） | 36500，约 100 年 |
-alias | 证书别名 | 纯英文字母或数字，如 myapp |
3.4 交互填写步骤
命令执行后，系统会依次提示：
- 证书库密码：输入并再次确认。输入时屏幕不显示字符。
- 名字与姓氏：如
Zhang San。 - 组织单位名称：如
YourCompany。 - 组织名称：如
YourCompany。 - 城市或区域名称：如
Beijing。 - 省/市/自治区名称：如
Beijing。 - 国家/地区代码：中国填
CN。 - 确认信息：输入
y。 - 密钥密码：提示
Enter key password for <myapp>时，直接按回车。
关键要求：DCloud 官方文档明确指出，HBuilderX 中证书库密码（storepass）和证书密码（keypass）必须一致。在生成证书的最后一步直接回车，让密钥密码与证书库密码相同，即可满足此要求。
3.5 验证证书
Windows 和 macOS 命令相同：
keytool -list -v -keystore myapp.keystore
输入密码后，重点确认输出中的：
Subject Public Key Algorithm: 2048-bit RSA key
如果显示为 2048-bit RSA key，证书即正确可用。如果显示 DSA，说明生成时未加 -keyalg RSA，需要重新生成。
3.6 关于 DSA 算法的兼容性说明
云端打包默认会添加 V1 和 V2 签名。已知 V1 签名不支持 2048 位 DSA 密钥，使用 DSA 算法生成的证书在云端打包时可能失败，提示 Failed to generate v1 signature。解决方法是生成证书时显式加上 -keyalg RSA。这也是本文反复强调必须使用 RSA 的原因。
四、在 HBuilderX 中配置证书
证书生成后，在 HBuilderX 中配置的位置根据使用场景分为两处，但使用的是同一套证书信息。
场景 A：制作自定义调试基座
- HBuilderX 菜单：运行 → 运行到手机或模拟器 → 制作自定义调试基座。
- 选择 Android 平台。
- 证书类型选择 “使用自有证书”。
- 填写：
- 证书文件：Windows 如
D:\android-keys\myapp.keystore，macOS 如/Users/你的用户名/android-keys/myapp.keystore - 证书别名：
myapp - 证书密码：你设置的证书库密码
- 证书文件：Windows 如
- 提交打包，完成后在真机运行界面选择 “运行基座选择 → 自定义调试基座”。
场景 B：正式云打包发布
- HBuilderX 菜单：发行 → 原生App-云打包。
- Android 打包配置中，证书类型选择 “使用自有证书”。
- 填写与调试基座完全相同的证书文件、证书库密码、证书别名、证书密码。
- 包名采用反写域名格式，如
com.yourcompany.myapp，配置路径为manifest.json → app-plus → distribute → android → packagename。包名一旦确定，整个应用生命周期中不要修改。 - 提交打包。
五、常见错误与修复
1. 证书库密码与密钥密码不一致 生成证书时在“密钥密码”提示处直接回车即可。HBuilderX 要求两者一致。
2. 使用 DSA 算法导致云端打包失败
生成证书时加上 -keyalg RSA。RSA 2048 是当前推荐的安全配置。
3. 证书别名填错
如果报“证书名称不正确”，用 keytool -list -v -keystore myapp.keystore 查看真实别名。
4. 证书路径包含中文或空格
DCloud 官方建议证书名称使用英文字母或数字，避免使用中文。将 .keystore 文件放在纯英文、无空格的路径下。
5. 证书文件丢失或密码遗忘
这是最严重的错误。证书一旦丢失，已上架应用将无法更新。请立即将 .keystore 文件、别名、密码一起备份到至少两个安全位置。
6. 团队协作中证书不一致 多人打包时必须使用完全相同的证书文件、别名、密码和 AppID。不同证书签名的同包名应用无法覆盖安装。
7. macOS 上 HBuilderX 无法读取证书
检查文件权限，执行 chmod 644 ~/android-keys/myapp.keystore 后重新选择证书文件。
