CI/CD流水线设计：ArkUI-X自动构建HAP/APK/IPA并分发至华为AppGallery/TestFlight

爱学习的小齐哥哥

发布于 2025-6-17 15:00

浏览

0收藏

引言

在跨端应用开发中，持续集成/持续部署（CI/CD）是提升研发效率、保障发布质量的核心环节。对于同时覆盖鸿蒙（HAP）、安卓（APK）、iOS（IPA）多端的电商/社交类应用，传统人工构建+手动分发的模式已难以满足敏捷开发需求。本文将基于ArkUI-X（鸿蒙跨端UI框架）的特性，设计一套完整的CI/CD流水线，实现从代码提交到多端包构建、测试、分发的自动化流程，并重点解决多端构建差异、分发流程自动化、环境安全管控三大核心问题。

一、CI/CD流水线核心目标
阶段目标

代码拉取自动触发构建（如PR提交/定时构建）
依赖安装统一管理多端依赖（ArkTS/Java/Swift），避免环境不一致
构建打包生成HAP（鸿蒙）、APK（安卓）、IPA（iOS）安装包
质量测试执行单元测试、UI测试、性能测试，拦截缺陷
分发部署自动上传至华为AppGallery、TestFlight，生成发布报告

二、流水线架构设计（以GitHub Actions为例）

2.1 整体流程图

graph TD
A[代码提交/PR] --> B[触发CI流水线]
–> C[环境检查]

–> D[依赖安装（pnpm）]

–> E[多端构建（HAP/APK/IPA）]

–> F[单元测试（ArkTS/Java/Swift）]

–> G[UI测试（ArkUI自动化）]

–> H[性能测试（内存/CPU）]

–> I[打包归档]

–> J[分发部署]

–> K[华为AppGallery上传]

–> L[TestFlight上传]

–> M[生成发布报告]

–> M

三、关键阶段实现细节

3.1 环境准备与依赖安装

3.1.1 基础环境配置
操作系统：Ubuntu 22.04（兼容多端构建工具）

必备工具：Node.js 18+、pnpm 8+、Android SDK（API 33+）、Xcode 15+（仅macOS节点）、Ohos SDK（鸿蒙开发工具链）

权限管理：通过GitHub Secrets存储敏感信息（如AppGallery API Key、TestFlight账号密码）

3.1.2 依赖安装脚本（.github/workflows/ci.yml）

jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest] # 覆盖安卓/iOS构建
steps:
name: Checkout code

    uses: actions/checkout@v4

    uses: pnpm/action-setup@v2
    with:
      version: 8.10.0

    uses: actions/setup-node@v4
    with:
      node-version: 18.x
      cache: 'pnpm'

    run: pnpm install
    env:
      # 共享公共依赖缓存（减少重复下载）
      PPNPM_CACHE_DIR: ~/.pnpm-store

3.2 多端构建：HAP/APK/IPA生成

3.2.1 鸿蒙HAP构建（Ubuntu节点）

ArkUI-X支持通过ohpm（鸿蒙包管理器）和hdc（鸿蒙调试工具）完成HAP构建：
name: Build HAP (HarmonyOS)

if: runner.os == ‘Linux’
run: |
# 安装鸿蒙SDK（需提前在GitHub Runner中配置）
wget https://repo.huaweicloud.com/harmonyos-sdk/1.0.0/harmonyos-sdk-1.0.0-linux.tar.gz
tar -xzf harmonyos-sdk-1.0.0-linux.tar.gz -C ~/

# 配置环境变量
export OHOS_SDK_HOME=~/harmonyos-sdk
export PATH=OHOS_SDK_HOME/bin:PATH

# 使用ArkUI-X CLI构建HAP
arkui-x build --platform harmony --output ./dist/hap

3.2.2 安卓APK构建（Ubuntu节点）

通过Gradle执行安卓构建，需确保Gradle缓存和Android SDK路径正确：
name: Build APK (Android)

if: runner.os == ‘Linux’
run: |
cd apps/android-app
./gradlew clean assembleDebug
# 输出APK路径：./app/build/outputs/apk/debug/app-debug.apk

3.2.3 iOS IPA构建（macOS节点）

通过Xcode CLI工具xcodebuild构建IPA，需配置Apple Developer账号：
name: Build IPA (iOS)

if: runner.os == ‘macOS’
env:
APPLE_DEVELOPER_ACCOUNT: ${{ secrets.APPLE_DEV_ACCOUNT }}
APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
run: |
cd apps/admin-system/ios # 假设iOS项目在admin-system目录
xcodebuild -workspace AdminSystem.xcworkspace
-scheme AdminSystem
-configuration Release
-archivePath ./build/AdminSystem.xcarchive
archive
xcodebuild -exportArchive
-archivePath ./build/AdminSystem.xcarchive
-exportPath ./build/AdminSystem.ipa
-exportOptionsPlist exportOptions.plist

3.3 质量测试：自动化验证

3.3.1 单元测试
ArkTS：使用jest或vitest测试业务逻辑

Java（安卓）：使用JUnit 5+Mockito测试工具类

Swift（iOS）：使用XCTest测试视图控制器

run: |
# 鸿蒙ArkTS测试
cd packages/common-utils
pnpm test

# 安卓Java测试
cd apps/android-app
./gradlew testDebugUnitTest

# iOS Swift测试（macOS节点）
cd apps/admin-system/ios
xcodebuild -workspace AdminSystem.xcworkspace \
           -scheme AdminSystemTests \
           -destination 'platform=iOS Simulator,name=iPhone 15' \
           test

3.3.2 UI自动化测试（ArkUI-X）

使用@ohos.arkui.test框架编写E2E测试，模拟用户操作：
// 示例：登录流程测试
import { test, expect } from ‘@ohos.arkui.test’;

test(‘Login Flow Test’, async () => {
// 启动应用
await launchApp(‘com.example.ecommerce’);

// 输入用户名/密码
await inputText(‘#usernameInput’, ‘test_user’);
await inputText(‘#passwordInput’, ‘test_password’);

// 点击登录按钮
await click(‘#loginButton’);

// 验证首页是否加载
await expect(element(‘#homeBanner’)).toBeVisible();
});

3.4 分发部署：自动化上传

3.4.1 华为AppGallery上传

通过华为提供的agc-api SDK实现自动化上传，需提前在AppGallery创建应用并获取appId和apiKey：
name: Upload to Huawei AppGallery

if: runner.os == ‘Linux’
run: |
# 安装agc-cli工具
npm install -g @agconnect/cli

# 配置认证信息（从Secrets获取）
agc config set authType apiKey
agc config set apiKey ${{ secrets.APPGALLERY_API_KEY }}

# 上传HAP包
agc app upload \
  --appId ${{ secrets.APPGALLERY_APP_ID }} \
  --file ./dist/hap/com.example.ecommerce.hap \
  --version 1.0.0 \
  --releaseNote "CI/CD自动构建版本"

3.4.2 TestFlight上传（iOS）

通过fastlane工具自动化上传IPA到TestFlight，需提前配置Fastfile：
name: Upload to TestFlight

if: runner.os == ‘macOS’
run: |
# 安装fastlane
gem install fastlane

# 配置Apple账号（从Secrets获取）
fastlane app_store_connect_api_key \
  --key_id ${{ secrets.APP_STORE_CONNECT_KEY_ID }} \
  --issuer_id ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }} \
  --key_filepath ./fastlane/AuthKey.p8

# 上传IPA
cd apps/admin-system/ios/build
fastlane upload_to_testflight \
  --ipa ./AdminSystem.ipa \
  --skip_waiting_for_build_processing true

四、安全与优化策略

4.1 敏感信息保护
Secrets管理：所有敏感信息（如API Key、Apple账号）通过GitHub Secrets存储，避免硬编码。

权限最小化：CI Runner仅授予必要的文件读写权限，禁止访问无关目录。

构建日志脱敏：通过actions/upload-artifact上传日志时，过滤token、password等关键词。

4.2 构建缓存优化
依赖缓存：使用pnpm cache缓存公共依赖，减少重复下载（配置PNPM_CACHE_DIR）。

构建产物缓存：对未变更的模块（如common-ui）缓存构建结果，加速增量构建。

Docker镜像缓存：预构建包含Android SDK、Xcode的工具镜像，避免重复安装。

4.3 失败处理与通知
自动重试：对网络波动敏感的步骤（如上传AppGallery）添加重试机制（retry: 3）。

即时通知：通过slack/webhook或企业微信机器人推送构建结果，失败时@相关责任人。

日志归档：将构建日志、测试报告上传至对象存储（如华为OBS），保留至少30天。

五、完整示例：GitHub Actions配置文件

on:
push:
branches: [ main ]
pull_request:
branches: [ main ]

jobs:
build-test-deploy:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, macos-latest]
steps:
name: Checkout Code

    uses: actions/checkout@v4

    uses: pnpm/action-setup@v2
    with:
      version: 8.10.0

    uses: actions/setup-node@v4
    with:
      node-version: 18.x
      cache: 'pnpm'

    run: pnpm install

  # 鸿蒙HAP构建（仅Ubuntu）

    if: runner.os == 'Linux'
    run: |
      wget https://repo.huaweicloud.com/harmonyos-sdk/1.0.0/harmonyos-sdk-1.0.0-linux.tar.gz
      tar -xzf harmonyos-sdk-1.0.0-linux.tar.gz -C ~/
      export OHOS_SDK_HOME=~/harmonyos-sdk
      export PATH=OHOS_SDK_HOME/bin:PATH
      arkui-x build --platform harmony --output ./dist/hap

  # 安卓APK构建（仅Ubuntu）

    if: runner.os == 'Linux'
    run: |
      cd apps/android-app
      ./gradlew clean assembleDebug

  # iOS IPA构建（仅macOS）

    if: runner.os == 'macOS'
    env:
      APPLE_DEVELOPER_ACCOUNT: ${{ secrets.APPLE_DEV_ACCOUNT }}
      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
    run: |
      cd apps/admin-system/ios
      xcodebuild -workspace AdminSystem.xcworkspace \
                 -scheme AdminSystem \
                 -configuration Release \
                 -archivePath ./build/AdminSystem.xcarchive \
                 archive
      xcodebuild -exportArchive \
                 -archivePath ./build/AdminSystem.xcarchive \
                 -exportPath ./build/AdminSystem.ipa \
                 -exportOptionsPlist exportOptions.plist

  # 单元测试

    run: |
      cd packages/common-utils && pnpm test
      cd ../android-app && ./gradlew testDebugUnitTest
      cd ../../apps/admin-system/ios && xcodebuild -workspace AdminSystem.xcworkspace -scheme AdminSystemTests -destination 'platform=iOS Simulator,name=iPhone 15' test

  # UI测试（示例）

    run: |
      cd packages/common-ui/tests
      pnpm test:arkui

  # 上传华为AppGallery

    if: runner.os  'Linux' && github.ref  'refs/heads/main'
    run: |
      npm install -g @agconnect/cli
      agc config set authType apiKey
      agc config set apiKey ${{ secrets.APPGALLERY_API_KEY }}
      agc app upload \
        --appId ${{ secrets.APPGALLERY_APP_ID }} \
        --file ./dist/hap/com.example.ecommerce.hap \
        --version 1.0.0 \
        --releaseNote "Auto-built by CI/CD"

  # 上传TestFlight（iOS）

    if: runner.os  'macOS' && github.ref  'refs/heads/main'
    run: |
      gem install fastlane
      cd apps/admin-system/ios/build
      fastlane upload_to_testflight \
        --ipa ./AdminSystem.ipa \
        --skip_waiting_for_build_processing true

六、总结

通过本文设计的CI/CD流水线，可实现：
多端统一构建：基于ArkUI-X的跨端能力，自动化生成HAP/APK/IPA三种安装包。

质量全链路保障：覆盖单元测试、UI测试、性能测试，拦截90%以上的低级错误。

分发效率提升：华为AppGallery和TestFlight的上传流程完全自动化，发布周期从"天"缩短至"分钟级"。

安全可控：敏感信息通过Secrets管理，构建日志和产物可追溯，符合企业级安全要求。

未来可进一步扩展流水线功能，例如：
集成性能监控（如华为APM、Firebase Performance）；

自动触发灰度发布（通过AppGallery的灰度策略API）；

支持多版本并行构建（通过矩阵策略扩展）。

分类

HarmonyOS

ArkUI / eTS

OpenHarmony