发布准备与上架

本文详细介绍 HarmonyOS 应用从签名配置、打包到上架 AppGallery 的完整流程。

证书与 Profile 概念

在 HarmonyOS 应用发布前，必须先理解签名体系的核心概念。

签名体系概览

HarmonyOS 应用签名涉及以下关键文件：

概念	文件格式	说明	生成位置
Key Store	`.p12`	存储开发者私钥的密钥库	DevEco Studio 本地生成
CSR	`.csr`	证书签名请求文件	DevEco Studio 本地生成
调试证书	`.cer`	用于真机调试的证书	AppGallery Connect 申请
发布证书	`.cer`	用于应用上架的证书	AppGallery Connect 申请
调试 Profile	`.p7b`	调试描述文件，含设备白名单	AppGallery Connect 申请
发布 Profile	`.p7b`	发布描述文件	AppGallery Connect 申请

调试证书 vs 发布证书

对比项	调试证书	发布证书
用途	开发期真机调试	应用上架发布
有效期	1 年	3 年
设备限制	需注册设备 UDID	无设备限制
是否可上架	否	是
申请数量	每个开发者 2 个	每个开发者 2 个

提示

调试证书和发布证书不能混用。上架必须使用发布证书签名的 APP 包。

AppGallery Connect 创建应用

注册开发者账号

访问 AppGallery Connect
使用华为账号登录
完成实名认证（个人或企业）

创建应用

登录 AppGallery Connect
点击 我的项目 → 新建项目
填写项目名称，点击确认
在项目页面点击 添加应用
选择平台：HarmonyOS
填写应用信息：

字段	说明	示例
应用名称	展示给用户的名字	我的应用
应用包名	唯一标识，与 `app.json5` 的 `bundleName` 一致	`com.example.myapp`
应用分类	选择最符合的分类	工具
默认语言	应用默认语言	简体中文

点击确认，创建成功后获得 APP ID

重要

应用包名（bundleName）创建后不可修改，上架前务必确认正确。

生成密钥与证书

方式一：DevEco Studio 自动生成（推荐开发期）

开发期可以使用 DevEco Studio 的自动签名功能，一键生成调试证书：

连接真机设备
点击 File → Project Structure → Project → Signing Configs
勾选 Automatically generate signature
DevEco Studio 自动完成：
- 生成 Key Store（.p12）
- 生成 CSR
- 在 AGC 申请调试证书
- 下载 Profile
- 配置到工程

方式二：手动生成（推荐上架前）

步骤 1：生成 Key Store 和 CSR

在 DevEco Studio 中，选择 Build → Generate Key and CSR
选择 New 创建新的 Key Store：

Key Store 文件：/path/to/myapp.keystore.p12
密码：********（务必牢记，丢失无法找回）
确认密码：********
Alias：myapp_key
Alias 密码：********
有效期：25 年（建议设置较长）

填写 CSR 信息：

Common Name：开发者姓名或公司名
Organization：组织名称
Organizational Unit：部门名称
Country：CN（中国）

点击 OK，生成：
- myapp.keystore.p12 — 密钥库文件
- myapp.csr — 证书请求文件

关键提醒

务必备份 .p12 文件和密码。如果丢失，已上架应用无法更新，必须重新创建应用。

步骤 2：在 AGC 申请证书

登录 AppGallery Connect
进入 用户与访问 → 证书管理
点击 新增证书：
- 证书类型：选择 发布证书（上架用）或 调试证书（调试用）
- 上传步骤 1 生成的 .csr 文件
- 点击提交
下载生成的 .cer 证书文件

步骤 3：申请 Profile

在 AGC 中进入 HarmonyOS 应用 → 应用信息
点击 Profile 管理 → 新建 Profile：
- 选择应用（步骤 2 创建的应用）
- 选择证书（步骤 3 下载的证书）
- 调试 Profile：选择要授权的设备（需先注册设备 UDID）
- 发布 Profile：无需选择设备
点击提交，下载 .p7b 文件

步骤 4：注册调试设备（仅调试需要）

连接真机，执行命令获取 UDID：

bash

hdc shell bm get --udid

在 AGC 中进入 HarmonyOS 应用 → 应用信息 → 设备管理
点击 添加设备：
- 设备名称：自定义（如"Mate 60 测试机"）
- UDID：粘贴上一步获取的 UDID
重新下载调试 Profile（包含新注册的设备）

配置工程签名

配置 build-profile.json5

在工程根目录的 build-profile.json5 中配置签名信息：

json5

{
  "app": {
    "signingConfigs": [
      {
        "name": "debug",
        "type": "HarmonyOS",
        "material": {
          "certpath": "/path/to/debug.cer",
          "storePassword": "******",
          "keyAlias": "myapp_key",
          "keyPassword": "******",
          "profile": "/path/to/debug.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "/path/to/myapp.keystore.p12"
        }
      },
      {
        "name": "release",
        "type": "HarmonyOS",
        "material": {
          "certpath": "/path/to/release.cer",
          "storePassword": "******",
          "keyAlias": "myapp_key",
          "keyPassword": "******",
          "profile": "/path/to/release.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "/path/to/myapp.keystore.p12"
        }
      }
    ],
    "products": [
      {
        "name": "default",
        "signingConfig": "debug",           // 开发期使用 debug
        "compileSdkVersion": "5.0.0",
        "compatibleSdkVersion": "5.0.0",
        "runtimeOS": "HarmonyOS"
      }
    ],
    "buildOptionSet": [
      {
        "name": "release",
        "signingConfig": "release"          // 发布时使用 release
      }
    ]
  }
}

安全建议

不要将密码明文提交到代码仓库
使用环境变量或本地配置文件管理敏感信息
团队成员各自使用自己的调试证书

配置 app.json5

确保应用版本信息正确：

json5

{
  "app": {
    "bundleName": "com.example.myapp",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  }
}

字段	说明	注意事项
`bundleName`	应用包名	必须与 AGC 创建应用时填写的一致
`versionCode`	内部版本号	整数，每次上架必须递增
`versionName`	对外版本号	展示给用户，建议语义化
`icon`	应用图标	建议 1024x1024 像素
`label`	应用名称	展示给用户

版本号规则

versionCode 必须大于上一次上架的值
建议格式：主版本 * 1000000 + 次版本 * 1000 + 修订版本
例如：1.2.3 → 1002003

打包 APP

构建配置

在打包前，确保 build-profile.json5 中切换到发布签名：

json5

{
  "app": {
    "products": [
      {
        "name": "default",
        "signingConfig": "release",    // 切换为 release
        "compileSdkVersion": "5.0.0",
        "compatibleSdkVersion": "5.0.0"
      }
    ]
  }
}

DevEco Studio 打包

点击 Build → Build Hap(s)/APP(s) → Build APP(s)
选择产物类型：
- Build HAP(s)：生成 .hap 文件（单模块，用于调试）
- Build APP(s)：生成 .app 文件（上架包，包含所有模块）
等待构建完成
产物路径：entry/build/default/outputs/default/xxx.app

命令行打包

bash

# 构建 release 模式的 APP
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

# 构建 debug 模式的 HAP
hvigorw assembleHap --mode module -p module=entry -p buildMode=debug

# 清理后重新构建
hvigorw clean
hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

重要

上架必须使用 release 模式 + 发布证书 构建的 .app 文件。

上架前自检清单

在提交审核前，逐项确认以下内容：

基础配置检查

[ ] bundleName 与 AGC 应用包名完全一致
[ ] versionCode 已递增（大于上次上架版本）
[ ] versionName 已更新
[ ] 应用图标 app_icon.png 已配置（建议 1024x1024）
[ ] 应用名称 label 已正确配置
[ ] 使用发布证书签名（确认不是调试证书）

权限与合规检查

[ ] 所有敏感权限已在 module.json5 的 requestPermissions 中声明
[ ] 危险权限已实现动态申请逻辑
[ ] 权限使用说明已在 AGC 中填写（与声明的权限一一对应）
[ ] 隐私政策 URL 已配置且页面内容合规

代码质量检查

[ ] 已移除所有 console.log 调试代码
[ ] 已移除所有测试代码和硬编码的测试数据
[ ] 已检查并处理所有 hilog 中的 %{public}s 敏感信息
[ ] 已使用 Code → Inspect Code 检查无 Error 级别问题
[ ] 生产环境使用 HTTPS（未配置 cleartextTrafficAllowed）

功能与性能检查

[ ] 在真机上完成回归测试（至少一台高端机和一台低端机）
[ ] 核心功能流程测试通过
[ ] 无崩溃、无白屏、无 ANR
[ ] 启动时间 < 3 秒
[ ] 内存占用在合理范围
[ ] 已测试深色模式适配（如支持）

素材准备

[ ] 应用截图已准备（按 AGC 要求尺寸，如 1080x1920）
[ ] 应用介绍文案已准备（简短描述 + 详细描述）
[ ] 应用分类和关键词已确定
[ ] 隐私政策页面已上线并可访问

截图要求（手机应用）：
- 尺寸：1080 x 1920 像素或更高
- 格式：JPG 或 PNG
- 数量：至少 3 张，最多 8 张
- 内容：展示应用核心功能和界面
- 要求：真实截图，不得包含第三方水印

提交审核流程

在 AGC 提交版本

登录 AppGallery Connect
进入 我的项目 → 选择项目 → 选择应用
点击 版本信息 → 准备提交（或 新增版本）

填写版本信息

1. 软件包

点击上传，选择本地构建的 .app 文件
AGC 会自动校验：
- 包名一致性
- 签名有效性
- versionCode 合规性
- 文件大小（超限需拆分为 HSP）

2. 应用详情

字段	填写建议
应用名称	与 AGC 创建时一致
一句话简介	30 字以内，突出核心价值
应用介绍	详细描述功能、特点、适用场景
新版本特性	本次更新的内容（更新时填写）
关键词	影响搜索排名，填写 3-5 个核心词

3. 素材上传

上传应用截图（按设备类型分别上传）
上传应用图标（如与之前版本不同）
可选：上传演示视频

4. 隐私与合规

隐私政策 URL：必填，指向合规的隐私政策页面
权限使用说明：每个敏感权限说明具体用途
内容分级：按 IARC 问卷填写
数据安全：说明收集的数据类型和用途

5. 资费与分发

选择免费/付费/应用内购买
选择分发国家/地区
配置灰度发布（可选）

提交审核

所有信息填写完成后：

点击 提交审核
确认提交信息无误
等待审核结果

审核状态流转：

待提交 → 审核中 → 审核通过 → 待发布 → 已发布
            ↓
         审核不通过（需修改后重新提交）

审核要点和常见被拒原因

审核标准

华为应用市场审核主要关注以下方面：

审核维度	检查内容
功能完整性	应用是否可正常运行，无崩溃、无白屏
内容合规	无违法违规内容，无侵权
隐私合规	隐私政策完整，权限申请合理
用户体验	界面清晰，交互合理，无诱导行为
技术规范	签名正确，版本号合规，使用 HTTPS

高频被拒原因及解决方案

被拒原因	解决方案
明文 HTTP 传输	全部改为 HTTPS；如确有必要，需在 AGC 中说明原因
权限缺失说明	在 AGC 的权限使用说明中，为每个权限写清用途
隐私政策不合规	隐私政策需包含：收集的数据类型、用途、第三方 SDK 列表、用户权利、联系方式
应用崩溃/白屏	在多款真机上测试，使用 hilog 排查错误
截图与实际不符	确保截图真实反映应用当前版本界面
侵权	使用自有版权素材，或提供授权证明
诱导下载/误导	描述文案真实准确，不夸大功能
未实名认证	完成开发者实名认证
应用内容违规	遵守《华为应用市场审核指南》
版本号未递增	确保 `versionCode` 大于上次上架版本

审核时间

普通应用：1-3 个工作日
涉及特殊权限或功能：3-7 个工作日
节假日可能延长

版本更新流程

更新步骤

修改代码：修复 bug 或添加新功能
更新版本号：

json5

// AppScope/app.json5
{
  "app": {
    "versionCode": 1000001,    // 必须递增
    "versionName": "1.0.1"     // 展示给用户
  }
}

重新构建：

bash

hvigorw assembleApp --mode project -p product=default -p buildMode=release --no-daemon

在 AGC 提交新版本：
- 进入应用 → 版本信息 → 新增版本
- 上传新的 .app 文件
- 填写新版本特性说明
- 提交审核

版本更新最佳实践

typescript

// 在应用中检测更新（可选）
import { updateManager } from '@kit.UpdateKit'

async function checkForUpdate() {
  try {
    const manager = updateManager.getAppUpdateManager()
    const info = await manager.checkAppUpdate()

    if (info.updateAvailable) {
      // 提示用户更新
      promptAction.showDialog({
        title: '发现新版本',
        message: `最新版本: ${info.versionName}\n更新内容: ${info.releaseNotes}`,
        buttons: [
          { text: '稍后', color: '#999999' },
          { text: '立即更新', color: '#007DFF' }
        ]
      }).then((result) => {
        if (result.index === 1) {
          manager.showUpdateDialog()
        }
      })
    }
  } catch (error) {
    hilog.error(0x0001, 'Update', '检查更新失败')
  }
}

热修复（HSP 动态加载）

对于紧急 bug 修复，可使用 HSP（Harmony Shared Package）动态更新：

json5

// module.json5
{
  "module": {
    "deliveryWithInstall": false,  // 不随应用安装
    "installationFree": true       // 免安装
  }
}

注意

HSP 热修复有严格限制，不能修改应用主体逻辑，仅适用于资源更新和有限的功能修复。

元服务上架（可选）

元服务（Atomic Service）是 HarmonyOS 特有的免安装服务形态：

元服务 vs 应用

对比项	元服务	应用
安装方式	免安装，即用即走	需要安装
体积限制	更严格（通常 ≤ 10MB）	相对宽松
入口	服务中心、卡片	桌面图标
开发模板	Atomic Service	Empty Ability

元服务上架流程

在 DevEco Studio 创建项目时选择 Atomic Service 模板
开发完成后，打包流程与普通应用相同
在 AGC 中选择 元服务 入口提交
审核标准相对应用更严格（体积、启动速度）

上架后运营

数据监控

AGC 提供丰富的应用数据看板：

下载量：日/周/月下载趋势
活跃用户：DAU、MAU
崩溃分析：线上崩溃堆栈和趋势
用户反馈：评论和评分

问题响应

关注用户评论，及时响应负面反馈
定期查看崩溃报告，修复线上问题
根据用户反馈规划版本迭代

常见问题 FAQ

签名相关

Q: 调试证书和发布证书可以用同一个 Key Store 吗？ A: 可以，但建议分开管理。同一个 Key Store 可以生成多个 CSR，分别申请调试和发布证书。

Q: Key Store 密码忘记了怎么办？ A: 无法找回，必须重新生成 Key Store 和证书。已上架应用将无法更新，需要重新创建应用。

Q: 团队成员如何共享调试证书？ A: 每个开发者应使用自己的调试证书。可以将发布证书统一管理，由专人负责上架。

上架相关

Q: 审核被拒后多久可以重新提交？ A: 修改完成后随时可以重新提交，没有等待限制。

Q: 可以撤回正在审核中的应用吗？ A: 可以，在 "审核中" 状态可以撤回修改。

Q: 上架后如何下架应用？ A: 在 AGC 的 版本管理 中选择下架。

Q: 一个应用可以同时在多个账号上架吗？ A: 不可以，一个 bundleName 只能对应一个 AGC 应用。

下一步

测试指南 — 学习如何编写测试用例
调试与调优 — 学习性能优化和调试技巧

发布准备与上架 ​

证书与 Profile 概念 ​

签名体系概览 ​

调试证书 vs 发布证书 ​

AppGallery Connect 创建应用 ​

注册开发者账号 ​

创建应用 ​

生成密钥与证书 ​

方式一：DevEco Studio 自动生成（推荐开发期） ​

方式二：手动生成（推荐上架前） ​

步骤 1：生成 Key Store 和 CSR ​

步骤 2：在 AGC 申请证书 ​

步骤 3：申请 Profile ​

步骤 4：注册调试设备（仅调试需要） ​

配置工程签名 ​

配置 build-profile.json5 ​

配置 app.json5 ​

打包 APP ​

构建配置 ​

DevEco Studio 打包 ​

命令行打包 ​

上架前自检清单 ​

基础配置检查 ​

权限与合规检查 ​

代码质量检查 ​

功能与性能检查 ​

素材准备 ​

提交审核流程 ​

在 AGC 提交版本 ​

填写版本信息 ​

1. 软件包 ​

2. 应用详情 ​

3. 素材上传 ​

4. 隐私与合规 ​

5. 资费与分发 ​

提交审核 ​

审核要点和常见被拒原因 ​

审核标准 ​

高频被拒原因及解决方案 ​

审核时间 ​

版本更新流程 ​

更新步骤 ​

版本更新最佳实践 ​

热修复（HSP 动态加载） ​

元服务上架（可选） ​

元服务 vs 应用 ​

元服务上架流程 ​

上架后运营 ​

数据监控 ​

问题响应 ​

常见问题 FAQ ​

签名相关 ​

上架相关 ​

下一步 ​

发布准备与上架

证书与 Profile 概念

签名体系概览

调试证书 vs 发布证书

AppGallery Connect 创建应用

注册开发者账号

创建应用

生成密钥与证书

方式一：DevEco Studio 自动生成（推荐开发期）

方式二：手动生成（推荐上架前）

步骤 1：生成 Key Store 和 CSR

步骤 2：在 AGC 申请证书

步骤 3：申请 Profile

步骤 4：注册调试设备（仅调试需要）

配置工程签名

配置 build-profile.json5

配置 app.json5

打包 APP

构建配置

DevEco Studio 打包

命令行打包

上架前自检清单

基础配置检查

权限与合规检查

代码质量检查

功能与性能检查

素材准备

提交审核流程

在 AGC 提交版本

填写版本信息

1. 软件包

2. 应用详情

3. 素材上传

4. 隐私与合规

5. 资费与分发

提交审核

审核要点和常见被拒原因

审核标准

高频被拒原因及解决方案

审核时间

版本更新流程

更新步骤

版本更新最佳实践

热修复（HSP 动态加载）

元服务上架（可选）

元服务 vs 应用

元服务上架流程

上架后运营

数据监控

问题响应

常见问题 FAQ

签名相关

上架相关

下一步