工程、签名与发布

一个鸿蒙应用从「新建工程」到「商店上架」的完整链路。工具链与 Android 差异很大：构建系统是 hvigor（非 Gradle），IDE 是 DevEco Studio，分发与签名绑定 AppGallery Connect（AGC）。示例语境：HarmonyOS NEXT / DevEco Studio 稳定线，需在实际环境验证。

工程结构速览

新建工程默认结构（以 entry 模块为例）：

AppScope/
  app.json5                # 应用级配置（bundleName、版本）
entry/
  src/main/
    module.json5           # 模块配置（abilities、权限等）
    ets/                   # ArkTS 源码
      entryability/        # 每个 UIAbility 一个目录
      pages/               # 页面组件
    resources/
      base/element/        # 颜色、字符串等资源
      base/media/          # 图片资源
      base/profile/        # main_pages.json 等
    ohosTest/              # 测试代码
  build-profile.json5      # 模块签名/构建配置
  oh-package.json5         # 依赖声明
  hvigorfile.ts            # hvigor 构建脚本
hvigorfile.ts              # 工程级构建脚本

工程配置横跨三份 JSON5：app.json5（应用）→ module.json5（模块/组件）→ build-profile.json5（构建/签名），改配置别只改 UI 代码；
依赖管理：oh-package.json5 + ohpm（鸿蒙包管理器），三方库来自 OpenHarmony 三方库中心或本地 har；
页面清单：resources/base/profile/main_pages.json 登记 @Entry 页面，新增页面要同步登记。

包类型：HAP / HAR / HSP

包	全称	用途	关键点
HAP	Harmony Ability Package	可安装的 Ability 包	一个应用可含多个 HAP（含 App 内 HAP），发布打包成 `.app`
HAR	Harmony Archive	静态共享库	代码+资源在编译期打进去，无法独立发布更新
HSP	Harmony Shared Package	动态共享库	运行期共享、支持独立更新，适合多模块抽公共能力

工程内复用逻辑先考虑拆 HAR/HSP，避免「大仓一个模块 + 复制粘贴」两个极端；模块边界要同时考虑编译依赖与更新粒度。

签名与上架（AGC 链路）

注册与建应用：AGC 创建应用，取得包名（bundleName 全局唯一）与 appId；
证书与 Profile：调试用自动签名（DevEco 登录后自动处理）；发布需在 AGC 生成发布证书（.cer/.p7b）并创建 Profile，配置到 build-profile.json5 的 signingConfigs；
打发布包：hvigor 打包出 .app/.hap；
上传与发布：AGC 上传构建，先走内测分发（定向用户）验证，再正式提交审核；商店审核关注权限声明、隐私合规与内容规范；
升级与灰度：发布后版本升级、灰度发布、回滚都回到 AGC 操作台管理。

签名与密钥纪律：证书私钥与 Profile 不入库、不下发，泄露等于把应用身份交给别人；CI 里用密码管理器/环境变量注入，构建产物不进 git。

测试与性能工具

单元/UI 测试：工程模板自带 ohosTest，可跑本地测试；集成到流水线用 hvigor 的 test 任务；
真机与预览：Previewer 快速看布局；真机联调用 DevEco 内置工具与 hdc（鸿蒙设备连接命令行，类似 adb）——hdc list targets、hdc install、日志抓取等；
性能分析：DevEco Profiler 看 CPU/内存/能耗；ArkUI Inspector 检查布局层级与属性；帧率与丢帧用性能打点定位卡顿；
稳定性基线：与性能与稳定性一致——先建立启动耗时、帧率、崩溃率基线，再谈优化。

常见坑速查

坑	现象	解法
新增页面不显示	路由 404	登记 `main_pages.json`
bundleName 撞名	安装/上架失败	AGC 唯一包名，改一处同步三份 json5
签名配置缺	真机装不上/报签名错误	检查 build-profile signingConfigs + Profile
HAR 改了不生效	依赖方还是旧行为	确认包引用方式与同步策略
把密钥提交进仓库	泄露风险	密钥管理走环境变量/密码库，CI 注入
内存泄漏排查无抓手	页面切换内存涨	Profiler + Inspector 逐屏定位

检查清单

[ ] 三份 json5（app/module/build-profile）与配置一致，页面均已登记；
[ ] 模块边界清晰：HAR/HSP 划分符合更新粒度与编译依赖；
[ ] 签名/Profile 使用与保管符合规范，敏感物不进仓库；
[ ] 上架前走完内测分发，权限与隐私声明与实际调用一致；
[ ] 有启动/帧率/崩溃基线，发布前对关键路径做过性能与稳定性回归。

工程、签名与发布 ​

工程结构速览 ​

包类型：HAP / HAR / HSP ​

签名与上架（AGC 链路） ​

测试与性能工具 ​

常见坑速查 ​

检查清单 ​

工程、签名与发布

工程结构速览

包类型：HAP / HAR / HSP

签名与上架（AGC 链路）

测试与性能工具

常见坑速查

检查清单