【笔下生辉｜20】HarmonyOS ArkTS AppGallery 发布复查实战：核对包名、版本、设备、素材和离线声明

HarmonyOS 5.0+ 应用准备上架或更新时，最危险的错误往往不是代码崩溃，而是发布材料和源码身份不一致：AGC 上选的包名和 bundleName 不一致，版本号没有递增，设备类型勾选超过代码实际适配范围，图标素材和启动图标不是同一套，应用描述写了在线能力但 module.json5 没有联网权限，或者自检报告仍保留旧项目名和旧包名。这些问题不一定在本地运行时暴露，却会直接影响 AppGallery 审核、包体绑定和用户看到的上架信息。

本文基于「笔下生辉」真实源码复核，包名标记为 com.jiaweikang.one17。复核文件包括 AppScope/app.json5、entry/src/main/module.json5、EntryAbility.ets、Index.ets、HomePage.ets，并对照项目中的上架自检文档、布局检查记录、色彩检查记录和功能整改说明。本文只讨论源码和本地文档可验证的发布复查方法，不声称已经完成本次全平台公开发布，也不伪造 AGC 审核结果。

1. 发布复查的第一步：先锁定应用身份

AppGallery 发布不是从截图开始，而是从应用身份开始。应用身份至少包含四个字段：包名、应用名、版本号、签名 Profile 对应关系。当前源码中，AppScope/app.json5 给出了最核心的身份信息：

{
  "app": {
    "bundleName": "com.jiaweikang.one17",
    "vendor": "JiaWeiKang",
    "versionCode": 10000000,
    "versionName": "1.0.0",
    "icon": "$media:layered_image",
    "label": "$string:app_name"
  }
}

这段配置对应的发布复查结论很明确。

这里要特别注意历史文档。项目中有自检报告曾提到旧包名或旧方向，发布前不能直接照搬旧文档结论。最终真源必须回到当前源码：本次复核的包名是 com.jiaweikang.one17，应用名资源指向「笔下生辉」，版本是 1.0.0。如果 AGC 后台仍绑定旧包名、旧图标、旧截图或旧说明，就必须先修正材料，不能把旧材料当成当前版本证明。

2. module.json5：设备类型、入口和安装方式要和 AGC 勾选一致

entry/src/main/module.json5 是模块发布能力的第二个关键文件。当前模块声明如下：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone", "tablet", "2in1"],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages"
  }
}

这段配置说明当前包支持 phone、tablet、2in1，是随安装交付的普通应用，不是免安装元服务。AGC 发布复查时，设备勾选必须与这里一致：如果 AGC 勾选了手机、平板和 2in1，就要准备对应设备截图并做布局验证；如果 AGC 多勾选了穿戴、智慧屏或其他设备，而源码没有对应 deviceTypes 和适配材料，就属于发布材料超范围。

Ability 部分也需要核对：

{
  "name": "EntryAbility",
  "srcEntry": "./ets/entryability/EntryAbility.ets",
  "icon": "$media:layered_image",
  "label": "$string:EntryAbility_label",
  "startWindowIcon": "$media:layered_image",
  "startWindowBackground": "$color:start_window_background",
  "exported": true
}

入口图标和启动图标都引用 $media:layered_image，这对 AppGallery 图标复查很重要。包内图标、启动页图标和 AGC 上传图标最好来自同一视觉源，避免安装界面、桌面图标、启动窗口和商店详情页看起来像不同应用。项目错误复盘文档里也记录过图标透明背景、前景后景图不满足规范等风险，因此发布前必须同时检查 AppScope 图标、entry Ability 图标、启动图标和 AGC 上传图标。

3. 版本复查：versionCode、versionName 和更新说明不能各说各话

当前 versionCode 是 10000000，versionName 是 1.0.0。这两个字段在发布复查中承担不同职责。

versionCode 是平台判断版本先后的数值，更新时必须递增；versionName 是用户看到的版本文本，应该和更新说明、截图、隐私材料中的版本描述一致。如果只是改截图或改文案，不一定需要改包；如果提交了新包，版本号和构建产物就必须对应。

发布前建议做一张本地核对表：

本文不展示签名材料中的密码、证书口令或私密文件内容。发布复查只需要确认“签名材料和包名是否匹配、上传包是否为目标 release 包”，不需要把任何密钥信息写进文章、日志或队列记录。

4. 离线声明：不能只看文案，要和权限、入口、首页能力交叉验证

「笔下生辉」当前定位是离线语文纠错题库。这个结论不能只从介绍文案得出，而要从配置和代码同时复核。

module.json5 没有 requestPermissions，也没有 ohos.permission.INTERNET。EntryAbility 启动时做的是浅色模式、用户数据本地初始化、Tab 默认值、安全区和断点系统注册。HomePage 使用 BANKS、CATEGORIES、TOTAL_QUESTIONS、TOTAL_REGIONS 等本地题库数据，页面跳转使用 router.pushUrl 或修改 currentTabIndex，没有看到 HTTP、WebView、账号、支付、广告、推送或外部内容加载。

可以把离线复查写成下面这张表：

这里还要避免一个误判：题库中有“网络热词”分类，这是语文纠错内容，不是联网功能。发布材料可以说“包含网络热词规范表达训练”，但不能据此写成“根据网络热度推荐题目”。

5. 首页能力：截图和描述要来自当前真实 UI

AGC 截图和应用描述应该体现当前源码中的真实页面。HomePage.ets 显示首页标题、今日挑战、题库统计、题型分类、推荐题库和快捷入口。核心数据来自本地题库和本地学习记录：

import { BANKS, CATEGORIES, TOTAL_QUESTIONS, TOTAL_REGIONS } from '../mock/MockBanks'

private myStats() {
  return StatService.summarize(this.progressList, this.examHistory, this.favRecords, this.wrongRecords)
}

这段代码对应的截图建议是：首屏展示应用名、题量、分类入口和推荐题库；题库页展示不同题库卡片；练习页展示题目、选项和解析；结果页展示分数、正确率、错题入口。截图不能复用旧版本素材，也不能出现旧应用名、旧题库方向、调试浮层、模拟器异常状态或不属于当前版本的在线能力。

项目复盘文档里有一条明确经验：上架截图必须来自当前最新构建，不能复用旧版本素材；同一设备组截图尺寸和方向必须一致；提交前逐张检查标题、安全区、底部导航、内容清晰度和版本真实性。这条经验应该直接纳入发布复查，而不是等审核退回后再补。

6. 多设备复查：phone、tablet、2in1 不是一句配置

module.json5 声明了 phone、tablet、2in1，这意味着发布材料和实际体验都要覆盖这些设备。源码中 EntryAbility 注册 BreakpointSystem，Index 使用底部导航和安全区，HomePage 根据 currentBp === 'lg' && pageWidth >= 700 判断是否使用更宽的布局。相关文档也把手机、平板、2in1/电脑类大屏作为目标设备。

发布复查可以按设备拆分：

这些检查和 AppGallery 布局审核直接相关。只声明 deviceTypes 不等于完成多设备发布准备；声明越多，截图和适配验证责任越多。如果 AGC 材料只准备了手机截图，却勾选了更多设备，发布前要补齐或收缩设备范围。

7. 图标和素材：layered_image 要贯穿包内与商店材料

当前 AppScope 图标、Ability 图标、启动窗口图标都指向 $media:layered_image。这说明项目已经按分层图标路径组织应用图标。发布复查时，至少要确认四类素材：

项目错误复盘文档曾记录过图标 alpha 通道、启动图标和安装图标不同源、未配置前景图和后景图等问题。发布前不要只看桌面图标是否显示，要检查资源文件、预览效果、暗色模式、浅色模式、安装界面、启动窗口和 AGC 展示面。

本文生成的文章封面只用于技术文章，不是 AppGallery 上架图标；同一软件合集的集合封面继续复用应用级 collection-cover.png，而每篇文章自己的 media/cover.png 保持不同，避免平台发布时把合集封面和文章封面混淆。

8. 文档复查：自检报告如果残留旧包名，要以源码为准

发布复查时，项目文档也要检查。当前项目文档中有几类有价值的信息：应用审核政策自检报告确认离线题库定位、无联网权限、无登录支付广告推送；布局基础要求检查记录确认 deviceTypes 覆盖 phone、tablet、2in1；色彩对比度检查记录提醒发布前复查文字、按钮、弹层和底部导航；功能异常整改说明记录了移除 ohos.permission.INTERNET、保持离线题库定位、使用最新 HAP 采集截图等要求。

但文档也可能有历史残留。例如旧自检报告可能提到旧项目名或旧包名。遇到这种情况，发布复查应采用下面的优先级：

1. 当前源码配置优先：AppScope/app.json5、module.json5、资源字符串；
2. 当前构建产物优先：最新 release 包、当前版本截图；
3. 最新整改文档优先：明确针对当前版本的检查记录；
4. 旧文档只作为风险提示，不作为最终发布字段。

这可以避免把旧包名、旧截图或旧功能写进 AGC。尤其是包名、版本、隐私政策、应用说明这几类字段，一旦错填，后续排查成本很高。

9. 发布前本地检查清单

基于当前源码，发布前可以执行一张最小复查清单：

如果这张表中任一项无法确认，就不应该进入最终提交。尤其是包名、签名 Profile、版本号和图标素材，必须在上传包之后回到 AGC 页面再次确认，因为“上传成功”不等于“版本绑定正确”。

10. 常见发布问题和修正方式

问题一：AGC 包名与源码包名不一致。 先确认 AppScope/app.json5 中的 bundleName，再确认签名 Profile 和 AGC 应用。不要通过临时改包名绕过上传失败；包名变化会牵涉 Profile、历史版本、截图和隐私材料。

问题二：版本号没有递增。 如果是更新包，versionCode 必须高于线上版本。versionName 也要和更新说明一致，不能让 AGC 说明写 1.0.1，源码仍是 1.0.0。

问题三：设备勾选超出源码。 当前源码声明 phone/tablet/2in1。如果 AGC 多选了其他设备，要么补源码和素材，要么收缩发布范围。不能只靠一套手机截图覆盖全部设备。

问题四：离线声明和文案冲突。 源码没有 INTERNET 权限，也没有 HTTP、WebView、账号、广告、支付和推送。发布描述应围绕本地题库和本地记录，不能写云同步、在线推荐或账号恢复。

问题五：旧截图残留。 重新基于最新 release 包截图，检查应用名、首页数据、底部导航、安全区、题目内容和结果页。旧截图即使尺寸合格，也不能代表当前版本。

11. 小结：发布复查要把源码、包体和 AGC 材料放在一张表里

「笔下生辉」当前源码给出的发布边界比较清晰：bundleName 是 com.jiaweikang.one17，版本是 1.0.0 / 10000000，设备类型是 phone/tablet/2in1，图标和启动图标引用 $media:layered_image，入口是 EntryAbility，首页能力来自本地题库和本地学习记录，module.json5 未声明 requestPermissions 和 ohos.permission.INTERNET。

发布复查的关键不是写一份很长的材料，而是让 AGC 字段、源码配置、截图素材、隐私说明和应用真实能力互相一致。只要这五者对齐，后续无论是 CSDN 技术文章、HarmonyOS 开发者官网文章，还是 AppGallery 更新说明，都能基于同一组可验证事实展开，而不会把旧文档或未实现能力带进发布流程。

部分内容由AI辅助生成。