【转盘决定吧|20】HarmonyOS ArkTS AppGallery 发布复查实战:核对包名、版本、设备、素材和离线声明
一次应用上架前的返工,往往不是因为某个字段不会填,而是因为“后台写的内容”和“包里真实存在的内容”来自两套记忆。比如后台选择了平板和鸿蒙电脑,模块却只声明了手机;简介写着完全离线,代码却声明了网络权限;版本号已经改过,截图和启动窗口还是上一版。审核阶段出现的问题,看起来分散,根源却都是同一个:没有把发布信息当作一条可以回查的工程链路。
本文以转盘决定吧的真实源码为例,复查 D:\huawei\one4 中的 AppScope/app.json5、entry/src/main/module.json5、EntryAbility.ets 与 Index.ets。它面向 HarmonyOS 5.0 及以上的发布准备场景,目标不是替任何项目做发布承诺,而是建立一套能从 AppGallery 字段回到包配置、再回到实际运行路径的办法。示例工程当前的应用身份是 com.jiaweikang.one4,版本名为 1.0.9。

这次复查要解决什么
发布复查并不是把一张表格勾完就结束。对工程团队来说,至少要能回答下面五个问题:
| 问题 | 证据应该在哪里 | 不能只看什么 |
|---|---|---|
| 这是不是正确的应用包 | AppScope/app.json5 的 bundleName、版本 | 后台里保存过的旧记录 |
| 允许在哪些设备上安装和展示 | module.json5 的 deviceTypes | 仅凭截图尺寸猜测 |
| 点击图标后用户先看到什么 | EntryAbility、启动窗口和首屏路由 | 只在 IDE 预览一张页面 |
| 权限、扩展与数据行为如何说明 | requestPermissions、扩展配置、相关服务 | 把“本地存储”写成“绝不联网” |
| AGC 的图标、简介、设备和隐私说明是否可信 | 源码、构建产物、实机冒烟证据 | 把源码中的占位字段直接抄进后台 |
后面的每一步都围绕这张表推进。最重要的顺序是:先读取包和运行证据,再填写后台;不是先填完后台,再为字段寻找解释。


先建立“一个版本”的身份基线
应用身份应当从 AppScope/app.json5 读取,而不是从文件夹名、测试机桌面名称或历史发布记录猜。示例工程中的核心字段如下:
{
"app": {
"bundleName": "com.jiaweikang.one4",
"vendor": "example",
"versionCode": 2000008,
"versionName": "1.0.9",
"icon": "$media:layered_image",
"label": "$string:app_name"
}
}
这里至少有四层含义。
bundleName是包的稳定身份。提交前应让 AGC 目标应用、签名包以及本地配置都指向com.jiaweikang.one4,不要依靠显示名称判断。versionCode是构建迭代号,versionName是用户可见版本。复查时要同时记录两者,避免只更新了展示版本而误选旧包。icon与label都通过资源引用取得。AppGallery 的图标和名称材料应该与最终包的资源效果一致,而不是另做一套看似相近的图片。vendor在该示例中是example。它可以是开发中的占位配置,但不应被机械复制为开发者主体、版权方或后台展示信息;这些对外信息必须以真实的账号和合规材料为准。
一个实用做法是在每次发版前创建一条不可覆盖的复查记录:版本名、版本号、包名、构建时间、构建产物哈希和负责人的确认人。这样当后台看到多个相似版本时,团队能用事实筛选,而不是靠记忆。
发布候选版本
bundleName : com.jiaweikang.one4
versionName: 1.0.9
versionCode: 2000008
icon : $media:layered_image
label : $string:app_name
这段清单不是新的配置,而是从配置中摘出的“身份快照”。它的作用是让包选择、AGC 页面和测试记录使用同一组值。
从模块声明确定可支持的设备范围
AppGallery 里的设备选择会影响用户可见范围,因此必须回到 entry/src/main/module.json5。示例应用将 entry 模块声明为:
{
"module": {
"name": "entry",
"type": "entry",
"mainElement": "EntryAbility",
"deviceTypes": [
"phone",
"tablet",
"2in1"
],
"deliveryWithInstall": true,
"installationFree": false,
"pages": "$profile:main_pages"
}
}
这段配置给出的结论很明确:当前包声明的目标设备是手机、平板和 2in1,不包含穿戴、智慧屏或其他未声明设备。发布后台的设备类型、素材组和实际测试范围应当以这个集合为起点。
但“配置里写了三类设备”不等于“已经验证过三类设备”。更稳妥的复查矩阵如下:
| 设备场景 | 要查看的真实结果 | 通过标准 |
|---|---|---|
| 手机竖屏 | 首次启动、底部三 Tab、引导浮层 | 控件不被系统区域遮挡,文字可读 |
| 平板横屏 | 内容区、引导最大宽度、Tab 宽度 | 页面不被无意义拉伸,操作仍在可视范围 |
| 2in1 调整窗口 | 窗口缩放后首页与二级页面 | 不截断、不重叠,仍能进入核心玩法 |
| 新装与保留数据 | 引导状态、偏好和历史恢复 | 首次与再次进入的路径都可解释 |
如果某类设备尚未跑过这张表,正确的做法是保留“待测”状态,而不是在 AGC 中把它当成已验证能力。声明范围决定需要测试什么,实机或对应环境的结果才决定能否交付。
把启动入口和首屏当成发布材料的一部分
用户从桌面点击图标后能否稳定进入首屏,是发布复查最容易被忽略的部分。模块配置把入口指向 EntryAbility,而 EntryAbility.ets 在创建阶段完成服务初始化,在窗口阶段加载 pages/Index:
export default class EntryAbility extends UIAbility {
async onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): Promise<void> {
try {
AppStorage.setOrCreate('appContext', this.context.getApplicationContext());
await PreferencesStore.init(this.context);
const settings = await SettingsService.load();
await HistoryService.load();
await WheelService.load();
SettingsService.applyTheme(settings.theme);
await SoundService.init();
} catch (error) {
hilog.error(DOMAIN, TAG, 'service init failed: %{public}s', JSON.stringify(error));
}
}
onWindowStageCreate(windowStage: window.WindowStage): void {
BreakpointSystem.register();
windowStage.loadContent('pages/Index', (err) => {
if (err.code) {
hilog.error(DOMAIN, TAG, 'load content failed: %{public}s', JSON.stringify(err));
}
});
}
}
这条链路说明复查至少要覆盖两类失败:本地服务初始化失败时,应用是否还能给出可理解的结果;pages/Index 加载失败时,日志中是否能准确定位入口问题。代码没有把异常继续抛出,而是记录错误后继续走生命周期,因此更不能只凭“没有崩溃”就判定体验正常,必须观察首屏是否真的出现、核心操作是否可用。
发布前的最小冒烟顺序可以写成:安装候选包,冷启动,等待首页出现,进入一个决策玩法,返回首页,切到历史和个人页,再退出并再次进入。每一步都应留下截图或日志索引。它不替代完整测试,却能拦住入口路由、资源引用和首屏初始化这类影响面最大的故障。
首次引导会改变“新装即用”的验证路径
Index.ets 并不是每次都直接露出三栏内容。它读取 onboarding_done_v1,新装状态会显示四步引导,完成或跳过后才写入本地偏好:
private async finishGuide(): Promise<void> {
this.showGuide = false;
this.guideStep = 0;
await PreferencesStore.putString(ONBOARDING_DONE_KEY, '1');
}
aboutToAppear(): void {
this.showGuide = PreferencesStore.getString(ONBOARDING_DONE_KEY, '0') !== '1';
}
因此发布复查不能只用一台已使用很久的测试机。至少应区分两组证据:
| 数据状态 | 首屏预期 | 需要核对的说明 |
|---|---|---|
| 新安装、无偏好 | 显示四步引导,可跳过或推进 | 新用户能找到开始使用入口 |
| 已完成引导 | 直接进入三栏 Tab 首页 | 本地状态恢复不会卡在遮罩层 |
这个差异还会影响截图选择。若上架素材需要展示首页主能力,应该选取能代表用户实际主要路径的状态,并确保图片里的 UI、版本和当前包一致。不要把只在内部调试中出现的浮层、日志或占位数据带入对外材料。
权限不是清单项,而是对外说明的边界
当前模块请求了两个权限:
"requestPermissions": [
{ "name": "ohos.permission.VIBRATE" },
{ "name": "ohos.permission.INTERNET" }
]
它们不能只在 AGC 页面“存在”,还要和功能说明、隐私说明保持同一口径。对这份工程来说,VIBRATE 应回到触感反馈相关能力核对;INTERNET 则意味着不要把应用描述成“完全不使用网络”。即使首页引导写着“历史记录、音效、震动和深色模式都可以按需调整,数据主要保存在本机”,其中的关键词是“主要”,不是“全部”。
一个可执行的写法是把每项权限都绑定到四列证据:
| 权限或能力 | 源码位置 | 对外描述应回答什么 | 复查动作 |
|---|---|---|---|
VIBRATE | module.json5 与触感调用处 | 什么交互会触发震动,是否可关闭 | 实机验证开关与不支持时的降级 |
INTERNET | module.json5 与网络相关功能 | 哪个功能可能联网,何时发生 | 断网与联网各走一遍核心路径 |
| 本地偏好/历史 | PreferencesStore、Index.ets | 什么数据保存在设备本机 | 新装、重启、清除数据后复查 |
特别是在“离线”描述上,建议使用能够被代码证明的措辞,例如“核心决策与本地记录可在本机使用;网络相关能力以实际功能和权限说明为准”。这比一句绝对化的“完全离线”更准确,也能避免权限与宣传互相冲突。
不要遗漏表单、备份和启动窗口这些非首页能力
审查者看到的并不只是一张 Index 页面。模块中还声明了表单和备份扩展能力:
"extensionAbilities": [
{
"name": "QuickDecisionFormAbility",
"type": "form",
"metadata": [{
"name": "ohos.extension.form",
"resource": "$profile:form_config"
}]
},
{
"name": "EntryBackupAbility",
"type": "backup",
"exported": false,
"metadata": [{
"name": "ohos.extension.backup",
"resource": "$profile:backup_config"
}]
}
]
与备份扩展对应的 backup_config.json 是:
{
"allowToBackupRestore": true
}
这不要求每次都把备份当作核心卖点,却要求发布信息不要遗漏“存在可备份恢复的数据行为”这一事实。做法是先确认该能力在当前版本是否面向用户开放、实际备份的数据范围是什么,再决定隐私材料、帮助页和审核备注如何如实描述。仅仅看到 exported: false 也不能直接推导为“没有数据影响”;它表示该扩展不作为对外导出入口,数据行为仍需结合备份配置和实际运行验证。
启动窗口同样值得检查。EntryAbility 使用 $media:startIcon 与 $color:start_window_background。在冷启动时,应对照图标、背景色和首屏主题观察是否出现白屏闪烁、透明图标难以辨认或明暗模式下对比不足。这里的体验问题往往在页面完全加载后消失,却会在用户第一次打开时留下很深印象。
素材复查要从资源引用走到实际像素
app.json5 的应用图标是 $media:layered_image,EntryAbility 的启动图标是 $media:startIcon。发布复查需要检查的不只是资源名正确,还包括最终像素效果:
- 最终图标是否有明确、非依赖透明背景的视觉底色,浅色和深色环境都能识别。
- AppGallery 图标、安装后桌面图标、冷启动图标是否来自同一视觉体系。
- 截图是否分别覆盖模块声明的主要设备形态;不能用一张拉伸的手机截图替代平板或 2in1 的实际布局。
- 首屏、引导和底部 Tab 的文本是否在大屏或窗口变化后仍可读,且没有调试标记。
素材审核不应只由设计文件完成。最可靠的顺序是:使用候选包安装到目标环境,截取真实运行界面,核对版本号与当前交互,再上传后台预览。只要素材和候选包不是同一个版本,就要明确标成待更新,而不是用“风格差不多”放行。
用发布字段映射表阻止“后台先于源码”
下面是一份可以直接放进项目发布记录的映射表。它不替代 AGC 的实际字段,而是让填写动作有证据来源。
| 发布项 | 当前源码证据 | 填写或检查方式 | 失败时先查哪里 |
|---|---|---|---|
| 应用包名 | com.jiaweikang.one4 | 与目标应用及候选包比对 | AppScope 与构建产物 |
| 版本 | 1.0.9 / 2000008 | 记录展示版本和版本号 | 选包列表、构建记录 |
| 支持设备 | phone、tablet、2in1 | 后台设备与素材组逐一对应 | module.json5 |
| 启动入口 | EntryAbility | 冷启动并确认进入 pages/Index | EntryAbility 日志与路由 |
| 图标/启动窗口 | layered_image、startIcon | 真机和后台预览都检查 | media、颜色资源 |
| 权限 | VIBRATE、INTERNET | 权限说明与功能说明一致 | 模块配置和功能调用 |
| 扩展能力 | form、backup | 是否开放、是否需要说明 | 扩展 metadata 与配置 |
| 本地与网络描述 | 引导称数据“主要保存在本机” | 避免绝对离线承诺 | 权限、服务实现、实际网络行为 |
这张表的价值在于它允许任何人复查。负责后台的人不需要了解全部 ArkTS 细节,但需要知道每个字段应该回到哪个文件;负责开发的人也不再只收到模糊的“上架资料不一致”。
构建、安装与卸载:不要把“能编译”当作完成
发布候选包至少需要经过一次面向真实安装流程的冒烟验证。可以把步骤固定下来:
1. 使用候选签名构建 HAP 或 APP。
2. 核对构建产物的包名、versionName、versionCode。
3. 在目标设备安装,冷启动应用。
4. 新装状态完成或跳过引导,进入一个决策玩法并返回。
5. 切换历史与个人页,检查本地状态可恢复。
6. 在已声明的设备形态或窗口尺寸下复查布局。
7. 卸载应用,确认流程正常结束。
上面的步骤描述的是应执行的验证,不是对本项目已经执行的结论。实际发布记录里要填入真正的构建时间、设备型号、系统版本、包的校验值、结果和失败日志位置。没有真实安装证据时,应标记为“未运行”,不能用开发环境预览替代。
常见不一致与排查顺序
| 现象 | 容易出现的误判 | 先做的排查 | 修复后的确认 |
|---|---|---|---|
| 后台版本显示不对 | 只改了 versionName | 同时读 versionName 与 versionCode | 候选包和后台选包一致 |
| 平板布局不自然 | 认为声明了 tablet 就自动适配 | 在平板横屏和窗口缩放下看首页与引导 | 文字、弹层、底栏都可操作 |
| 离线描述被质疑 | 把本地数据误写成绝不联网 | 先看 INTERNET 权限与网络功能 | 描述限定到真实可离线范围 |
| 启动闪屏不协调 | 只检查首页 UI | 看 startIcon、启动背景和冷启动过程 | 首屏前后颜色与图标连贯 |
| 表单或备份说明缺失 | 只关注主 Ability | 读 extensionAbilities 和 metadata | 对外材料与当前开放范围一致 |
| 新装后首页不同 | 用已有数据设备验证 | 清除数据或新装重走引导 | 引导可完成、可跳过且状态能保存 |
排查时先看“配置、运行、对外描述”三者哪一个不一致,再决定改代码还是改资料。这样可以避免为了迁就一个旧字段而去改动本来正确的产品行为。
源码事实与建议实现的边界
为了让后续接手者知道哪些结论可以直接回到文件,本文使用唯一的发布身份与材料证据边界标记。这不是发布状态,也不是平台结论,而是一条阅读约定:表格左侧只记录当前源码与资源中已经存在的内容;右侧记录提交前仍需执行或确认的动作。
| 当前源码事实 | 建议实现或待验证动作 |
|---|---|
bundleName 为 com.jiaweikang.one4,版本为 1.0.9 / 2000008,vendor 当前写作 example | 在 AGC 目标应用和候选包中逐项回读;vendor 是否仍为占位值要由项目负责人核实,不能把它解释成已经修正 |
deviceTypes 声明 phone、tablet、2in1 | 分别执行手机、平板和 2in1 的布局与核心流程测试;设备声明本身不是适配通过的证据 |
EntryAbility 初始化偏好、设置、历史、转盘、主题和声音服务,随后加载 pages/Index | 用候选包验证初始化失败路径、冷启动时长、首屏可见性和返回流程 |
Index 使用 onboarding_done_v1 控制四步引导,完成或跳过后写入状态 | 在新装和保留数据两种状态下回归引导,确认跳过、完成和再次启动都符合预期 |
| 模块声明 VIBRATE 与 INTERNET;引导文案使用“主要保存在本机” | 隐私和应用简介应保留限定语,并结合真实网络调用核对数据范围,不能写成“绝不联网” |
| 工程存在卡片扩展和备份扩展,备份配置允许备份恢复 | 确认当前版本实际开放范围、备份对象与用户可感知行为,再决定帮助页、隐私材料和审核备注怎么写 |
| 图标由前景、背景和启动图资源组合;抽样检查发现部分前景资源含透明像素,背景资源为不透明像素 | 必须以安装后的桌面图标、冷启动画面和 AGC 预览为准;逐张检查 alpha、明暗模式辨识度和包内/后台两处素材一致性 |
还要明确本文没有完成的工作:没有在本轮文章精修中构建或签名候选包,没有执行安装、启动、核心流程、卸载和多设备测试,也没有替项目上传 AGC、提交审核或取得审核结论。文中的构建与发布步骤均是建议执行路径,真正的发布记录必须附上实际命令、产物、设备、时间和结果。
最后把复查变成一次可交接的发布动作
对 HarmonyOS 应用而言,发布复查不只是发布人员的最后一小时工作。AppScope/app.json5 决定身份基线,module.json5 决定设备、权限和扩展边界,EntryAbility 决定从图标到首页的运行链路,Index 又决定新装用户会看见什么。把这些点串起来,AGC 的每个字段才会有可回查的来源。
发布前最有价值的复查,不是把后台字段逐项填完,而是让每一项对外说明都能回到包、配置和真实运行路径。这样当版本、设备或素材发生变化时,团队知道该重新验证什么,也能把“上架前再看一眼”变成可重复执行的工程流程。
更多推荐



所有评论(0)