HarmonyOS 6.1 CI/CD流水线实战：从DevEco到AGC的自动化发布

listening777

287人浏览 · 2026-07-15 23:23:05

listening777 · 2026-07-15 23:23:05 发布

系列工程化终章。上篇讲完单元测试，有读者问：“每次测试完还要手动打包、上传AGC、填应用信息，太繁琐了，有没有办法一键发布？” 这正是CI/CD（持续集成/持续部署）要解决的核心痛点。作为系列的最后一篇工程化内容，本文将把电商Demo的发布流程彻底自动化：从代码提交到Git，到自动运行测试、构建HAP包、上传到AGC（AppGallery Connect）、甚至自动分发到测试人员手中。全程基于华为云DevCloud，无需自建服务器，30分钟即可搭建一套企业级发布流水线。所有配置均适配API23，含官方文档未提及的权限陷阱与签名方案。

一、前言：为什么CI/CD是专业开发的“分水岭”？

在之前的19篇文章里，我们实现了：

用@State/@Link构建UI；
用分布式流转实现跨端体验；
用端云一体化处理业务逻辑；
用单元测试保障代码质量。

但所有这些成果，最终都要通过“发布”到达用户手中。传统的手动发布流程是这样的：

写完代码，本地跑测试；
打开DevEco Studio，点Build HAP；
打开浏览器，登录AGC；
上传HAP包，填写版本信息、更新说明；
提交审核，等待……

这个过程不仅枯燥，而且极易出错：比如上传了旧版本的包、忘记了版本号的递增、或者签名证书用错了。在团队开发中，这种“手工发布”更是灾难，每个人发布的包可能都不一致。

CI/CD的核心价值就是标准化与自动化：

持续集成（CI）：代码一提交，自动跑测试、构建包，快速反馈质量问题。
持续部署（CD）：测试通过后，自动上传到AGC，甚至自动开启灰度发布。

对于鸿蒙生态来说，CI/CD还有一个特殊意义：多端统一构建。我们的电商Demo用ArkUI-X支持Android/iOS，CI/CD可以一键同时构建鸿蒙、安卓、iOS三个平台的包，确保版本一致性。

二、核心概念辨析（CI/CD工具链）

很多新手会被Jenkins、GitLab CI、GitHub Actions等名词吓到。其实在鸿蒙生态里，工具链非常清晰：

工具/服务	角色定位	适用场景
DevEco Studio	本地开发IDE	写代码、本地调试、手动构建
Git	代码版本管理	代码提交、分支管理（本地或托管平台）
华为云DevCloud	云端CI/CD引擎	自动化构建、测试、部署（推荐，与AGC无缝集成）
AppGallery Connect (AGC)	应用分发平台	存储HAP包、审核、上架应用市场
Command Line Tools	命令行构建工具	在无界面的服务器（如DevCloud）上构建HAP包

💡 核心认知：我们将使用Git托管代码，华为云DevCloud作为CI/CD引擎，AGC作为发布终点。DevEco Studio只是我们写代码的工具，构建和发布都交给云端自动完成。

三、代码实现：搭建自动化流水线

3.1 准备工作

代码托管：将之前的电商Demo代码上传到码云（Gitee）或华为云CodeHub（推荐，与DevCloud集成更顺畅）。
AGC配置：
- 在AGC上创建好应用（Package Name要与代码一致）。
- 生成API Key：进入AGC“用户与访问-密钥管理”，创建一个API Key，下载credentials.json文件。这是CI/CD上传包到AGC的凭证，必须保密！
- 准备好签名证书：在DevEco Studio中生成.p12、.cer、.p7b文件，并备份好密码。
华为云DevCloud：
- 登录华为云控制台，进入“软件开发生产线 DevCloud”。
- 创建项目，关联你的代码仓库。

3.2 编写构建脚本（hvigorfile.js）

DevEco Studio使用hvigor作为构建工具（类似前端的Webpack）。我们需要在项目根目录创建或修改hvigorfile.js，使其支持命令行构建。

关键点：CI/CD环境中没有图形界面，无法通过弹窗输入签名密码，所以我们使用环境变量传递密码。

// 项目根目录/hvigorfile.js
const hvigor = require("@ohos/hvigor");
const fs = require("fs");

// 定义一个名为'buildHap'的任务
hvigor.task("buildHap")
  .applyPlugin("@ohos/hvigor-plugin-ohos-app")
  .doFirst(() => {
    console.log("开始构建HAP包...");
    // 从环境变量读取签名密码（CI/CD环境中设置）
    const storePassword = process.env.SIGN_STORE_PASSWORD;
    const keyPassword = process.env.SIGN_KEY_PASSWORD;

    if (!storePassword || !keyPassword) {
      throw new Error("签名密码未设置，请在CI/CD环境中配置环境变量！");
    }

    // 动态修改构建配置（可选，例如修改版本号）
    const buildProfilePath = "entry/build-profile.json5";
    if (fs.existsSync(buildProfilePath)) {
      let profile = fs.readFileSync(buildProfilePath, "utf-8");
      // 示例：将版本号改为环境变量中的值
      const buildNumber = process.env.BUILD_NUMBER || "1";
      profile = profile.replace(/"versionCode":\s*\d+/, `"versionCode": ${buildNumber}`);
      fs.writeFileSync(buildProfilePath, profile);
      console.log(`版本号已更新为: ${buildNumber}`);
    }
  })
  .doLast(() => {
    console.log("HAP包构建完成！");
    console.log("输出路径: entry/build/outputs/default/entry-default-signed.hap");
  });

// 导出任务
module.exports = {
  tasks: ["buildHap"]
};

安全提示：千万不要把密码硬编码在脚本里！一定要使用环境变量。

3.3 配置DevCloud流水线

进入华为云DevCloud的项目，点击“构建&发布-流水线”，新建流水线。我们分步配置：

步骤1：克隆代码

源：选择你的代码仓库（Gitee/CodeHub）。
分支：选择master或main。

步骤2：构建HAP包（核心步骤）

构建工具：选择“Hvigor构建”。

脚本：输入构建命令：

# 设置环境变量（在DevCloud的界面上设置，不要写在这里）
# export SIGN_STORE_PASSWORD='你的密码'
# export SIGN_KEY_PASSWORD='你的密码'
# export BUILD_NUMBER=${BUILD_NUMBER} # DevCloud内置变量

# 执行构建
node hvigorw.js buildHap --no-daemon

制品：设置“归档制品”，路径填写entry/build/outputs/default/*.hap。这一步是为了把构建好的HAP包保存下来，供后续步骤使用。

步骤3：运行单元测试

构建工具：选择“命令行”。

脚本：在构建目录下执行测试命令：

# 进入测试模块目录
cd entry_test
# 执行测试（使用Hypium测试框架）
npm install # 如果测试依赖需要安装
npx hypium run tests --testRunner OhosTestRunner

配置：勾选“测试报告解析”，路径填写entry_test/build/reports/tests/index.html。这样DevCloud会自动收集测试报告。

步骤4：上传到AGC（CD的关键）

插件：选择“AppGallery Connect上传”。
凭证：上传你之前下载的credentials.json文件。
配置：
- 应用ID：填写AGC上的App ID。
- 构建产物：选择上一步归档的HAP包路径。
- 版本更新说明：可以填写Auto-release by CI/CD at ${BUILD_TIME}。
- 分发范围：选择“测试人员”（先给测试人员，没问题再手动点发布）。

步骤5：通知（可选）

插件：选择“邮件通知”或“钉钉通知”。
配置：构建成功/失败后，自动发送消息给团队。

3.4 触发流水线

配置完成后，你可以在DevCloud中手动点击“执行”，也可以设置自动触发：

代码提交触发：当开发人员git push代码到master分支时，自动启动流水线。
定时触发：每天凌晨2点自动构建一次，确保主分支始终是可发布的。

四、踩坑记录（官方文档没写的7个细节）

环境变量优先级：DevCloud的环境变量会覆盖系统变量，但hvigor脚本中如果硬编码了密码，会优先使用硬编码的。务必确保脚本中是从process.env读取。
签名证书的路径问题：CI/CD服务器上没有你的本地证书，需要将.p12等证书文件也提交到代码仓库（注意：.p12包含私钥，务必在私有仓库中操作，且设置严格的访问权限！），或者在DevCloud中配置“文件保密存储”，构建时动态下载。
AGC API的速率限制：频繁调用AGC的上传API可能会被限流。建议在流水线中设置合理的重试机制。
构建机的环境差异：DevCloud的构建机可能预装了不同版本的Node.js或Java。最好在流水线中显式指定hvigor和Node.js的版本，避免因版本差异导致构建失败。
测试环境的初始化：如果单元测试依赖AGC的云数据库，需要在测试前通过脚本初始化测试数据，并在测试后清理。否则测试会相互干扰。
构建产物的清理：每次构建都会生成HAP包，长期积累会占满磁盘。需要在流水线末尾或定期清理旧的构建产物。
权限最小化：AGC的API Key权限要最小化，只授予“上传应用包”的权限，不要授予“删除应用”或“修改财务信息”的权限，防止凭证泄露造成损失。