同一个应用需要交给不同人试用,工程配置该怎么组织?开发团队希望保留内部体验包,正式版本则使用稳定的包名和发布配置。如果每次打包前都手工修改 app.json5、勾选不同签名、再把改动改回来,几轮之后,版本标识和构建产物之间就很难对应。更危险的是,把调试配置误当成正式发布配置,错误不一定发生在编译阶段,而可能直到安装或提审才出现。

HarmonyOS 的构建系统提供了比“复制两份工程”更明确的分层手段:product 决定要生成哪类产品包,target 决定模块产生哪个目标,buildMode 决定采用哪组构建编译选项。理解它们的组合关系,比背下某个打包菜单的位置更有用。这套连载将沿着构建配置、签名、发布质量检查和版本迭代逐步推进;第一篇先把变体边界理顺。

HarmonyOS 多产品构建技术封面

先把三个概念分别放到正确位置

假设有一个使用 ArkTS Stage 模型的“资料目录”应用,内部需要一个用于功能预览的包,公开分发则需要另一套稳定身份。内部与公开产品并不一定需要不同业务代码,更不应该分别维护两套状态逻辑。两者最基本的差异是应用身份、可选资源、签名关联以及构建目的。

工程级 build-profile.json5 的 app.products 声明 product,app.buildModeSet 定义或覆盖构建模式。模块级 entry/build-profile.json5 的 targets 声明目标。工程级 modules[].targets[].applyToProducts 用于指定目标参与哪些 product。这里的配置相互关联,却绝不是同一个概念。product 名称选择 internal、public;buildMode 保留 debug、release;entry 的 target 暂时保持 default。这种设计先控制变量:目标源码相同,验证不同产品身份及构建模式是否按照约定组合。

product、target 与 buildMode 三层关系图

华为的多目标与多产品构建文档给出了 product 定义不同应用包、模块 target 定义不同 HAP 以及构建模式控制编译选项的规则。需要注意:不同 product 不必硬性绑定一套独立源码;先从一套 entry/default 目标开始,更容易确认产品层配置没有被业务文件意外覆盖。

配置样例:以工程级产物约定为中心

从 DevEco Studio 新建 Stage 模型工程后,保留工程已经生成的 hvigorfile.ts、模块配置和资源文件。下面展示的是用于理解双产品结构的 build-profile.json5 关键配置,采用官方文档中确有定义的字段。compatibleSdkVersion 与 targetSdkVersion 的示例值需要与本机安装的 HarmonyOS SDK、产品支持范围同步检查;不能因为文中采用 26.0.0 就自动认定所有设备都应以这个版本为最低兼容要求。

// 工程根目录:build-profile.json5
{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "internal",
        "bundleName": "com.example.catalog.internal",
        "compatibleSdkVersion": "26.0.0",
        "targetSdkVersion": "26.0.0",
        "runtimeOS": "HarmonyOS"
      },
      {
        "name": "public",
        "bundleName": "com.example.catalog",
        "compatibleSdkVersion": "26.0.0",
        "targetSdkVersion": "26.0.0",
        "runtimeOS": "HarmonyOS"
      }
    ],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": ["internal", "public"]
        }
      ]
    }
  ]
}

signingConfigs 留空只是说明构建拓扑,并不构成可安装或可发布的签名配置。真实工程需按环境、帐号和证书材料填写对应配置,再让每个 product 的 signingConfig 指向存在且匹配的名称;签名文件路径、密钥和敏感材料应根据团队的凭据管理流程处理,不能直接放进公开文章或提交到仓库。第二篇将围绕这一步专门梳理失败定位。

模块级只声明一个 target,可以保留模板中的其他 buildOption 属性。若为了图省事,把 target 也复制成 internal 与 public 两份,之后在 entry 里复制源代码目录,很容易出现两个版本的业务逻辑逐渐分叉。只有确实需要差异化资源、原生库、源码集或分发规则时,再引入多个目标,并在评审中说明差异来源。

// entry/build-profile.json5 的基本形态
{
  "apiType": "stageMode",
  "buildOption": {},
  "targets": [
    { "name": "default" }
  ]
}

应用的 AppScope/app.json5 仍保存默认应用信息,例如资源标签和版本字段。产品级 bundleName 是特定产物的覆写,不应为了“内部包”与“公开包”来回直接修改默认文件。业务代码依旧可以复用同一页面;只要产品没有真正不同的业务需求,就没有必要新增运行时“我是测试版还是正式版”的布尔变量。

构建配置关键字段与对应覆盖范围

四种组合不是四份源码

选择 product 与选择 buildMode 是两个维度。internal + debug 用于内部调试,internal + release 可以检查内部发布配置,public + debug 可用于排查正式产品身份下的调试问题,public + release 才是正式发布流程重点检查的组合。它们是否全部保留,应由团队实际测试矩阵决定,而不是把四种组合都当成必须交付的应用包。

产品构建模式主要用途检查重点
internaldebug日常集成调试调试能力、资源、包名
internalrelease内部发布预检查混淆及资源收集
publicdebug对比定位正式身份下的问题复现
publicrelease正式交付候选签名、版本与应用身份

配置完成后,在 DevEco Studio 的构建配置界面选择对应 product 与构建模式,先执行同步,再选择实际要构建的目标。官方文档同时支持命令行方式,但团队应根据所用 Hvigor/DevEco Studio 版本的帮助信息核对参数,再把经过验证的命令固定进 CI;直接照搬网上另一版本的参数,可能得到错误的目标组合。若多个产品需要分别发布,产物名称应包含明确的产品维度,由交付流程记录,而不是依赖人工猜测文件名。

预检查要从配置一致性开始

这类工程最值得做的检查往往不用启动设备:确认每个 applyToProducts 的名称都能在 products 找到;确认每个 module target 在模块级定义存在;检查不同产品的 bundleName 是否按预期分离;签名启用后验证 products[].signingConfig 确实指向存在的签名配置。它们是静态关系校验,适合放到构建前的审核步骤中。下面的 TypeScript 函数以经过 JSON5 解析的配置对象为输入,说明最基本的引用关系检查;实际工程读文件时应使用已有的 JSON5 解析工具,不要把带注释的 JSON5 直接传给 JSON.parse。

interface Product { name: string; bundleName?: string; signingConfig?: string }
interface TargetBinding { name: string; applyToProducts: string[] }
interface Module { name: string; targets: TargetBinding[] }
interface BuildProfile {
  app: { products: Product[]; signingConfigs: { name: string }[] };
  modules: Module[];
}

export function inspectProfile(profile: BuildProfile): string[] {
  const errors: string[] = [];
  const productNames = new Set(profile.app.products.map(p => p.name));
  const signNames = new Set(profile.app.signingConfigs.map(s => s.name));
  for (const product of profile.app.products) {
    if (product.signingConfig && !signNames.has(product.signingConfig)) {
      errors.push(`产品 ${product.name} 找不到签名配置 ${product.signingConfig}`);
    }
  }
  for (const module of profile.modules) {
    for (const target of module.targets) {
      for (const name of target.applyToProducts) {
        if (!productNames.has(name)) {
          errors.push(`模块 ${module.name}/${target.name} 指向未知产品 ${name}`);
        }
      }
    }
  }
  return errors;
}

注意这个检查器只证明“名字引用关系自洽”,不能证明构建产物一定可安装、签名有效或设备兼容。真正发布前还需要静态分析、依赖和权限审查、签名校验、安装及业务验收。技术上必须把“配置能解析”“构建完成”“可以发布”看作三个独立关口。

多变体发布前的静态检查与分阶段验收

为签名和迭代留下可控的空间

多 product 的价值不在于配置项多,而在于需求变化时不用复制整套项目。内部包与公开包可以共享 entry、资源和业务逻辑;当签名要求、包身份或发布策略发生变化时,在配置层明确地体现。日常排错可按“选择的 product → 目标绑定 → buildMode → 最终覆写值 → 签名关联”的顺序核查,通常比盲目清理缓存更有效。

还有一个容易忽略的问题:包名不同意味着应用身份不同,数据目录和更新关系也不能随意视为同一应用。想把内部包直接当作正式包的升级包,需要额外分析签名、包名和应用市场的规则,而不能仅凭页面内容相同推断升级关系。首次落地宜先确保两个变体都有清晰身份、能被构建系统正确解析,再进入签名与发布工序。

下一阶段将不再扩充 product 数量,而是从签名配置名称、材料引用和失败定位入手,解决“配置看着都对,但产物无法安装”的实际问题。

参考资料:

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐