uni-app 安卓自有证书完全指南

本文参考 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 环境验证：

cmd 复制代码

java -version
keytool -help

如果提示"不是内部或外部命令"，需要将 JDK 的 bin 目录添加到系统 PATH 环境变量中。临时配置方式（仅当前命令行窗口有效）：

cmd 复制代码

set PATH=%PATH%;"C:\Program Files\Java\jdk-17\bin"

macOS 环境验证：

bash 复制代码

java -version
keytool -help

macOS 上如果安装了多个 Java 版本，可以用 /usr/libexec/java_home -V 查看已安装版本，然后临时指定：

bash 复制代码

export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PATH="$JAVA_HOME/bin:$PATH"

3.3 生成自有证书

Windows：

cmd 复制代码

mkdir D:\android-keys
cd /d D:\android-keys
keytool -genkeypair -v -keystore myapp.keystore -keyalg RSA -keysize 2048 -validity 36500 -alias myapp

macOS：

bash 复制代码

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 命令相同：

bash 复制代码

keytool -list -v -keystore myapp.keystore

输入密码后，重点确认输出中的：

text 复制代码

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
- 证书密码：你设置的证书库密码
提交打包，完成后在真机运行界面选择 "运行基座选择 → 自定义调试基座"。

场景 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 后重新选择证书文件。

uni-app 安卓自有证书完全指南

一、核心前提：Android 只需要一套自有证书

二、uni-app 三种证书的权威对比

2.1 自有证书（推荐用于正式发布）

2.2 云端证书（适用于开发阶段）

2.3 公共测试证书（已下线，不可使用）

2.4 三种证书对比一览

三、自有证书生成：Windows 与 macOS 完整实操

3.1 关于 -genkey 与 -genkeypair 的准确说明

3.2 环境准备

3.3 生成自有证书

3.4 交互填写步骤

3.5 验证证书

3.6 关于 DSA 算法的兼容性说明

四、在 HBuilderX 中配置证书

场景 A：制作自定义调试基座

场景 B：正式云打包发布

五、常见错误与修复

3.1 关于 `-genkey` 与 `-genkeypair` 的准确说明