Flutter OH 3.35.7 环境配置与插件开发指南

一、参考文档

Flutter OH 开发相关的指导、规范及资料，优先参考以下官方文档：

• Google Flutter 官方文档：Flutter 核心开发指南与 API 参考。

• Flutter OH 适配开发文档：Flutter 适配 OpenHarmony 的专属开发指导与示例工程。

二、环境依赖与配置

2.1 开发系统支持

Flutter Tools 指令已适配 Linux、macOS、Windows 三大主流操作系统，可按需选择。

2.2 环境配置步骤

步骤1：安装基础配套工具

步骤2：下载 Flutter OH SDK

克隆 OpenHarmony 适配版 Flutter 仓库的 oh-3.35.7-dev 分支（指定分支避免拉取错误版本）：

# 克隆仓库并切换到指定分支
git clone -b oh-3.35.7-dev https://gitcode.com/openharmony-tpc/flutter_flutter.git

步骤3：配置环境变量

核心提示：所有路径需替换为本地实际安装路径，路径中禁止包含中文、空格或特殊字符，否则会导致环境识别失败。

（1）macOS / Linux 系统

1. 编辑环境配置文件（优先选 ~/.zshrc，新版macOS默认使用zsh）：

   # bash终端：vim ~/.bash_profile；zsh终端：vim ~/.zshrc
   vim ~/.zshrc

2. 在文件末尾添加以下配置（替换 <你的路径> 为实际值）：

   # ===== JDK 17 配置 =====
   export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home
   export PATH=$JAVA_HOME/bin:$PATH
   ​
   # ===== OpenHarmony 工具链配置 =====
   # DevEco Studio 安装路径（macOS示例）
   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
   ​
   # ===== Flutter 配置 =====
   # PUB缓存目录（自定义，避免权限问题）
   export PUB_CACHE=~/PUB
   # Flutter SDK 路径（替换为克隆的flutter_flutter目录）
   export PATH=/Users/你的用户名/flutter_flutter/bin:$PATH
   # 国内镜像源（加速依赖下载）
   export PUB_HOSTED_URL=https://pub.flutter-io.cn
   export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

3. 保存并生效配置：

   # 按 Esc → 输入 :wq 保存退出vim
   source ~/.zshrc # 使配置立即生效
   # 验证配置（可选）
   echo $JAVA_HOME # 应输出JDK17路径
   flutter --version # 应识别到flutter命令

（2）Windows 系统

1. 打开环境变量配置界面： 右键「此电脑」→「属性」→「高级系统设置」→「高级」→「环境变量」。

2. 配置系统变量（新增/编辑，路径替换为实际值）：

1. 验证配置： 打开新的CMD/PowerShell窗口，执行以下命令，无报错则生效：

   java -version # 显示jdk17版本
   flutter --version # 识别flutter命令

三、Flutter OH 应用构建指南

3.1 环境校验

# 详细检查环境配置（关键：Flutter和HarmonyOS toolchain需显示[√]）
flutter doctor -v

提示：若出现 [!] 警告，根据提示补全依赖（如缺失的SDK组件、权限问题等）。

3.2 创建并编译工程

# 1. 创建仅支持OHOS的工程（指定平台，避免冗余）
flutter create --platforms ohos my_ohos_app
​
# 2. 进入工程目录
cd my_ohos_app
​
# 3. 编译HAP包（release版，指定arm64架构）
# 基础版（使用默认engine）
flutter build hap --target-platform ohos-arm64 --release
# 自定义engine版（需提前构建engine）
flutter build hap --target-platform ohos-arm64 --release --local-engine=src/out/ohos_release_arm64

编译产物路径：<工程名>/ohos/entry/build/default/outputs/default/entry-default-signed.hap

3.3 Impeller 渲染开关配置

Flutter OH 支持 Impeller-Vulkan 渲染模式（默认开启），可通过以下方式开关：

1. 配置文件路径：ohos/entry/src/main/resources/rawfile/buildinfo.json5（首次build/run后生成，初始在profile目录）。

2. 配置内容（修改value为true/false）：

   {
     "string": [
       {
         "name": "enable_impeller",
         "value": "true" // true=开启，false=关闭
       }
     ]
   }

提示：旧工程需手动创建该文件并放到指定路径，否则默认开启Impeller。

3.4 安装与运行应用

# 1. 查看已连接的OHOS设备
flutter devices
​
# 2. 方式1：手动安装HAP包（替换deviceId和hap路径）
hdc -t <deviceId> install <hap文件绝对路径>
​
# 3. 方式2：直接运行（调试版，自动编译+安装+启动）
flutter run --debug -d <device-id>
# 自定义engine运行
flutter run --debug -d <device-id> --local-engine=src/out/ohos_debug_unopt_arm64

3.5 构建 Flutter OH Engine

如需自定义构建 Flutter OH Engine，参考官方文档： Flutter OH Engine 构建指导

四、Flutter OH 插件开发指南

4.1 开发原生插件（Packages）

步骤1：创建插件工程

# 创建支持Android、iOS、OHOS的插件项目（指定组织名+插件名）
flutter create --org com.nutpi --template=plugin --platforms=android,ios,ohos hello_plugin

工程结构说明：

• lib/hello_plugin.dart：Dart 层插件 API 实现（对外暴露的接口）；

• android/src/main/：Android 平台原生实现（Kotlin/Java）；

• ios/Classes/：iOS 平台原生实现（Objective-C/Swift）；

• ohos/hello_plugin/src/main/ets/：OHOS 平台原生实现（ArkTS）；

• example/：插件使用示例工程（可直接运行验证插件功能）。

步骤2：配置插件支持的平台

在插件根目录的 pubspec.yaml 中，补充 OHOS 平台配置（确保插件能被OHOS工程识别）：

flutter:
  plugin:
    platforms:
      android:
        package: com.nutpi.hello_plugin
        pluginClass: HelloPlugin
      ios:
        pluginClass: HelloPlugin
      ohos:
        pluginClass: HelloPlugin # 与OHOS侧ArkTS实现类名一致
​
environment:
  sdk: ">=2.19.6 <3.0.0"
  flutter: ">=2.5.0" # 最低兼容版本

步骤3：实现插件功能

1. 编辑 lib/hello_plugin.dart：定义 Dart 层对外暴露的 API（如方法、参数、回调）；

2. 编辑 OHOS 侧代码：在 ohos/hello_plugin/src/main/ets/components/plugin/HelloPlugin.ets 中实现 ArkTS 原生逻辑；

3. 编译示例工程验证：

   cd hello_plugin/example # 进入示例工程目录
   flutter pub get # 下载依赖
   flutter build hap --debug # 编译OHOS版HAP包

步骤4：DevEco Studio 调试（可选）

如需可视化调试 OHOS 原生代码，推荐使用 DevEco Studio：

1. 启动 DevEco Studio，打开 hello_plugin/example/ohos 目录；

2. 配置签名：File → Project Structure → Signing Configs → 勾选「Support HarmonyOS & Automatically generate signature」→ 登录华为开发者账号；

3. 运行项目：选择 OHOS 设备/模拟器，点击运行按钮即可调试。

4.2 为现有插件添加 OHOS 支持

若已有 Flutter 插件未适配 OHOS，在插件根目录执行以下命令即可快速添加 OHOS 平台支持：

flutter create . --template=plugin --platforms=ohos

提示：执行后会自动生成 OHOS 平台的基础工程结构，只需补充 ArkTS 原生实现代码即可。

4.3 开发 FFI 插件（跨语言调用）

FFI（Foreign Function Interface）插件支持 Flutter 调用 C/C++ 代码，适配 OHOS 平台的创建命令：

# 创建仅支持OHOS的FFI插件
flutter create hello_ffi_plugin --template=plugin_ffi --platforms=ohos

适用场景：需要调用 C/C++ 底层库、高性能计算、硬件交互等场景。

五、核心指令速查表

备注：所有指令均适配 OpenHarmony 平台，仅新增 --platforms ohos/--target-platform ohos-arm64 等 OH 专属参数。

六、常见问题提示

1. 环境配置失败：检查 JDK 版本是否为17、环境变量路径是否有中文/空格、Flutter SDK 分支是否正确；

2. 插件编译报错：确保 DevEco Studio 已配置签名、OHOS SDK 版本与插件适配、pubspec.yaml 中平台配置完整；

3. 运行应用失败：确认设备已连接（flutter devices 能识别）、HAP 包架构与设备匹配（arm64/arm32）。

总结

1. 环境配置核心：JDK 必须用17版本，环境变量路径无中文/空格，通过 flutter doctor -v 校验环境；

2. 应用构建关键：使用 flutter build hap 编译 HAP 包，Impeller 渲染可通过 buildinfo.json5 开关；

3. 插件开发要点：原生插件需配置 pubspec.yaml 平台信息，现有插件可通过 flutter create 快速添加 OHOS 支持，FFI 插件适用于跨语言调用场景。