在开发鸿蒙应用时，模拟器虽方便，但像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开发场景。 |
发表于 
发表于