梳理完设计和生态规范，接下来就要进入正式的工程构建环节。本章中，我们将了解如何配置 DevEco Studio 环境，跑通签名与打包流程，并使用官方测试工具完成上架预检。

概括地说，在将源码变成可以安装的发布产物的过程中，需要经过编译、打包和签名等步骤。DevEco Studio 的构建系统 Hvigor 可以自动完成大部分工作，而你作为开发者需要做的，是提前准备好签名所需的材料，包括证书和 Profile 文件。

鸿蒙的签名机制、涉及的的文件和证书类型与其他平台存在一定差异，跨平台开发者要严格按照文档操作，不能直接照搬过往经验。下面，我们就走一遍完整的流程，从基础的环境配置开始，直到把你的应用送入测试通道。

DevEco Studio 环境配置与易错点

DevEco Studio 是鸿蒙官方的开发环境。从官方下载页获取最新稳定版，并按向导安装即可。HarmonyOS SDK 已嵌入 DevEco Studio 中，无需额外下载配置。

已预装的 SDK

值得注意，DevEco Studio 的大版本与 API Level 是强绑定的。例如要开发 API 12（HarmonyOS 5.0）的应用，必须使用 DevEco Studio 5.0 版本；如果错用旧版 IDE，将无法下载新版 SDK，反之亦可能产生兼容问题。

另外，工程文件夹中有两个与提交应用相关的配置文件需要分清。如下图所示，AppScope/app.json5 存放包名（bundleName）、版本信息（versionCode / versionName）以及应用图标等全局配置，是应用递交给 AppGallery Connect 的身份证；模块目录下的 entry/src/main/module.json5 存放权限声明、Ability 入口、目标 API 版本等模块级配置，系统会读取它来获取运行规约。

应用级配置与模块级配置所在的不同位置

签名：调试期自动，上架前手动

鸿蒙的签名体系分四层，即密钥（.p12）、证书请求（.csr）、数字证书（.cer）以及 Profile 文件（.p7b）。为了兼顾开发效率与发布安全，鸿蒙进一步区分了调试与发布两种场合，其签名流程有一定差异。

调试期：开启自动签名

在日常开发和设备调试阶段，你完全可以把繁琐的申请过程交给 IDE 的自动签名功能。如下图所示，在 File > Project Structure > Project > Signing Configs 中保持勾选 Automatically generate signature，DevEco Studio 就会自动生成密钥、请求证书，并向 AppGallery Connect 申请调试证书和 Profile 文件，然后将信息填回工程。

开启自动签名

自动签名顺利运行需要满足几个前提条件：

  • 系统时间已对齐北京时间；
  • IDE 已登录具备「APP 管理员」或更高权限的华为开发者账号；
  • 已连接真机或模拟器（系统需要获取设备信息以写入调试 Profile）；
  • 工程的 bundleName 已在 AppGallery Connect 中创建了对应的应用或元服务。

最后一点常常容易忽略。你需要前往 AppGallery Connect 控制台新建应用，如下图所示，将包名设置为与工程中的 bundleName 完全一致。未完成实名认证的开发者只能获取 14 天有效期的调试证书，实名后有效期为 180 天。因此，建议尽早完成实名认证。

在 AGC 创建应用，包名必须与本地工程完全一致

上架前：手动配置发布签名

调试期的包无法用来上架。准备打包正式发布版本时，必须手动申请并配置发布证书和发布 Profile。此时，你需要跟前面提到的四个核心文件打交道了。为了避免后续混乱，建议你先理清这四个文件的作用：

  • .p12 密钥库（Key Store）：在本地生成，包含用于签名的公私钥对。请妥善保管，不要泄漏。.p12 一旦丢失就无法找回，虽然存量用户可以继续更新（只要 APP ID 不变），但后续发版流程会变得非常麻烦；
  • .csr 证书请求文件（Certificate Signing Request）：由 DevEco Studio 从 .p12 中导出，包含公钥和开发者主体信息。它相当于一份递交给 AppGallery Connect 的身份申请表，可以安全地存放在工程目录中；
  • .cer 数字证书（Certificate）：AppGallery Connect 接收 .csr 后签发的文件，绑定了你的公钥和身份。实名认证开发者的发布证书有效期通常为 3 年。你应当在申请后下载并保存在本地；
  • .p7b Profile 文件：包含包名、关联证书、允许申请的 ACL 权限列表以及允许调试的设备列表（发布 Profile 此处为空）。同样从 AppGallery Connect 申请并下载。

获得这些文件的操作顺序是：

在 DevEco Studio 生成 .p12 和 .csr。选择菜单 Build > Generate Key and CSR（如下图所示）。创建 Key Store 时，密码需要包含大小写字母、数字、特殊符号中的至少两种，长度不小于 8 位。请务必记住密码和密钥别名（Alias），后续配置中需要用到。

在 DevEco Studio 中生成密钥与证书请求文件

在 AppGallery Connect 上传 .csr 申请 .cer。在 AppGallery Connect 首页选择「证书、APP ID 和 Profile > 证书」页面，点击「新增证书」，如下图所示，选择「发布证书」并上传刚才生成的 .csr 文件。提交后下载生成的 .cer 证书。实名认证开发者的发布证书有效期通常为 3 年。

上传 .csr 文件以申请发布证书

在 AppGallery Connect 申请 .p7b Profile。进入同级目录的「Profile」页签，点击「添加」，如下图，类型选择「发布」，关联刚刚申请的发布证书（发布类无需选择设备）。提交后下载 .p7b 文件。

申请发布 Profile 并关联对应的数字证书

在 DevEco Studio 配置签名。选择 File > Project Structure > Project > Signing Configs，取消勾选 Automatically generate signature，依次填入 Store file（.p12 路径）、Store password、Key alias、Key password、Profile file（.p7b 路径）和 Certpath file（.cer 路径）。签名算法（Sign alg）保持默认的 SHA256withECDSA。

配置完成后，工程根目录的 build-profile.json5 会生成对应的 signingConfigs 记录。如果团队协作开发，建议使用相对路径存放 .cer 和 .p7b 文件，并将 .p12 与密码通过加密团队密码箱管理，避免直接将其提交入代码仓库。

证书分类与配额

AppGallery Connect 控制台中提供了多种证书选项。对于大多数独立开发者和小团队而言，只需关注两类：

  • 调试证书（Debug）：日常开发测试使用，配套调试 Profile，且必须绑定具体的调试设备；
  • 发布证书（Release）：公开发布到华为应用市场使用，配套发布 Profile，不绑定设备。

其余的「企业应用发布证书」及「二进制证书」主要面向内部应用或鸿蒙 PC 端二进制程序分发。每类证书在云端都有配额限制。当配额占满时，你可以废弃旧证书，或者让同公司的多个应用共用同一张发布证书，只需为每个应用单独申请专属的 Profile 即可。

配置 SHA256 指纹

如果应用接入了华为账号登录、Push Kit、内购（IAP）等云侧服务，需要在 AppGallery Connect 的「项目设置 > 常规 > SHA256 证书 / 公钥指纹」中登记证书指纹（如下图）。AppGallery Connect 会自动根据上传的证书计算好，下拉勾选确认即可。指纹配置的生效可能会有延迟，如果急需验证可尝试修改 versionCode 触发即时生效。

配置证书的 SHA256 指纹

需要特别留意的是：调试证书和发布证书是两张不同的证书，它们的指纹需要分别配置。如果只配了调试证书的指纹，会导致本地测试账号登录正常，一旦打出发布包上线，线上环境就会直接报错。

ACL 受限权限申请

ACL（Access Control List）权限即「受限开放权限」，允许应用申请超出默认基础级别的能力，比如读取联系人、访问图库、系统悬浮窗等。如果你的应用功能涉及这类高敏感权限场景，就需要申请 ACL 权限。

对于需要 ACL 权限的应用，申请流程分为三步：

在 AppGallery Connect 提交申请。如下图所示，在「项目设置 > ACL 权限」中勾选所需权限并填写申请理由。填写的「使用场景」必须与实际表现一致，超范围使用会在审核阶段被驳回。权限审批通常需要 1 个工作日。

提交 ACL 权限申请时必须如实填写使用场景

将权限编入 Profile。审批通过后，在 AppGallery Connect 重新申请一份 Profile，此时需要在「申请权限」栏中勾选刚刚获批的 ACL 权限。如果 Profile 声明的权限没有覆盖代码中使用的范围，会导致签名失败或上架驳回。

在 module.json5 声明。在模块配置文件的 requestPermissions 数组中添加对应的权限名称，并写明 reason 字段。

为方便调试，DevEco Studio（4.0 Release 及以上）支持在自动签名阶段自动申请部分常用的 ACL 权限（例如通讯录、悬浮窗、图库读写等），如下图所示。另外，在你向云端提交 ACL 申请期间，AGC 页面可能会弹出一个有效期 5 天的「试用调试 Profile」入口，供你先在本地跑通流程。此入口通常只弹出一次，建议及时点开并保存。

IDE 自动签名已支持自动申请部分常用 ACL 权限

真实案例：避免滥用 ACL 权限

在少数派文章《鸿蒙，我的独家记忆》中，开发者分享了这样的踩坑经历：最初为了实现保存网络图片到相册的功能，开发者申请了读写图库的 ACL 权限。虽然在本地开发和测试阶段一切正常，但在正式提交上架审核时却遭到了无情驳回。审核团队给出的理由是：「申请的 ACL 权限不被允许，建议使用非权限的替代方案实现功能」。

最终，开发者采用鸿蒙原生的 SaveButton（保存控件）免权限方案重写了该功能，才顺利过审。这印证了鸿蒙应用上架审核的一条标准：如果有免权限的安全控件或系统接口（如 Picker、Button 等）能够实现同等功能，该项 ACL 权限的申请是很难通过的。

构建打包：将工程转换为发布包

签名的前期工作就绪后，就可以开始构建发布包了。

在这个环节，你需要明确产物的基本结构：一个模块（Module）对应一个 .hap 文件，而多个模块在向上架交付时会被统合打包成一个 .app 文件（即 Bundle）。尽管端侧分发和安装依然是以 HAP 为单位解压，但你向 AGC 上传的必须是 .app 包。

绝大多数独立开发者的工程只有一个 entry 模块，因此了解这层对应关系即可。

构建发布包

准备上架时，选择菜单栏的 Build > Build Hap(s)/APP(s) > Build APP(s) 选项。Hvigor 会在一轮构建中完成编译、打包和签名。

这里有一个易混淆的细节：日常调试常用的是 Build Hap(s)，该操作默认走 Debug 模式；而打包上架则必须点击 Build APP(s)，它会默认采用 Release 模式，并自动套用你刚刚配置的发布签名信息。如果顺手点击了前者或错把调试用的包上传至 AGC，系统会提示「正式版本应用不得使用 debug 签名」并退回。

真实案例：使用稳定版 SDK 构建提审版本

在少数派文章《GitHub 都没用明白，我这样用 Gemini 零起点开发应用》中，作者提到：如果你使用了 Beta 版的 DevEco Studio 或 Beta 版的系统 SDK 进行编译，它打包签名出来的 .app 同样是无法提交正式上架审核的。如果要打准备正式发版的包，请务必使用官方最新稳定版环境。

构建成功后，上架用的带签名 .app 文件会生成在工程下的 build > outputs > default 路径中。

HAP 与 APP 的常见构建产物

资产保护和代码混淆

构建发布包时，有一个保护代码资产的必备动作，那就是开启代码混淆。要知道，HAP 中的 resources.index 和资源目录是明文打包进去的，模块 ets 目录下除源码以外的文件也会被原样保留。因此，绝对不要将任何敏感的密钥或 Token 硬编码在 string.json 等资源文件中。

为了进一步提高安全性，建议在模块级的 build-profile.json5 中，将 obfuscation 配置块的 enable 设为 true。开启后，工具默认会执行推荐的属性名、顶层作用域名、文件和导出名称等混淆规则。

代码混淆有时会引发局部错误（比如 JSON 反序列化对象字段映射失败，或是动态 import 路径错误）。如果 Release 包运行时闪退，可以通过菜单 Tools > ObfuscationHelper 扫描源码并生成推荐的白名单（keep-list），如下图所示。将生成的规则配置在 files 字段下，再重新进行测试即可。

利用 ObfuscationHelper 工具生成混淆白名单

上传方式

打包完毕后，有两种方式将 .app 上传到 AppGallery Connect：

  1. IDE 内上传：如图所示，通过 Build > Upload Product 直接登录账号上传，支持选择「仅测试」或「测试并发布」，上传后可自动触发云端测试。
  2. 网页端手动上传：将生成的 .app 拿到 AppGallery Connect 控制台的版本发布页面手动上传。

需要重申的是，无论采用哪种方式，平台只接受通过 Release 签名的产物包。

测试与预检：根据场景选择工具

包打好了、也上传到了 AGC，是不是就可以直接点「提交审核」了呢？先别急。在真正把应用送上审核流水线之前，鸿蒙提供了多条测试与预检渠道供你把关。根据应用所处的开发阶段和测试目标，你可以灵活选择。

适配早期：云调试

云调试提供了远程的真机测试环境，支持截取屏幕和拉取运行日志。假设你在适配折叠屏或平板，但手边恰好没有对应的设备，云调试就是非常便利的工具。只需进入 AGC 的「质量 > 云调试」，上传应用包后即可在浏览器中操作远程设备。

云调试是一项免费服务，不过每次会话有 30 到 60 分钟的时间限制，适合用来做短期的功能确认，不太适合长时间的马拉松式测试。

提交审核前：上架预检与云测试并行

在应用基本完成开发，准备正式交卷之前，你应当做更为全面和仔细的测试。此时，DevEco Testing 的上架预检和 AGC 的云测试是两把互补的利器。

DevEco Testing 上架预检是一款本地客户端工具。它通过 USB 连接 HarmonyOS 5.0 以上的真机，运行兼容性、性能、稳定性、UX、功耗五大专项测试。如下方截图所示，建议你在本地用自己的手机跑一遍「综合预检」，将报告里可复现的问题优先解决掉。

使用 DevEco Testing 客户端在本地发起综合预检

AGC 云测试则是远程的自动化服务。你可以在控制台的「质量 > 云测试」中发起「上架测试」，系统会根据官方审核标准在多台热门机型上运行检查，并输出详细报告。它可以有效覆盖「部分机型概率性崩溃」这种你在本地单台设备上难以发现的碎片化缺陷。

AGC 云测试提供的详尽测试报告

邀请真人内测：三种分发渠道

机器查完，有时候还需要真人验证。对于开发过程中需要收集真实用户反馈的场景，鸿蒙提供了三个不公开上架的内测渠道：

  1. AppTest 邀请测试：最适合团队内部或早期小规模验证。测试包发布在单独的 AppTest 应用中，支持内部成员（上限 100 人）的极速审核机制，几十分钟即可分发；外部用户上限 1 万人。分享方式简单，直接将测试链接发给参与者即可。
  2. AppGallery 邀请测试：适合有一定规模忠实种子用户的场景。测试包发布在华为应用市场的「测试专区」中。用户数量上限 1 万人，参与者需要获取并输入邀请码才能下载。
  3. 公开测试：适合作为应用上架前的全网灰度测试。下载上限可达 1000 万次。

如果你只想发给特定个人的特殊场景，还可以选择指定设备发布。在打包时提前将特定设备（上限 100 台）的 UDID 写入 Profile 文件进行授权分发。每个账号每年有设备数量额度限制，且注册后一年内不回收名额。

除上述渠道外，还有针对企业的「定向应用发布」和「非公开发布」。这两种模式存在单向门槛（一旦切换不可逆转回公开发布），独立开发者通常无需涉及。

总结

到这一步，你已经跑通了能调试的工程，走完了手动配置发布签名和 Profile 的全部流程，用 Release 模式构建出了标准 .app 包，还借助官方提供的预检和内测渠道排查了暗雷。技术层面的交付物已然准备妥当。

不过，对于鸿蒙应用而言，这还只过了一半的关。下一章，我们将把视线从代码和命令行移开，去直面一系列不可跳过的行政流程：实名认证、APP 备案以及资质证明。这些流程往往需要几周的周期，提前了解并并行推进，才能让你的上架之路有条不紊。

延伸阅读：