企业官网建设流程全解析

HarmonyOS 6.1 全场景实战｜《灵犀厨房》实战（番外篇）：【打包上架】三模块一体化工程的 Release 包构建与元服务独立分发

摘要：经过几十篇的迭代，《灵犀厨房》从一行代码成长为包含主应用、元服务和 HSP 共享库的完整项目。但在通往 AppGallery 的最后一步——打包 Release 包时，我们遭遇了一场“配置风暴”：同一个工程如何分别打出主应用和元服务的包？为什么entry和atomicservice会冲突？元服务上架为什么要求type必须是entry？本文将完整复盘从工程配置到构建产物的全流程，提炼出“一个工程、两个产品、两条命令”的打包法则。

一、引言：最后的关卡

经过功能开发、Bug 修复、HarmonyOS 6.1 新特性适配，《灵犀厨房》终于走到了上架前的最后一步——打包 Release 包。

你打开 DevEco Studio，配置好发布证书，执行构建命令，然后——

> hvigor ERROR: The tablet,2in1,phone device type under product default already has an entry module.

这不是 Bug，这是 HarmonyOS 多模块工程的设计约束：一个产品（Product）下只能有一个entry类型的模块。而我们的工程里，主应用的entry和元服务的atomicservice都是entry类型，它们不能同时存在于同一个产品中。

二、核心原理：理解 Product、Module 和 applyToProducts

要解决这个冲突，必须先理解 HarmonyOS 构建系统的三个核心概念：

图一解读：一个工程可以定义多个产品，每个产品通过applyToProducts字段选择包含哪些模块。同一个模块可以被多个产品共享（如shared），但entry类型的模块在同一个产品中只能出现一次。

主应用和元服务共享同一个bundleName和同一套发布证书，但它们需要生成两个独立的.app文件，分别上传到 AppGallery Connect 的“应用”和“元服务”入口。因此，必须定义两个产品。

三、完整配置

3.1 根目录build-profile.json5

{ "app": { "signingConfigs": [ { "name": "release", "type": "HarmonyOS", "material": { "storeFile": "D:/BaiduNetdiskDownload/HarmonyOS/certificates/release/lingxikitchenrelease.p12", "profile": "D:/BaiduNetdiskDownload/HarmonyOS/certificates/release/lingxikitchenreleaseRelease.p7b", "certpath": "D:/BaiduNetdiskDownload/HarmonyOS/certificates/release/lingxikitchenrelease.cer" } } ], "products": [ { "name": "default", "signingConfig": "release", "targetSdkVersion": "6.1.1(24)", "compatibleSdkVersion": "6.1.0(23)", "runtimeOS": "HarmonyOS", "buildOption": { "strictMode": { "caseSensitiveCheck": true, "useNormalizedOHMUrl": true } } }, { "name": "atomicserviceProduct", "signingConfig": "release", "targetSdkVersion": "6.1.1(24)", "compatibleSdkVersion": "6.1.0(23)", "runtimeOS": "HarmonyOS", "buildOption": { "strictMode": { "caseSensitiveCheck": true, "useNormalizedOHMUrl": true } } } ], "buildModeSet": [ { "name": "debug" }, { "name": "release" } ] }, "modules": [ { "name": "entry", "srcPath": "./entry", "targets": [{ "name": "default", "applyToProducts": ["default"] }] }, { "name": "shared", "srcPath": "./shared", "targets": [{ "name": "default", "applyToProducts": ["default", "atomicserviceProduct"] }] }, { "name": "atomicservice", "srcPath": "./atomicservice", "targets": [{ "name": "default", "applyToProducts": ["atomicserviceProduct"] }] } ] }

3.2 关键配置解读

3.3 atomicservice 的 module.json5

元服务上架要求模块类型为entry：

{ "module": { "name": "atomicservice", "type": "entry", // ★ 必须为 entry "installationFree": true, ... } }

四、打包命令

清理旧产物

hvigorw clean

构建主应用 Release 包

hvigorw assembleApp-pproduct=default-pbuildMode=release

产物路径：build/outputs/default/lingxi-kitchen-v2-default-signed.app

构建元服务 Release 包

hvigorw assembleApp-pproduct=atomicserviceProduct-pbuildMode=release

产物路径：build/outputs/atomicserviceProduct/atomicservice-default-signed.app

五、上传 AppGallery Connect

注意事项：

1. 两个包使用同一套发布证书和bundleName，元服务可正常唤醒主应用
2. 元服务包的大小限制为 10MB（可申请放宽至 20MB）
3. 主应用的应用名称和元服务的label必须与 AGC 填写的一致

六、设计决策

七、本阶段总结

这次打包过程的核心教训是：HarmonyOS 的多模块工程通过“产品（Product）”来区分不同的构建产物，而不是通过拆分工程。

• 一个工程：维护成本最低，代码复用最方便
• 两个产品：default（主应用）和atomicserviceProduct（元服务）
• 两条命令：分别构建，分别上传

从开发到上架的最后一公里，配置的每一个字段都有其存在的原因。理解“Product”和“applyToProducts”的关系，是驾驭多模块工程的关键。

📚 本系列持续更新中：下一篇将介绍应用发布的完整流程——从签名校验到审核上架的全链路。

🔗专栏入口：[《HarmonyOS6.1全场景实战》合集]
📦 获取基线版本源码包：包括第1-15篇所有代码 + 架构文档 + Flask 后端
**如果你发现本文还有任何不严谨之处，欢迎随时指出，我们一起共建最优质的 HarmonyOS 6.1 学习内容！如果觉得有帮助，请不要吝啬你的点赞 👍、收藏 ⭐ 和评论 💬!
纯血鸿蒙，用心造厨。我们下一篇见！