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

第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）：主版本.次版本.补丁。

三、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 的应用必须经过签名。签名材料包括：

调试阶段 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：

打包流程

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

1. 代码编译：ArkTS 源码经 ArkCompiler 编译为方舟字节码。
2. 资源聚合：收集各模块的资源文件（图片、字符串、配置文件）。
3. 签名：使用signingConfigs中的证书和 Profile 对 HAP 签名。
4. 生成 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 将应用推向市场。

前提条件

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

上架步骤

步骤一：创建应用

登录 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 个工作日。

审核常见问题

六、测试框架：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';exportdefaultfunctionlocalUnitTest(){describe('localUnitTest',()=>{beforeAll(()=>{// 测试套件开始前执行一次});beforeEach(()=>{// 每个测试用例前执行});afterEach(()=>{// 每个测试用例后执行});afterAll(()=>{// 测试套件结束后执行一次});it('assertContain',0,()=>{leta='abc';letb='b';expect(a).assertContain(b);expect(a).assertEqual(a);});});}

测试入口与组织

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

importlocalUnitTestfrom'./LocalUnit.test';exportdefaultfunctiontestsuite(){localUnitTest();}

测试类型

在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"]

三种设备类型解析

在项目中实现多设备适配

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

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 配置要点

九、版本迭代策略

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

语义化版本策略

遵循 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
• 场景：修复特定机型崩溃、优化内存占用、更新依赖版本

版本规划节奏

版本号维护实践

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

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

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

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

功能迭代方向

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

性能监控

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

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

用户反馈闭环

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

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

常见反馈处理策略：

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

总结

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

从开发者的 IDE 到用户手机的桌面，每一行代码都历经了配置、编译、测试、签名、审核的漫长旅程。理解这一过程，不仅能帮你顺利上架应用，更能让你在设计架构时有更长远的视野——好的架构，不仅服务于今天的代码，更要服务于明天的迭代与生态。