鸿蒙 Flutter CI/CD 进阶：Jenkins + 鸿蒙打包自动化流程

原创于 2025-12-12 13:44:17 发布 · 814 阅读

CC 4.0 BY-SA版权

文章标签：

引言：为什么需要鸿蒙 Flutter 自动化构建？

随着鸿蒙（HarmonyOS）生态的快速发展，越来越多开发者选择 Flutter + 鸿蒙 进行跨平台开发 ——Flutter 提供高效的 UI 渲染能力，鸿蒙则实现多设备协同与分布式能力。但在实际开发中，手动打包鸿蒙应用（生成 HAP 包）存在诸多痛点：

重复性操作：每次迭代需打开 DevEco Studio 执行「Build → Generate HAP」，效率低下；
环境一致性问题：不同开发者的本地环境（SDK 版本、依赖版本）差异可能导致打包失败；
发布延迟：无法实时响应代码提交，需人工触发打包，影响测试与发布节奏。

而 CI/CD（持续集成 / 持续部署） 正是解决这些问题的核心方案。本文将以 Jenkins（业界主流 CI/CD 工具）为核心，手把手教你搭建「代码提交 → 自动打包 → 产物归档 → 通知」的全流程自动化体系，让鸿蒙 Flutter 项目的构建效率提升 10 倍。

前置知识：你需要了解基本的 Flutter 开发、鸿蒙应用结构（如 HAP 包、hvigor 构建工具）及 Jenkins 基础操作。

一、环境准备：搭建自动化构建基础

在开始配置 Jenkins 前，需先准备好基础环境。所有工具推荐使用 Linux（Ubuntu 20.04+） 或 macOS（鸿蒙打包对 Windows 兼容性稍弱，部分命令需调整）。

1.1 必备工具清单

工具名称	作用说明	推荐版本	官方下载链接
JDK	鸿蒙 / Flutter 构建的基础 Java 环境	11（LTS）	Oracle JDK 11
HarmonyOS SDK	鸿蒙应用开发与打包核心工具集	API 10+	通过 DevEco Studio 下载
Flutter SDK	Flutter 跨平台开发框架	3.16+	Flutter 官方下载
Jenkins	CI/CD 核心工具，用于编排自动化流程	2.400+	Jenkins 官方下载
Git	代码版本控制，用于拉取项目代码	2.30+	Git 官方下载
Hvigor	鸿蒙官方构建工具（替代 Gradle）	3.1.0+	随 DevEco Studio 自动安装，或通过 Hvigor 官网单独下载

1.2 环境变量配置（关键步骤）

所有工具安装完成后，需配置全局环境变量，确保 Jenkins 能调用相关命令（以 Linux 为例，配置文件为 /etc/profile）：

bash

运行

# 1. 配置 JDK 环境变量
export JAVA_HOME=/usr/lib/jvm/jdk-11-oracle
export PATH=$JAVA_HOME/bin:$PATH

# 2. 配置 Flutter 环境变量
export FLUTTER_HOME=/opt/flutter
export PATH=$FLUTTER_HOME/bin:$PATH

# 3. 配置鸿蒙 SDK 环境变量（关键：指向 DevEco Studio 中的 SDK 路径）
export HARMONYOS_SDK_HOME=~/DevEcoStudio2.3/sdk
export PATH=$HARMONYOS_SDK_HOME/toolchains/hvigor/bin:$PATH

# 4. 配置 Hvigor 环境变量
export HVIGOR_HOME=~/DevEcoStudio2.3/sdk/toolchains/hvigor
export PATH=$HVIGOR_HOME/bin:$PATH

配置完成后，执行 source /etc/profile 生效，并通过以下命令验证环境是否正常：

bash

运行

# 验证 JDK
java -version  # 应输出 JDK 11 版本信息

# 验证 Flutter（需确保已配置鸿蒙 Flutter 引擎）
flutter --version  # 应输出 Flutter 3.16+ 版本信息

# 验证 Hvigor
hvigor -v  # 应输出 Hvigor 3.1.0+ 版本信息

、

二、Jenkins 初始化：安装核心插件与配置工具

Jenkins 本身是一个空框架，需通过插件扩展功能。我们需要安装与「Git 代码拉取」「Flutter 构建」「鸿蒙打包」相关的插件。

2.1 安装必备插件

登录 Jenkins（默认地址：http://服务器IP:8080），进入「系统管理 → 插件管理 → 可选插件」；
搜索并安装以下插件，安装后重启 Jenkins：
- Git Plugin：用于拉取 Git 仓库代码；
- Gradle Plugin：兼容鸿蒙项目的 Gradle 依赖管理；
- NodeJS Plugin：若项目需 Node 环境（如前端资源编译）；
- Pipeline Plugin：支持通过 Jenkinsfile 定义自动化流程（推荐）；
- HarmonyOS Build Plugin：鸿蒙官方提供的 Jenkins 插件（可选，简化打包流程）。

插件安装技巧：若 Jenkins 插件下载慢，可在「系统管理 → 插件管理 → 高级」中修改「升级站点」为国内镜像，如：https://mirrors.tuna.tsinghua.edu.cn/jenkins/updates/update-center.json

2.2 配置全局工具（Jenkins 内关联本地工具）

进入「系统管理 → 全局工具配置」，将本地安装的 JDK、Flutter、Hvigor 关联到 Jenkins，避免权限问题：

2.2.1 配置 JDK

取消「自动安装」，选择「手动安装」；
「名称」填写 JDK_11（自定义，后续 Pipeline 需引用）；
「JAVA_HOME」填写本地 JDK 路径（如 /usr/lib/jvm/jdk-11-oracle）；
点击「保存」。

2.2.2 配置 Flutter

取消「自动安装」，选择「手动安装」；
「名称」填写 Flutter_3.16；
「FLUTTER_HOME」填写本地 Flutter 路径（如 /opt/flutter）；
点击「保存」。

2.2.3 配置 Hvigor

取消「自动安装」，选择「手动安装」；
「名称」填写 Hvigor_3.1；
「HVIGOR_HOME」填写本地 Hvigor 路径（如 ~/DevEcoStudio2.3/sdk/toolchains/hvigor）；
点击「保存」。

三、Flutter 项目适配鸿蒙：确保可打包

在配置 Jenkins 前，需先确保本地 Flutter 项目能正常生成鸿蒙 HAP 包。关键是集成鸿蒙 Flutter 引擎与配置签名。

3.1 集成鸿蒙 Flutter 插件

鸿蒙 Flutter 项目需依赖官方插件 ohos_flutter，在 pubspec.yaml 中添加依赖：

yaml

dependencies:
  flutter:
    sdk: flutter
  # 鸿蒙 Flutter 核心插件（需与 SDK 版本匹配）
  ohos_flutter:
    git:
      url: https://gitee.com/openharmony-sig/ohos_flutter.git
      ref: 1.0.0  # 对应鸿蒙 API 10 版本

执行 flutter pub get 安装依赖，若下载慢可配置 Flutter 国内镜像：

bash

运行

# 临时配置（终端执行）
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

# 永久配置（写入 /etc/profile）
echo 'export PUB_HOSTED_URL=https://pub.flutter-io.cn' >> /etc/profile
echo 'export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn' >> /etc/profile
source /etc/profile

3.2 配置鸿蒙应用签名（必须）

鸿蒙应用打包（尤其是 Release 包）必须签名，否则无法安装到设备。需先生成签名文件，步骤如下：

打开 DevEco Studio，进入「Build → Generate Key and CSR」；
按照提示生成 .p12 签名文件和 .csr 证书请求文件；
登录鸿蒙开发者平台，上传 .csr 生成 profile 文件（应用权限配置）；
将 .p12 签名文件和 profile 文件放入项目的 entry/src/main/sign 目录（需手动创建 sign 文件夹）。

3.2.1 配置签名信息（hvigorfile.ts）

在项目根目录的 hvigorfile.ts 中指定签名文件路径和密码（建议通过环境变量存储密码，避免硬编码）：

typescript

运行

import { HvigorFile, OhosHapPlugin } from '@ohos/hvigor-ohos-plugin';

export default class AppHvigorFile extends HvigorFile {
  override config(): void {
    // 配置鸿蒙 HAP 插件
    this.plugin(OhosHapPlugin);
    
    // 签名配置（Release 模式）
    this.project.setProperty('sign.release.storeFile', './entry/src/main/sign/my_sign.p12');
    this.project.setProperty('sign.release.storePassword', process.env.HARMONY_SIGN_PASSWORD); // 环境变量获取密码
    this.project.setProperty('sign.release.keyAlias', 'my_alias'); // 签名别名
    this.project.setProperty('sign.release.keyPassword', process.env.HARMONY_SIGN_PASSWORD);
    this.project.setProperty('sign.release.profile', './entry/src/main/sign/my_profile.prof');
  }
}

3.3 本地验证打包

在项目根目录执行以下命令，验证是否能生成 Release 版本的 HAP 包：

bash

运行

# 清理缓存（可选）
hvigor clean

# 构建 Release 版本 HAP 包
hvigor build --mode release

若构建成功，HAP 包会生成在 entry/build/outputs/hap/release 目录下，文件名类似 entry-release.hap。

四、Jenkins Pipeline：编写自动化流程

Jenkins Pipeline 是通过代码定义 CI/CD 流程的工具，支持将流程写入项目根目录的 Jenkinsfile，实现「代码即流程」。本文采用 声明式 Pipeline（结构清晰，适合新手）。

4.1 Jenkinsfile 完整代码

在 Flutter 项目根目录创建 Jenkinsfile，内容如下（关键步骤已加注释）：

groovy

pipeline {
    // 指定 Jenkins 执行节点（若为单机，填 "any"）
    agent any
    
    // 环境变量配置（可在 Jenkins 全局配置中设置，避免硬编码）
    environment {
        // 鸿蒙签名密码（在 Jenkins → 系统管理 → 管理凭据 中添加 Secret Text）
        HARMONY_SIGN_PASSWORD = credentials('harmony-sign-password')
        // 项目名称（自定义）
        PROJECT_NAME = 'flutter_harmony_demo'
        // HAP 包输出路径
        HAP_OUTPUT_PATH = 'entry/build/outputs/hap/release'
        // 构建日期（用于产物命名）
        BUILD_DATE = sh(script: 'date +%Y%m%d%H%M', returnStdout: true).trim()
    }
    
    // 工具配置（关联 Jenkins 全局工具）
    tools {
        jdk 'JDK_11'
        flutter 'Flutter_3.16'
        hvigor 'Hvigor_3.1'
    }
    
    // 构建流程（按阶段执行）
    stages {
        // 阶段1：拉取 Git 代码
        stage('拉取代码') {
            steps {
                echo "=== 开始拉取 ${PROJECT_NAME} 代码 ==="
                // 拉取 Git 仓库（替换为你的仓库地址和分支）
                git url: 'https://gitee.com/your-username/flutter_harmony_demo.git',
                    branch: 'main',
                    credentialsId: 'git-credentials' // Git 账号凭据（Jenkins 中添加）
            }
        }
        
        // 阶段2：安装 Flutter 依赖
        stage('安装依赖') {
            steps {
                echo "=== 开始安装 Flutter 依赖 ==="
                // 切换到项目根目录（若已在根目录，可省略）
                dir('./') {
                    // 安装 Flutter 依赖
                    sh 'flutter pub get'
                    // 安装鸿蒙 Hvigor 依赖（可选，若项目未自带）
                    sh 'hvigor install'
                }
            }
        }
        
        // 阶段3：代码检查（可选，提升代码质量）
        stage('代码检查') {
            steps {
                echo "=== 开始代码检查 ==="
                dir('./') {
                    // Flutter 代码规范检查（--no-fatal-infos 表示警告不阻断构建）
                    sh 'flutter analyze --no-fatal-infos'
                    // （可选）单元测试
                    sh 'flutter test'
                }
            }
        }
        
        // 阶段4：构建鸿蒙 HAP 包
        stage('构建 HAP 包') {
            steps {
                echo "=== 开始构建鸿蒙 Release 版本 HAP 包 ==="
                dir('./') {
                    // 清理缓存
                    sh 'hvigor clean'
                    // 构建 Release 包（依赖环境变量中的签名密码）
                    sh 'hvigor build --mode release'
                }
            }
        }
        
        // 阶段5：归档 HAP 包（保存产物）
        stage('归档产物') {
            steps {
                echo "=== 开始归档 HAP 包 ==="
                // 归档 HAP 包（Jenkins 中可通过「工作空间 → 归档产物」查看）
                archiveArtifacts(
                    artifacts: "${HAP_OUTPUT_PATH}/*.hap", // 匹配所有 HAP 包
                    fingerprint: true, // 生成指纹，便于追溯
                    onlyIfSuccessful: true, // 仅当构建成功时归档
                    // 重命名产物（添加日期，避免覆盖）
                    allowEmptyArchive: false
                )
                // （可选）复制 HAP 包到指定目录（如服务器下载目录）
                sh "cp ${HAP_OUTPUT_PATH}/*.hap /var/www/html/harmony-builds/${PROJECT_NAME}_${BUILD_DATE}.hap"
            }
        }
        
        // 阶段6：发送构建通知（可选，支持邮件、企业微信等）
        stage('发送通知') {
            steps {
                echo "=== 开始发送构建通知 ==="
                // 示例：发送企业微信通知（需安装企业微信插件）
                wechatNotification(
                    corpId: 'your-corp-id',
                    agentId: 'your-agent-id',
                    corpSecret: credentials('wechat-corp-secret'),
                    touser: '@all',
                    msgtype: 'text',
                    text: [
                        content: "【${PROJECT_NAME} 鸿蒙构建完成】\n" +
                                "构建状态：成功\n" +
                                "构建时间：${BUILD_DATE}\n" +
                                "HAP 包下载地址：http://your-server-ip/harmony-builds/${PROJECT_NAME}_${BUILD_DATE}.hap"
                    ]
                )
            }
        }
    }
    
    // 构建后操作（失败时通知）
    post {
        failure {
            echo "=== ${PROJECT_NAME} 构建失败 ==="
            // 发送失败通知
            wechatNotification(
                corpId: 'your-corp-id',
                agentId: 'your-agent-id',
                corpSecret: credentials('wechat-corp-secret'),
                touser: '@all',
                msgtype: 'text',
                text: [
                    content: "【${PROJECT_NAME} 鸿蒙构建失败】\n" +
                            "构建时间：${BUILD_DATE}\n" +
                            "失败原因：请查看 Jenkins 日志 → http://your-jenkins-ip/job/${PROJECT_NAME}/lastFailedBuild/"
                ]
            )
        }
    }
}

4.2 关键配置说明

凭据管理：代码中的 credentials('harmony-sign-password') 和 git-credentials 需在 Jenkins 中提前配置：
- 进入「Jenkins → 系统管理 → 管理凭据 → 全局凭据 → 添加凭据」；
- 签名密码选择「Secret Text」，ID 填写 harmony-sign-password；
- Git 账号选择「Username with password」，ID 填写 git-credentials。
产物归档：archiveArtifacts 步骤会将 HAP 包保存到 Jenkins 工作空间，可通过 Jenkins 界面直接下载；若需对外提供下载，可将 HAP 包复制到 Web 服务器目录（如 Nginx 的 /var/www/html）。
通知配置：本文示例用企业微信通知，若需邮件通知，可替换为 emailext 插件，参考 Jenkins Email Extension 文档。

、五、Jenkins 项目创建：触发自动化流程

编写完 Jenkinsfile 后，需在 Jenkins 中创建 Pipeline 项目，关联 Git 仓库，实现「代码提交后自动构建」。

5.1 创建 Pipeline 项目

登录 Jenkins，点击「新建 Item → 输入项目名称（如 Flutter_Harmony_CI）→ 选择「Pipeline」→ 点击「确定」；
进入项目配置页面，找到「Pipeline」配置项：
- 「Definition」选择「Pipeline script from SCM」（从 Git 仓库读取 Jenkinsfile）；
- 「SCM」选择「Git」；
- 「Repository URL」填写你的 Git 仓库地址（如 https://gitee.com/your-username/flutter_harmony_demo.git）；
- 「Credentials」选择之前配置的 git-credentials；
- 「Branches to build」填写分支（如 */main）；
- 「Script Path」填写 Jenkinsfile（默认在项目根目录，无需修改）；
点击「保存」。

5.2 触发构建（两种方式）

5.2.1 手动触发

进入项目页面，点击「立即构建」，Jenkins 会开始执行 Jenkinsfile 中的流程；
点击「正在执行的构建 → Console Output」，可实时查看构建日志。

5.2.2 自动触发（代码提交后触发）

若需实现「Git 提交代码后，Jenkins 自动构建」，需配置 Git 仓库的 WebHook：

Jenkins 配置：进入项目配置 → 「构建触发器」→ 勾选「GitHub hook trigger for GITScm polling」（若为 Gitee，需安装「Gitee Plugin」，勾选「Gitee webhook trigger」）。
Git 仓库配置（以 Gitee 为例）：
- 进入 Gitee 仓库 → 「管理 → WebHooks → 添加 WebHook」；
- 「URL」填写 Jenkins 的 WebHook 地址：http://your-jenkins-ip/github-webhook/（Gitee 为 http://your-jenkins-ip/gitee-hook/）；
- 「Secret」填写 Jenkins 中配置的「Gitee 密钥」（在「系统管理 → Gitee 配置」中设置）；
- 「触发事件」勾选「Push 事件」；
- 点击「添加」，并测试 WebHook 是否正常（Gitee 提供「测试」按钮）。

配置完成后，向 Git 仓库提交代码，Jenkins 会自动触发构建。

六、常见问题排查与优化

在搭建过程中，可能会遇到各种问题，以下是高频问题的解决方案：

6.1 问题 1：Hvigor 命令找不到

报错信息：hvigor: command not found原因：Jenkins 未正确读取 Hvigor 环境变量。解决方案：

检查 Jenkins 全局工具中 Hvigor 的路径是否正确；
在 Jenkinsfile 的 steps 中手动添加环境变量：
groovy
```
sh 'export PATH=$HVIGOR_HOME/bin:$PATH && hvigor -v'
```

6.2 问题 2：签名失败

报错信息：Signing failed: invalid keystore format原因：签名文件路径错误或密码错误。解决方案：

检查 hvigorfile.ts 中 storeFile 和 profile 的路径是否为相对路径（相对于项目根目录）；
验证 Jenkins 凭据中的 harmony-sign-password 是否与 .p12 文件的密码一致；
确保签名文件的权限为 644（避免 Jenkins 无读取权限）：
bash

运行
```
chmod 644 entry/src/main/sign/*.p12 entry/src/main/sign/*.prof
```

6.3 问题 3：构建速度慢

原因：每次构建都重新下载依赖（Flutter pub、Hvigor 依赖）。解决方案：使用 Jenkins Cache 插件缓存依赖：

安装「Cache Plugin」；

在 Jenkinsfile 中添加缓存配置：

groovy

stages {
    // 新增「缓存依赖」阶段
    stage('缓存依赖') {
        steps {
            cache(path: [
                "${FLUTTER_HOME}/.pub-cache", // Flutter pub 缓存
                "~/.hvigor/cache" // Hvigor 缓存
            ], key: "cache-{{ checksum 'pubspec.yaml' }}") {
                echo "=== 依赖缓存已加载 ==="
            }
        }
    }
    // 后续阶段...
}

七、总结与扩展

通过本文的步骤，你已实现「Git 提交 → Jenkins 自动拉取代码 → 安装依赖 → 构建 HAP 包 → 归档产物 → 通知」的全流程自动化。这不仅解决了手动打包的痛点，还能确保每次构建的环境一致性，提升团队协作效率。

7.1 扩展方向

多环境构建：通过 Jenkins 参数化构建，实现「开发 / 测试 / 生产」环境的一键切换；
自动部署到设备：使用鸿蒙 hdc 工具（鸿蒙设备调试工具），在构建完成后自动将 HAP 包安装到设备：
bash

运行
```
# 示例：通过 hdc 安装 HAP 包
hdc install entry/build/outputs/hap/release/entry-release.hap
```
参考文档：鸿蒙 HDC 工具使用指南
集成测试报告：在 Jenkinsfile 中添加测试报告归档，如 junit 'test/reports/*.xml'，支持在 Jenkins 中查看测试结果。

7.2 参考资料

若在实践中遇到其他问题，欢迎在评论区留言交流！