Flutter 鸿蒙三方库适配指南

第四章：Flutter 鸿蒙开发环境搭建指南 (MacOS & Windows)

前言：在了解了 ArkTS 和 Flutter 的基础架构后，本章我们将进入实战环节。要在鸿蒙系统上运行 Flutter 应用，必须使用鸿蒙社区维护的 Flutter SDK 版本，并配合华为官方的 DevEco Studio。本指南将分别针对 MacOS 和 Windows 用户，详细讲解环境搭建的每一个步骤。

---

一、 核心准备工作 (通用)

无论使用哪种操作系统，以下准备工作是必须的：

1. Git 工具：
   • 用于克隆代码仓库。
   • Windows 用户：建议安装 Git Bash，并在安装时勾选添加到系统 PATH。
   • MacOS 用户：通常系统自带，如版本过低可通过 brew install git 升级。
2. 网络环境：
   • 由于部分资源位于国外服务器，建议配置良好的网络环境，或在后续步骤中配置国内镜像源。

---

二、 安装 DevEco Studio 与 OpenHarmony SDK

DevEco Studio 是鸿蒙开发的官方 IDE，我们需要依赖它提供的 SDK 和编译工具链。

1. 下载与安装

• 访问 HarmonyOS 开发者官网。
• 根据你的操作系统（Mac x86/ARM 或 Windows x64）下载对应的 DevEco Studio 安装包。
• 按照提示完成安装。

2. 下载 OpenHarmony SDK

安装完成后，启动 DevEco Studio 并进行如下配置：

1. 进入 SDK 管理页：
   • Mac：点击顶部菜单 DevEco Studio -> Preferences -> SDK。
   • Windows：点击 File -> Settings -> SDK。
2. 选择 OpenHarmony SDK：
   • 在 SDK 列表中，勾选 API Version 15 (或视频中演示的最新版本)。
   • 关键步骤：确保右侧侧边栏中勾选了 Native (用于 C++ 编译) 和 Toolchains。
3. 执行下载：点击 Apply 和 OK，等待 SDK 组件下载完成。
4. 记录路径：请记下 SDK 的安装路径（Location），后续配置环境变量时需要用到。

---

三、 获取鸿蒙版 Flutter SDK

注意：官方 Google Flutter SDK 尚未完全合并鸿蒙支持，我们需要使用 OpenHarmony-SIG (鸿蒙开源社区) 维护的分支版本。

1. 确定仓库与分支

• 仓库地址：Gitee - OpenHarmony-SIG/flutter_flutter (或者 GitCode 镜像)。
• 推荐分支：视频中推荐使用 custom_3.22.0 分支（基于 Flutter 3.22.0 深度适配）。

2. 克隆代码 (Windows/Mac 通用)

在终端（Terminal）或 Git Bash 中执行以下命令。建议创建一个名为 fvm/versions 的目录来管理不同版本的 SDK：

# 进入你希望存放 SDK 的目录
cd ~/fvm/versions  # 示例路径，请根据实际情况调整

# 克隆指定分支代码
git clone -b custom_3.22.0 https://gitee.com/openharmony-sig/flutter_flutter.git custom_3.22.0

• 该命令会将代码克隆到当前目录下的 custom_3.22.0 文件夹中。

---

四、 环境变量配置

这是最关键的一步，系统需要通过环境变量找到 Flutter 命令以及鸿蒙的构建工具。

场景 A：MacOS 环境配置

Mac 用户通常修改 Shell 配置文件（如 ~/.zshrc 或 ~/.bash_profile）。

1. 打开配置文件：

   vim ~/.zshrc
   

2. 添加以下内容（请根据你的实际安装路径修改路径部分）：

   # 1. 配置 Flutter 镜像 (加速下载)
   export PUB_HOSTED_URL=https://pub.flutter-io.cn
   export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
   
   # 2. 配置 Flutter SDK 路径
   # 假设你克隆到了 ~/fvm/versions/custom_3.22.0
   export PATH="$HOME/fvm/versions/custom_3.22.0/bin:$PATH"
   
   # 3. 配置鸿蒙 SDK 路径 (DevEco Studio 的 SDK Location)
   # 默认路径通常如下，请核对你的实际路径
   export DEVECO_SDK_HOME="/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony"
   
   # 4. 配置鸿蒙工具链 (OHPM, Hvigor, Node)
   # 这些工具通常在 DevEco Studio 安装目录的 tools 中
   export PATH="/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin:$PATH"
   export PATH="/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin:$PATH"
   export PATH="/Applications/DevEco-Studio.app/Contents/tools/node/bin:$PATH"
   

3. 生效配置：

   source ~/.zshrc
   

场景 B：Windows 环境配置

Windows 用户需在“系统属性” -> “环境变量”中进行图形化配置。

1. 打开环境变量设置：右键“此电脑” -> “属性” -> “高级系统设置” -> “环境变量”。

2. 配置用户变量 (新建或编辑)：

   变量名	变量值 (示例路径，请替换为你的实际路径)	说明
   PUB_HOSTED_URL	https://pub.flutter-io.cn	镜像源
   FLUTTER_STORAGE_BASE_URL	https://storage.flutter-io.cn	镜像源
   DEVECO_SDK_HOME	C:\Users\YourName\AppData\Local\OpenHarmony\Sdk	鸿蒙 SDK 根目录
   JAVA_HOME	C:\Program Files\Huawei\DevEco Studio\jbr	重要：推荐使用 DevEco 自带的 JBR 避免版本冲突

3. 配置 Path 变量 (在 Path 中添加以下条目)：

   • Flutter Bin 目录：D:\fvm\versions\custom_3.22.0\bin
   • OHPM Bin 目录：C:\Users\YourName\AppData\Local\Huawei\ohpm\bin (或 DevEco 安装目录下的 tools/ohpm/bin)
   • Hvigor Bin 目录：C:\Program Files\Huawei\DevEco Studio\tools\hvigor\bin
   • Node Bin 目录：C:\Program Files\Huawei\DevEco Studio\tools\node
   • Git 命令目录：C:\Program Files\Git\cmd

   > 注意：Windows 下的工具链路径可能因安装方式不同位于 AppData 下或 DevEco 安装目录下，请务必在文件资源管理器中确认路径存在后再填写。

---

五、 检查环境 (Verify)

配置完成后，我们需要验证环境是否完整。

1. 重启终端：关闭并重新打开 Terminal (Mac) 或 PowerShell/CMD (Windows) 以加载新的环境变量。
2. 运行诊断命令：

   flutter doctor
   

3. 分析输出结果：
   • Flutter：应显示 Channel custom_3.22.0，版本号正确。
   • HarmonyOS：应显示 HarmonyOS toolchain - develop for HarmonyOS devices，且状态为 ✅。
   • OpenHarmony：如果配置了 OpenHarmony SDK，也应显示为 ✅。
   • IDE：DevEco Studio 若已安装插件会显示勾选（此处插件非必须，核心是工具链）。

常见问题排查：

• 报错 command not found: flutter：检查 PATH 中是否正确添加了 Flutter 的 bin 目录。
• Java 报错：Windows 用户请检查 JAVA_HOME 是否指向了 DevEco Studio 自带的 jbr 目录，且该路径已包含在 Path 中。
• SDK 版本警告：确保下载的 OpenHarmony SDK 版本（如 API 15）与 Flutter 鸿蒙分支要求的版本匹配。

---

六、 本章总结

通过本章的操作，我们已经成功在本地机器上建立起了 Flutter 与鸿蒙之间的桥梁。

• 我们安装了 DevEco Studio 获取了构建鸿蒙应用的基础能力。
• 我们克隆了 社区版 Flutter SDK，使其具备编译鸿蒙代码的能力。
• 我们通过 环境变量 将两者串联起来。

下一章预告：
环境搭建完毕后，我们将深入探讨 插件适配原理，解析 Flutter 究竟是如何通过 Platform Channel 调用鸿蒙原生能力的。