自动化构建 OpenHarmony Flutter 应用：从本地脚本到 CI/CD 流水线实战

引言

在 OpenHarmony 生态中，Flutter 作为高性能跨端 UI 框架，正被广泛用于国产化应用开发。然而，由于其混合架构特性（Dart + ArkTS + Native Bridge），构建流程远比纯 Flutter 或纯 OpenHarmony 项目复杂：

需先编译 Flutter 模块生成 libflutter.so 和资源包；
再将产物集成到 OpenHarmony 工程中；
最后调用 DevEco Studio 的构建工具链生成 HAP 包。

若每次手动操作，不仅效率低下，还极易出错。本文将手把手教你搭建一套 端到端自动化构建体系，涵盖：

本地一键构建脚本（Shell / PowerShell）；
GitHub Actions / GitLab CI 自动化流水线；
构建产物管理与版本发布策略。

并附完整可运行代码案例，助你实现"提交即构建、构建即交付"。

一、OpenHarmony + Flutter 项目结构详解

1.1 典型混合项目目录结构

完整的项目目录结构如下所示，包含三个主要部分：

复制代码

my_oh_flutter_app/
├── flutter_module/          # 独立 Flutter 模块
│   ├── lib/                 # Dart 源代码目录
│   │   ├── main.dart        # 入口文件
│   │   └── pages/           # 页面组件目录
│   ├── pubspec.yaml         # Flutter 依赖配置文件
│   ├── android/             # Android 平台相关代码（可选）
│   ├── ios/                 # iOS 平台相关代码（可选）
│   └── build/               # 构建输出目录
│
├── openharmony_app/         # OpenHarmony 主工程（DevEco 项目）
│   ├── entry/               # 主模块
│   │   ├── src/main/ets/    # ArkTS 代码目录
│   │   │   ├── MainAbility/ # 主Ability
│   │   │   └── pages/       # 原生页面
│   │   └── src/main/resources/ # 资源文件
│   ├── hvigorfile.ts        # 构建配置文件
│   ├── module.json5         # 模块配置文件
│   └── libs/                # 第三方库目录
│       └── flutter_engine/  # Flutter 引擎库
│
└── build_scripts/           # 自动化脚本目录
    ├── build_flutter.sh     # Flutter 模块构建脚本
    ├── copy_assets.sh       # 资源拷贝脚本
    └── build_ohos.sh        # OpenHarmony 构建脚本

1.2 架构设计要点

模块化设计：
- Flutter 作为独立模块开发，保持与平台无关性
- OpenHarmony 主工程负责原生能力集成和分发
构建流程：

Flutter模块构建生成.so和资源文件拷贝产物到OH主工程 OpenHarmony完整构建
通信机制：
- 通过 MethodChannel 实现 Dart 与 ArkTS 的双向通信
- 原生能力通过 Platform Channel 暴露给 Flutter

💡 关键设计原理 ：

Flutter 采用动态库集成方式（而非直接嵌入），其产物包括：

libflutter.so：Flutter 引擎库

libapp.so：编译后的Dart代码

assets/：静态资源文件
这些产物会被复制到 openharmony_app/entry/libs/ 目录下参与最终打包。

1.3 典型应用场景示例

场景1：混合导航

dart 复制代码

// Flutter 侧
Navigator.push(
  context,
  MethodChannel('native_page').invokeMethod('openOhosPage')
);

// OpenHarmony 侧
methodChannel.setMethodCallHandler((call) {
  if (call.method == "openOhosPage") {
    router.push({ url: "pages/OhosPage" });
  }
});

场景2：平台能力调用

dart 复制代码

// 调用OHOS系统振动
final result = await methodChannel.invokeMethod('vibrate', {'duration': 500});

二、本地自动化构建脚本（Shell）

目标

执行一个命令，完成：

编译 Flutter Release 版本；
复制产物到 OpenHarmony 工程；
调用 hvigorw 构建 HAP。

脚本实现（Linux/macOS）

bash 复制代码

#!/bin/bash
# build_scripts/build_oh_flutter.sh

set -e  # 遇错退出

FLUTTER_MODULE="./flutter_module"
OH_APP="./openharmony_app"
BUILD_DIR="$FLUTTER_MODULE/build"

echo "🚀 开始构建 OpenHarmony Flutter 应用..."

# 1. 进入 Flutter 模块目录
cd "$FLUTTER_MODULE"

# 2. 获取当前系统架构（OpenHarmony 支持 arm64, x86_64）
ARCH=$(uname -m)
if [[ "$ARCH" == "x86_64" ]]; then
  OH_ARCH="x86_64"
elif [[ "$ARCH" == "aarch64" || "$ARCH" == "arm64" ]]; then
  OH_ARCH="arm64"
else
  echo "❌ 不支持的架构: $ARCH"
  exit 1
fi

echo "🔧 目标架构: $OH_ARCH"

# 3. 构建 Flutter Release（生成 libflutter.so 和 assets）
flutter build ohos --release --target-platform=ohos-$OH_ARCH

# 4. 定义产物路径
FLUTTER_LIB="$BUILD_DIR/ohos/ohos-$OH_ARCH/libflutter.so"
FLUTTER_ASSETS="$BUILD_DIR/ohos/flutter_assets"

# 5. 复制到 OpenHarmony 工程
OH_LIB_DIR="$OH_APP/entry/src/main/cpp/libs/$OH_ARCH"
OH_ASSETS_DIR="$OH_APP/entry/src/main/resources/rawfile"

mkdir -p "$OH_LIB_DIR"
mkdir -p "$OH_ASSETS_DIR"

cp "$FLUTTER_LIB" "$OH_LIB_DIR/"
cp -r "$FLUTTER_ASSETS" "$OH_ASSETS_DIR/"

echo "✅ Flutter 产物已注入 OpenHarmony 工程"

# 6. 构建 HAP 包
cd "$OH_APP"
npx hvigorw assembleHap

# 7. 输出结果路径
HAP_PATH="$OH_APP/outputs/default/entry-default-signed.hap"
if [ -f "$HAP_PATH" ]; then
  echo "🎉 构建成功！HAP 路径: $HAP_PATH"
else
  echo "❌ HAP 未生成，请检查构建日志"
  exit 1
fi

使用方式

bash 复制代码

chmod +x build_scripts/build_oh_flutter.sh
./build_scripts/build_oh_flutter.sh

✅ 优势：

屏蔽底层细节，开发者只需运行一个脚本；

支持多架构自动识别；

可集成到 IDE 快捷任务中。

三、Windows 支持（PowerShell）

powershell 复制代码

# build_scripts/build_oh_flutter.ps1

$ErrorActionPreference = "Stop"

$FLUTTER_MODULE = ".\flutter_module"
$OH_APP = ".\openharmony_app"

Write-Host "🚀 开始构建..." -ForegroundColor Green

Set-Location $FLUTTER_MODULE

# 假设使用 arm64（可根据需求扩展）
$OH_ARCH = "arm64"

# 构建 Flutter
flutter build ohos --release --target-platform=ohos-$OH_ARCH

# 复制产物
$LIB_SRC = "build\ohos\ohos-$OH_ARCH\libflutter.so"
$ASSETS_SRC = "build\ohos\flutter_assets"
$LIB_DST = "$OH_APP\entry\src\main\cpp\libs\$OH_ARCH"
$ASSETS_DST = "$OH_APP\entry\src\main\resources\rawfile"

New-Item -ItemType Directory -Path $LIB_DST -Force | Out-Null
New-Item -ItemType Directory -Path $ASSETS_DST -Force | Out-Null

Copy-Item $LIB_SRC $LIB_DST -Force
Copy-Item $ASSETS_SRC $ASSETS_DST -Recurse -Force

Write-Host "✅ 产物注入完成" -ForegroundColor Cyan

# 构建 HAP
Set-Location $OH_APP
npx hvigorw assembleHap

$HAP_PATH = "$OH_APP\outputs\default\entry-default-signed.hap"
if (Test-Path $HAP_PATH) {
    Write-Host "🎉 构建成功！HAP: $HAP_PATH" -ForegroundColor Green
} else {
    Write-Host "❌ 构建失败" -ForegroundColor Red
    exit 1
}

四、CI/CD 集成：GitHub Actions 示例

场景

每次 git push 到 main 分支，自动构建 HAP 并上传为 Release Asset。

`.github/workflows/build.yml`

yaml 复制代码

name: Build OpenHarmony Flutter App

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Setup Flutter (for OpenHarmony)
        run: |
          git clone https://gitee.com/openharmony-sig/flutter_ohos.git
          cd flutter_ohos
          ./flutter/tools/gn --ohos --unoptimized
          ./flutter/tools/ninja -C out/ohos_unopt

      - name: Add Flutter to PATH
        run: |
          echo "$(pwd)/flutter_ohos/flutter/bin" >> $GITHUB_PATH

      - name: Install DevEco CLI dependencies
        run: |
          cd openharmony_app
          npm install @ohos/hvigor

      - name: Run build script
        run: |
          chmod +x build_scripts/build_oh_flutter.sh
          ./build_scripts/build_oh_flutter.sh

      - name: Upload HAP as Artifact
        uses: actions/upload-artifact@v4
        with:
          name: ohos-app-hap
          path: openharmony_app/outputs/default/entry-default-signed.hap

      - name: Create GitHub Release (optional)
        if: startsWith(github.ref, 'refs/tags/')
        uses: softprops/action-gh-release@v2
        with:
          files: openharmony_app/outputs/default/entry-default-signed.hap

🔧 注意：

需提前在 Gitee/GitHub 上 fork flutter_ohos 社区项目；

实际项目中建议将 Flutter Engine 预编译为 Docker 镜像，加速 CI。

五、高级优化建议

1. 增量构建缓存

缓存 flutter_module/.dart_tool 和 openharmony_app/node_modules；
使用 actions/cache 提升 CI 速度。

2. 多架构并行构建

bash 复制代码

# 同时构建 arm64 和 x86_64
flutter build ohos --release --target-platform=ohos-arm64,ohos-x86_64

然后分别复制到对应 libs/arm64/ 和 libs/x86_64/ 目录。

3. 签名自动化

在 module.json5 中配置自动签名：

json 复制代码

{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "type": "automatic"
      }
    ]
  }
}

或通过 hvigorw 传入 keystore 参数实现企业签名。

4. 构建日志分析

将 hvigorw 输出重定向到文件，便于排查：

bash 复制代码

npx hvigorw assembleHap > build.log 2>&1

六、常见问题排查

1. `libflutter.so not found` 错误

详细解决方案：

首先确认 Flutter 构建是否成功完成：
bash 复制代码
```
flutter build ohos --target-platform android-arm,android-arm64
```
检查构建产物目录（build/ohos/outputs）中是否存在对应架构的 .so 文件
常见架构匹配问题：
- 设备是 arm64-v8a 但构建了 armeabi-v7a
- 模拟器是 x86 但构建了 arm 架构

2. HAP 安装后闪退问题

排查步骤：

资源完整性检查：
- 解压 HAP 文件确认 resources/rawfile/flutter_assets 目录存在
- 检查 AssetManifest.json 是否包含所有资源文件

MethodChannel 问题：

确认 Dart 端和 Native 端的 channel 名称完全一致

检查 MainAbility 中是否正确定义了 FlutterOhosPlugin：

java 复制代码

public class MainAbility extends Ability {
    @Override
    public void onStart(Intent intent) {
        FlutterOhosPlugin.register(this);
        super.onStart(intent);
    }
}

3. CI 构建超时问题

优化方案：

使用预构建的 Docker 镜像（包含 Flutter 和 OH 工具链）：
dockerfile 复制代码
```
FROM registry.example.com/flutter-ohos:3.7
```
分阶段构建策略：
1. 先执行 Flutter 构建并缓存产物
2. 再执行 OHOS 应用打包
3. 并行执行单元测试

4. 权限相关错误

完整配置示例：

在 entry/src/main/module.json5 中添加：

json 复制代码

"abilities": [
  {
    "permissions": [
      "ohos.permission.INTERNET",
      "ohos.permission.READ_USER_STORAGE",
      "ohos.permission.WRITE_USER_STORAGE"
    ]
  }
]

常见权限场景：

网络请求需要 INTERNET
文件读写需要 READ/WRITE_USER_STORAGE
相机功能需要 CAMERA

5. 其他常见问题补充

问题现象	可能原因	解决方案
UI 显示异常	未启用硬件加速	在 `config.json` 添加 `"hwAccelerated": true`
字体不显示	字体未打包	检查 `pubspec.yaml` 的 fonts 配置
插件不生效	未注册插件	在 `MainAbility` 调用 `YourPlugin.register()`

七、总结

自动化构建是保障 OpenHarmony + Flutter 项目交付效率与质量的基石。通过：

本地脚本：提升开发者日常构建体验；
CI/CD 流水线：实现持续集成与快速反馈；
产物标准化：确保 HAP 包一致性与可追溯性。

你可以将更多精力聚焦于业务创新，而非重复的打包操作。

随着 OpenHarmony 工具链的成熟，未来有望出现官方支持的 flutter create --platform=ohos 与一键构建插件。但在当下，掌握这套自动化方案，是你在国产化开发浪潮中不可或缺的核心能力。

自动化构建 OpenHarmony Flutter 应用：从本地脚本到 CI/CD 流水线实战

引言

一、OpenHarmony + Flutter 项目结构详解

1.1 典型混合项目目录结构

1.2 架构设计要点

1.3 典型应用场景示例

二、本地自动化构建脚本（Shell）

目标

脚本实现（Linux/macOS）

使用方式

三、Windows 支持（PowerShell）

四、CI/CD 集成：GitHub Actions 示例

场景

.github/workflows/build.yml

五、高级优化建议

1. 增量构建缓存

2. 多架构并行构建

3. 签名自动化

4. 构建日志分析

六、常见问题排查

1. libflutter.so not found 错误

2. HAP 安装后闪退问题

3. CI 构建超时问题

4. 权限相关错误

5. 其他常见问题补充

七、总结

`.github/workflows/build.yml`

1. `libflutter.so not found` 错误