上架前先对齐应用名、包名和版本号【鸿蒙心迹】

应用已经能启动、能登录、能进入主要页面，不等于可以直接打包上架。

我们在 HarmonyOS 版本收尾时发现，最容易引起连锁问题的不是某一段业务代码，而是应用名、包名和版本号。它们分散在工程配置、开发者平台、签名材料和第三方开放平台里，一处改动可能让另外几处同时失效。

应用名：先分清显示位置

用户在桌面看到的名称、Ability 使用的 label 和应用市场展示名，并不一定来自同一个位置。

工程中的基础资源通常会有类似配置：

{
  "string": [
    {
      "name": "EntryAbility_label",
      "value": "<应用名称>"
    }
  ]
}

如果项目提供多语言资源，base、zh_CN、en_US 等目录里的同名字段都要检查。只改基础目录，切换语言后可能又显示旧名字。

这个项目还有一个特殊情况：三维能力来自团结引擎导出库。每次重新导出都会重新生成一批资源，库内的 label 可能恢复成导出工程的旧名称。后来我们把“同步后恢复正式名称”写成固定步骤，不再靠记忆处理。

因此，应用名检查至少包括：

• AppScope 中的应用 label；
• EntryAbility 的 label 资源；
• 独立 Ability 或三方模块使用的 label；
• 多语言目录；
• 开发者平台上的商店展示名。

包名：它连接着工程外部的配置

包名是应用的唯一标识。工程里常见的配置形式如下：

{
  "app": {
    "bundleName": "<开发者平台登记的包名>",
    "versionCode": 5,
    "versionName": "1.2.7"
  }
}

包名不只影响系统安装。微信、支付宝等第三方平台会使用包名、应用标识或签名信息核对调用方；证书和 Profile 也需要对应正确的应用。

我们真机联调时遇到过“第三方应用信息校验失败，identifier 错误”。客户端调用流程看起来没有问题，最后需要回到平台登记信息、应用标识和签名配置逐项核对。

所以包名应该尽量在创建应用时确定。确实需要修改时，不能只改 app.json5，还要同步检查：

1. HarmonyOS 开发者平台中的应用；
2. 证书和 Profile；
3. 微信、支付宝等开放平台；
4. 回调 URI、scheme 和相关服务端配置；
5. 已经安装在测试设备上的旧包。

版本号：技术规则和产品策略要分开

versionCode 用于系统判断版本先后，新提交版本必须满足平台的递增要求。versionName 主要展示给用户。

这里容易出现一个误解：HarmonyOS 版本号并不因为 Android 已经发布过某个数字，就天然获得跨平台升级关系。两个平台各自遵守自己的发布和升级规则。

我们的项目选择让 HarmonyOS 的 versionName 与 Android 当期版本保持一致，目的是方便产品、客服和用户沟通；这是一种版本管理策略，不是系统强制要求。

更稳妥的做法是：

• HarmonyOS 的 versionCode 按本平台发布历史递增；
• versionName 使用团队统一的产品版本规则；
• 每次出包前同时记录代码版本、签名类型和构建时间；
• 不用覆盖旧版本号的方式“重发”正式包。

签名和 Profile 要跟着检查

身份信息对齐后，下一关是签名。调试签名能安装到测试设备，不代表它可以直接用于正式上架。

项目早期曾出现：

ENOENT: no such file or directory, stat '<工程目录>\signing\material'

这说明构建配置引用了不存在的本地材料。正式打包时还需要确认应用、证书、Profile 和包名相互对应。签名材料不能为了方便直接提交到公开仓库，也不应该出现在文章截图中。

第三方能力还会继续放大签名问题。包名没变但签名环境变了，开放平台侧登记的信息也可能需要更新。授权或支付在“返回应用”这一步失败时，要把签名和平台配置一起纳入排查，而不是只改客户端代码。

上架前检查表

检查项	检查位置	通过标准
桌面名称	AppScope、Ability label、多语言资源	真机不同语言下显示正确
商店名称	开发者平台应用信息	与正式产品名称一致
包名	AppScope/app.json5	与平台登记完全一致
版本号	versionCode、versionName	code 递增，name 符合团队规则
证书与 Profile	本机签名配置、开发者平台	对应当前应用和包名
第三方平台	微信、支付宝等开放平台	包名、应用标识、签名信息一致
回调声明	querySchemes、Ability skills、服务端配置	授权返回路径完整
权限与隐私	requestPermissions、隐私政策	只申请真实使用的权限并说明用途

这张表最好在正式打包前走一遍，而不是等审核失败或第三方回调失败后再补。

应用名、包名和版本号看起来只是三行配置，实际共同构成了应用的身份。越接近发布阶段，越不适合凭印象修改它们。

你上一次打包失败，是卡在代码、签名，还是平台登记信息？这三类问题的排查入口完全不同。

---

系列上一篇：《命令行走通 hvigor 构建：三个报错怎么排【鸿蒙心迹】》

系列下一篇预告：《页面写了却打不开：main_pages.json 与 module.json5 的注册规矩【鸿蒙心迹】》