鸿蒙版 Flutter 应用构建指导

本文介绍从环境检查、创建工程、签名、编译到安装的完整流程，适用于在 OpenHarmony / HarmonyOS 上构建 Flutter 应用。

一、环境检查

在项目根目录执行：

flutter doctor -v

确认 Flutter 与 HarmonyOS toolchain 两项均为 [√]。若出现 [!]，按终端提示配置对应环境（如 ohos-sdk 路径、环境变量等）。

• 环境配置参考：OpenHarmony 版 Flutter 环境配置^[1]

二、创建应用

flutter create --platforms ohos <projectName>

将 <projectName> 替换为你的工程名。执行后会在当前目录生成带 ohos 平台目录的 Flutter 工程。

三、配置签名

1. 使用 DevEco Studio 打开 <projectName>/ohos 目录（不要打开整个 Flutter 工程根目录）。
2. 打开 File → Project Structure → Signing Configs，按向导配置签名。
3. 配置完成后保存，后续编译出的 HAP 将使用该签名。

四、Impeller 渲染开关（可选）

OpenHarmony 版 Flutter 支持 Impeller-Vulkan 渲染，可通过配置文件开关控制。

配置文件路径（首次 flutter run 或 flutter build 后会在 rawfile 下生成）：

• ohos/entry/src/main/resources/rawfile/buildinfo.json5
• 若尚未运行/构建，可能位于 ohos/entry/src/main/resources/profile/buildinfo.json5，运行或构建后会自动迁移到 rawfile。

文件内容示例：

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

• "value": "true"：开启 Impeller 渲染（新建工程默认开启）。
• "value": "false"：关闭 Impeller 渲染，修改后下次运行生效。

旧工程若没有该文件，可从其他工程复制到上述 rawfile 路径，并按需修改 value。不添加该配置时，默认按开启处理。

五、编译应用

在工程根目录执行：

Debug 构建（开发调试）：

flutter build hap --debug

Release 构建（发布用）：

flutter build hap --release

指定目标架构（可选）：

flutter build hap --release --target-platform ohos-arm64

使用本地引擎（可选，多用于引擎开发/调试）：

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

路径需替换为你本机引擎产物目录。

产物位置（默认签名后）：

• <projectName>/ohos/entry/build/default/outputs/default/entry-default-signed.hap

六、运行与安装

1. 发现设备

flutter devices

确认列表中出现 OHOS 设备或模拟器，并记下 <deviceId>。

2. 直接运行（推荐开发时使用）

flutter run --debug -d <deviceId>

应用将自动编译、安装并启动。

3. 仅安装已有 HAP

若已通过 flutter build hap 生成 HAP，可使用 hdc 安装：

hdc -t <deviceId> install <hap文件路径>

七、小结

完成以上步骤后即可开始日常开发与调试。