第八篇：HarmonyOS 更新包打包流程：versionCode、签名配置与 assembleApp 验证

摘要：这篇不讲功能，而讲一次已上架应用更新应该怎样收口：版本、签名、构建、上传和回归证据。

本篇解决更新包最容易乱的地方

已上架应用更新不是“重新打包上传”这么简单。包名、签名、versionCode、versionName、AGC 选包、更新说明和隐私材料都要保持一致。本文按发布流程拆开讲，避免最后因为一个配置错误被卡住。

| 发布环节 | 常见风险 | 处理方式 |

| — | — | — |

| 版本号 | versionCode 没递增 | 每次更新明确递增 |

| 签名 | 与线上包不一致 | 使用同一 release 证书/profile |

| AGC 选包 | 上传了但没选中新包 | 上传后返回版本页确认 |

| 更新说明 | 写了未实现功能 | 只写真实可用能力 |

已上架应用更新，最怕签名和版本乱

功能改完不等于可以上架。对于已经上架的 HarmonyOS 应用，更新包最关键的是版本递增和签名一致。如果 versionCode 没变，平台无法识别升级；如果签名和线上版本不一致，真机更新安装也可能失败。

这篇以化学实验室更新包为例，整理从版本号到最终 .app 包的检查流程。

第八篇｜更新包构建架构

versionName 和 versionCode 不是一回事

versionName 是用户看到的版本，比如 1.0.3。versionCode 是平台判断升级关系的整数，必须比线上版本大。很多开发者只改 versionName，结果上传或更新时出问题。

第八篇｜版本配置代码片段

我的习惯是每次构建前先确认线上版本，再决定本次 versionCode。不要凭感觉改，也不要多个包共用同一个内部版本号。

构建命令要生成可上传产物

本地调试 HAP 能跑，不代表 AGC 可以上传。发布更新时应该生成 signed .app 包，并记录构建路径、时间、大小和版本号。

构建成功后不要急着提交。先在本地做一次核心流程检查：启动、首页入口、实验保存分享、阅读朗读、每日一题、服务卡片配置。

上传 AGC 后还要选包

AGC 上传成功只是第一步。版本页面里通常还要选择最新上传的包并保存。如果只是传上去了但没有选中，提交时可能仍然用旧包。这个细节很容易漏。

第八篇｜打包上架流程

我会用上传时间、版本号和包大小来确认是否选中了正确包。更新说明也要和本次功能一致，不能写不存在的能力。

发布材料要跟应用行为一致

这次更新涉及实验结果保存分享、化学阅读朗读、每日一题、错题本、服务卡片和宣传图。因此更新说明、截图、隐私材料、权限声明都要跟真实功能对齐。

第八篇｜发布材料数据卡片

如果应用定位离线学习，就不要突然声明无关网络权限；如果截图出现服务卡片，就要保证包里确实有卡片配置；如果说明写了朗读，就要能在真机上播放。

第八篇｜更新包检查清单

第八篇的重点是发布纪律。更新包不是“能构建出来”就完成，而是版本、签名、包选择、核心流程和材料一致性全部闭环。

更新说明要写给用户，不是写给自己

很多更新说明写成“修复已知问题，优化体验”，用户和审核人员都不知道你到底改了什么。化学实验室这次更新可以更具体：修复实验结果保存分享，新增化学阅读朗读，增加每日一题和错题本，接入服务卡片，更新宣传素材。

这类说明既真实，也方便审核复测。审核人员可以根据说明逐项点，开发者也能按说明做回归。

签名失败要先判断是不是旧包冲突

本地安装更新时，如果设备上已有同包名但不同签名的版本，安装会失败。这不一定是新包坏了，而是签名身份不一致。处理方式是卸载旧调试包，或者使用和线上一致的发布签名。

这个问题在已上架应用更新里非常常见。不要看到安装失败就去乱改代码，先看错误信息是不是签名不一致。

构建产物要记录清楚

每次生成更新包，我建议记录四个信息：版本号、构建时间、包路径、包大小。比如 build/outputs/default/xxx-signed.app。上传 AGC 时用这些信息确认自己选的是最新包。

如果团队里多人协作，这个记录更重要。否则很容易出现 A 构建了新包，B 上传了旧包，最后审核看到的不是你以为的版本。

回滚预案也要想一下

更新包提交前要问自己：如果这版审核失败，能不能快速定位原因？如果某个新功能有风险，能不能先隐藏入口？如果素材被指出不一致，能不能快速重出图？这些不是悲观，而是发布工程的一部分。

稳定的发布流程会让后续更新越来越快。第一次把版本、签名、构建、上传、复测跑顺，后面每次只是重复可靠步骤。

本地调试包和上架包要分清

DevEco 运行时常用的是调试包，上架需要的是签名后的发布包。调试包能安装，不代表发布包没问题；发布包构建成功，也不代表能覆盖设备上的旧调试包。两者签名不同，是很多安装错误的来源。

所以我会把测试分成两类：开发阶段用调试包快速验证功能，提交前用发布包做最终烟测。不要把调试环境的结果当成上架结论。

上传后截图材料也要同步检查

如果这次更新新增了阅读朗读和服务卡片，截图里最好能体现这些入口；如果修复了实验保存分享，更新说明要写清楚。包和素材不同步，会让审核人员困惑，也会让用户下载后预期不一致。

我更喜欢在上传包之前先整理一个发布清单，把本次功能、截图、隐私说明、权限、版本号放在一起看。这样能提前发现“包里有功能但材料没写”或“材料写了功能但包里没有”的问题。

构建日志也有保存价值

构建成功时，可以保留关键日志或至少记录命令。以后如果出现“本地能跑，上传包不对”的情况，构建记录能帮助定位是不是用了不同 SDK、不同 profile 或不同分支。

发布工程最怕凭记忆。把命令、产物、版本和时间记录下来，是很低成本但很有效的习惯。

包名不要在更新中变化

已上架应用更新必须保持包名一致。包名一变，平台会认为这是另一个应用，用户也无法正常升级。化学实验室的 bundleName 应该在所有发布配置、AGC 信息和包产物中保持一致。

如果需要做测试包，可以用不同环境，但正式更新包不要随意改包名。版本可以变，功能可以加，应用身份不能乱。

更新包验证最好分两次跑

第一次在开发环境跑，目的是确认功能没坏；第二次在发布包上跑，目的是确认签名、资源、配置和构建产物都正确。两次验证关注点不同，缺一不可。只跑开发环境，很容易漏掉发布配置问题。

小结补充：发布流程要能复用

一次更新跑通后，要把命令、产物位置、版本规则和检查清单留下来。下一次更新时照着执行，风险会小很多，速度也会更快。

发布工程越规范，后续每次上架越轻松，这也是独立开发最值得沉淀的能力。

已上架应用更新，重点是“同一个应用继续升级”

应用已经上架后，再更新软件包，最关键的不是重新打一个包，而是保证它被平台识别为同一个应用的升级版本。包名不能变，签名证书要保持一致，versionCode 必须递增，versionName 要能解释这次更新。只要这些基础条件错一个，就可能出现安装失败、上传失败或无法覆盖旧版本。

发布前我会把更新拆成四类材料：代码包、版本信息、更新说明、审核说明。代码包证明功能实现；版本信息证明它是新版本；更新说明告诉用户改了什么；审核说明帮助审核人员快速找到核心路径。尤其是本次有化学阅读、朗读、服务卡片、保存分享修复，说明里就要写清楚。

更新说明不要写得像广告，要写用户能感知的变化。比如“新增化学阅读功能，支持文章朗读”“优化实验结果保存和分享体验”“新增今日化学学习桌面卡片”。这些表述既真实，又方便用户理解，也方便审核复测。

最后还要保留包路径和构建时间。独立开发时很容易混淆多个输出文件，尤其是 debug、release、signed、unsigned 同时存在时。每次上架只上传确认过的 release 签名包，并记录对应版本号，能少掉很多低级错误。

更新后也要留意老用户覆盖安装。能够全新安装不代表能顺利升级，尤其是签名、版本号和本地数据迁移相关问题，最好都用已安装旧版本的设备再跑一次。

实战复盘：更新包要跑升级路径

| 检查点 | 为什么重要 | 怎么验证 |

| — | — | — |

| 覆盖安装 | 证明老用户能升级 | 旧版本设备安装新包 |

| 核心流程 | 证明更新没有破坏功能 | 首页、实验、阅读、我的逐项走 |

| AGC 包选择 | 防止提交旧包 | 核对上传时间、版本号、大小 |

发布类文章要写得高质量，最有用的是把“容易错的地方”列成流程。读者看完能照着检查自己的项目，这种实用性比单纯贴构建命令更能体现价值。

也想请你帮忙体验一下

如果你正在准备自己的 HarmonyOS 应用更新，也欢迎下载「化学实验室」对照体验一下这次更新内容。觉得更新说明、功能入口、上架材料哪里还可以更好，麻烦评论区指出来。你的下载和反馈，就是我继续迭代版本的动力。