HarmonyOS APP《画伴梦工厂》开发第50篇-从项目到生态——鸿蒙应用上架与持续演进

言程序plus

17人浏览 · 2026-07-07 14:36:39

言程序plus 鸿蒙领航者 · 2026-07-07 14:36:39 发布

第6.8篇：从项目到生态——鸿蒙应用上架与持续演进

难度：⭐⭐ 进阶
前置知识：无
涉及源文件：AppScope/app.json5、build-profile.json5、oh-package.json5、products/default/src/main/module.json5

概述

从一行行代码到最终出现在用户手机上的应用，中间要经历配置、构建、测试、签名、上架等一系列环节。这不仅是对代码质量的考验，更是对工程化能力的综合检验。

"画伴梦工厂"作为一个完整的鸿蒙应用，从开发环境到 AppGallery Connect 上架，涉及了整个鸿蒙生态的工具链。本文将从 AppScope 全局配置出发，逐步拆解 HAP 打包、DevEco Testing 测试框架、AppGallery Connect 发布流程，以及版本迭代策略和持续演进的最佳实践。

一、AppScope：应用全局配置

鸿蒙应用工程的根目录下有一个特殊的目录——AppScope，它存放着整个应用的元信息。其中最重要的文件是 app.json5，它定义了应用的全局属性，所有 HAP（Harmony Ability Package）共享这份配置。

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

bundleName —— 应用的唯一身份标识

bundleName 相当于应用的身份证号，在鸿蒙生态中全局唯一。命名规则遵循反向域名风格（Reverse Domain Name），例如 com.example.drawing。一旦应用在 AppGallery Connect 上创建并关联了 bundleName，后续版本不得修改——这一点与 Android 的 packageName 类似，但鸿蒙对其管理更为严格。

vendor —— 开发者的品牌标识

vendor 字段填写开发者或组织名称，用于在应用市场中展示。例如 “example” 可以替换为实际的公司名称。

icon 与 label —— 应用的第一印象

应用图标和名称通过资源引用方式声明：

$media:layered_image —— 引用 resources/base/media/ 目录下的图标资源。鸿蒙支持分层图标（Layered Image），允许将前景和背景分开设计，在系统中自适应圆形遮罩。
$string:app_name —— 引用 resources/element/string.json 中的多语言字符串，确保应用名称在不同语言环境下正确显示。

二、版本管理：versionCode 与 versionName

版本号是上架流程中最不容忽视的细节。在 app.json5 中，版本通过两个字段协同定义：

versionCode

versionCode 是一个整数，用于系统内部判断版本新旧。每次发版必须递增。

在"画伴梦工厂"中，初始值为 1000000。
推荐格式：主版本 * 100000 + 次版本 * 1000 + 补丁版本。
1.0.0 → 1000000
1.1.0 → 1001000
1.1.1 → 1001001
2.0.0 → 2000000

这种编码方式的优势在于：升级判定简单直观，且能保证单调递增。

versionName

versionName 是展示给用户看的字符串，如 "1.0.0"。它遵循语义化版本规范（SemVer）：主版本.次版本.补丁。

版本类型	versionCode	versionName	升级场景
初始发布	1000000	1.0.0	首次上架
小功能迭代	1001000	1.1.0	新增语音识别、相册采集
问题修复	1001001	1.1.1	修复崩溃、UI 适配问题
重大更新	2000000	2.0.0	架构重构、新能力集加入

三、build-profile.json5：构建配置全景

项目的构建行为由 build-profile.json5 文件控制。根目录下的文件定义了应用的全局构建配置：

{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "type": "HarmonyOS",
        "material": {
          "certpath": "xxx.cer",
          "keyAlias": "debugKey",
          "keyPassword": "***",
          "profile": "xxx.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "xxx.p12",
          "storePassword": "***"
        }
      }
    ],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "targetSdkVersion": "6.0.0(20)",
        "compatibleSdkVersion": "6.0.0(20)",
        "runtimeOS": "HarmonyOS"
      }
    ],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [
    { "name": "default", "srcPath": "./products/default", "targets": [...] },
    { "name": "common", "srcPath": "./common", "targets": [...] },
    { "name": "adaptiveLayout", "srcPath": "./features/adaptiveLayout", "targets": [...] },
    { "name": "responsiveLayout", "srcPath": "./features/responsiveLayout", "targets": [...] }
  ]
}

signingConfigs —— 签名配置

上架到 AppGallery Connect 的应用必须经过签名。签名材料包括：

要素	说明
证书文件 (.cer)	开发者身份凭证，通过 DevEco Studio 或 AppGallery Connect 生成
Profile 文件 (.p7b)	分发描述文件，包含应用的权限范围和设备限制
密钥库 (.p12)	包含私钥，用于代码签名
签名算法	推荐 `SHA256withECDSA`，确保签名安全性

调试阶段 DevEco Studio 会自动生成调试证书；发布阶段需通过 AppGallery Connect 申请发布证书。

buildModeSet —— 构建模式

debug：用于开发调试，包含调试符号，不混淆代码。
release：用于发布上架，开启代码混淆和优化。

在 products/default/build-profile.json5 中，release 模式还可以配置代码混淆规则：

"buildOptionSet": [
  {
    "name": "release",
    "arkOptions": {
      "obfuscation": {
        "ruleOptions": {
          "enable": false,
          "files": ["./obfuscation-rules.txt"]
        }
      }
    }
  }
]

代码混淆可以有效保护应用逻辑不被逆向分析，建议在 release 构建中启用。

四、HAP 打包与 HAG 发布

HAP 是什么？

HAP（Harmony Ability Package）是鸿蒙应用的部署单元。每个 HAP 包含一个模块的所有代码、资源和配置文件。

"画伴梦工厂"的模块结构产生了多个 HAP：

模块	HAP 名称	用途
`products/default`	`entry.hap`	主入口模块，包含 UI 页面和 Ability
`common`	`common.hap`	共享工具库
`features/adaptiveLayout`	`adaptiveLayout.hap`	自适应布局能力
`features/responsiveLayout`	`responsiveLayout.hap`	响应式布局能力

打包流程

在 DevEco Studio 中构建 HAP 的流程如下：

代码编译：ArkTS 源码经 ArkCompiler 编译为方舟字节码。
资源聚合：收集各模块的资源文件（图片、字符串、配置文件）。
签名：使用 signingConfigs 中的证书和 Profile 对 HAP 签名。
生成 HAP：输出到 build/outputs/default/ 目录。

HAG —— 鸿蒙应用包

HAG（HarmonyOS App Package）是用于上架的分发格式，它将一个或多个 HAP 打包成单个文件，后缀名为 .app。

在 DevEco Studio 中，通过 Build → Build HAP(s) / APP(s) 即可同时生成 HAP 和 APP 包。生成的 APP 包位于 build/outputs/app/ 目录下，这就是最终要上传到 AppGallery Connect 的文件。

五、AppGallery Connect 上架流程

当 APP 包构建完成后，下一步就是通过 AppGallery Connect 将应用推向市场。

前提条件

注册华为开发者账号，并通过实名认证。
在 AppGallery Connect 创建应用，填写应用名称、分类、描述等信息。
生成发布证书和 Profile：在 AppGallery Connect 的"用户与访问"中创建发布证书，下载到本地。

上架步骤

步骤一：创建应用

应用名称（对应 $string:app_name）
包名（对应 bundleName: "com.example.drawing"）
应用分类（如"教育"或"娱乐"）

步骤二：上传 APP 包

在"应用信息 → 版本信息"页面上传 .app 文件。系统会自动解析：

versionCode 和 versionName
支持的设备类型（phone、tablet、2in1）
权限声明列表

步骤三：填写应用详情

应用图标（96×96 和 144×144 两套）
应用截图（至少 2 张，建议涵盖主要功能页面）
应用描述（中英文各一份）
隐私政策链接

步骤四：提交审核

提交后 AppGallery Connect 会进行自动化审核和人工审核，通常需要 1~3 个工作日。

审核常见问题

问题类型	常见原因	解决方案
权限声明不完整	使用 `CAMERA` 权限但未说明使用场景	在 `module.json5` 中完整填写 `usedScene` 和 `reason`
隐私政策缺失	应用收集个人信息但未提供隐私链接	部署隐私政策页面并在 AppGallery Connect 填写链接
图标不符合规范	使用非分层图标或图片尺寸不达标	使用自适应图标，参考 HMS Core 图标规范
版本号错误	versionCode 未递增	每次发布前确保 versionCode 比上一次大

六、测试框架：hypium 与 hamock

在上架之前，充分的测试是保证应用质量的关键。鸿蒙提供了两套测试工具：hypium（单元测试框架）和 hamock（Mock 框架）。

hypium —— 单元测试框架

在项目的根 oh-package.json5 中声明了测试依赖：

{
  "modelVersion": "6.0.0",
  "dependencies": {},
  "devDependencies": {
    "@ohos/hypium": "1.0.24",
    "@ohos/hamock": "1.0.0"
  }
}

@ohos/hypium：单元测试框架，提供 describe、it、expect 等测试套件 API。
@ohos/hamock：Mock 框架，用于模拟依赖对象。

编写测试用例

"画伴梦工厂"项目中的测试文件位于 products/default/src/test/ 和 ohosTest/ 目录下。一个典型的测试用例：

import { describe, beforeAll, beforeEach, afterEach, afterAll, it, expect } from '@ohos/hypium';

export default function localUnitTest() {
  describe('localUnitTest', () => {
    beforeAll(() => {
      // 测试套件开始前执行一次
    });
    beforeEach(() => {
      // 每个测试用例前执行
    });
    afterEach(() => {
      // 每个测试用例后执行
    });
    afterAll(() => {
      // 测试套件结束后执行一次
    });

    it('assertContain', 0, () => {
      let a = 'abc';
      let b = 'b';
      expect(a).assertContain(b);
      expect(a).assertEqual(a);
    });
  });
}

测试入口与组织

测试用例通过 List.test.ets 文件统一注册，作为测试入口：

import localUnitTest from './LocalUnit.test';

export default function testsuite() {
  localUnitTest();
}

测试类型

测试类型	目录	用途
本地单元测试	`src/test/`	纯逻辑测试，不依赖设备能力
仪器测试	`src/ohosTest/`	需要真机或模拟器的集成测试

在 ohosTest/module.json5 中，测试模块声明了支持的设备类型：

{
  "module": {
    "name": "default_test",
    "type": "feature",
    "deviceTypes": ["phone", "tablet", "2in1"],
    "deliveryWithInstall": true,
    "installationFree": false
  }
}

DevEco Testing 运行测试

在 DevEco Studio 中可以通过 View → Tool Windows → Test Runner 面板运行测试，支持：

单个测试方法执行
测试套件批量执行
测试覆盖率统计
测试报告导出

七、多设备支持：phone、tablet、2in1

鸿蒙系统的一大特色是一次开发，多端部署。在 module.json5 中，通过 deviceTypes 字段声明支持的设备形态：

"deviceTypes": ["phone", "tablet", "2in1"]

三种设备类型解析

设备类型	典型设备	UI 适配策略
phone	手机	竖屏为主，窄布局，单列展示
tablet	平板	横竖屏兼顾，中等宽度，双列或多列布局
2in1	笔记本/台式机	大屏为主，支持键盘鼠标交互，多窗口

在项目中实现多设备适配

"画伴梦工厂"项目的多设备适配体现在三个层面：

1. 响应式断点系统

通过 BreakpointSystem 监听窗口尺寸变化，在不同断点下切换布局。系统将屏幕宽度分为 sm（手机竖屏）、md（手机横屏/小平板）、lg（平板）和 xl（2in1/桌面）四个等级。

2. 自适应布局组件

adaptiveLayout 模块提供了 GridRow/GridCol 响应式网格布局，根据设备宽度自动调整列数和元素大小。

3. 权限按需声明

不同设备类型可能需要不同的权限。例如，CAMERA 权限仅在支持拍照的设备上才会被使用。在 module.json5 中，通过 usedScene.abilities 精确定位权限使用范围。

八、module.json5 扩展能力：Form 与 Backup

除了核心 Ability，鸿蒙应用还可以通过 extensionAbilities 提供系统级扩展能力。项目中声明了两个有趣的扩展：

服务卡片（Form）

{
  "name": "CreationFormAbility",
  "srcEntry": "./ets/creationformability/CreationFormAbility.ets",
  "label": "$string:creation_form_ability_label",
  "description": "$string:creation_form_ability_desc",
  "type": "form",
  "metadata": [
    {
      "name": "ohos.extension.form",
      "resource": "$profile:form_config"
    }
  ]
}

服务卡片允许用户无需打开应用即可看到"画伴梦工厂"的创作动态。卡片类型 form 支持多种尺寸（1×2、2×2、2×4），开发者需要通过 form_config.json 定义卡片的布局和刷新频率。

备份服务（Backup）

{
  "name": "DefaultBackupAbility",
  "srcEntry": "./ets/defaultbackupability/DefaultBackupAbility.ets",
  "type": "backup",
  "exported": false,
  "metadata": [
    {
      "name": "ohos.extension.backup",
      "resource": "$profile:backup_config"
    }
  ]
}

备份服务使得应用数据可以通过系统云备份功能进行备份和恢复。对"画伴梦工厂"这样的创作类应用来说，这意味着用户的画作和创作历史不会因为换机而丢失。backup_config 中指定了需要备份的文件路径和数据库。

extensionAbilities 配置要点

字段	说明	示例值
`name`	扩展能力的唯一名称	`CreationFormAbility`
`srcEntry`	入口文件路径	`./ets/creationformability/CreationFormAbility.ets`
`type`	扩展类型	`form`、`backup`、`service` 等
`exported`	是否对其他应用可见	`false`（备份服务通常不导出）
`metadata`	扩展相关的元数据配置	`ohos.extension.form` 等系统定义 key

九、版本迭代策略

应用上架不是终点，而是持续演进的起点。合理的版本迭代策略能让产品稳步前行。

语义化版本策略

遵循 SemVer 规范，结合鸿蒙生态特点：

主版本.次版本.补丁

主版本（Major）：破坏性变更，如架构重写、API 不兼容、UI 全面改版。

示例：1.0.0 → 2.0.0
场景：从单设备架构迁移到跨设备分布式架构

次版本（Minor）：新功能、新能力，向后兼容。

示例：1.0.0 → 1.1.0
场景：新增语音识别、新增相册采集、新增 3D 模型展示

补丁版本（Patch）：问题修复、性能优化，不引入新功能。

示例：1.0.0 → 1.0.1
场景：修复特定机型崩溃、优化内存占用、更新依赖版本

版本规划节奏

阶段	频率	内容	版本示例
MVP 发布	-	核心功能可用	1.0.0
快速迭代	2~4 周	新功能敏捷交付	1.1.0 → 1.2.0 → 1.3.0
修复维护	按需	线上 Bug 修复	1.0.1 → 1.0.2
大版本更新	3~6 月	架构升级或重大改版	2.0.0

版本号维护实践

每次发版前，确认以下事项：

AppScope/app.json5 中的 versionCode 是否已递增
versionName 是否与版本计划一致
所有模块的 build-profile.json5 是否同步更新
生成 CHANGELOG，记录本次变更的内容

十、持续演进：从功能到生态

技术架构的演进不仅仅是新功能的堆叠，更是从产品思维到生态思维的跃迁。

功能迭代方向

"画伴梦工厂"的后续演进可以考虑以下方向：

领域	迭代内容	预期价值
AI 能力增强	支持更多文生图模型、图生视频风格多样化	提升创作天花板
社交分享	接入 `systemShare` 跨设备分享能力	扩大用户传播
元服务	推出原子化服务（Atomic Service），无需安装即可体验核心功能	降低获客成本
分布式协作	利用鸿蒙的分布式数据管理，实现多设备协同创作	打造生态壁垒

性能监控

应用上线后，需要持续监控以下指标：

启动耗时：冷启动时长应控制在 2 秒以内，使用 @kit.PerformanceAnalysisKit 的 hilog 打点收集。
页面渲染帧率：确保 UI 交互不低于 60fps，关注滚动列表和动画场景。
内存使用：监控应用的内存占用量，防止 OOM，尤其是图片加载和 Canvas 使用场景。
网络请求成功率：确保 AI 编排流程中的请求成功率在 99% 以上，对超时场景做重试策略。

用户反馈闭环

用户反馈是持续演进的核心驱动力。建议建立以下反馈闭环：

用户反馈 → 问题分类 → 优先级评估 → 迭代排期 → 版本发布 → 验证关闭

常见反馈处理策略：

Crash 类：通过 AppGallery Connect 的崩溃服务自动收集堆栈，提高优先级为 P0。
功能建议：纳入需求池，结合用户投票决定排期。
UI 体验问题：走快速迭代通道，在下一个次版本中修复。
性能问题：建立性能基线，在每次 release 前对比。

总结

本文完整覆盖了鸿蒙应用从开发到上架再到持续演进的全链路：

阶段	关键操作	涉及文件
应用配置	定义 bundleName、版本号、图标	`AppScope/app.json5`
构建签名	配置证书、Profile、构建模式	`build-profile.json5`
测试验证	编写 hypium 测试用例、hamock 模拟	`oh-package.json5`、`src/test/`
打包发布	构建 HAP → 生成 APP 包 → 上传 AppGallery Connect	`hvigorfile.ts`
设备适配	声明 phone/tablet/2in1 支持	`module.json5`
扩展能力	配置服务卡片、备份服务	`module.json5` → `extensionAbilities`
上架审核	填写应用详情、提交审核	AppGallery Connect
持续演进	版本规划、性能监控、用户反馈	CHANGELOG、监控平台