【拥抱鸿蒙】基于 Cocos Creator 的 HarmonyOS 自动构建

概述

随着 Cocos Creator 新版本的发布，开发者们迎来了一个令人振奋的消息：Cocos Creator 现已支持发布到 HarmonyOS 平台。这为游戏开发者和应用开发者开辟了新的天地，使他们能够利用 HarmonyOS 的强大功能和生态优势，将作品推向更广阔的市场。

然而，传统的手动构建方式在面对频繁的版本迭代和复杂的项目管理时，往往效率低下且容易出错。为了提高开发效率，实现高效、稳定的构建与发布流程，我们迫切需要一种自动化解决方案。

幸运的是，华为官方提供了一套功能强大的命令行工具，包括 hvigor、ohpm、hdc 等，这些工具为自动化构建提供了坚实的基础。借助这些工具，我们可以通过编写脚本，轻松实现自动构建的流程。

本文将详细介绍如何使用 bash 脚本，在 Jenkins 构建平台上实现 HarmonyOS 的自动构建与发布。

在开始之前，我们需要明确构建机的环境配置，以确保整个构建流程能够顺利进行。以下是构建机的环境要求：

Cocos Creator 的版本：v2.4.14（目前官方 2.x 最新版本）或 v3.8.6（目前官方 3.x 最新版本）；
DevEco Studio 版本：5.0.0 release（Mac）；
SDK 版本：API 17（HarmonyOS NEXT Developer）。

获取命令行工具

下载与安装

访问华为开发者网站：前往华为 Developer 网站下载中心，搜索并下载最新版本的命令行工具 Command Line Tools for HarmonyOS NEXT Developer Beta1（5.0.3.404）。
解压并配置环境变量：将下载的工具包解压后，将以下环境变量添加到 ~/.bash_profile（bash）或 ~/.zshrc（zsh）中：
```
export PATH=~/command-line-tools/bin:$PATH
```
配置完成后，使用以下命令使环境变量生效：
```
source ~/.bash_profile
```
或
```
source ~/.zshrc
```

配置 hvigor

hvigor 是一套基于任务管理机制的自动化构建工具，它为 HarmonyOS OS 应用的 JS/eTS 开发场景提供了任务注册编排、编译工程模型管理、编译配置定制以及插件扩展等核心能力。hvigor 的结构化模型由 build-profile.json5 和 hvigorfile.js 组成，其工程结构如下：

rootProject                        // Hvigor 工程根目录

├── build-profile.json5            // 工程级别 Hvigor 配置，主要配置工程相关信息，包括子模块名字、路径等。

├── hvigorfile.js                  // 工程级别任务脚本，当前暂不支持自定义

├── moduleA

│   ├── build-profile.json5  // 模块级别 Hvigor 配置，主要模块构建相关参数

│   └── hvigorfile.js        // 模块级别任务脚本，当前暂不支持自定义

└── moduleB

    ├── build-profile.json5       // 模块级别 Hvigor 配置，主要模块构建相关参数

    └── hvigorfile.js             // 模块级别任务脚本，当前暂不支持自定义

在实际使用中，我们可以通过 hvigorw 命令来调用 hvigor 的功能，其基本使用格式为：

hvigorw [taskNames...] <options>

例如，我们可以使用 hvigorw clean 来清理构建环境，或者使用 hvigorw assembleHap 来生成 HAP 文件。

编写自动构建脚本

为了实现自动构建，我们需要编写一个完整的 bash 脚本，该脚本将涵盖从环境配置到最终构建的全过程。以下是脚本的详细内容：

1. 配置环境

（1）下载并配置 Node.js

Node.js 是一个基于 Chrome V8 引擎的 JavaScript 运行环境，它在构建过程中用于运行各种工具和脚本。以下是配置 Node.js 的脚本：

init_Node() {

  if [ ! -d "${NODE_HOME}" ]; then

     mkdir "${NODE_HOME}"

  fi

  cd ${NODE_HOME}

  wget --no-check-certificate -q "${node下载路径}" -O node-linux.tar.xz #下载node，需要替换node下载路径

  tar -vxf node-linux.tar.xz

  NODE_DIR=xxx #node压缩包文件里面的目录

  cd ${NODE_DIR}

  mv -f ./* .[^.]* ../

  cd ..

  rm -rf NODE_DIR node-linux.tar.xz

  export NODE_HOME=${NODE_HOME}

  export PATH=$NODE_HOME/bin:$PATH

  node -v

  npm config set registry=https://repo.huaweicloud.com/repository/npm/

  npm config set @ohos:registry=https://repo.harmonyos.com/npm/ 

  npm config get @ohos:registry

  npm config set proxy=http://user:password@proxy.server.com:port  #配置npm http代理，企业网络受限的情况下需要配置

  npm config set https-proxy=http://user:password@proxy.server.com:port  #配置npm https代理，企业网络受限的情况下需要配置

  npm info express

}

（2）下载并配置 JDK

JDK（Java Development Kit）是 Java 语言的软件开发工具包，它在构建过程中用于编译和运行 Java 代码。以下是配置 JDK 的脚本：

init_JDK() {

  if [ ! -d "${JAVA_HOME}" ]; then

     mkdir "${JAVA_HOME}"

  fi

  cd ${JAVA_HOME}

  wget --no-check-certificate -q "${jdk下载路径}" -O jdk-linux.tar.xz #下载jdk，需要替换jdk下载路径

  tar -vxf jdk-linux.tar.xz

  JDK_DIR=xxx #jdk压缩包文件里面的目录

  cd ${JDK_DIR}

  mv -f ./* .[^.]* ../

  cd ..

  rm -rf JDK_DIR jdk-linux.tar.xz

  export JAVA_HOME=${JAVA_HOME}

  export PATH=$JAVA_HOME/bin:$PATH

  java -version

  check "JDK install"

}

（3）配置 HarmonyOS SDK

HarmonyOS SDK 是开发 HarmonyOS 应用的核心工具包，它提供了必要的编译工具和运行时环境。以下是配置 SDK 的脚本：

init_SDK() {

  ./${COMMANDLINE_TOOL_DIR}/bin/sdkmgr install HarmonyOS-NEXT/DB1 --sdk-directory="/opt/HarmonyOS/SDK/" --accept-license

  #设置hdc工具的环境变量，hdc工具在toolchains所在路径下，请以实际路径为准

  export PATH=$HDC_HOME:$PATH

  export HDC_HOME=/opt/HarmonyOS/SDK/HarmonyOS-NEXT-DB1/base/toolchains

  export HOS_SDK_HOME=${HOS_SDK_HOME}

  check "SDK install"

}

（4）安装 ohpm

ohpm 是 HarmonyOS 的包管理工具，用于管理和安装项目依赖。以下是安装 ohpm 的脚本：

init_ohpm() {

    # 初始化ohpm

    OHPM_HOME=${COMMANDLINE_TOOL_DIR}/command-line-tools/ohpm

    export PATH=${OHPM_HOME}/bin:$PATH

    ohpm -v

    # 配置ohpm仓库地址

    ohpm config set registry=https://ohpm.HarmonyOS.cn/ohpm/

}

2. 同步代码

synccode() {

  PRO_PATH=$1; PRO_NAME=$2; REPO_URL=$3; BRAN_NAME=$4;

  if [ ! -d $PRO_PATH ]; then

    #新创建 Clone

    echo "mkdir $PRO_PATH && cd $PRO_PATH && git clone -b $BRAN_NAME $REPO_URL $PRO_NAME && cd $PRO_NAME"

    mkdir $PRO_PATH && \

    cd $PRO_PATH && \

    git clone -b $BRAN_NAME $REPO_URL $PRO_NAME && \

    cd $PRO_NAME

    check "Git clone"

  else

    local NEW_PATH=${PRO_PATH}${PRO_NAME}

    if [ ! -d ${NEW_PATH} ]; then

      #新分支 Clone

      echo "cd $PRO_PATH && git clone -b $BRAN_NAME $REPO_URL $PRO_NAME && cd $PRO_NAME"

      cd $PRO_PATH && git clone -b $BRAN_NAME $REPO_URL $PRO_NAME && cd $PRO_NAME

    else

      #原分支 Checkout & Pull

      echo "cd $PRO_PATH$PRO_NAME && git checkout . && git clean -df && git checkout -B $BRAN_NAME origin/$BRAN_NAME && git pull"

      cd $PRO_PATH$PRO_NAME && \

      git checkout . && \

      git clean -df && \

      git checkout -B $BRAN_NAME origin/$BRAN_NAME && \

      git pull

      if [[ ${VERSION_FLAG} != "X" ]]; then

        echo "checkout 指定版本：${VERSION_FLAG}"

        git checkout ${VERSION_FLAG}

      fi

      check "Git checkout & pull"

    fi

  fi

}

3. 从Cocos Creator导出HarmonyOS工程

cocosbuild() {

  local COCOS_APP_PATH="/Applications/CocosCreator/Creator/${COCOS_VERSION}/CocosCreator.app/Contents/MacOS/CocosCreator"

  echo "$COCOS_APP_PATH --project $1 --build configPath=./buildConfig/buildConfig_harmonryos.json"

  $COCOS_APP_PATH \

  --project $1 \

  --build configPath=./buildConfig/buildConfig_harmonryos.json

  check "Cocos build"

}

4. 运行Gulp

rungulp() {

    RES_VERSION=$1

    echo "/usr/local/bin/npm install"

    /usr/local/bin/npm install

    echo "/usr/local/bin/gulp --ver $RES_VERSION --platform harmonryos"

    /usr/local/bin/gulp --ver $RES_VERSION --platform harmonryos

    echo "rm -rf build/harmonryos/data/assets"

    rm -rf build/harmonryos/data/assets

    echo "cp -r remote-assets/hall/$RES_VERSION/assets build/harmonryos/data/"

    cp -r remote-assets/hall/$RES_VERSION/assets build/harmonryos/data/

    echo "cp -r remote-assets/hall/$RES_VERSION/src build/harmonryos/data/"

    cp -r remote-assets/hall/$RES_VERSION/src build/harmonryos/data/

    echo "/usr/local/bin/gulp copyCertificate --platform harmonryos"

    /usr/local/bin/gulp copyCertificate --platform harmonryos

    check "Run Gulp"

}

5. 构建出包

buildHAP() {

    # 根据业务情况适配local.properties

    cd ${PROJECT_PATH}

    echo "hwsdk.dir=${HOS_SDK_HOME}"  > ./local.properties

    # 根据业务情况安装ohpm三方库依赖

    ohpm_install "${PROJECT_PATH}"

    ohpm_install "${PROJECT_PATH}/entry"

    ohpm_install "${PROJECT_PATH}/xxx"

    # 如果构建过程报错 ERR_PNPM_OUTDATED_LOCKFILE，需要增加配置：lockfile=false, 根据node版本选择设置方式：

    # node.version<18

    npm config set lockfile=false # 如果执行此命令报错，建议直接在镜像的.npmrc文件中需要增加一行配置：lockfile=false

    # node.version>=18

    #cat ${HOME}/.npmrc | grep 'lockfile=false' || echo 'lockfile=false' >> ${HOME}/.npmrc

    # 根据业务情况，采用对应的构建命令，可以参考IDE构建日志中的命令

    cd ${PROJECT_PATH}

    chmod +x hvigorw

    ./hvigorw clean --no-daemon

    ./hvigorw assembleHap --mode module -p product=default -p debuggable=false --no-daemon # 流水线构建命令建议末尾加上--no-daemon

    check "Hap Build"

}

install_hap() {

    hdc file send "${PROJECT_PATH}/entry/build/default/outputs/default/entry-default-signed.hap" "data/local/tmp/entry-default-signed.hap"

    hdc shell bm install -p "data/local/tmp/entry-default-signed.hap"

    hdc shell rm -rf "data/local/tmp/entry-default-signed.hap"

    hdc shell aa start -a MainAbility -b com.example.myapplication -m entry

    check "HAP install"

}

# 使用ohpm发布har

upload_har() {

  ohpm publish pkg.har

}

6. 移动文件到WorkSpace

movehap() {

  local TARGET_HAP_NAME=${AUTO_BUILD_NUMBER}_${JOB_NAME}_${BUILD_VERSION}_${RES_VERSION}_${NET_MODE}_by_${USER_NAME}

  local TARGET_HAP_PATH=$HOME/Desktop/Jenkins/Workspace/${JOB_NAME}/${TARGET_HAP_NAME}.hap

  local ORIGIN_HAP_PATH=${1}/Project/build/harmonryos/proj/build/Debug/${PROJ_NAME}.hap

  echo "cp ${ORIGIN_HAP_PATH} ${TARGET_HAP_PATH}"

  cp ${ORIGIN_HAP_PATH} ${TARGET_HAP_PATH}

  check "Move hap"

}

以上，就是整个自动构建的流程。

我是郑知鱼，欢迎大家讨论与指教。

如果你觉得有所收获，也请点赞收藏️关注我吧~~