Flutter OH Engine构建指导

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

1. 环境准备

1.1 下载并安装DevEco Studio

1.1.1 官方下载地址

OpenHarmony开发套件官方下载地址

1.1.2 构建前注意事项

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

1.1.3 下载清单

下载DevEco Studio

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

下载OpenHarmony版Flutter SDK

shell 复制代码

# 克隆仓库
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：

从 Oracle官网或 OpenJDK 下载 JDK 17
配置环境变量后，验证安装：
shell 复制代码
```
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 配置示例

shell 复制代码

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

在配置文件中添加：

shell 复制代码

# 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

保存并生效：

shell 复制代码

# 保存文件（Esc → :wq → Enter）
source ~/.zshrc

Linux 配置示例

shell 复制代码

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

在配置文件中添加：

shell 复制代码

# 假设 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

保存并生效：

shell 复制代码

# 保存文件（Esc → :wq → Enter）
source ~/.bashrc

2. 搭建Engine构建环境

2.1 安装必要工具

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

macOS（使用 Homebrew）

shell 复制代码

brew install git
brew install curl
brew install unzip

Linux

shell 复制代码

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

2.2 配置构建工具

2.2.1 克隆 depot_tools

shell 复制代码

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

2.2.2 添加环境变量

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

shell 复制代码

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

生效配置：

shell 复制代码

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

2.2.3 安装基础依赖库

macOS：

shell 复制代码

brew install python3
brew install pkg-config
brew install ninja

Linux：

shell 复制代码

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 源码
shell 复制代码
```
cd flutter_flutter
```
在本地 flutter_flutter 源码目录下，新建 .gclient 文件
shell 复制代码
```
touch .gclient
```
提示：macOS 下查看隐藏文件可按 Command (⌘) + Shift (⇧) + .(句号)
复制 flutter_flutter/engine/scripts/ohos.gclient 里的配置内容到 flutter_flutter/.gclient 文件里

2.3.2 Flutter Engine 3.32 以下版本

创建 engine 目录：
shell 复制代码
```
mkdir engine
cd engine
```
创建 .gclient 文件：
复制代码
```
touch .gclient
```
提示：macOS 下查看隐藏文件可按 Command (⌘) + Shift (⇧) + .(句号)

配置 .gclient 文件：

请选择 engine 版本进行配置

engine 3.27.4 版本

json 复制代码

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 版本

json 复制代码

 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 版本

json 复制代码

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 同级目录中执行以下命令同步代码：

shell 复制代码

gclient sync

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

注意事项：

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

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

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

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

3. 开始构建

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

shell 复制代码

# 进入 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

验证构建产物：

shell 复制代码

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

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

从 3.22.0 版本开始，Engine 编译会同时生成 local-engine 和 local-host-engine。

使用本地 Engine 构建应用时，需要同时指定这两个参数：

shell 复制代码

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 产物路径

示例：

shell 复制代码

# 假设 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