先说我为什么要做这套自查

做 HarmonyOS 应用时，页面能跑起来只是第一步。真正临近上架时，容易暴露出来的是另外一类问题：release 包和调试包不一致，隐私政策入口在代码里有但真机点不开，权限说明写得太泛，返回路径在某些页面上会断。中式美食这类内容型应用看起来不复杂，但只要涉及首页、详情、收藏、设置、反馈和协议页面，上架前就不能只看主流程。

我现在会把上架前自查拆成四块：构建包、合规入口、真机路径、证据记录。这样做不是为了把流程写复杂，而是为了避免最后一天才发现问题，只能一边改代码一边补截图。

release 包单独跑一遍

我不会只用 DevEco Studio 的运行按钮判断应用状态。发布前要单独跑 release 构建，并把构建日志和产物路径留下来。

$DevEcoHome = '<DevEco Studio 安装目录>'
$hvigor = Join-Path $DevEcoHome 'tools\hvigor\bin\hvigorw.bat'

$env:DEVECO_SDK_HOME = Join-Path $DevEcoHome 'sdk'
$env:JAVA_HOME = Join-Path $DevEcoHome 'jbr'
$env:PATH = "$env:JAVA_HOME\bin;$env:PATH"

& cmd /c "`"$hvigor`" --no-daemon assembleHap --mode module -p product=default -p buildMode=release 2>&1" |
  Tee-Object -FilePath .\release-check\build-release.log

这里我主要看三件事：是不是 release 构建，版本号有没有跟本次提交一致，日志里有没有资源缺失、签名、权限或 profile 相关异常。调试包跑通不能替代这一步。

权限说明要和实际功能对齐

权限不是越少写越好，也不是提前把未来可能用到的都写进去。更稳的做法是：当前功能确实用到了什么，就声明什么；没有入口、没有功能闭环的权限，先不要写。

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:permission_internet_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

隐私入口要从真机路径走通

我以前容易犯的错，是只确认项目里存在隐私政策页面，却没有从真机首页一路点进去。审核看的是用户能不能找到、能不能打开、内容是否对应当前功能。

interface LegalItem {
  title: string
  route: string
}

const LEGAL_ITEMS: LegalItem[] = [
  { title: '用户协议', route: 'pages/legal/UserAgreementPage' },
  { title: '隐私政策', route: 'pages/legal/PrivacyPolicyPage' },
]

设置页里不要只放一个很小的文字链接。至少要让用户能明确看到“用户协议”“隐私政策”“反馈与帮助”这些入口，并且返回路径要正常。

为什么要留证据

上架前自查不是做完就算。最好把证据留下来：构建日志、版本截图、隐私入口截图、权限说明截图、真机主路径截图。原因很简单，后面如果审核反馈某个点异常，自己能快速对比：是提交前就有问题，还是提交包和本地包不一致。

release-check/
  build-release.log
  version-info.txt
  screenshots/
    01-home.png
    02-settings.png
    03-privacy.png
    04-feedback.png

这套目录不需要复杂，但要能复现。个人开发者最怕的是“我记得我测过”，但过两天完全找不到当时测的包、测的设备和测的截图。

我以后会按这个顺序做

这篇的重点不是把 AppGallery Connect 每一个表单都讲完，而是把个人开发者最容易忽略的“提交前自查”讲清楚。只要 release 包、权限说明、隐私入口和真机路径先稳住，后面再补截图、描述、分类和版本说明时，返工概率会低很多。

为什么这篇适合放到鸿蒙生态共创里

鸿蒙生态里的经验文章，如果只写“我做了一个页面”，对后来的人帮助不大。更有价值的是把一个真实应用从开发走向提交时遇到的边界写清楚。中式美食这个案例不复杂，但它覆盖了个人 HarmonyOS 应用常见的几类问题：ArkUI 页面、Stage 路由、release 构建、权限说明、隐私入口和真机主路径。这些内容不是某一个项目独有，换成工具类、内容类、学习类应用也能参考。

我更愿意把这类文章写成“我怎么排查、为什么这么做、做完以后怎么验证”，而不是把官方文档重新抄一遍。官方文档告诉我们规则，项目实践负责把规则落到一个真实页面、真实包、真实设备上。

一次自查里我会留下哪些结果

这些文件不一定都要放进公开文章，但本地一定要有。因为审核返工时，最怕不知道“当时测的是哪一个包”。有了这些证据，才能快速判断是代码问题、构建问题、配置问题，还是提交材料没对齐。

我会怎么处理发现的问题

这个顺序很重要。不要在构建包都不稳定时去补材料，也不要在隐私入口打不开时去写一大段解释。上架前自查要解决的是实际可用性，不是把问题包装得好看。

给后续自己的提醒

如果后面中式美食继续加更多能力，比如 AI 菜谱推荐、图片识别食材、购物清单提醒或者多设备同步，上架前自查还要继续扩展。新增能力越多，权限、隐私说明、用户入口和真机路径越要同步更新。否则功能本身做出来了，发布时还是会因为材料和入口不一致返工。

所以这套检查不是一次性的。每次版本增加新能力，都要问四个问题：包能不能稳定产出，用户能不能找到入口，权限能不能解释清楚，真机路径能不能走完。能回答清楚，再进入提交流程。

真机检查不要只点一次主流程

我会把真机检查拆成“冷启动、连续返回、异常入口、二次进入”四轮。冷启动看首页和资源是否正常；连续返回看路由栈有没有残留；异常入口看网络失败、空数据、无权限时页面有没有兜底；二次进入看应用从后台回来以后状态是否还稳定。

这一步其实很朴素，但能抓到很多“开发时没感觉、审核时很明显”的问题。特别是个人项目，很多页面是边做边补，路由和状态很容易留下旧写法。上架前多走几轮，比提交后等审核反馈再改更省时间。

版本记录也要写清楚

我会在本地留一份很短的版本记录，不需要写成长文档，但要能回答三个问题：这次提交的包是哪一个，改了哪些和审核相关的点，真机检查用的是什么设备。

versionName: 1.0.3
versionCode: 103
device: HUAWEI nova 14 Pro
system: HarmonyOS 6.1
check:
  - release build passed
  - privacy path passed
  - permission reason checked
  - main route return passed

以后如果有人问“为什么这个版本能提交”，这份记录就能直接说明，不需要靠记忆回想。

module.json5 我会重点看这几项

上架前我会单独把 module.json5 拿出来看一遍。不是为了改成多漂亮，而是确认发布包里声明的东西和真实应用能力一致。中式美食当前更像内容浏览和本地记录应用，如果没有拍照、定位、录音，就不要提前声明这些敏感权限。

{
  "module": {
    "name": "entry",
    "type": "entry",
    "mainElement": "EntryAbility",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "exported": true
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:permission_internet_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

这段配置我会对照三件事：EntryAbility 是否真的是发布入口，权限 reason 是否写进资源文件，页面里是否真的有使用该能力的入口。如果只是未来可能会用，就不放进当前版本。

隐私和协议入口最好用统一配置

设置页里如果到处手写跳转路径，后面改页面名时很容易漏。我的做法是把协议入口收在一个配置里，设置页只负责渲染和跳转。

type LegalRoute = {
  title: string
  routeName: string
  description: string
}

const LEGAL_ROUTES: LegalRoute[] = [
  {
    title: '用户协议',
    routeName: 'UserAgreementPage',
    description: '说明账号、内容使用和基础服务规则'
  },
  {
    title: '隐私政策',
    routeName: 'PrivacyPolicyPage',
    description: '说明数据收集、使用、存储和撤回方式'
  }
]

function openLegalPage(route: LegalRoute) {
  this.pathStack.pushPathByName(route.routeName, null)
}

这样做的好处是：审核前只要检查这份配置，就能知道公开协议入口有没有漏；真机上点不开时，也能快速定位是路由名错、页面没注册，还是设置页没有渲染入口。

返回路径也要写验收用例

上架审核不会只停在首页。设置页、协议页、反馈页、详情页都会被点到。中式美食里我会把返回路径按页面链路记录下来，尤其是 NavPathStack 相关页面。

const releaseRouteCases = [
  ['HomePage', 'RecipeDetailPage', 'HomePage'],
  ['HomePage', 'SettingsPage', 'PrivacyPolicyPage', 'SettingsPage', 'HomePage'],
  ['HomePage', 'SettingsPage', 'FeedbackPage', 'SettingsPage', 'HomePage'],
  ['HomePage', 'SearchPage', 'RecipeDetailPage', 'SearchPage', 'HomePage']
]

这不是自动化测试的完整替代，但它能提醒我：发布前要按这些路径真机点一遍。尤其是搜索页和详情页，最容易出现返回后列表状态丢失、关键词还在但结果被默认列表覆盖的问题。

检查结果要能复盘

我会把每次自查结论写成一份很短的 Markdown，不需要复杂格式，但要能看出检查日期、设备、系统版本、包版本和发现的问题。

# release 自查记录

- 日期：2026-07-17
- 设备：HUAWEI nova 14 Pro
- 系统：HarmonyOS 6.1
- versionName：1.0.3
- versionCode：103

## 结论

- release 构建：通过
- 隐私入口：通过
- 权限说明：通过
- 主路径返回：通过

## 遗留问题

- 搜索页空结果文案还可以再自然一点
- 设置页反馈入口需要补一张正式截图

这份记录以后也能反过来服务文章：不是凭空写经验，而是把真实检查过程、真实问题和真实修正沉淀出来。