持续集成实战：GitLab + HarmonyOS 5 RN 应用的自动化构建（附完整配置）

在智能座舱、物联网设备等场景中，HarmonyOS 5 的 React Native（RN）应用需快速迭代并保证质量。GitLab CI/CD 作为自动化构建与部署的核心工具，可高效串联「代码提交→编译→测试→打包→发布」全流程。本文结合 HarmonyOS 5 RN 应用特性，实战搭建一套 自动化构建流水线，覆盖编译、测试、打包、部署四大环节，代码可直接复用。

一、环境准备与工具链
前置条件

GitLab 环境：企业版/社区版 GitLab（建议 14.0+），已安装 GitLab Runner（推荐使用 shell 或 docker 执行器）。

开发环境：

DevEco Studio 5.0+（HarmonyOS 官方 IDE，用于本地调试）；

Node.js 18+（RN 依赖）；

Java 11+（HarmonyOS 原生模块编译）；

Gradle 7.5+（Android 构建工具）。
关键依赖安装

在 GitLab Runner 执行器（如 Linux 服务器）中安装以下工具：
安装 Node.js 18

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

安装 Java 11

sudo apt-get install -y openjdk-11-jdk

安装 Gradle 7.5

wget https://services.gradle.org/distributions/gradle-7.5-bin.zip
sudo unzip gradle-7.5-bin.zip -d /opt/gradle
sudo ln -s /opt/gradle/gradle-7.5/bin/gradle /usr/bin/gradle

安装 HarmonyOS SDK（需登录华为开发者账号）

参考：https://developer.harmonyos.com/cn/develop/deveco-studio/#download-sdk

二、GitLab CI/CD 核心流程设计
流程概览

graph TD
A[代码提交] --> B[CI 触发]
–> C[安装依赖]

–> D[编译原生模块]

–> E[打包 RN JS Bundle]

–> F[运行单元测试]

–> G[集成测试（可选）]

–> H[生成安装包（APK/HAP）]

–> I[上传制品库]

–> J[部署测试/生产环境]

关键配置：.gitlab-ci.yml

在项目根目录创建 .gitlab-ci.yml，定义构建流水线的阶段与任务。以下是针对 HarmonyOS 5 RN 应用的完整配置：

.gitlab-ci.yml

stages:
install_deps

build_native

build_rn_bundle

test

package

deploy

全局变量（根据实际环境调整）

variables:
ANDROID_SDK_PATH: “/opt/android-sdk” # Android SDK 路径
GRADLE_CACHE_DIR: “${CI_PROJECT_DIR}/.gradle” # Gradle 缓存目录
NODE_MODULES_CACHE: “${CI_PROJECT_DIR}/node_modules” # Node.js 依赖缓存
HARMONYOS_SDK_PATH: “/opt/harmonyos-sdk” # HarmonyOS SDK 路径

缓存策略（加速构建）

cache:
key: ${CI_COMMIT_REF_SLUG}
paths:
${NODE_MODULES_CACHE}

${GRADLE_CACHE_DIR}

阶段1：安装 Node.js 与 RN 依赖

install_deps:
stage: install_deps
image: node:18-alpine # 轻量级镜像
script:
npm install --registry=https://registry.npm.taobao.org # 使用淘宝镜像加速

artifacts:
paths:
node_modules/

阶段2：编译 HarmonyOS 原生模块（Java/Kotlin）

build_native:
stage: build_native
image: openjdk:11-jdk # 需 Java 环境
needs: [install_deps]
script:
# 初始化 HarmonyOS SDK 环境变量
export ANDROID_HOME=${ANDROID_SDK_PATH}

export HARMOONYOS_SDK_HOME=${HARMONYOS_SDK_PATH}

# 编译原生模块（假设项目使用 Gradle 构建）

cd entry/src/main/java # 进入原生代码目录

gradle clean assembleDebug # 编译 Debug 版本

artifacts:
paths:
entry/build/outputs/apk/debug/ # 保存编译后的 APK

阶段3：打包 React Native JS Bundle

build_rn_bundle:
stage: build_rn_bundle
image: node:18-alpine
needs: [install_deps]
script:
# 进入 RN 项目根目录
cd ${CI_PROJECT_DIR}

# 打包 JS Bundle（HarmonyOS RN 需指定编译参数）

npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output ./android/app/src/main/assets/index.android.bundle --assets-dest ./android/app/src/main/res/

artifacts:
paths:
android/app/src/main/assets/index.android.bundle # 保存 JS Bundle

阶段4：运行单元测试（RN 逻辑 + 原生模块）

test:
stage: test
image: node:18-alpine
needs: [install_deps, build_native]
script:
# 运行 RN 单元测试（使用 Jest）
cd ${CI_PROJECT_DIR}

npm test – --coverage # 生成覆盖率报告

# 运行原生模块单元测试（Java）

cd entry/src/test/java

gradle testDebugUnitTest # 执行 Gradle 测试任务

artifacts:
reports:
junit: entry/build/test-results/testDebugUnitTest/*.xml # 上传测试报告
cobertura: coverage.xml # 上传覆盖率报告

阶段5：生成安装包（APK/HAP）

package:
stage: package
image: openjdk:11-jdk
needs: [build_native, build_rn_bundle]
script:
# 合并 JS Bundle 到 APK（HarmonyOS RN 打包命令）
cd entry

./gradlew assembleRelease -PenableHermes=true # 启用 Hermes 优化

artifacts:
paths:
entry/build/outputs/apk/release/ # 保存最终 APK/HAP

expire_in: 1 week  # 制品保留1周

阶段6：部署到测试服务器（可选）

deploy_test:
stage: deploy
image: alpine:latest
needs: [package]
only:
main # 仅主分支触发

script:
# 上传 APK 到测试服务器（使用 scp 或 HTTP API）
apk_path=$(ls entry/build/outputs/apk/release/*.apk)

scp $apk_path root@test-server:/data/apps/

environment:
name: test
url: http://test-server/apps/

三、关键技术细节解析
HarmonyOS RN 构建适配

Hermes 引擎优化：在 build.gradle 中启用 Hermes 编译（enableHermes: true），可提升 JS 执行效率 20%+。

多端资源隔离：通过 productFlavors 区分车机/手机/平板的资源配置（如屏幕尺寸、权限）。

// build.gradle（示例）

android {
flavorDimensions “device”
productFlavors {
car {
dimension “device”
resValue “string”, “app_name”, “车机导航”
manifestPlaceholders = [permissions: “ohos.permission.SENSOR_HEALTH”]
phone {

    dimension "device"
    resValue "string", "app_name", "手机导航"
    manifestPlaceholders = [permissions: "android.permission.ACCESS_FINE_LOCATION"]

}

缓存优化

Node.js 依赖缓存：通过 cache 字段缓存 node_modules，避免重复下载。

Gradle 缓存：复用本地 Gradle 缓存目录（~/.gradle），加速编译过程。
测试集成

RN 单元测试：使用 Jest 框架测试 JS 逻辑（如组件交互、状态管理）。

原生模块测试：通过 Gradle 的 testDebugUnitTest 任务执行 Java/Kotlin 单元测试。

四、常见问题与解决方案
问题类型 现象描述 解决方案
原生模块编译失败 gradle assembleDebug 报错 检查 build.gradle 依赖版本是否与 HarmonyOS SDK 兼容；清理 build 目录后重试。
JS Bundle 打包超时 react-native bundle 超过 CI 超时限制 增加 --max-workers 参数限制并行线程数；使用 --dev false 关闭调试模式。
测试报告无法上传 GitLab 未显示覆盖率数据 确保 junit 和 cobertura 插件已正确安装；检查 artifacts 路径是否正确。

五、扩展优化建议
质量门禁：集成 SonarQube 扫描代码，设置「测试覆盖率≥80%」才能合并代码。

多环境部署：通过 GitLab 的 environments 功能，区分测试/预发布/生产环境，自动触发不同部署流程。

增量构建：利用 changes 关键字仅对修改的文件执行构建（如仅修改 RN 代码时跳过原生编译）。

总结

通过 GitLab CI/CD 与 HarmonyOS 5 RN 应用的深度集成，可实现「代码提交→自动化构建→测试→部署」的全流程闭环，显著提升开发效率与应用质量。核心要点是：
环境适配：正确配置 HarmonyOS SDK 与 Gradle 环境；

缓存优化：复用依赖与编译结果，加速流水线；

测试覆盖：集成单元测试与覆盖率统计，保障代码质量。