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

不爱吃糖的程序媛2026-02-13 8:24

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

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

一、参考文档

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

二、环境依赖与配置

2.1 开发系统支持

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

2.2 环境配置步骤

步骤1：安装基础配套工具
工具名称 版本要求 下载地址 备注
JDK 17 Oracle JDK17 下载页 必须使用17版本，低版本不兼容
DevEco Studio / 命令行工具 最新版 华为开发者官网 二选一，推荐安装DevEco Studio（插件开发需依赖）
步骤2：下载 Flutter OH SDK

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

powershell 复制代码 
# 克隆仓库并切换到指定分支
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 复制代码 
    # bash终端：vim ~/.bash_profile；zsh终端：vim ~/.zshrc
vim ~/.zshrc

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

    bash 复制代码 
    # ===== 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. 保存并生效配置：

    bash 复制代码 
    # 按 Esc → 输入 :wq 保存退出vim
source ~/.zshrc # 使配置立即生效
# 验证配置（可选）
echo $JAVA_HOME # 应输出JDK17路径
flutter --version # 应识别到flutter命令
（2）Windows 系统
  1. 打开环境变量配置界面：
    右键「此电脑」→「属性」→「高级系统设置」→「高级」→「环境变量」。
  2. 配置系统变量（新增/编辑，路径替换为实际值）：
变量类别 变量名 变量值 操作说明
系统变量 JAVA_HOME C:\Program Files\Java\jdk-17 新增
系统变量 TOOL_HOME D:\DevEco-Studio 新增（DevEco安装路径）
系统变量 DEVECO_SDK_HOME %TOOL_HOME%\sdk 新增
系统变量 PUB_CACHE D:\PUB 新增（Flutter缓存目录）
系统变量 PUB_HOSTED_URL https://pub.flutter-io.cn 新增（国内镜像）
系统变量 FLUTTER_STORAGE_BASE_URL https://storage.flutter-io.cn 新增（国内镜像）
Path变量 %JAVA_HOME%\bin 追加到Path末尾 编辑Path，新增该行
Path变量 %TOOL_HOME%\tools\ohpm\bin 追加到Path末尾 编辑Path，新增该行
Path变量 %TOOL_HOME%\tools\hvigor\bin 追加到Path末尾 编辑Path，新增该行
Path变量 %TOOL_HOME%\tools\node\bin 追加到Path末尾 编辑Path，新增该行
Path变量 D:\flutter_flutter\bin 追加到Path末尾（Flutter SDK路径） 编辑Path，新增该行

  1. 验证配置：

    打开新的CMD/PowerShell窗口，执行以下命令，无报错则生效：

    powershell 复制代码 
    java -version # 显示jdk17版本
flutter --version # 识别flutter命令

三、Flutter OH 应用构建指南

3.1 环境校验

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

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

3.2 创建并编译工程

bash 复制代码 
# 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）：

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

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

3.4 安装与运行应用

bash 复制代码 
# 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：创建插件工程
sh 复制代码 
# 创建支持Android、iOS、OHOS的插件项目（指定组织名+插件名）
flutter create --org com.example --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工程识别）：

yaml 复制代码 
flutter:
  plugin:
    platforms:
      android:
        package: com.example.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. 编译示例工程验证：

    sh 复制代码 
    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 平台支持：

sh 复制代码 
flutter create . --template=plugin --platforms=ohos

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

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

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

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

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

五、核心指令速查表

指令 功能描述 典型使用示例
flutter doctor 环境检测 flutter doctor -v（详细输出）
flutter create 创建项目/插件 应用：flutter create --platforms ohos my_app 原生插件：flutter create --template=plugin --platforms=ohos hello_plugin FFI插件：flutter create --template=plugin_ffi --platforms=ohos hello_ffi
flutter devices 查看已连接OHOS设备 flutter devices
flutter build hap 构建OHOS应用HAP包 调试版：flutter build hap --debug 正式版：flutter build hap --release
flutter run 运行OHOS应用 flutter run -d <device-id> --debug
flutter pub get 下载项目/插件依赖 flutter pub get
flutter clean 清除项目缓存/依赖 flutter clean
flutter screenshot 设备截屏 flutter screenshot

备注：所有指令均适配 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 插件适用于跨语言调用场景。
相关推荐
恋猫de小郭18 小时前
2026 Flutter VS React Native ，同时在 AI 时代 VS Native 开发，你没见过的版本
android·前端·flutter
明君879971 天前
Flutter 如何给图片添加多行文字水印
前端·flutter
四眼肥鱼1 天前
flutter 利用flutter_libserialport 实现SQ800 串口通信
前端·flutter
火柴就是我2 天前
让我们实现一个更好看的内部阴影按钮
android·flutter
王晓枫2 天前
flutter接入三方库运行报错：Error running pod install
前端·flutter
shankss2 天前
Flutter 下拉刷新库 pull_to_refresh_plus 设计与实现分析
flutter
忆江南3 天前
iOS 深度解析
flutter·ios
明君879973 天前
Flutter 实现 AI 聊天页面 —— 记一次 Markdown 数学公式显示的踩坑之旅
前端·flutter
恋猫de小郭3 天前
移动端开发稳了？AI 目前还无法取代客户端开发，小红书的论文告诉你数据
前端·flutter·ai编程
MakeZero3 天前
Flutter那些事-交互式组件
flutter
热门推荐
01GitHub 镜像站点02OpenClaw 使用和管理 MCP 完全指南03OpenClaw + 飞书（Feishu）环境搭建指南04OpenClaw优化飞书API 额度已耗尽问题05Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services06本地部署 OpenClaw + DeepSeek-R1 完全指南07Window 10部署openclaw报错node.exe : npm error code 12808小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）09OpenClaw大龙虾机器人完整安装教程10Clawdbot部署教程：解决‘gateway token missing’授权问题的完整步骤