鸿蒙应用开发 UI 基础：真机调试与开发者认证签名配置

特殊说明：
目前不支持香港（中国）、澳门（中国）、台湾（中国）及海外企业注册认证中国大陆开发者联盟账号，相关主体可访问华为开发者联盟海外官网办理。

三、配置安装 DevEco Studio

（一）下载渠道

1. 访问鸿蒙开发者官网的 DevEco Studio 下载页；
2. 根据电脑系统（Windows/macOS/Linux）选择对应版本，点击下载并同意用户协议（需先登录华为账号）。

开发工具下载安装配置在零基础入门阶段就已经学过，本节不做重复讲解。

四、创建工程并完成真机自动签名

（一）创建工程 FirstApplication

图 1-5 鸿蒙工程创建界面（选择 Stage 模型模板）

• 模拟器运行：无需配置签名，可直接创建并运行应用程序；
• 真机运行：需完成签名配置，否则会出现应用未签名安装失败提示。

签名分为自动签名、手动签名两类。调试阶段仅使用单台测试设备时，优先使用自动签名。

（二）鸿蒙真机调试环境配置

1. 物理连接：使用原装数据线将手机连接至电脑 USB 接口，避免非原装线导致连接不稳定；
2. 开启开发者选项：
   • 打开手机「设置」→「关于本机」；
   • 连续点击「软件版本」，直至弹出开发者选项已开启提示；
3. 开启 USB 调试：
   • 打开手机「设置」→「系统和更新」→「开发者选项」；
   • 开启「USB 调试」，同步开启允许 USB 安装应用，避免安装权限不足；
4. 设备连接授权：
   • 手机端弹出USB 用途选择框，必须选择「文件传输（MTP）」；
   • 电脑端弹出调试授权框，勾选始终允许此计算机调试并确认；
5. DevEco Studio 识别设备：
   • 打开开发工具，点击顶部运行设备下拉框，确认显示已连接的真机名称；
   • 选择该设备，点击运行按钮即可尝试调试（未配置签名会直接提示安装失败）。

（三）真机安装应用程序失败场景

图 1-6 未配置签名导致的真机安装失败提示

• 核心原因：未配置有效签名信息，鸿蒙系统强制要求应用完成签名后，才可在真机安装与运行；
• 解决方向：
  • 调试场景：优先使用自动签名，操作简单，适配单设备调试；
  • 发布/多设备调试场景：必须配置手动签名，支持应用上架与多设备调试。

五、配置签名信息

签名信息是鸿蒙应用的数字身份证，未配置有效签名的应用无法在真机调试、运行，也无法上架应用市场，需完成实名认证后再进行配置。

（一）签名配置核心概念

鸿蒙签名的核心是通过四个手动创建/获取的关键文件完成身份验证、合法性校验与运行授权，四者形成完整签名链路，缺一不可，是应用能在真机运行、后续上架的基础，具体信息如下：

1. 密钥库文件（.p12）—— 签名基础根凭证

DevEco Studio 本地创建的签名核心根文件，是所有鸿蒙签名操作的基础，无此文件则无法开展任何签名相关流程。核心作用为加密存储非对称加密的公钥/私钥对：私钥用于对应用安装包进行数字签名，公钥会提取至.csr 文件用于申请官方证书；最终实现双重核心价值，一是验证应用完整性，防止安装包被篡改，二是标识开发者唯一身份，绑定应用与开发者的归属关系。

• 自动签名：系统自动创建、加密保管，全程无需手动操作；
• 手动签名：需自行设置 8 位以上密码（含大小写/数字/特殊符号两类及以上），密码丢失无法找回，文件需妥善留存；调试/发布环境建议复用同一.p12，避免签名不一致导致应用无法覆盖安装。

2. 证书请求文件（.csr）—— 证书申请专属桥梁文件

与.p12 在 DevEco Studio同步本地创建的标准化申请文件，是连接本地.p12 与官方.cer 的唯一桥梁，无此文件无法向 AGC 申请数字证书。核心作用是提取.p12 中的公钥，整合开发者填写的身份信息（个人姓名/企业名称、所属地区等），形成 AGC 认可的证书申请材料；华为官方基于此文件的公钥和身份信息完成校验，为开发者生成对应.cer 文件。

• 自动签名：系统自动生成并完成上传，无需手动干预；
• 手动签名：与.p12 强绑定，一个.p12 仅能生成一个对应.csr，申请.cer 时必须上传匹配的.csr，不可混用；生成时信息需英文填写、无特殊字符；申请到.cer 后无需长期保管，丢失可随原.p12 重新生成。

3. 数字证书（.cer）—— 官方合法性准入凭证

在 AGC 上传.csr 后申请下载的华为官方文件，是鸿蒙系统允许应用真机安装的电子准入证明。核心作用是经华为官方对.csr 中的开发者身份（个人/企业）和公钥校验后，颁发的合法性凭证；验证开发者身份真实有效、应用来源正规，同时将开发者身份、应用包名与.p12 的公钥永久绑定，确保签名的唯一性和合规性。

• 分调试版、发布版，调试版仅用于真机调试，发布版为应用上架必备，二者不可混用；
• 与.csr/.p12 强绑定，丢失可在 AGC 重新下载；需与应用包名、.p7b 文件信息完全一致，否则会出现签名验证失败、应用无法安装的问题。

4. Profile 文件（.p7b）—— 应用运行最终授权文件

在 AGC 关联已申请的.cer 后，申请下载的官方授权文件，是应用能在指定设备运行的最终授权令。核心作用是统一绑定应用核心信息，包括应用包名、.cer 数字证书、调试设备 UDID、应用申请的权限列表，明确应用的运行边界；鸿蒙系统将依据此文件信息，判定是否允许应用在设备上安装、启动及使用对应权限。

• 分调试型、发布型，调试型需绑定设备 UDID，仅指定设备可运行，发布型无设备限制，适用于应用上架；
• 新增调试设备后，需在 AGC 重新生成并下载新.p7b，替换旧文件后重新编译工程，否则新设备无法运行应用；此文件是签名配置中最易出现信息不匹配的环节，也是真机调试失败的常见原因，需与包名、.cer 证书信息完全匹配。

四个核心文件关联逻辑总结

DevEco 本地创建.p12+ 同步生成.csr → 上传.csr 至 AGC 申请下载.cer → AGC 关联.cer 生成.p7b → 四者配合完成 DevEco 绑定 → 应用签名生效，真机可运行 

核心逻辑：.p12 是签名的基础根凭证，.csr 是证书申请的专属桥梁，.cer 是官方的合法认证，.p7b 是最终的运行授权，四者形成完整签名链路、信息强绑定，包名、设备 UDID 等关键信息必须完全一致，否则签名失效。

（二）签名方式分类与适用场景

（三）自动签名操作流程（调试/真机运行推荐）

1. 保持真机与电脑正常连接，且 DevEco Studio 已成功识别设备；
2. 打开 DevEco Studio，进入路径：File > Project Structure > Project > Signing Configs；
3. 勾选Automatically generate signature；
4. 未登录账号时，点击Sign In，登录已完成实名认证的华为开发者账号；
5. 系统自动完成全流程配置：本地生成.p12/.csr，自动上传.csr 至 AGC，获取.cer/.p7b 并写入工程配置文件；
6. 验证配置：重新运行应用至真机，可正常安装启动即代表自动签名配置成功。

自动配置调试证书

图 1-7 自动签名配置界面（勾选自动生成并登录华为账号）

（四）工程级编译配置文件说明

自动签名完成后，工程根目录 build-profile.json5 会自动填充签名信息，核心字段说明如下：

1. 调试证书配置项

图 1-8 工程级编译配置文件（自动填充的签名信息）

{"app":{"signingConfigs":[{"name":"default","type":"HarmonyOS","material":{"certpath":"/Users/xxx/.ohos/config/xxxx.cer","keyAlias":"debugKey","keyPassword":"xxxx","profile":"/Users/g/.ohos/config/xxxx.p7b","signAlg":"SHA256withECDSA","storeFile":"/Users/xxxx/.ohos/config/xxxx.p12","storePassword":"xxxx"}],"products":[{"name":"default","signingConfig":"default","targetSdkVersion":"6.0.0(20)","compatibleSdkVersion":"5.0.0(12)","runtimeOS":"HarmonyOS"}]},"modules":[{"name":"entry","srcPath":"./entry","targets":[{"name":"default"}]}]}

2. 配置应用程序包名 (bundleName)

修改完应用包名需点击 Sync Now 完成同步更新

{"app":{"bundleName":"com.sanxiu.firstapp","vendor":"example","versionCode":1000000,"versionName":"1.0.0","icon":"$media:layered_image","label":"$string:app_name"}}

（五）手动签名操作流程（发布必用）

步骤 1：本地生成密钥库（.p12）与证书请求（.csr）文件

图 1-9 密钥库与 CSR 文件创建入口（DevEco Studio 顶部菜单路径）

1. 打开 DevEco Studio，点击顶部菜单栏 Build > Generate Key and CSR；

2. 创建密钥库文件（首次操作）：

   • 点击New（已有密钥库可点击Choose Existing）；
   • 选择存储路径（无中文、无特殊字符），填写英文文件名（如 firstApp.p12）并保存；
   • 设置密钥库密码：要求至少 8 位，包含大写、小写、数字、特殊符号中两类及以上，务必记录保存，丢失无法找回；

3. 配置密钥别名（Alias）：
   图 1-10 密钥别名配置界面（设置别名、密码及有效期）

   • 命名规范：应用标识，如 firstApp_debug；
   • 密钥密码建议与密钥库密码一致，降低记忆成本；

4. 高级设置（Advance Setting，选填）：
   图 1-11 密钥证书高级设置（填写开发者身份信息）

   • Validity(years)：证书有效期，默认 25 年，建议保持默认；
   • First and last name：个人填姓名，企业填应用名/企业简称；
   • Organizational unit：企业填部门，个人填 Personal；
   • Organization：企业填全称，个人填姓名；
   • City/locality/State/province：使用英文填写城市、省份，如 Beijing；
   • Country code：中国大陆统一填写 CN；
   • 禁止使用双引号、斜杠、反引号等特殊字符；

5. 生成 CSR 证书请求文件：

   • 点击Next切换至Generate CSR标签；
   • 选择与.p12 相同的存储目录，填写英文文件名（如 firstApp.csr），点击Finish；

6. 验证结果：前往存储路径，确认.p12与.csr两个文件均已成功生成。

图 1-12 生成 CSR 文件配置界面（切换至 Generate CSR 标签）

步骤 2：在 AGC 上传.csr 并申请数字证书（.cer）与 Profile（.p7b）文件

登录 AGC 官网，使用已实名认证的华为账号登录：

1. 创建应用（包名必须与 DevEco 工程完全一致）：点击APP 与元服务→HarmonyOS：新建发布；
   图 1-15 AGC 新建应用入口（选择 HarmonyOS 应用类型）

2. 新建应用与 APP ID：

   • 应用类型：HarmonyOS 应用；
   • 应用名称：自定义，如'第一个应用'；
   • 应用包名：与工程 bundleName 完全一致，格式 com.xxx.xxx；
   • 应用分类：选择应用/游戏；
   • 点击下一步完成创建。

图 1-16 填写应用基本信息（包名需与工程完全一致）

• 填写证书名称，选择证书类型（调试/发布）；
• 点击上传 CSR 文件，选择步骤 1 生成的 .csr 文件，提交后立即下载 .cer 并妥善保存；

4. 申请 Profile 文件（.p7b）：进入Profile→添加；
   图 1-21 AGC 构建 Profile 文件界面（关联应用、证书与设备）

申请数字证书（.cer）：进入证书、APP ID 和 Profile→新增证书；
图 1-20 AGC 新增数字证书界面（选择证书类型并上传 CSR）

• 应用名称：选择当前应用，包名自动匹配；
• Profile 名称：自定义英文名称，如 firstApp；
• Profile 类型：调试（需绑定设备 UDID）/发布（无设备限制）/指定设备；
• 关联证书：选择上一步生成的数字证书；
• 提交后下载 .p7b 文件；

5. 添加调试设备：
   • 点击设备→添加；
   • 填写设备名称，选择设备类型，录入设备 UDID；

图 1-22 手动签名核心文件集合（.p12/.csr/.cer/.p7b）

6. UDID 获取方法：
   图 1-23 设备 UDID 查询说明（通过 HDC 命令或自动签名同步）

• 前提：设备已开启 USB 调试，仅保留一台真机连接电脑，关闭所有模拟器；
• Mac 默认 HDC 路径：Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains；
• 简易方案：先使用自动签名连接一次真机，AGC 会自动同步设备 UDID；
• 官方参考：注册设备官方指南。

命令行获取（Windows/Mac 通用）：
进入 HDC 工具目录，执行官方标准命令：

hdc shell bm get --udid

步骤 3：DevEco Studio 配置手动签名

1. 打开 DevEco Studio，进入 File > Project Structure > Project > Signing Configs；
   图 1-24 DevEco 手动配置签名界面（逐项填写签名文件信息）

2. 取消勾选Automatically generate signature；

3. 按下表逐项填写签名参数：

4. 点击Apply > OK保存配置，运行项目验证签名是否生效：
   图 1-25 手动签名验证成功（应用正常安装至真机）

核心提醒

1. .p12/.cer/.p7b 是应用签名的核心留存文件，需单独创建文件夹妥善保管，丢失会导致应用无法更新、上架，密码需单独记录；.csr 为申请凭证，申请到.cer 后可留存备用，丢失可随.p12 重新生成；
2. 调试/发布环境建议复用同一套签名文件，避免签名不一致导致应用无法覆盖安装，需重新安装并丢失用户数据；
3. 执行 HDC 命令若提示：[Fail]ExecuteCommand need connect-key? please confirm a device by help info，为多设备冲突问题：只保留一台真机连接，关闭所有模拟器；
4. 四个文件的应用包名、设备 UDID（调试版）信息必须完全一致，这是签名生效的关键，信息不匹配是真机调试失败的主要原因；
5. .p12 与.csr 强绑定，申请.cer 时必须上传对应.p12 生成的.csr，不可跨文件混用。

六、下节预告

本节完成了华为开发者账号注册与实名认证、DevEco 环境复用、自动/手动签名配置、真机调试环境搭建与问题排查，同时完整解析了.p12/.csr/.cer/.p7b 四大核心签名文件的作用、关联链路及实操要点，明确了工程配置文件与签名文件的配合要求，为后续开发筑牢前置基础。下一节将正式进入核心环节，讲解鸿蒙应用程序框架核心能力。