Flutter OH Engine 构建指导（macOS 版本）

欢迎大家加入开源鸿蒙跨平台开发者社区：https://openharmonycrossplatform.csdn.net/

本文档介绍如何在 macOS 系统上构建 OpenHarmony 版本的 Flutter Engine。构建成功后，您可以使用本地 Engine 编译 OpenHarmony 应用。

目录

1. 环境准备
2. 搭建 Engine 构建环境
3. 开始构建
4. 使用构建产物编译应用
5. 常见问题排查

---

1. 环境准备

1.1 系统要求

• 操作系统：macOS（推荐 macOS 10.15 或更高版本）
• 磁盘空间：建议预留 50GB 以上
• 内存：建议 16GB 或以上
• 网络：需要能够访问外网（构建过程中需要下载大量依赖）

1.2 下载必要工具

1.2.1 下载 DevEco Studio

从 OpenHarmony 开发套件官方下载地址 下载并安装最新版 DevEco Studio。

1.2.2 下载 OpenHarmony 版 Flutter SDK

# 克隆仓库
git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git

# 切换到对应版本分支（以 dev 分支为例）
cd flutter_flutter
git checkout -b dev origin/dev

版本说明：查看版本演进规划和分支策略

1.2.3 配置 JDK 环境

OpenHarmony SDK 依赖 Java 环境，请安装 JDK 17：

1. 从 Oracle 官网 或 OpenJDK 下载 JDK 17

2. 安装后验证安装：

   java -version
   

   确保输出显示版本为 17.x.x

1.3 前置条件检查

在开始构建前，请确认以下环境已就绪：

环境项	版本/要求	验证命令
操作系统	macOS 10.15+	sw_vers
JDK	17	java -version
DevEco Studio	最新版	检查应用版本
网络	可访问外网	-
磁盘空间	50GB+	df -h

1.4 配置环境变量

编辑 Shell 配置文件（macOS 默认使用 zsh）：

# 打开配置文件
vim ~/.zshrc

在配置文件中添加以下内容：

# DevEco Studio 环境变量（请根据实际安装路径调整）
export TOOL_HOME=/Applications/DevEco-Studio.app/Contents
export DEVECO_SDK_HOME=$TOOL_HOME/sdk
export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH
export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH
export PATH=$TOOL_HOME/tools/node/bin:$PATH

保存并使配置生效：

# 保存文件（按 Esc，输入 :wq，按 Enter）
source ~/.zshrc

注意：如果 DevEco Studio 安装路径不同，请相应调整 TOOL_HOME 的值。

---

2. 搭建 Engine 构建环境

2.1 安装必要工具

使用 Homebrew 安装基础工具：

# 确保 Homebrew 已安装
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装必要工具
brew install git curl unzip python3 pkg-config ninja

2.2 配置 depot_tools

2.2.1 克隆 depot_tools

选择以下任一方式克隆 depot_tools：

# 方式一：使用官方源（可能需要科学上网）
git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git

# 方式二：使用国内镜像
git clone https://atomgit.com/jianguoxu/depot_tools.git

2.2.2 配置环境变量

编辑 Shell 配置文件：

vim ~/.zshrc

添加以下内容：

# 将 depot_tools 添加到 PATH
export PATH=$HOME/depot_tools:$PATH

使配置生效：

source ~/.zshrc

2.2.3 验证安装

gclient --version

如果显示版本信息，说明安装成功。

2.3 配置 .gclient 文件

2.3.1 创建 .gclient 文件

进入 Flutter 源码目录：

cd flutter_flutter

创建 .gclient 文件：

touch .gclient

提示：macOS 下查看隐藏文件可按 Command (⌘) + Shift (⇧) + .(句号)

2.3.2 复制配置内容

将 flutter_flutter/engine/scripts/ohos.gclient 文件的内容复制到刚创建的 .gclient 文件中：

# 查看配置内容
cat engine/scripts/ohos.gclient

# 复制内容到 .gclient 文件
cp engine/scripts/ohos.gclient .gclient

2.4 同步代码

在 .gclient 文件所在目录执行同步命令：

gclient sync

同步过程说明：

• 此过程会下载 Engine 源码、官方 packages 仓库
• 自动执行 ohos_setup 任务
• 需要网络代理（科学上网）
• 同步时间较长（约 30-60 分钟，视网络情况而定）

注意事项：

• 如遇连接超时，请检查网络代理后重新执行 gclient sync
• 确保可以访问 engine 源码中 DEPS_ohos 配置文件内 allowed_hosts 字段列出的所有 URL
• 同步成功后终端会自动退出

验证同步结果：

# 检查 engine 目录是否存在
ls -la engine/

# 检查关键目录是否下载完成
ls -la engine/src/

---

3. 开始构建

3.1 执行构建命令

代码同步完成后，进入 engine 目录并执行构建：

# 进入 engine 目录
cd engine

# 执行构建（选择以下一种模式）
./ohos -t debug      # 调试模式
./ohos -t profile    # 性能分析模式
./ohos -t release    # 发布模式

构建模式说明：

模式	用途	特点
debug	开发调试	包含调试信息，体积较大，性能较低
profile	性能分析	优化性能，保留部分调试信息
release	生产发布	完全优化，体积最小，性能最佳

3.2 构建产物

产物路径：

<engine目录>/src/out/ohos_<mode>_arm64/
# 例如：
# /Users/yourname/engine/src/out/ohos_debug_arm64
# /Users/yourname/engine/src/out/ohos_release_arm64

主要产物文件：

• flutter.har - Flutter Engine HAP 包
• libflutter.so - Flutter Engine 动态库
• gen_snapshot - Dart 代码编译工具

验证构建产物：

# 检查 debug 模式产物
ls -la src/out/ohos_debug_arm64/

# 检查 release 模式产物
ls -la src/out/ohos_release_arm64/

# 检查 host engine 产物
ls -la src/out/host_release/

确保输出包含 flutter.har、libflutter.so 等关键文件。

3.3 构建注意事项

• 构建时间：首次构建可能需要 1-3 小时，后续构建会更快
• 内存占用：构建过程内存占用较高，建议关闭其他应用程序
• 磁盘空间：确保有足够的磁盘空间用于构建产物
• 网络连接：构建过程可能需要下载部分依赖，保持网络连接

---

4. 使用构建产物编译应用

4.1 使用本地 Engine 构建应用

从 Flutter 3.22.0 版本开始，Engine 编译会同时生成 local-engine 和 local-host-engine。使用本地 Engine 构建应用时，需要同时指定这两个参数。

基本命令格式：

flutter build hap \
  --target-platform ohos-arm64 \
  --release \
  --local-engine=<ENGINE_PATH>/src/out/ohos_release_arm64/ \
  --local-engine-host=<ENGINE_PATH>/src/out/host_release/

4.2 参数说明

参数	说明	可选值
--target-platform	目标平台	ohos-arm64
--release	构建模式	--debug、--profile 或 --release
--local-engine	OpenHarmony Engine 产物路径	绝对路径
--local-engine-host	Host Engine 产物路径	绝对路径

4.3 实际使用示例

示例 1：使用环境变量

# 设置 Engine 路径
export ENGINE_PATH=$HOME/flutter_flutter/engine

# 使用 release 模式构建
flutter build hap \
  --target-platform ohos-arm64 \
  --release \
  --local-engine=$ENGINE_PATH/src/out/ohos_release_arm64/ \
  --local-engine-host=$ENGINE_PATH/src/out/host_release/

示例 2：使用绝对路径

flutter build hap \
  --target-platform ohos-arm64 \
  --release \
  --local-engine=/Users/yourname/flutter_flutter/engine/src/out/ohos_release_arm64/ \
  --local-engine-host=/Users/yourname/flutter_flutter/engine/src/out/host_release/

示例 3：使用 debug 模式开发

flutter build hap \
  --target-platform ohos-arm64 \
  --debug \
  --local-engine=$HOME/flutter_flutter/engine/src/out/ohos_debug_arm64/ \
  --local-engine-host=$HOME/flutter_flutter/engine/src/out/host_debug/

4.4 验证构建结果

构建成功后，检查生成的 HAP 文件：

# 查看构建产物
ls -la build/ohos/outputs/hap/release/

# HAP 文件通常位于：
# build/ohos/outputs/hap/release/<app_name>-release.har

---

5. 常见问题排查

5.1 gclient sync 失败

现象	解决方案
连接超时	检查网络代理是否正常，重新执行 gclient sync
权限错误	确保对 engine 目录有读写权限
依赖下载失败	检查是否能访问 allowed_hosts 中的 URL

5.2 构建失败

现象	解决方案
编译错误	检查 JDK 版本是否为 17，确认环境变量配置正确
内存不足	关闭其他应用程序，增加虚拟内存
依赖缺失	重新执行 gclient sync 确保所有依赖已下载

5.3 运行时问题

现象	解决方案
应用无法启动	检查 Engine 路径是否正确，确认产物文件完整
性能问题	使用 release 模式重新构建 Engine
兼容性问题	确认 Flutter SDK 版本与 Engine 版本匹配

5.4 获取帮助

如果遇到文档未涵盖的问题，可以通过以下方式获取帮助：

• 查看官方文档和 Wiki
• 在社区论坛提问
• 检查AtomGit Issues

---

附录

A. 相关链接

• OpenHarmony 官方网站
• Flutter OpenHarmony 仓库
• DevEco Studio 下载

B. 版本兼容性

Flutter 版本	OpenHarmony SDK 最低版本
3.35.7+	API 23
3.27.4+	API 20

---

文档版本：1.0
最后更新：2026-04-04
适用平台：macOS