HarmonyOS云调试真机签名问题：从debug包到release包
在开发鸿蒙应用时，模拟器虽方便，但像Vision Kit（照相识别）和Speech Kit（TTS朗读）这类依赖真实硬件的功能无法在模拟器上验证。我手头也没有真机，于是转向华为云调试服务，结果遇到一个典型的签名障碍——自动签名生成的hap包是debug类型，云调试只接受release签名包。本文将完整梳理从生成签名文件、申请证书Profile到编译release包并使用云调试的流程，帮你避开同样坑。## 一、问题背景：模拟器缺能力，云调试却卡签名
项目中使用了Core Vision Kit的通用文字识别（OCR）和Speech Kit的语音合成功能。官方提供完整的OCRService代码示例（见下文），在模拟器调试时发现照相相关API无法调用。因此计划使用AppGallery Connect中的云调试功能，在真机（云上）上运行测试。
/**
* 文字识别服务类
* 使用 Core Vision Kit 的 textRecognition 进行通用文字识别(OCR)
* 输入 PixelMap，输出识别到的文字字符串
*/
export class OCRService {
/**
* 识别图片中的文字
* @param pixelMap 待识别的图片像素数据
* @returns 识别到的全部文字
*/
async recognizeText(pixelMap: image.PixelMap): Promise<string> {
try {
hilog.info(DOMAIN, TAG, 'Starting text recognition...');
// 构建VisionInfo，传入PixelMap
const visionInfo: textRecognition.VisionInfo = {
pixelMap: pixelMap
};
// 配置文字识别参数
const configuration: textRecognition.TextRecognitionConfiguration = {
isDirectionDetectionSupported: true
};
// 调用文字识别API（回调模式包装为Promise）
const result = await new Promise<textRecognition.TextRecognitionResult>((resolve, reject) => {
textRecognition.recognizeText(
visionInfo,
configuration,
(error: BusinessError, data: textRecognition.TextRecognitionResult) => {
if (error.code === 0) {
resolve(data);
} else {
hilog.error(DOMAIN, TAG, 'Text recognition failed: code=%{public}d, msg=%{public}s',
error.code.toString(), error.message);
reject(error);
}
}
);
});
// 提取识别结果
const recognizedText = result.value.toString();
hilog.info(DOMAIN, TAG, 'Text recognition completed, length=%{public}d', recognizedText.length.toString());
return recognizedText;
} catch (error) {
hilog.error(DOMAIN, TAG, 'recognizeText error: %{public}s', JSON.stringify(error));
throw error as Error;
}
}
/**
* 释放资源
*/
release(): void {
hilog.info(DOMAIN, TAG, 'OCRService released');
}
}
代码可正常编译，但在模拟器运行到相机调用时直接退出。于是决定使用云调试真机。然而第一次推送hap包时，云调试报错，提示签名不合法——此时我使用的是DevEco Studio的自动签名功能（File -> Project Structure -> Signing Configs，勾选Automatically generate signature），这种签名仅用于调试，生成的hap包属于debug类型，无法用于云调试或发布。必须生成正式的release签名hap包。
## 二、签名文件生成与Profile申请全流程
云调试要求hap包使用release签名。需要准备三个核心文件：.p12密钥文件、.cer数字证书、.p7b Profile文件。
### 2.1 生成密钥对和证书请求文件（CSR）
1. 在DevEco Studio中，点击菜单栏 Build -> Generate Key and CSR。
2. 如果已有.p12密钥库，可选择已有的；这里以新建为例。填写密钥库名称（仅含字母、数字、下划线、中划线、句号），选择保存路径，设置强密码（至少8位，包含大写、小写、数字、特殊符号中的两类以上），并记住别名（Alias）。
3. 高级设置中建议将证书有效期设为25年以上，覆盖应用生命周期。通用名称、组织单位等信息可选填，但建议填写真实信息以便管理。
4. 点击Next，DevEco同时生成.p12（密钥库文件）和.csr（证书请求文件）。
### 2.2 在AGC申请数字证书
1. 登录AppGallery Connect（https://developer.huawei.com/consumer/cn/service/josp/agc/index.html），进入“证书、App ID和Profile > 证书”页面。
2. 点击“新增证书”，填写证书名称，选择证书类型（发布证书或调试证书，云调试需要发布证书），上传上一步生成的.csr文件，提交。
3. 申请成功后，在证书列表点击“下载”获取.cer证书文件。
### 2.3 生成Profile文件
1. 仍在该AGC页面，切换到“Profile”标签，点击“添加”。
2. 选择Profile所属应用，输入Profile名称，类型必须选择“发布”（对应release包），关联刚才申请的数字证书，并为Profile选择所需的应用权限（特别注意：如果需要Vision Kit、Speech Kit等敏感权限，请在这里勾选，否则云调试运行时可能报权限拒绝）。
3. 点击“添加”生成Profile，然后下载得到.p7b文件。
## 三、配置Release签名并构建hap包
1. 回到DevEco Studio，取消自动签名的勾选。
2. 进入File -> Project Structure -> Signing Configs，手动配置签名信息：
- Store File：选择之前生成的.p12文件
- Store Password：输入设置的密钥库密码
- Key Alias：输入之前设置的别名
- Key Password：与Store Password可相同或不同，取决于生成时的设置
- CertPath：选择从AGC下载的.cer文件
- Profile：选择从AGC下载的.p7b文件
3. 确认配置无误后，选择构建类型为“release”（在Build Variants或通过菜单Build -> Build Hap(s) -> Release），生成正式的release hap包。
## 四、使用云调试验证
1. 登录AGC控制台，进入“我的项目” -> “云调试”页面（https://developer.huawei.com/consumer/cn/service/josp/agc/index.html#/myProject/...）。
2. 点击“上传应用”，选择刚才编译好的release hap包。上传成功后，选择一台云真机（支持Vision Kit和Speech Kit的设备型号）。
3. 启动云调试，即可在远程真机上运行应用，测试OCR和TTS功能。实际测试中，文字识别成功返回结果，语音合成也能正常播报。
## 五、总结与注意事项
- 云调试只接受release签名的hap包，自动签名仅用于本地调试。
- 申请Profile时，权限声明必须覆盖应用所需的所有敏感权限，否则在云真机上可能因为权限缺失导致功能异常。
- 签名密钥和密码务必妥善保存，更新版本时需使用同一签名文件保持一致性。
- 如果遇到“Install Failed”或“签名校验失败”提示，请优先检查签名配置的四个文件是否完整匹配（p12、cer、p7b和别名密码）。
通过以上流程，没有鸿蒙实体设备的开发者也能利用云调试完成真机级的功能验证，尤其适合依赖物理硬件的Kit开发场景。
Re: HarmonyOS云调试真机签名问题：从debug包到release包
非常感谢楼主的详细分享！正好最近也在折腾云调试，遇到了完全一样的签名坑——自动签名默认debug，云调试只认release。你提供的从生成密钥到AGC申请证书、再到编译release包的完整流程非常清晰，特别是那个25年有效期的建议很实用，避免后续证书过期麻烦。 想请教一下：在AGC申请证书时，你提到选择“发布证书”用于云调试，这一步有没有什么特殊注意事项？比如证书类型选错会导致云调试仍然报错吗？另外，Profile文件创建时是否也需要勾选“云调试”相关的设备或权限？希望能再补充一点细节，多谢！Re: HarmonyOS云调试真机签名问题：从debug包到release包
感谢楼主分享这么详细的云调试签名流程，能看出是真踩过坑之后的经验总结。自动签名生成的debug包确实很容易让人忽略签名类型的差异，我一开始用云调试也卡在这一步。 另外想请教一下，在生成CSR文件时，证书有效期楼主建议设25年以上，这个是不是为了防止证书过期后还要重新签包？还是纯粹为了省事？还有一点，楼主提到的“发布证书”和“调试证书”在云调试时具体有什么区别，是不是发布证书签的包在云调试里也能正常调用那些依赖硬件的API（比如OCR和TTS）？期待后续的Profile申请和编译release包的部分！Re: HarmonyOS云调试真机签名问题：从debug包到release包
感谢楼主这么详细的分享！我在做 HarmonyOS 开发时也遇到过模拟器无法调用相机和语音功能的问题，云调试确实是好思路。但签名这块的坑确实不少，debug 和 release 包的区别在官方文档里容易忽略，楼主把从生成 .p12、申请证书到编译 release 包的流程梳理得很清楚，对新人来说非常实用。后面我也打算按这个步骤去体验下云上的真机，省得自己买设备了。谢谢！
页:
[1]