Flutter-OH 3.35.7 环境配置与构建指南

Flutter-OH 3.35.7 环境配置与构建指南

Flutter-OH 3.35.7 现已正式更新，其适配 OpenHarmony 的开发分支 oh-3.35.7-dev 处于持续迭代状态，会每日进行 bug 修复与功能优化。

📌 版本信息 ：查看最新更新日志：release-notes

环境配置

开发系统支持

Flutter Tools指令目前已支持在Linux、Mac和Windows下使用。

HarmonyOS SDK 配置

请从鸿蒙SDK下载配套开发工具

• API20, DevEco Studio 6.0.2 Release 或 Command Line Tools 6.0.2 Release
• 配置 Java17
• 配置环境变量 (SDK, node, ohpm, hvigor)

Mac/Linux 环境

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

Windows 环境

使用 PowerShell：

$env:TOOL_HOME="C:\Users\你的用户名\AppData\Local\Huawei\Sdk"
$env:DEVECO_SDK_HOME="$env:TOOL_HOME\sdk"
$env:PATH="$env:TOOL_HOME\tools\ohpm\bin;$env:PATH"
$env:PATH="$env:TOOL_HOME\tools\hvigor\bin;$env:PATH"
$env:PATH="$env:TOOL_HOME\tools\node\bin;$env:PATH"

使用 CMD：

set TOOL_HOME=C:\Users\你的用户名\AppData\Local\Huawei\Sdk
set DEVECO_SDK_HOME=%TOOL_HOME%\sdk
set PATH=%TOOL_HOME%\tools\ohpm\bin;%PATH%
set PATH=%TOOL_HOME%\tools\hvigor\bin;%PATH%
set PATH=%TOOL_HOME%\tools\node\bin;%PATH%

注意 ：Windows环境下，如果使用DevEco Studio安装，SDK路径通常在 C:\Users\你的用户名\AppData\Local\Huawei\Sdk。如果使用command-line-tools，请根据实际安装路径调整。

Flutter 仓库配置

通过代码工具下载当前仓库代码，指定 oh-3.35.7-dev 分支：

Mac/Linux 环境

git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git
cd flutter_flutter
git checkout oh-3.35.7-dev

export PUB_CACHE=$HOME/.pub-cache
export PATH=你的flutter_flutter路径/bin:$PATH
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

Windows 环境

使用 PowerShell：

git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git
cd flutter_flutter
git checkout oh-3.35.7-dev

$env:PUB_CACHE="$env:USERPROFILE\.pub-cache"
$env:PATH="你的flutter_flutter路径\bin;$env:PATH"
$env:PUB_HOSTED_URL="https://pub.flutter-io.cn"
$env:FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"

使用 CMD：

git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git
cd flutter_flutter
git checkout oh-3.35.7-dev

set PUB_CACHE=%USERPROFILE%\.pub-cache
set PATH=你的flutter_flutter路径\bin;%PATH%
set PUB_HOSTED_URL=https://pub.flutter-io.cn
set FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

提示：Windows环境下，也可以使用Git Bash，命令与Mac/Linux相同。
💡 重要提示 ：由于 oh-3.35.7-dev 是开发分支 ，官方会每日进行bug修复、问题优化，建议每次开发前/定期 在 flutter_flutter 目录下执行 git pull 同步仓库最新更新。

Engine 构建产物配置

应用构建依赖 Flutter engine 构建产物与 engine host，默认从云端获取。也可以手工指定本地构建产物：

使用示例：

--local-engine=src/out/engine产物目录 --local-engine-host=src/out/host产物目录

构建产物目录说明：

• Engine产物 ：ohos_debug_arm64、ohos_release_arm64、ohos_profile_arm64
• Engine Host产物 ：host_debug、host_release、host_profile

构建步骤

1. 环境检查

运行 flutter doctor -v 检查环境变量配置是否正确，Flutter 与OpenHarmony应都为ok标识。

2. 创建工程

Mac/Linux：

# 创建工程
flutter create --platforms ohos 你的项目名称

# 编译命令（选择一种构建模式）
flutter build hap --target-platform ohos-arm64 --debug
flutter build hap --target-platform ohos-arm64 --release
flutter build hap --target-platform ohos-arm64 --profile

# 使用本地engine（可选）
flutter build hap --target-platform ohos-arm64 --release \
  --local-engine=src/out/ohos_release_arm64 \
  --local-engine-host=src/out/host_release

Windows：

# 创建工程
flutter create --platforms ohos 你的项目名称

# 编译命令（选择一种构建模式）
flutter build hap --target-platform ohos-arm64 --debug
flutter build hap --target-platform ohos-arm64 --release
flutter build hap --target-platform ohos-arm64 --profile

# 使用本地engine（可选）
flutter build hap --target-platform ohos-arm64 --release `
  --local-engine=src/out/ohos_release_arm64 `
  --local-engine-host=src/out/host_release

编译产物位置：

• Mac/Linux: 你的项目名称/ohos/entry/build/default/outputs/default/entry-default-signed.hap
• Windows: 你的项目名称\ohos\entry\build\default\outputs\default\entry-default-signed.hap

3. Impeller 渲染开关

当前Flutter ohos平台中支持impeller-vulkan渲染模式，可通过开关控制是否打开。

开关位于 ohos/entry/src/main/resources/rawfile/buildinfo.json5 文件中，文件内容如下：

{
  "string": [
    {
      "name": "enable_impeller",
      "value": "true"
    }
  ]
}

说明：

• 新建工程默认打开impeller选项
• 对于旧工程，可将以上 buildinfo.json5 文件复制到工程目录的对应路径下（rawfile目录），并修改 value 值即可实现开关功能
• 设置为 "true" 启用impeller渲染，设置为 "false" 禁用

4. 安装与运行

通过 flutter devices 指令发现ohos设备之后，使用以下命令安装：

Mac/Linux：

# 安装HAP文件
hdc -t 设备ID install HAP文件路径

# 或直接运行（推荐）
flutter run --debug -d 设备ID

# 使用本地engine运行（可选）
flutter run --debug \
  --local-engine=你的路径/src/out/ohos_debug_unopt_arm64 \
  --local-engine-host=你的路径/src/out/host_debug_unopt \
  -d 设备ID

Windows：

# 安装HAP文件（路径使用正斜杠或反斜杠均可）
hdc -t 设备ID install HAP文件路径

# 或直接运行（推荐）
flutter run --debug -d 设备ID

# 使用本地engine运行（可选）
flutter run --debug `
  --local-engine=你的路径/src/out/ohos_debug_unopt_arm64 `
  --local-engine-host=你的路径/src/out/host_debug_unopt `
  -d 设备ID

注意 ：Windows PowerShell使用反引号 ````` 作为行继续符，CMD和Git Bash使用反斜杠 \。

5. 构建 App 包

Mac/Linux：

# 构建App包
flutter build app --release

# 使用本地engine构建（可选）
flutter build app --release \
  --local-engine=你的路径/src/out/ohos_release_arm64 \
  --local-engine-host=你的路径/src/out/host_release

Windows：

# 构建App包
flutter build app --release

# 使用本地engine构建（可选）
flutter build app --release `
  --local-engine=你的路径/src/out/ohos_release_arm64 `
  --local-engine-host=你的路径/src/out/host_release

已兼容 OpenHarmony 开发的指令列表

指令名称	指令描述	使用说明
doctor	环境检测	flutter doctor
config	环境配置	flutter config --配置项 配置值
create	创建新项目	flutter create --platforms ohos,android,ios --org 组织名 应用名称
create	创建module模板	flutter create -t module 模块名称
create	创建plugin模板	flutter create -t plugin --platforms ohos,android,ios 插件名称
create	创建plugin_ffi模板	flutter create -t plugin_ffi --platforms ohos,android,ios 插件名称
devices	已连接设备查找	flutter devices
install	应用安装	flutter install -t 设备ID HAP文件路径
assemble	资源打包	flutter assemble
build	测试应用构建	flutter build hap --debug [--target-platform ohos-arm64]
build	正式应用构建	flutter build hap --release [--target-platform ohos-arm64]
run	应用运行	flutter run [-d 设备ID]
attach	调试模式	flutter attach
screenshot	截屏	flutter screenshot
pub	获取依赖	flutter pub get
clean	清除项目依赖	flutter clean
cache	清除全局缓存数据	flutter pub cache clean

参考资源

• Flutter三方库适配计划
• Flutter-OH 仓库地址
• Flutter-OH 示例代码
• 开源鸿蒙跨平台开发者社区