上架发布与 CI/CD

发布前准备：AGC 账号与应用创建

在华为应用市场（AppGallery Connect，AGC）发布应用，需要完成以下准备工作：

1. 注册华为开发者账号（个人账号或企业账号），完成实名认证
2. 登录 AGC（appgallery.huawei.com/agc），在"我的项目"中创建新项目
3. 在项目下创建应用，填写应用包名（bundleName，须与代码一致）、应用名称、分类
4. 下载 agconnect-services.json（类似 Firebase 的配置文件），放入项目根目录
5. 申请发布证书和 Profile 文件（用于签名）

证书与签名体系

HarmonyOS 应用在发布前必须经过签名。签名机制保证应用来源可信，系统安装时会验证签名完整性。理解签名体系是发布的关键：

配置签名（DevEco Studio 方式）

1. 在 DevEco Studio 中，进入 File → Project Structure → Project → Signing Configs
2. 点击"Automatically generate signature"（调试模式），或手动配置发布证书
3. 选择从 AGC 下载的证书文件（.p12 格式）和 Profile 文件（.p7b 格式）
4. 填写证书密钥密码（创建证书时设置的密码）
5. 点击 Apply，DevEco Studio 自动更新 build-profile.json5

// build-profile.json5 — 签名配置
{
  "app": {
    "signingConfigs": [{
      "name": "release",
      "type": "HarmonyOS",
      "material": {
        "certpath": "./signing/release.cer",
        "storePassword": "***",
        "keyAlias": "release",
        "keyPassword": "***",
        "profile": "./signing/release.p7b",
        "signAlg": "SHA256withECDSA",
        "storeFile": "./signing/release.p12"
      }
    }],
    "products": [{
      "name": "default",
      "signingConfig": "release",
      "compileSdkVersion": 12,
      "compatibleSdkVersion": 12,
      "runtimeOS": "HarmonyOS"
    }]
  }
}

构建与打包

HarmonyOS 使用 hvigor 作为构建工具（类似 Gradle），以下是常用构建命令：

# 调试构建（Debug，不优化，包含调试符号）
hvigorw assembleHap --mode module -p product=default -p buildMode=debug

# 发布构建（Release，AOT 优化，代码压缩）
hvigorw assembleHap --mode module -p product=default -p buildMode=release

# 生成 App 包（包含所有 HAP 的完整应用包，用于 AGC 上传）
hvigorw assembleApp --mode project -p product=default -p buildMode=release

# 单独构建指定模块
hvigorw assembleHap -p module=entry -p buildMode=release

# 清理构建缓存
hvigorw clean

# 构建完成后，产物位于：
# entry/build/default/outputs/default/entry-default-signed.hap（单 HAP）
# build/outputs/app/entry-default-signed.app（App 包）

AGC 审核规范

提交到华为应用市场的应用需要通过严格的审核。了解审核规范，可以避免被拒回来需要多次修改的情况：

审核维度	常见拒绝原因	解决方案
权限合规	申请了不必要的权限，或权限用途说明不充分	只申请功能必须的权限，在 reason 字段详细说明用途
隐私政策	没有隐私政策链接，或隐私政策内容不完整	提供完整的隐私政策 URL，说明所有数据收集和使用方式
内容安全	含有违规内容（赌博、暴力、色情等）	内容审核，用户生成内容需实现举报和过滤机制
功能完整性	核心功能无法正常使用，或存在崩溃	提交前充分测试，提供测试账号给审核人员
UI/UX 规范	与华为 HIG（Human Interface Guidelines）严重不符	遵循鸿蒙设计规范，特别是导航和交互模式
多设备适配	在平板/折叠屏上布局严重异常	使用 Navigation 自适应布局，测试所有目标设备

CI/CD 自动化发布

生产级应用应建立完整的 CI/CD 流水线，实现代码推送后自动构建、测试、打包、发布到测试环境，以及版本管理和灰度发布：

GitHub Actions 流水线示例

# .github/workflows/harmonyos-release.yml
name: HarmonyOS Release Build

on:
  push:
    branches: [main]
    tags: ['v*']   # 推送 tag 时触发

jobs:
  build-and-release:
    runs-on: ubuntu-latest

    steps:
      ### 1. 检出代码
      - uses: actions/checkout@v4

      ### 2. 安装 hvigor CLI
      - name: Setup HarmonyOS SDK
        run: |
          npm install -g @ohos/hvigor-ohos-plugin
          npm install -g @ohos/hvigor

      ### 3. 恢复签名证书（从 GitHub Secrets 注入）
      - name: Restore Signing Files
        run: |
          echo "${{ secrets.RELEASE_P12_BASE64 }}" | base64 -d > signing/release.p12
          echo "${{ secrets.RELEASE_P7B_BASE64 }}" | base64 -d > signing/release.p7b
          echo "${{ secrets.RELEASE_CER_BASE64 }}" | base64 -d > signing/release.cer

      ### 4. 写入签名配置
      - name: Configure Signing
        run: |
          sed -i "s/STORE_PASSWORD/${{ secrets.STORE_PASSWORD }}/g" build-profile.json5
          sed -i "s/KEY_PASSWORD/${{ secrets.KEY_PASSWORD }}/g" build-profile.json5

      ### 5. 安装依赖
      - name: Install Dependencies
        run: npm install

      ### 6. 构建 Release 包
      - name: Build Release App
        run: |
          hvigorw assembleApp --mode project -p product=default -p buildMode=release

      ### 7. 上传构建产物
      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: harmonyos-app
          path: build/outputs/app/*.app

      ### 8. 通过 AGC API 上传到内测
      - name: Upload to AGC Internal Test
        if: startsWith(github.ref, 'refs/tags/')
        env:
          AGC_CLIENT_ID: ${{ secrets.AGC_CLIENT_ID }}
          AGC_CLIENT_SECRET: ${{ secrets.AGC_CLIENT_SECRET }}
        run: |
          # 使用 AGC 开放 API 自动上传
          python3 scripts/upload_to_agc.py \
            --app-id ${{ secrets.AGC_APP_ID }} \
            --file build/outputs/app/*.app

灰度发布策略

AGC 支持按比例灰度发布，新版本先推送给一部分用户，验证稳定后再全量推送：

// AGC 灰度发布流程（通过 AGC 后台配置，无需代码）
// 但应用需要上报版本信息，方便监控
// 通常结合 AGC App Messaging 向灰度用户推送新特性介绍

// 应用内版本检查（检测是否有新版本）
import { CheckUpdateCallBack } from '@hms.core.appservice'

async function checkForUpdate() {
  try {
    // 通过 AGC 更新服务检查新版本
    // 实际使用 HMS Core 的 App Update Kit
    const currentVersion = '1.0.0'
    const updateInfo = await queryUpdateInfo(currentVersion)

    if (updateInfo.forceUpdate) {
      // 强制更新：弹框要求用户立即更新，不可关闭
      showForceUpdateDialog(updateInfo)
    } else if (updateInfo.newVersion) {
      // 可选更新：提示用户有新版本，用户可选择忽略
      showOptionalUpdateDialog(updateInfo)
    }
  } catch (e) {
    // 检查失败不影响正常使用
    console.warn('版本检查失败', e)
  }
}

版本管理规范

HarmonyOS 应用有两个版本号概念，理解它们的区别对于管理版本迭代非常重要：

// AppScope/app.json5
{
  "app": {
    "bundleName": "com.example.myapp",
    "vendor": "example",
    "versionCode": 102000,      // 数字版本号，只增不减，AGC 和系统用此判断新旧
    "versionName": "1.2.0",    // 展示给用户的版本号字符串
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  }
}

// 版本号规范建议：
// versionCode = major * 1000000 + minor * 1000 + patch
// 例：1.2.0 → 1*1000000 + 2*1000 + 0 = 1002000
// 这样从 versionCode 可以直接反推版本号，便于调试

发布检查清单

课程总结

恭喜你完成了《鸿蒙 HarmonyOS NEXT 开发》全部 10 章的学习！回顾一下我们掌握的内容：

章节	核心知识	实际应用
第1章	ArkTS 语言基础、DevEco Studio、Stage 模型	搭建任何鸿蒙项目的地基
第2章	声明式 UI、装饰器、布局容器	构建所有可视化界面
第3章	AppStorage、PersistentStorage、@Observed	复杂应用的状态管理
第4章	Navigation、路由、转场动画、深链接	多页面应用导航
第5章	HTTP 请求、RDB、Preferences、沙箱	数据存取与网络通信
第6章	相机、AVPlayer、PixelMap、传感器	多媒体功能开发
第7章	分布式数据、任务迁移、设备发现	鸿蒙特色分布式体验
第8章	LazyForEach、@Reusable、Profiler	性能调优与分析
第9章	权限管理、SysCap、HUKS、服务卡片	系统级能力与安全
第10章	签名、构建、AGC 审核、CI/CD	应用交付与发布