产品配置正确,为什么构建出的 HAP 仍无法安装?这个问题很容易被归咎于“DevEco Studio 缓存”。但上一阶段建立的 internal、public 两个 product 共享一个 entry/default target 后,影响安装的因素已经不止编译:产品名、包名、签名配置引用、证书与 Profile、调试设备、系统时间都可能参与结果。把这些环节混在一起处理,往往是改掉一个错误,又引入一个新的错误。

这一次继续使用上一阶段的资料目录应用,产品保持 internal 和 public,模块 target 保持 default,构建模式保持 debug、release,不增加新的源码分支。目标只有一个:让签名从一个依赖开发者记忆的界面操作,变成能够逐项核对的工程关系。

HarmonyOS 多产品签名与故障定位技术封面

先判断失败发生在哪道关口

签名问题并不等于“打包失败”。构建系统先选择 product,再解析其参与的 module target 和构建模式,随后根据所选产品的 signingConfig 查找签名配置。如果引用不存在、签名文件失效或其身份信息不匹配,错误可以出现在构建签名阶段;如果包已经产生但签名身份与设备或发布规则不符,也可能直到安装阶段才暴露。因此第一步不是删除 .ohos 目录,而是记录选了哪个 product、用了什么 buildMode、最终构建目标是什么。

上一阶段的 build-profile.json5 中,产品 internal 对应包名 com.example.catalog.internal,public 对应 com.example.catalog。这是两个不同的应用身份,不能为了让内部包覆盖正式包而临时把二者改成同一个 bundleName。若业务确实要验证同一应用的升级行为,应另外设计相同包名、相容证书和版本链路的验证方案,不能把“双产品构建”误解为“两个可以互相升级的安装包”。

对签名本身,至少需要厘清三个对象:工程中保存的签名配置名称、具体签名材料、面向设备或发布环境的 Profile。开发时的自动签名会根据配置及账号、设备条件生成相关文件;文档中的 .p12 密钥容器、.cer 证书以及 .p7b Profile 承担的职责并不相同。一个文件能被读取,不意味着另两个文件必然匹配。

一张关联图解决一半问题

在工程根目录的 build-profile.json5 中,app.signingConfigs 是签名配置集合,app.products[].signingConfig 是指向配置名称的引用;注意是字符串匹配,而不是凭界面里显示了一个证书就会自动选择它。官方多产品构建文档明确支持给不同 product 指派不同的签名配置。签名的具体字段和私密文件路径建议交由当前 DevEco Studio 的 Signing Configs 界面根据实际帐号生成,然后核对生成结果,不在版本库中硬编码密码。

下面是上一阶段双产品片段的最小增量,signingConfigs 中的记录应通过签名界面生成。这里展示“引用”而不替工程捏造证书密码或真实文件路径。

// 工程根目录 build-profile.json5 中 app 的相关部分
{
  "app": {
    "signingConfigs": [], // 首次签名前由 DevEco Studio 填入真实配置
    "products": [
      {
        "name": "internal",
        "bundleName": "com.example.catalog.internal",
        "signingConfig": "internalSign",
        "compatibleSdkVersion": "26.0.0",
        "targetSdkVersion": "26.0.0",
        "runtimeOS": "HarmonyOS"
      },
      {
        "name": "public",
        "bundleName": "com.example.catalog",
        "signingConfig": "publicSign",
        "compatibleSdkVersion": "26.0.0",
        "targetSdkVersion": "26.0.0",
        "runtimeOS": "HarmonyOS"
      }
    ],
    "buildModeSet": [{ "name": "debug" }, { "name": "release" }]
  }
}

该片段强调配置关系,不可直接作为完整可签名工程使用。示例的两个签名名称需要在 IDE 中生成相应配置后才成立,26.0.0 还应与本机 SDK 和实际目标设备适配要求匹配。modules[].targets[].applyToProducts 和模块级 entry/build-profile.json5 应保留上一篇已经建立的 default 绑定。做故障定位时应读取完整工程文件,而不是用这个局部片段覆盖原文件。

internal/public 对应签名配置的引用关系图

工程审查常见的疏漏是名字看起来相近:publicSign、PublicSign、public_sign 在配置关联时不能当作同一对象。官方故障定位资料还指出,signingConfigs.name 有长度和字符约束;因此这里采用字母组成、可读性强的名称,不建议把日期、空格、路径或中文说明放进该字段。另一种隐蔽问题是 signingConfigs 中存在正确条目,但具体 product 仍指向上次实验留下的旧名字。

为避免依靠肉眼来回比较,可以使用独立的 TypeScript 校验器。它不替代 Hvigor 和签名工具,只在进入真正的签名步骤之前检查名称约束和引用的完整性。使用时将项目配置通过支持 JSON5 的解析器解析为 BuildProfile 类型并传入;不能直接用 JSON.parse 读取带注释的 JSON5。

interface SigningRef { name: string }
interface ProductRef {
  name: string;
  bundleName: string;
  signingConfig?: string;
}
interface BuildProfile {
  app: {
    signingConfigs: SigningRef[];
    products: ProductRef[];
  };
}

export function checkSigningGraph(profile: BuildProfile): string[] {
  const problems: string[] = [];
  const names = new Set<string>();
  for (const config of profile.app.signingConfigs) {
    if (!/^[A-Za-z0-9]{1,64}$/.test(config.name)) {
      problems.push(`签名配置名称无效:${config.name}`);
    }
    if (names.has(config.name)) {
      problems.push(`签名配置名称重复:${config.name}`);
    }
    names.add(config.name);
  }
  const products = new Set<string>();
  for (const product of profile.app.products) {
    if (products.has(product.name)) {
      problems.push(`产品名重复:${product.name}`);
    }
    products.add(product.name);
    if (!product.signingConfig) {
      problems.push(`产品 ${product.name} 尚未绑定签名配置`);
    } else if (!names.has(product.signingConfig)) {
      problems.push(`产品 ${product.name} 找不到 ${product.signingConfig}`);
    }
  }
  return problems;
}

还有一个签名配置容易造成误解的地方:打包使用的应用证书、安装设备允许的 Profile 与产品包名之间存在关联,而 internal 与 public 是两条不同的身份链。不能把 internal 的调试 Profile 挪到 public 的发行包里试错,也不要为了通过校验把配置改成一个随意的新包名。正确的方式是在实际目标账号、对应设备或发布场景下重新生成并核对材料,再检查生成的引用是否仍指向期望的 product。

这段检查不会触碰密钥、口令、Profile,也不输出任何凭据信息。生产工程还应增加 applyToProducts、bundleName 唯一性和构建模式核对;已经有的产品校验逻辑不必重写。对于需要构建未签名产物的特殊流程,缺少签名引用的项目可以把对应检查改为按交付目标判断,但安装与发布阶段不能省略签名验证。

报错排查按证据树走,而不是按情绪清缓存

以几种典型信号为例。出现 The signing config name must be less than or equal to 64 characters 时,先检查 signingConfigs.name 的字符和长度,不要去修改业务包名。出现 The signature does not take effect or has expired 时,既要核对系统时间,也要检查 products[].signingConfig 和 signingConfigs[].name 是否精确对应。出现 Unable to create the profile due to a lack of a device 时,优先检查调试设备连接和 UDID 可获取性,再考虑设备注册与 Profile 的适用范围。

如果提示材料认证失败或签名文件过期,应检查实际证书、Profile 的有效期和签名路径。DevEco Studio 的自动签名排错文档给出了按场景重新配置签名文件的处理方式;但删除 .ohos 中的 material 或签名材料属于有影响的操作,应先确认有重新生成凭据的权限并备份相关材料,不要把它作为通用“第一步”。账号未实名、协议未完成、网络代理和签名服务访问异常,也会造成看起来像构建失败的错误。

签名失败按错误现象分类排查的决策树

给问题单留一份最小定位记录同样重要:写清楚所选 product 和构建模式、报错关键词、配置检查结果、证书到期情况、所连接设备类型、采取的修复操作,以及修复前后错误是否发生变化。它比只截取一行红色报错更有价值,下一位排查人员可以据此排除已验证过的原因,而不必再次修改源码。

一个实用的定位顺序是:先确定错误阶段,再查配置引用,然后查签名文件,最后查账号与设备条件。如果构建日志里是源代码编译错误,就不要继续往证书方向猜;如果没有生成签名产物,就不要拿安装失败当唯一证据。日志应保存错误码、产品选择和触发步骤,但不要在共享材料中附带密钥口令、完整个人账号信息或私有证书内容。

对 public + release 的签名还要更谨慎。调试签名成功,不能推出正式发布签名已经满足应用市场的证书、权限、包名和上架条件。尤其是使用了受限开放能力或 ACL 权限的工程,签名流程与应用审核是两套关口,获准调试和符合正式分发条件应分别核查。

把签名故障变成能交接的定位清单

这篇工作的落点不是发明新的构建插件,而是在已有双产品工程中明确:产品身份稳定、签名引用可静态检查、证书文件受控、自动签名失败有固定排查路径。交接时记录 product、buildMode、target、错误阶段、官方错误关键词和处理动作,就能让下一位维护者从证据继续,而不是重新猜一遍。

这里也留下了两条工程边界。第一,检查器能证明配置引用一致,不能证明私有签名材料正确或构建一定成功;第二,发布包即使成功生成,也还要经过权限审查、稳定性检查和安装验证。下一篇将顺着这个边界处理发布质量门禁:让“能构建”与“能交付”有清楚的区别。

参考资料:

Logo

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

更多推荐