欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
前言
在鸿蒙应用开发的工程化实践中，应用签名配置是连接本地开发与云端发布的关键桥梁，也是初学者最容易陷入“报错循环”的环节。无论是模拟器正式打包、真机稳定运行，还是上架华为应用市场，一套完整、规范、合法的签名体系都是必不可少的前提。任何一个文件选错、密码输错、路径包含中文，都可能导致项目构建失败、应用闪退、无法安装，甚至让整个项目无法交付。
本篇教程以 KuiklyUI 鸿蒙轻量级组件库 为全新案例，全程基于最新版 DevEco Studio 与华为 AppGallery Connect（AGC）控制台操作，不依赖命令行、不涉及复杂底层原理，从本地密钥生成、云端证书申请、应用绑定、Profile 配置文件下载，到 DevEco 内签名配置、项目构建、模拟器运行，进行逐按钮、逐输入框、逐界面、逐注意事项的超详细讲解。
前置要求：
✅ DevEco Studio 5.0+

✅ 没有账号，及时注册（已注册 AppGallery Connect 账号，可以跳过）

✅ 项目已通过本地编译（ohpm install 无报错）
✅下载SDK

首先打开文件OHOSAPP

构建成功的标志2.1 生成 .p12 密钥库文件（全新操作流程）•输出：KuiklyUI_Key.p12（本地加密密钥库，签名核心载体）•注意：路径必须纯英文，密码必须记录，别名必须唯一在开始生成签名文件之前，我们首先确保电脑上的 DevEco Studio 已经正常打开，并且 KuiklyUI 项目已经完全加载完成。打开项目后，先观察左侧工程目录，确保 entry 模块、oh_modules 依赖文件夹、资源文件夹全部正常显示，没有出现红色波浪线、红色文件名、红色报错标识。如果此时项目还有语法错误、资源缺失、依赖同步失败的问题，必须先修复完成，再进行签名文件生成，否则会导致文件生成失败、配置读取异常等额外问题。确认项目状态正常后，我们将目光移至 DevEco Studio 软件最顶部的全局菜单栏，在菜单栏中找到 Build 选项，将鼠标指针缓慢移动到 Build 文字上方，单击左键，此时会展开一个长长的下拉菜单列表，里面包含构建项目、清理项目、生成签名文件、打包 HAP 等一系列功能。在展开的 Build 下拉菜单中，我们找到 Generate Key and CSR 这一选项，它的位置通常在菜单中间偏下部分，找到后，单击鼠标左键，进入官方密钥与证书请求文件的生成向导界面。这个功能是鸿蒙 IDE 自带的标准工具，不需要使用 keytool 第三方命令，不需要配置环境变量，安全性高、操作简单、不易出错，是所有鸿蒙开发者生成 p12 与 csr 文件的标准入口。
进入生成界面后，你会看到一个初始的窗口，上方有 Key Store 信息区域，默认是空白的，没有任何文件路径。因为我们是第一次生成签名文件，所以需要全新创建一个密钥库文件，也就是我们常说的 .p12 文件，这是整个签名体系的核心文件，一定要保管好，丢失后无法找回，已发布的应用将无法更新。
在当前窗口中，找到 New 按钮，位置在 Key Store 输入框的右侧，点击 New，点击后会立刻弹出一个名为 Create Key Store 的新弹窗，这个窗口用于创建全新的 p12 密钥库文件，是我们第一步要生成的文件。


在弹出的 Create Key Store 弹窗中，第一行是密钥库文件的保存路径，后面有一个文件夹样式的图标，我们需要点击这个文件夹图标，打开电脑目录选择器，选择一个位置来存放我们即将生成的 p12 文件。
这里有一个超级重要的注意事项，新手90%报错都源于这里：你选择的保存路径必须全部是英文，不能出现任何中文、空格、特殊符号、标点符号，例如 D:\Dev\KuiklyUI\Sign\ 这种路径是正确的，D:\我的项目\签名文件\ 这种路径是错误的，一旦路径包含中文，后续生成文件、配置签名、构建项目一定会报错，且无法修复，只能重新生成。
点击文件夹图标后，在电脑中新建一个专门存放签名的文件夹，命名为 KuiklyUI_Sign，进入文件夹，在文件名输入框中输入 KuiklyUI_Key.p12，后缀必须是 .p12，不能写错，然后点击右下角的 保存 按钮，回到 Create Key Store 弹窗界面。

一定要把CSR和.P12的文件在不同的文件中保存，不要学我，保存在同一个文件中，一定要分开，一点要分开，一定要分开
回到创建窗口后，我们开始填写所有必填信息，每一项都要认真填写，不能留空，否则无法点击下一步：
第一项：Password，密钥库密码，自己设置一个密码，建议包含字母+数字，长度≥6位，一定要记住这个密码，后续每一步都要用到，忘记密码文件直接作废。
第二项：Confirm，确认密码，和上面输入的密码完全一致，再次输入一遍，确保两次输入相同，避免输错。
第三项：Alias，密钥别名，这个名称是后续签名配置中必须填写的内容，本次项目我们统一填写 kuiklyui_key，你也可以自定义英文名称，但是不能用中文，不能有空格，记住这个别名，后续配置会反复用到。
第四项：Password，密钥密码，这一项可以和最上方的密钥库密码填写一样的内容，方便记忆，减少密码数量，避免忘记，同样需要牢记。
第五项：Confirm，确认密钥密码，和上一行保持一致即可。
所有信息填写完成后，仔细检查一遍，确保没有空白项，密码一致，别名正确，路径无中文，确认无误后，点击窗口右下角的 OK 按钮，完成 p12 文件的创建，回到上一级 Generate Key and CSR 窗口。

2.2 生成 .csr 证书请求文件（全新操作流程）
•复用 KuiklyUI_Key.p12 文件路径与密码
•输出：KuiklyUI_Request.csr（用于 AGC 申请证书，不可跳过）
回到上级窗口后，你会发现 Key Store 路径已经自动填充为我们刚刚保存的 KuiklyUI_Key.p12 文件路径，密码也自动填充，这说明 p12 文件创建成功。接下来我们进行 csr 文件的生成，csr 文件是证书请求文件，用于上传到华为 AGC 平台申请官方证书，是连接本地文件与云端证书的核心文件。
在当前窗口中，找到 CSR File 输入框，右侧同样有一个文件夹图标，点击这个图标，打开保存路径选择器，强烈建议将 csr 文件保存在和 p12 文件完全相同的文件夹中，方便后续查找、使用、整理，不要随意存放在桌面或其他杂乱位置。
点击文件夹图标后，选择我们之前创建的 KuiklyUI_Sign 文件夹，文件名填写 KuiklyUI_Request.csr，后缀必须是 .csr，不能修改，点击保存，回到生成窗口。

此时，整个 Generate Key and CSR 窗口所有内容都已填写完成，Key Store 路径正确，密码正确，CSR 路径正确，文件名正确，检查无误后，点击窗口右下角的 Finish 按钮，等待系统自动生成文件。
系统生成过程只需要几秒，生成完成后窗口会自动关闭，没有其他提示，代表生成成功。
执行完以上步骤后我们打开存放文件的 KuiklyUI_Sign 文件夹，此时文件夹中必须出现两个文件：
第一个：KuiklyUI_Key.p12 （密钥库文件）
第二个：KuiklyUI_Request.csr （证书请求文件）
这两个文件是后续所有操作的基础，缺一不可，必须同时存在。如果你的文件夹里只有一个文件，或者一个都没有，说明前面的步骤出现错误，可能是路径包含中文、信息未填完、点击错误，必须删除错误文件，重新从 New 开始创建，直到文件夹中同时出现这两个文件为止，否则后续流程完全无法进行。

2.3 在 AGC 生成 .cer 证书（全新操作流程）
1.访问 AGC 控制台 → 项目设置 → 证书管理 → 新增证书
2.证书类型：发布证书（调试证书无法用于正式打包与真机稳定运行）
3.上传 KuiklyUI_Request.csr → 下载 KuiklyUI_Cert.cer
首先，打开电脑浏览器，搜索 AppGallery Connect，进入华为开发者官方控制台，也就是我们常说的 AGC 平台。如果你还没有 AGC 账号，点击页面上的蓝色注册文字，使用手机号完成注册、实名认证，实名认证是必须的步骤，没有实名认证无法创建证书、无法创建应用、无法进行任何发布相关操作。

登录成功后，进入 AGC 控制台首页，在页面中找到我的项目，如果是第一次使用，先创建一个新项目，项目名称可以填写 KuiklyUI，和我们的应用名称保持一致，方便管理。项目创建完成后，进入项目详情页面，在左侧菜单栏中找到 项目设置 选项，点击进入项目设置页面。
在项目设置页面中，找到顶部的标签栏，在标签中找到 证书管理 标签页，点击切换到证书管理界面，这里是管理所有鸿蒙应用证书的地方，我们需要在这里上传本地生成的 csr 文件，生成官方的 cer 证书。


在证书管理页面中，找到右上角的 添加证书 按钮，点击按钮，弹出新增证书窗口，开始创建我们 KuiklyUI 项目对应的证书。
在新增证书窗口中，首先填写证书名称，为了方便识别，我们填写 KuiklyUI_Cert，和之前的别名保持一致。然后选择证书类型，这里有两个选项：调试证书和发布证书。重点注意：我们必须选择「发布证书」，调试证书权限受限，无法完成完整打包，也会出现各种兼容报错，只有发布证书可以用于完整的签名配置、真机运行、应用打包，新手千万不要选错，选错只能删除重新创建。
接下来是最关键的一步：上传 CSR 文件。点击上传文件按钮，选择我们之前在 DevEco 中生成的 KuiklyUI_Request.csr 文件，注意是 csr 后缀，不是 p12 文件，很多新手在这里传错文件，导致后续证书无效，一定要仔细区分文件后缀。
文件上传完成后，窗口会显示文件名称，确认是 KuiklyUI_Request.csr 后，点击 提交 按钮，系统会自动根据我们上传的请求文件生成证书，生成过程秒完成，无需等待。

提交成功后，证书会自动出现在证书管理列表中，状态显示为正常，在列表右侧操作栏中，有一个 下载 按钮，点击下载按钮，将生成的 KuiklyUI_Cert.cer 证书文件下载到本地，同样保存到 KuiklyUI_Sign 文件夹中，和 p12、csr 放在一起。
下载完成后，再次打开我们的签名文件夹，此时文件夹中已经有三个核心文件：
4.KuiklyUI_Key.p12
5.KuiklyUI_Request.csr
6.KuiklyUI_Cert.cer
三个文件全部齐全，代表证书申请与下载流程完成，缺少任何一个文件，都无法进行下一步的 Profile 文件生成，新手在这里一定要核对文件数量与后缀，不要下载错误、放错位置。

2.4 生成 .p7b 配置文件（全新操作流程）

2.4.1 创建 APP ID（全新操作流程）
•包名来源：module.json5 / app.json5 中的 bundleName
•包名必须全局唯一，不能与其他应用重复
•本次 KuiklyUI 包名：com.kuikly.ui.demo.app
回到 AGC 控制台，在左侧菜单栏中找到 应用 选项，点击进入应用管理页面，然后点击 创建应用 按钮，开始创建和我们 KuiklyUI 项目对应的应用信息，这一步用于绑定证书与应用，生成最终的签名配置文件。
在创建应用页面中，依次填写以下信息：
•应用名称：KuiklyUI
•设备类型：勾选 手机
•操作系统：选择 HarmonyOS
•包名：这是最核心的一项，必须和 DevEco Studio 项目中的 bundleName 完全一模一样，一个字符都不能差
包名的获取位置：回到 DevEco，打开项目中的 entry/src/main/module.json5 文件，在文件中找到 bundleName 字段，后面的字符串就是包名，直接复制这段内容，粘贴到 AGC 创建应用的包名输入框中，千万不要手动打字输入，非常容易输错，复制粘贴是最安全的方式。
包名是应用的唯一标识，一旦创建无法修改，如果 AGC 中的包名和 DevEco 中的包名不一致，后续配置签名一定会报错，且无法修复，这是新手第二大高频报错原因，必须严格核对。
所有信息填写完成后，点击创建按钮，应用创建成功，系统会自动分配唯一的 APP ID，记录下这个 APP ID，后续绑定 Profile 时会用到。


我们暂时不需要这些功能的帮助，所以我们划到底，去点击确认
2.4.2 创建发布 Profile（全新操作流程）
•Profile 类型：应用发布
•关联证书：选择 3.3 步骤下载的 KuiklyUI_Cert 证书
•绑定应用：选择刚才创建的 KuiklyUI 应用
•下载 KuiklyUI_Profile.p7b 配置文件
应用创建完成后，回到 AGC 控制台左侧菜单，找到 Profile 选项，点击进入 Profile 管理页面，Profile 文件是 DevEco 中直接使用的签名配置文件，后缀为 .p7b，是整个签名流程的最后一个云端文件。
点击页面中的 新建 Profile 按钮，开始创建配置文件：
第一步，填写 Profile 名称，填写 KuiklyUI_Profile，方便识别；
第二步，选择 Profile 类型，选择 应用发布，和证书类型保持一致；
第三步，关联证书，在下拉列表中找到我们之前创建并下载的 KuiklyUI_Cert 证书，选中它；
第四步，绑定应用，在应用列表中找到刚刚创建的 KuiklyUI 应用，勾选绑定。
所有选项设置完成后，仔细检查：证书正确、应用正确、类型正确，确认无误后，点击 创建 按钮，Profile 创建完成。
创建完成后，在 Profile 列表右侧操作栏中，点击 下载 按钮，将 KuiklyUI_Profile.p7b 配置文件下载到本地，依旧保存到 KuiklyUI_Sign 文件夹中，和前面三个文件放在一起。

下载完成后，打开我们的签名文件夹，此时文件夹中四个核心签名文件全部齐全，这是完整签名配置所需要的全部文件，一个不多，一个不少：
7.KuiklyUI_Key.p12 （本地密钥库）
8.KuiklyUI_Request.csr （证书请求文件）
9.KuiklyUI_Cert.cer （云端证书）
10.KuiklyUI_Profile.p7b （签名配置文件）
至此，云端所有操作全部完成，接下来我们回到 DevEco Studio，进行最后一步：将所有签名文件配置到项目中，彻底解决所有签名报错。

2.5 回到 DevEco 配置签名（最关键、最容易错步骤）
打开 DevEco Studio 中的 KuiklyUI 项目，在软件顶部菜单栏中，依次点击 File → Project Structure，打开项目结构配置窗口，这是配置项目签名、模块、SDK 的核心入口。
打开窗口后，在左侧列表中找到 Modules 选项，点击展开，在右侧找到我们的主模块 entry，选中 entry 模块，然后在窗口上方的标签栏中，找到并切换到 Signing 签名配置标签页，这就是我们之前报错弹出的页面，也是最终解决 key alias not found、无法创建 profile 的地方。

进入 Signing 页面后，我们按照从上到下的顺序，依次填写所有内容，每一项都严格对应我们生成的文件与密码，不能出现任何错误：
第一项：Provisioning Profile，点击右侧文件夹图标，选择我们从 AGC 下载的 KuiklyUI_Profile.p7b 文件，这是签名配置的核心文件，必须选择正确。
第二项：Store file (*.p12)，点击文件夹图标，选择我们本地生成的 KuiklyUI_Key.p12 文件，路径同样无中文。
第三项：Store password，输入我们最开始创建 p12 文件时设置的密钥库密码，必须和当时填写的完全一致，区分大小写。
第四项：Key alias，输入我们创建 p12 时填写的别名 kuiklyui_key，必须完全一致，这就是解决 key alias not found 报错的核心，之前报错就是因为别名填了 debugKey，而我们的文件里没有这个别名，现在填写自己创建的真实别名，就不会报错。
第五项：Key password，输入创建 p12 时设置的密钥密码，和之前保持一致。
所有内容填写完成后，再次逐行检查一遍：
•p7b 文件路径正确
•p12 文件路径正确
•两个密码都正确
•别名是自己创建的 kuiklyui_key
•所有路径都没有中文
确认没有任何错误后，先点击窗口右下角的 Apply 按钮，应用配置，然后点击 OK 按钮关闭窗口。
关闭窗口后，DevEco 会自动触发项目同步，等待右上角同步进度条完成，不要中途取消，同步完成代表签名配置已经生效。


运行前一定要改关系

从这样改为这样

这两个命令都需要依次执行，具体操作步骤如下：
首先在终端或命令行界面输入第一个命令，按回车键执行
等待第一个命令完全执行完成（通常会有执行进度提示或完成状态显示）
确认第一个命令执行成功后，再输入第二个命令
按回车键执行第二个命令

2.6 验证配置是否成功，构建项目测试
配置完成后，我们进行最终验证，测试是否还会出现签名报错。
第一步，点击软件右上角 Sync Project 按钮，手动强制执行一次完整同步，确保所有配置都被系统加载。
第二步，在顶部菜单栏点击 Build → Build Hap(s)，开始构建项目，生成 HAP 安装包。
此时观察底部控制台输出，如果控制台最终显示：

hvigor BUILD SUCCESSFUL in xxx ms
Process finished with exit code 0
代表签名配置完全成功，之前所有的：
•Unable to create the profile
•key alias not found
•SignHap 执行失败
•hvigor ERROR 构建失败
所有报错全部消失，项目可以正常构建、打包、运行。

2.7 启动模拟器，运行 KuiklyUI 应用
签名配置完成后，我们启动 DevEco 自带的手机模拟器，在顶部设备选择栏中选择已经启动的手机模拟器，点击绿色运行按钮，系统会自动构建、安装、启动 KuiklyUI 应用。
应用在模拟器中正常打开，界面、文字、图片、布局、样式全部正常显示，无闪退、无黑屏、无弹窗、无报错、无异常退出，代表从本地文件生成 → 云端证书申请 → 应用绑定 → Profile 下载 → DevEco 配置 → 项目构建 → 模拟器运行，整个流程全部完美完成、无任何问题。


这里面的手机都可以选，我选的是最贵的！！!

2.8 新手最常见 8 大签名错误与解决方法（超详细版）
错误1：key alias not found（别名不存在）
原因：填写了系统默认的 debugKey，而自己的 p12 文件里没有这个别名，别名不匹配、大小写不一致、拼写错误。
解决：删除默认别名，填写自己创建 p12 时的真实别名 kuiklyui_key，使用自己生成的文件，不使用系统默认值，严格核对大小写与字符。
错误2：无法创建 Provisioning Profile
原因：未连接真机，系统试图自动生成调试签名；或未手动配置 p7b 文件，依赖自动生成失败。
解决：按照本教程手动配置完整签名文件，不使用自动生成，直接填写 p7b、p12、密码、别名，关闭自动签名尝试。
错误3：Store file 路径包含中文
原因：p12、p7b 存放在中文名称的文件夹中，系统无法解析路径编码，导致文件加载失败。
解决：将所有签名文件移动到纯英文路径，重新选择文件路径，重新配置，重启 IDE 后再次构建。
错误4：AGC 包名与 DevEco 包名不一致
原因：手动输入包名出现错别字、漏字、多字、符号错误、大小写不一致，两端不匹配。
解决：从 module.json5 中复制 bundleName，粘贴到 AGC，不手动打字，严格保持完全一致。
错误5：密码错误，无法加载密钥库
原因：输入的密码和创建 p12 时的密码不一致，忘记密码、输错大小写、符号顺序错误。
解决：重新创建 p12 文件，记录新密码，重新走全套流程，不使用遗忘密码的旧文件。
错误6：上传了错误的文件（传 p12 代替 csr）
原因：在 AGC 上传证书时，误上传 p12 文件，而非 csr 文件，系统无法解析请求格式。
解决：删除错误证书，重新上传正确的 csr 文件，下载新的 cer 证书，重新生成 Profile。
错误7：Profile 关联错误证书
原因：创建 Profile 时，选择了其他项目的证书，和当前 p12、csr 不匹配，导致签名链断裂。
解决：删除错误 Profile，重新创建，关联自己生成的 KuiklyUI_Cert 证书，绑定对应应用。
错误8：构建成功，但安装失败/闪退
原因：签名文件配置不完整、模拟器版本过低、包名冲突、资源缺失、代码异常。
解决：重启模拟器，重新构建，确认四个签名文件齐全，检查项目代码与资源，清理项目缓存。
三.完整流程总结（超详细总结版）
整个 KuiklyUI 签名流程，一共分为五大核心步骤，一环扣一环，不可跳过、不可颠倒、不可省略、不可随意修改：
1…本地文件生成：DevEco 中生成 KuiklyUI_Key.p12 密钥库文件与 KuiklyUI_Request.csr 证书请求文件，路径纯英文、信息完整、密码一致、别名规范。
2.云端证书申请：AGC 平台上传 csr，生成并下载 KuiklyUI_Cert.cer 官方证书，选择发布证书，不使用调试证书。
3.应用绑定创建：AGC 平台创建应用，填写与项目完全一致的包名，生成唯一 APP ID，实现证书与应用绑定。
4.配置文件生成：AGC 平台创建 Profile，关联证书、绑定应用，下载 KuiklyUI_Profile.p7b 最终配置文件。
5.本地 IDE 配置：DevEco 中配置 p7b、p12、密码、别名，完成全量签名配置，实现项目正常构建与运行。
按照本教程的步骤，严格执行、不跳步、不瞎改、不填错、不混用文件，任何零基础新手都可以一次性完成签名配置，彻底解决鸿蒙开发中所有签名类报错、构建类报错、运行类报错，实现项目正常构建、模拟器运行、真机安装、HAP 打包全功能可用。
对于 KuiklyUI 项目来说，签名配置完成后，应用不再受限于调试模式、临时签名、自动签名，具备完整的发布级签名能力，可用于功能测试、界面演示、课程作业、项目提交、比赛展示、学习记录等所有场景，是从入门级 Demo 走向规范化、工程化、可交付项目的关键一步。
未来再遇到任何签名弹窗、红色报错、构建失败，不要慌张、不要乱填信息、不要随意删除文件，只需要按照本教程的流程，检查文件、路径、密码、别名、包名五个核心点，99% 的问题都可以快速定位、快速解决、快速恢复正常。
至此，KuiklyUI 鸿蒙应用签名全流程，从原理、操作、配置、排错、验证到总结，全部完整、详细、无跳步、无省略讲解完毕，全程可复现、可验证、可直接用于学习、笔记、长图制作、作业提交、项目交付。