Flutter OH Engine构建指导

欢迎大家 加入跨平台开发者社区。

1. 环境准备

1.1 下载并安装DevEco Studio

1.1.1 官方下载地址

OpenHarmony开发套件官方下载地址

1.1.2 构建前注意事项

1. 支持的操作系统：
   • Linux：完整支持 Engine 构建
   • macOS：完整支持 Engine 构建
   • Windows：仅支持构建 gen_snapshot
2. 网络要求：确保构建环境可以访问 engine 源码里 DEPS_ohos 配置文件内 allowed_hosts 字段列出的所有 URL。

1.1.3 下载清单

1. 下载DevEco Studio

   根据自身操作系统下载对应最新版 DevEco Studio：

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.1.4 配置JDK环境

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

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

2. 配置环境变量后，验证安装：

   java -version
   

1.2 前置条件检查清单

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

环境项	版本/要求	验证命令
操作系统	Linux 或 macOS	uname -a
JDK	17	java -version
DevEco Studio	最新版	检查应用版本
网络	可访问外网及 allowed_hosts	-
磁盘空间	建议预留 50GB+	df -h

1.3 配置环境变量

根据您的操作系统和使用的 Shell，编辑对应的配置文件：

• macOS (zsh)：~/.zshrc
• Linux (bash)：~/.bashrc
• Linux (zsh)：~/.zshrc

macOS 配置示例

# 打开配置文件
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

Linux 配置示例

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

在配置文件中添加：

# 假设 DevEco Studio 安装在 ~/deveco-studio 目录
export TOOL_HOME=$HOME/deveco-studio
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 ~/.bashrc

---

2. 搭建Engine构建环境

2.1 安装必要工具

根据操作系统选择对应的安装命令：

macOS（使用 Homebrew）

brew install git
brew install curl
brew install unzip

Linux

sudo apt install git
sudo apt install curl
sudo apt install unzip

2.2 配置构建工具

2.2.1 克隆 depot_tools

git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git

2.2.2 添加环境变量

编辑 Shell 配置文件（~/.zshrc 或 ~/.bashrc）：

# 将 depot_tools 添加到 PATH（请替换为实际路径）
export PATH=$HOME/depot_tools:$PATH

生效配置：

source ~/.zshrc	# 或 source ~/.bashrc

2.2.3 安装基础依赖库

macOS：

brew install python3
brew install pkg-config
brew install ninja

Linux：

sudo apt install python3
sudo apt install pkg-config
sudo apt install ninja-build

2.3 配置 .gclient 文件

2.3.1 Flutter Engine 3.32 及以上版本

• 打开 git clone 到本地的 flutter_flutter 源码

  cd flutter_flutter
  

• 在本地 flutter_flutter 源码目录下，新建 .gclient 文件

  touch .gclient
  

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

• 复制 flutter_flutter/engine/scripts/ohos.gclient 里的配置内容到 flutter_flutter/.gclient 文件里

2.3.2 Flutter Engine 3.32 以下版本

• 创建 engine 目录：

  mkdir engine
  cd engine
  

• 创建 .gclient 文件：

  touch .gclient
  

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

• 配置 .gclient 文件：

  请选择 engine 版本进行配置

  • engine 3.27.4 版本

  solutions = [
    {
      "managed": False,
      "name": "src/flutter",
      "url": "git@gitcode.com:openharmony-tpc/flutter_engine.git@oh-3.27.4-dev",
      "custom_deps": {},
      "deps_file": "DEPS_ohos",
      "safesync_url": "",
      "custom_vars": {"download_emsdk": True},
    },
  ]
  

  • engine 3.22.0 版本

   solutions = [
     {
       "managed": False,
       "name": "src/flutter",
       "url": "git@gitcode.com:openharmony-sig/flutter_engine.git@oh-3.22.0",
       "custom_deps": {},
       "deps_file": "DEPS_ohos",
       "safesync_url": "",
     },
   ]
  

  • engine 3.7.12 版本

  solutions = [
    {
      "managed": False,
      "name": "src/flutter",
      "url": "git@gitcode.com:openharmony-tpc/flutter_engine.git",
      "custom_deps": {},
      "deps_file": "DEPS",
      "safesync_url": "",
    },
  ]
  

2.4 同步代码

在 .gclient 同级目录中执行以下命令同步代码：

gclient sync

这里会同步 engine 源码、官方 packages仓、执行 ohos_setup任务

注意事项：

此过程需要网络代理（科学上网）

同步时间较长（约 30-60 分钟，视网络情况而定）

如遇超时错误，请重新执行 gclient sync

同步成功完成后，终端会自动退出

---

3. 开始构建

代码同步完成后，执行构建命令：

# 进入 engine 目录
cd engine

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

构建产物路径：

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

验证构建产物：

ls -la out/ohos_debug_arm64/
# 应包含 flutter.har、libflutter.so 等文件

---

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

从 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/

参数说明：

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

示例：

# 假设 engine 目录在 ~/engine
flutter build hap \
  --target-platform ohos-arm64 \
  --release \
  --local-engine=$HOME/engine/src/out/ohos_release_arm64/ \
  --local-engine-host=$HOME/engine/src/out/host_release/

---

5. 常见问题排查

5.1 gclient sync 失败

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