本指导介绍如何构建支持 OpenHarmony 设备的 Flutter Engine 产物。面向有自定义 Engine 修改需求的开发者。如仅需使用 Engine 产物构建应用可直接执行flutter build hap云端会自动拉取 Engine 产物无需自行编译。1. 构建环境要求1.1 操作系统支持操作系统支持范围Linux完整支持 Engine 构建macOS完整支持 Engine 构建Windows仅支持构建gen_snapshot1.2 前置条件检查清单在开始构建前请确认以下环境已就绪环境项版本/要求验证命令JDK17及以上java -versionPython3.8 – 3.113.12 存在兼容问题python3 --versionNode.jsv14.19.1 及以上且低于 v17.0.0node -vDevEco Studio5.0.3.300 及以上—Xcode14.3 及以上仅 macOSxcodebuild -version磁盘空间建议预留 50GBdf -h1.3 网络要求构建过程需访问DEPS_ohos配置文件中allowed_hosts字段列出的全部 URLboringssl.googlesource.comchrome-infra-packages.appspot.comchromium.googlesource.comdart.googlesource.comflutter.googlesource.comllvm.googlesource.comskia.googlesource.comswiftshader.googlesource.comgitcode.com/openharmony-sig如部分域名无法访问需配置网络代理后重试。2. 搭建 Engine 构建环境2.1 安装 depot_toolsdepot_tools提供gclient与gn构建工具git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git将depot_tools添加到PATH环境变量编辑~/.zshrc或~/.bashrcexportPATH$HOME/depot_tools:$PATHsource~/.zshrc # 或 source ~/.bashrc2.2 安装基础依赖macOSHomebrewbrewinstallgit curl unzipbrewinstallpython3# 需为 3.8–3.113.12 存在兼容问题brewinstallpkg-configninjaLinuxsudoapt install git curl unzipsudoapt install python3 # 需为3.8–3.113.12存在兼容问题sudoapt install pkg-config ninja-build2.3 配置 Engine 构建环境变量在开发环境搭建的基础上确认以下环境变量已正确配置以下为 macOS 示例Linux 请将TOOL_HOME改为实际安装路径# JDKexportJAVA_HOMEJAVA_HOME pathexportPATH$JAVA_HOME/bin:$PATH# DevEco Studio 工具链含 ohpm、hvigor、node、OpenHarmony SDKexportTOOL_HOME/Applications/DevEco-Studio.app/ContentsexportDEVECO_SDK_HOME$TOOL_HOME/sdkexportPATH$TOOL_HOME/tools/ohpm/bin:$PATHexportPATH$TOOL_HOME/tools/hvigor/bin:$PATHexportPATH$TOOL_HOME/tools/node/bin:$PATH3. 获取与同步 Engine 源码3.1 配置 .gclient 文件flutter_flutter仓库内置了.gclient模板文件engine/scripts/ohos.gclient可直接使用进入已克隆的flutter_flutter源码目录cdflutter_flutter将模板文件复制为.gclientcp engine/scripts/ohos.gclient .gclient.gclient文件内容如下solutions [ {custom_deps: {},deps_file:DEPS_ohos,managed:False,name:.,safesync_url:,url:https://gitcode.com/openharmony-tpc/flutter_flutter.git, }, ]如使用 SSH 方式连接 GitCode可将url改为gitgitcode.com:openharmony-tpc/flutter_flutter.git。3.2 执行 gclient sync在.gclient所在目录执行以下命令同步源码gclientsync此命令会同步 Engine 源码、官方 packages 仓并执行ohos_setup钩子任务将构建脚本ohos等文件复制到源码根目录。注意事项同步过程需要访问allowed_hosts中列出的全部 URL如遇部分域名无法访问需配置网络代理。同步时间较长约 30–60 分钟视网络情况而定。如遇超时错误请重新执行gclient sync。同步成功完成后终端会自动退出。4. 构建 Engine4.1 执行构建代码同步完成后构建脚本ohos已自动复制到源码根目录。在该目录执行构建命令# 查看帮助./ohos-h# 构建所有模式debug profile release默认行为./ohos# 仅构建指定模式./ohos-t debug# 调试模式./ohos-t profile# 性能分析模式./ohos-t release# 发布模式4.2 构建产物构建产物位于src/out/目录下。目录命名规则为ohos_{mode}{_unopt}_{cpu}其中 debug 模式额外添加_unopt后缀构建模式Target Engine 产物目录Host Engine 产物目录debugsrc/out/ohos_debug_unopt_arm64/src/out/host_debug_unopt/profilesrc/out/ohos_profile_arm64/src/out/host_profile/releasesrc/out/ohos_release_arm64/src/out/host_release/如通过--ohos-cpu指定了非arm64的架构或通过--host-cpu指定了arm64产物目录名会相应变化。请以src/out/目录下实际生成的文件夹为准。验证构建产物ls-lasrc/out/ohos_release_arm64/ # 应包含 libflutter.so、flutter.har 等文件4.3 更新代码如需拉取最新代码后重新构建分两步执行# 第一步更新 Engine 源码到指定分支不执行构建./ohos -bmaster# 第二步重新构建 ./ohos-t release5. 使用本地 Engine 构建应用自 3.22.0 版本起Engine 编译会同时生成local-engine目标平台和local-host-engine主机平台。使用本地 Engine 构建应用时需同时指定这两个产物flutter build hap \--target-platform ohos-arm64 \--release \--local-engineohos_release_arm64 \--local-engine-hosthost_release参数说明参数说明--target-platform目标平台ohos-arm64--release构建模式--debug、--profile或--release--local-engineEngine 构建产物路径--local-engine-hostHost Engine 构建产物路径各构建模式对应的产物名称构建模式--local-engine--local-engine-hostdebugohos_debug_unopt_arm64host_debug_unoptprofileohos_profile_arm64host_profilereleaseohos_release_arm64host_release示例# 假设 engine 目录在 ~/engineflutter build hap \--target-platform ohos-arm64 \--release \--local-engineohos_release_arm64 \--local-engine-hosthost_release6. 构建 Embedding 层 HAR 产物Engine 构建完成后flutter.har位于src/out/output_dir/flutter.har目录下。如需单独构建或重建 HAR 产物可使用ohos脚本的har步骤# 构建 release 模式的 flutter.har./ohos-t release -n har# 使用未裁剪的 so 构建含调试符号./ohos-t release -n har--har-unstripped7. 常见问题7.1 gclient sync 失败现象解决方案连接超时检查网络代理是否正常确保可访问allowed_hosts中的 URL重新执行gclient sync权限错误确保对源码目录有读写权限依赖下载失败检查是否能访问allowed_hosts中的 URL必要时配置网络代理Python 相关报错确认 Python 版本为 3.8–3.113.12 版本存在兼容问题Windows 下A required privilege is not held by the client设置 → 开发者选项 → 开启「开发人员模式」7.2 构建脚本问题现象解决方案Permission denied执行chmod x ohos添加执行权限Member notfound:isOhos确保已应用 Dart 补丁补丁位于src/flutter/attachment/repos使用git apply应用后重新编译修改 Embedding 层代码后构建未生效修改任意 C 文件的时间戳如添加空格后保存再删除触发编译系统重新识别后重新构建7.3 Dart VM Snapshot Hash 不一致不同操作系统对换行符处理方式不同可能导致 Dart VM Snapshot Hash 不一致。检查方法python3 src/third_party/dart/tools/make_version.py --format{{SNAPSHOT_HASH}}如获取到的值不是预期值需检查src/third_party/dart/runtime/vm/dart.cc和src/third_party/dart/runtime/vm/image_snapshot.cc文件中所有行是否以 LF 换行符结尾Windows 可使用 Notepad 查看。