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

IT喂嘟盲

350人浏览 · 2026-06-10 23:53:07

IT喂嘟盲 · 2026-06-10 23:53:07 发布

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 类型的模块在同一个产品中只能出现一次。

概念	作用	类比
Product（产品）	定义一次构建的产物组合	一道菜的“套餐”
Module（模块）	代码和资源的组织单元	套餐中的“食材”
applyToProducts	决定某个模块属于哪些产品	食材被哪些套餐使用

主应用和元服务共享同一个 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 关键配置解读

配置项	值	作用
`products[0].name`	`default`	主应用产品
`products[1].name`	`atomicserviceProduct`	元服务专用产品
`entry.applyToProducts`	`["default"]`	仅主应用包含
`shared.applyToProducts`	`["default", "atomicserviceProduct"]`	两个产品共享
`atomicservice.applyToProducts`	`["atomicserviceProduct"]`	仅元服务包含

3.3 atomicservice 的 module.json5

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

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

四、打包命令

清理旧产物

hvigorw clean

构建主应用 Release 包

hvigorw assembleApp -p product=default -p buildMode=release

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

构建元服务 Release 包

hvigorw assembleApp -p product=atomicserviceProduct -p buildMode=release

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

五、上传 AppGallery Connect

产物	上传入口	说明
`lingxi-kitchen-v2-default-signed.app`	AGC 应用 → 版本管理	主应用完整包
`atomicservice-default-signed.app`	AGC 元服务 → 版本管理	元服务独立包

注意事项：

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

六、设计决策

决策	选择	理由
主应用和元服务是否拆分工程	否——同一工程，不同产品	共享 HSP 代码，避免维护两套工程
元服务模块类型	`type: "entry"`	AGC 元服务上架的硬性要求
`atomicservice` 是否被主应用包含	否——仅属于元服务产品	避免同一产品出现两个 entry 模块
`shared` 是否被两个产品共享	是	推荐引擎、数据模型等核心代码复用
构建模式指定方式	命令行 `-p buildMode=release`	较新版本已废弃 `products` 内的 `buildMode` 字段

七、本阶段总结

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

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

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

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

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