在鸿蒙（HarmonyOS）项目中配置 GitLab CI 以实现自动构建与签名，是提升研发效能的关键步骤。结合鸿蒙的构建工具链（Hvigor）和 GitLab CI 的特性，以下是完整的实战配指南：
一、 核心前置准备
在编写流水线之前，必须解决 CI 环境下的签名问题。由于 CI 服务器无法使用 DevEco Studio 的自动签名，必须采用手动签名方案。
- 准备签名文件：在 AppGallery Connect 获取应用对应的
.cer（证书）、.p12（密钥库）和.p7b（Profile）文件。 - 安全存储密钥：严禁将密码硬编码在代码中。应将签名文件内容（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三、 关键配置与工程化实践
- 签名配置注入：
除了使用hap-signer命令行工具外，你也可以在项目的build-profile.json5中配置signingConfigs，并通过环境变量动态注入密码，让构建工具在打包时自动完成签名。 - 构建性能优化：
在 CI 环境中，务必添加--no-daemon参数。因为 CI 通常是短暂的隔离容器，常驻的 daemon 进程没有复用价值，反而会占用内存或引发缓存冲突。同时，可以结合 GitLab 的缓存机制缓存oh_modules和build目录，以支持增量编译。 - 触发时机控制：
通过only或rules关键字限制流水线的触发条件。例如，仅在代码合入main分支或打 Tag 时才执行签名和发布，而在普通的 Merge Request 中仅执行代码检查（Lint）和单元测试。 - 发布前自检：
在签名完成后，建议增加一个校验步骤，使用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 最佳实践总结
- 密钥全生命周期管理：生产环境的签名私钥（
.p12）应尽可能接入企业级 KMS（密钥管理服务）或 HSM（硬件安全模块），避免 Base64 明文存储在 GitLab 变量中。 - 流水线性能调优：除了
--no-daemon，应充分利用 GitLab CI 的cache机制缓存oh_modules、hvigor缓存及编译中间产物，将增量构建时间缩短 50% 以上。 - AI 辅助研发集成：在流水线中接入鸿蒙 AI 辅助研发工具（如 Harmony Trace Analyzer），在每次性能测试后自动生成 Trace 分析报告，精准定位性能瓶颈。
- 发布策略自动化：结合 GitOps 理念，签名加固后的产物自动推送至内部制品库，并通过 FluxCD 等工具触发灰度发布或金丝雀部署，实现从代码提交到多端上线的全链路自动化闭环。
