在鸿蒙（HarmonyOS）项目中配置 GitLab CI 以实现自动构建与签名，是提升研发效能的关键步骤。结合鸿蒙的构建工具链（Hvigor）和 GitLab CI 的特性，以下是完整的实战配指南：

一、 核心前置准备

在编写流水线之前，必须解决 CI 环境下的签名问题。由于 CI 服务器无法使用 DevEco Studio 的自动签名，必须采用手动签名方案。

1. 准备签名文件：在 AppGallery Connect 获取应用对应的 .cer（证书）、.p12（密钥库）和 .p7b（Profile）文件。
2. 安全存储密钥：严禁将密码硬编码在代码中。应将签名文件内容（Base64编码）及密码存入 GitLab 项目的 Settings -> CI/CD -> Variables 中，并勾选 Masked 和 Protected。

二、 GitLab CI 配置文件 (.gitlab-ci.yml)

以下是一个标准的鸿蒙应用自动构建与签名流水线配置示例：

# 定义流水线阶段
stages:
  - build
  - sign

# 全局环境变量
variables:
  NODE_VERSION: "18"
  JAVA_VERSION: "17"

# 1. 自动构建阶段
build_hap:
  stage: build
  image: ubuntu:latest # 建议使用预装了鸿蒙 SDK 的自定义 Docker 镜像
  script:
    # 1. 安装基础依赖
    - apt update && apt install -y nodejs npm
    - npm install -g @ohos/hvigor-cli
    
    # 2. 安装项目依赖
    - ohpm install --all --lockfile_stable_order
    
    # 3. 执行 Release 模式构建（关闭 daemon 模式以节省 CI 资源）
    - hvigorw assembleHap -p buildMode=release --no-daemon
  artifacts:
    paths:
      - entry/build/default/outputs/default/entry-default-unsigned.hap
    expire_in: 1 week

# 2. 自动签名阶段
sign_hap:
  stage: sign
  image: ubuntu:latest
  script:
    # 1. 安装鸿蒙签名工具
    - npm install -g @ohos/hap-signer
    
    # 2. 从 GitLab CI 变量中解码并还原签名文件
    - echo $SIGN_KEY_BASE64 | base64 -d > release.p12
    - echo $SIGN_CERT_BASE64 | base64 -d > release.cer
    - echo $SIGN_PROFILE_BASE64 | base64 -d > release.p7b
    
    # 3. 执行 HAP 签名
    - hap-signer sign 
        --hap entry/build/default/outputs/default/entry-default-unsigned.hap 
        --key-file release.p12 
        --password $KEYSTORE_PASSWORD 
        --output entry-signed.hap
  artifacts:
    paths:
      - entry-signed.hap

三、 关键配置与工程化实践

1. 签名配置注入：
   除了使用 hap-signer 命令行工具外，你也可以在项目的 build-profile.json5 中配置 signingConfigs，并通过环境变量动态注入密码，让构建工具在打包时自动完成签名。
2. 构建性能优化：
   在 CI 环境中，务必添加 --no-daemon 参数。因为 CI 通常是短暂的隔离容器，常驻的 daemon 进程没有复用价值，反而会占用内存或引发缓存冲突。同时，可以结合 GitLab 的缓存机制缓存 oh_modules 和 build 目录，以支持增量编译。
3. 触发时机控制：
   通过 only 或 rules 关键字限制流水线的触发条件。例如，仅在代码合入 main 分支或打 Tag 时才执行签名和发布，而在普通的 Merge Request 中仅执行代码检查（Lint）和单元测试。
4. 发布前自检：
   在签名完成后，建议增加一个校验步骤，使用 hap-signer verify 或生成 SHA256 哈希值进行比对，确保产物的完整性，防止分发过程中被篡改。

四、 安全与合规扩展：流水线集成代码规范与上架预检

在构建与签名之间，必须加入质量与安全门禁，防止带有严重缺陷或安全漏洞的代码流入生产环境。

# 在 build 和 sign 之间插入质量门禁阶段
stages:
  - build
  - quality-gate  # 新增质量门禁阶段
  - sign

# 1. 集成代码规范检测（Code Linter）
code-lint:
  stage: quality-gate
  script:
    # 使用鸿蒙官方 codelinter 命令行工具进行静态代码检查
    # 发现严重规范问题将直接中断流水线
    - codelinter check --format json --output lint-report.json
  artifacts:
    reports:
      codequality: lint-report.json

# 2. 上架预检测试（Pre-release Test）
pre-release-test:
  stage: quality-gate
  script:
    # 调用 DevEco Testing 进行上架预检测试，模拟应用市场审核标准
    # 验证权限声明、隐私合规等关键项，提升上架审核通过率
    - deveco test --testType preRelease --report html
  artifacts:
    paths:
      - pre-release-report.html

五、 测试扩展：多设备并发与分布式自动化测试

利用 GitLab CI 的动态变量注入能力，结合鸿蒙的分布式测试框架，实现多终端的并发验证。

# 自动化分布式测试阶段
harmonyos-e2e-test:
  stage: quality-gate
  image: harmonyos/deveco-cli:5.1
  script:
    # 通过 GitLab CI 变量动态注入设备矩阵，实现手机、平板、智慧屏的并发测试
    - deveco test --deviceMatrix device-cluster.json --testType e2e
    # 执行 UI 自动化测试用例（基于 Hypium 框架）
    - deveco test --run hypium-tests/
  artifacts:
    paths:
      - e2e-test-report.json
      - performance-report.json

六、 安全加固扩展：二进制级防逆向与防篡改

在签名完成后，引入第三方安全加固工具，对核心资产进行字节级加密，防止应用被逆向分析或二次打包。

# 应用安全加固阶段
app-armor:
  stage: sign
  script:
    # 调用第三方安全加固 SDK 对签名后的 HAP 包进行字节码加密
    # 开启防动态调试、内存防篡改及 SO 库保护
    - bangcle-armor-cli \
        --input entry-signed.hap \
        --output entry-secured.hap \
        --config armor-config.json
  artifacts:
    paths:
      - entry-secured.hap

七、 多端协同扩展：跨平台统一构建流水线

针对鸿蒙 5+ 支持多端协同的特性，结合 Unity 等跨平台引擎或原生 ArkTS，实现“一次提交，多端构建”。

# 跨端统一构建流水线示例
multi-platform-build:
  stage: build
  script:
    # 1. 触发鸿蒙原生端构建
    - hvigorw assembleHap -p buildMode=release --no-daemon
    
    # 2. 触发 Unity 鸿蒙端构建（如适用）
    # 自动检测 @ohos.env 标记，生成智慧屏或手机端安装包
    - unity-cloud-build --platform HarmonyOS --targetSdkVersion 5.0
  artifacts:
    paths:
      - entry/build/default/outputs/default/*.hap
      - unity-build/outputs/*.apk

八、 企业级 CI/CD 最佳实践总结

1. 密钥全生命周期管理：生产环境的签名私钥（.p12）应尽可能接入企业级 KMS（密钥管理服务）或 HSM（硬件安全模块），避免 Base64 明文存储在 GitLab 变量中。
2. 流水线性能调优：除了 --no-daemon，应充分利用 GitLab CI 的 cache 机制缓存 oh_modules、hvigor 缓存及编译中间产物，将增量构建时间缩短 50% 以上。
3. AI 辅助研发集成：在流水线中接入鸿蒙 AI 辅助研发工具（如 Harmony Trace Analyzer），在每次性能测试后自动生成 Trace 分析报告，精准定位性能瓶颈。
4. 发布策略自动化：结合 GitOps 理念，签名加固后的产物自动推送至内部制品库，并通过 FluxCD 等工具触发灰度发布或金丝雀部署，实现从代码提交到多端上线的全链路自动化闭环。