一次应用上架前的返工,往往不是因为某个字段不会填,而是因为“后台写的内容”和“包里真实存在的内容”来自两套记忆。比如后台选择了平板和鸿蒙电脑,模块却只声明了手机;简介写着完全离线,代码却声明了网络权限;版本号已经改过,截图和启动窗口还是上一版。审核阶段出现的问题,看起来分散,根源却都是同一个:没有把发布信息当作一条可以回查的工程链路。

本文以转盘决定吧的真实源码为例,复查 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。

AppGallery 发布复查封面

这次复查要解决什么

发布复查并不是把一张表格勾完就结束。对工程团队来说,至少要能回答下面五个问题:

问题证据应该在哪里不能只看什么
这是不是正确的应用包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"
  }
}

这里至少有四层含义。

  1. bundleName 是包的稳定身份。提交前应让 AGC 目标应用、签名包以及本地配置都指向 com.jiaweikang.one4,不要依靠显示名称判断。
  2. versionCode 是构建迭代号,versionName 是用户可见版本。复查时要同时记录两者,避免只更新了展示版本而误选旧包。
  3. icon 与 label 都通过资源引用取得。AppGallery 的图标和名称材料应该与最终包的资源效果一致,而不是另做一套看似相近的图片。
  4. 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 则意味着不要把应用描述成“完全不使用网络”。即使首页引导写着“历史记录、音效、震动和深色模式都可以按需调整,数据主要保存在本机”,其中的关键词是“主要”,不是“全部”。

一个可执行的写法是把每项权限都绑定到四列证据:

权限或能力源码位置对外描述应回答什么复查动作
VIBRATEmodule.json5 与触感调用处什么交互会触发震动,是否可关闭实机验证开关与不支持时的降级
INTERNETmodule.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。发布复查需要检查的不只是资源名正确,还包括最终像素效果:

  1. 最终图标是否有明确、非依赖透明背景的视觉底色,浅色和深色环境都能识别。
  2. AppGallery 图标、安装后桌面图标、冷启动图标是否来自同一视觉体系。
  3. 截图是否分别覆盖模块声明的主要设备形态;不能用一张拉伸的手机截图替代平板或 2in1 的实际布局。
  4. 首屏、引导和底部 Tab 的文本是否在大屏或窗口变化后仍可读,且没有调试标记。

素材审核不应只由设计文件完成。最可靠的顺序是:使用候选包安装到目标环境,截取真实运行界面,核对版本号与当前交互,再上传后台预览。只要素材和候选包不是同一个版本,就要明确标成待更新,而不是用“风格差不多”放行。

用发布字段映射表阻止“后台先于源码”

下面是一份可以直接放进项目发布记录的映射表。它不替代 AGC 的实际字段,而是让填写动作有证据来源。

发布项当前源码证据填写或检查方式失败时先查哪里
应用包名com.jiaweikang.one4与目标应用及候选包比对AppScope 与构建产物
版本1.0.9 / 2000008记录展示版本和版本号选包列表、构建记录
支持设备phone、tablet、2in1后台设备与素材组逐一对应module.json5
启动入口EntryAbility冷启动并确认进入 pages/IndexEntryAbility 日志与路由
图标/启动窗口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 的每个字段才会有可回查的来源。

发布前最有价值的复查,不是把后台字段逐项填完,而是让每一项对外说明都能回到包、配置和真实运行路径。这样当版本、设备或素材发生变化时,团队知道该重新验证什么,也能把“上架前再看一眼”变成可重复执行的工程流程。

Logo

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

更多推荐