鸿蒙版 Flutter 环境 3.32 版本搭建指南（Mac 版）

Flutter Flutter 项目是我们整个工程的核心，但是很多人都倒在了第一步，其原因就是——需要使用 Dev 分支！！！

项目地址：https://atomgit.com/openharmony-tpc/flutter_flutter

 

注意事项

1. 支持的操作系统：目前支持 Linux、Mac、Windows 环境下使用

2. 系统架构判断：Mac 系统在终端输入uname -m判断系统架构选择对应的开发组件套

   • 如果输出结果是 x86_64，则表示你的系统是 x86-64 架构

   • 如果输出结果是 arm64，则表示你的系统是 arm64 架构（如 M1/M2/M3/M4 芯片）

3. IDE 版本要求：使用官方下载地址的最新套件更加稳定，性能更佳，且鸿蒙 Flutter 需要依赖最新套件编译

本文以 Mac 系统为例进行详细说明。

下载并安装鸿蒙最新开发套件

1. 下载 DevEco Studio

鸿蒙开发套件官方下载地址：https://developer.huawei.com/consumer/cn/download/[1]

2. 推荐版本信息

我们本次演示用的 IDE 版本是：

DevEco Studio 6.0.0 Beta3
Build Version: 6.0.0.828, built on August 19, 2025
Runtime version: 21.0.6+8-b631.39 aarch64 (JCEF 122.1.9)
VM: OpenJDK 64-Bit Server VM by JetBrains s.r.o.
Toolkit: sun.lwawt.macosx.LWCToolkit
macOS 15.2
GC: G1 Young Generation, G1 Concurrent GC, G1 Old Generation
Memory: 1536M
Cores: 10
Metal Rendering is ON
Registry:
  idea.plugins.compatible.build=IC-243.24978.46

3. 安装步骤

1. 下载对应架构的 DevEco Studio 安装包

2. 双击安装包进行安装

3. 首次启动时，会自动下载必要的 SDK 组件

4. 安装完成后，记录安装路径（通常在/Applications/DevEco-Studio.app/Contents）

下载鸿蒙版 Flutter（3.32.4 版本）

1. 克隆项目

项目地址：https://atomgit.com/openharmony-tpc/flutter_flutter

通过 Git 工具下载仓库代码并指定 oh-3.32.4-dev 分支：

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

2. 验证下载

下载完成后，可以验证 Flutter 版本：

./bin/flutter --version
flutter doctor -v

3. 版本特点

Flutter 3.32.4 版本特点：

• 支持最新的鸿蒙系统特性

• 性能优化和稳定性提升

• 更好的开发工具集成

• 支持最新的 API 和组件

下载完成后就可以配置开发环境了。

环境变量配置

1. 配置文件选择

对于 M4 苹果电脑（ARM64 架构），建议使用~/.zshrc配置文件：

# 编辑zsh配置文件（推荐）
open ~/.zshrc

# 或者使用命令行编辑
nano ~/.zshrc

如果使用 bash shell，则编辑：

open ~/.bash_profile

2. 环境变量配置

在配置文件中添加以下环境变量：

# DevEco Studio配置
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路径配置（请根据实际路径修改）
export PATH=/Users/jianguo/Desktop/harmony/flutter/flutter_flutter/bin:$PATH

# Flutter镜像配置（加速下载）
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

# Flutter Git配置（解决警告）
export FLUTTER_GIT_URL=git@gitcode.com:openharmony-tpc/flutter_flutter.git

# Android SDK配置（如果需要Android开发）
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$ANDROID_HOME/tools:$PATH
export PATH=$ANDROID_HOME/platform-tools:$PATH

3. 刷新配置

配置完成后，刷新环境变量：

# 如果使用zsh
source ~/.zshrc

# 如果使用bash
source ~/.bash_profile

4. 注意事项

• 请根据实际的 DevEco Studio 安装目录修改TOOL_HOME路径

• Flutter 路径需要根据实际下载位置进行修改

• 如果本地有多个安装目录，请选择正确的路径进行配置

   

环境检测

1. 运行环境检测

配置完成后，运行以下命令检测环境变量是否配置正确：

flutter doctor -v

2. 检测结果分析

运行检测后，您会看到类似以下的输出：

Downloading darwin-arm64/font-subset tools...                      256ms
[!] Flutter (Channel [user-branch], 3.32.4-ohos-0.0.1, on macOS 15.2 24C103 darwin-arm64, locale zh-Hans-CN) [81ms]
    ! Flutter version 3.32.4-ohos-0.0.1 on channel [user-branch] at /Users/jianguo/Desktop/harmony/flutter/flutter_flutter
      Currently on an unknown channel. Run `flutter channel` to switch to an official channel.
      If that doesn't fix the issue, reinstall Flutter by following instructions at https://flutter.dev/setup.
    ! Upstream repository git@gitcode.com:openharmony-tpc/flutter_flutter.git is not a standard remote.
      Set environment variable "FLUTTER_GIT_URL" to git@gitcode.com:openharmony-tpc/flutter_flutter.git to dismiss this error.
    • Framework revision daefe215e1 (4 days ago), 2025-08-29 17:32:50 +0800
    • Engine revision 8cd19e509d
    • Dart version 3.8.1
    • DevTools version 2.45.1
    • Pub download mirror https://pub.flutter-io.cn
    • Flutter download mirror https://storage.flutter-io.cn
    • If those were intentional, you can disregard the above warnings; however it is recommended to use "git" directly to perform update checks and upgrades.

[✓] HarmonyOS toolchain - develop for HarmonyOS devices
    • OpenHarmony Sdk at /Applications/DevEco-Studio.app/Contents/sdk, available api versions has [20:default]
    • Ohpm version 5.3.1
    • Node version v18.20.1
    • Hvigorw binary at /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw

[✗] Android toolchain - develop for Android devices [44ms]
    ✗ Unable to locate Android SDK.
      Install Android Studio from: https://developer.android.com/studio/index.html
      On first launch it will assist you in installing the Android SDK components.
      (or visit https://flutter.dev/to/macos-android-setup for detailed instructions).
      If the Android SDK has been installed to a custom location, please use
      `flutter config --android-sdk` to update to that location.

[✗] Xcode - develop for iOS and macOS [59ms]
    ✗ Xcode installation is incomplete; a full installation is necessary for iOS and macOS development.
      Download at: https://developer.apple.com/xcode/
      Or install Xcode via the App Store.
      Once installed, run:
        sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
        sudo xcodebuild -runFirstLaunch
    ✗ CocoaPods not installed.
        CocoaPods is a package manager for iOS or macOS platform code.
        Without CocoaPods, plugins will not work on iOS or macOS.
        For more info, see https://flutter.dev/to/platform-plugins
      For installation instructions, see https://guides.cocoapods.org/using/getting-started.html#installation

[✓] Chrome - develop for the web [21ms]
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[!] Android Studio (not installed) [21ms]
    • Android Studio not found; download from https://developer.android.com/studio/index.html
      (or visit https://flutter.dev/to/macos-android-setup for detailed instructions).

[✓] Connected device (2 available) [1,480ms]
    • macOS (desktop) • macos  • darwin-arm64   • macOS 15.2 24C103 darwin-arm64
    • Chrome (web)    • chrome • web-javascript • Google Chrome 139.0.7258.155

[✓] Network resources [658ms]
    • All expected network resources are available.

! Doctor found issues in 4 categories.

3. 结果分析

✅ 正常工作的组件：

• HarmonyOS toolchain - 鸿蒙开发工具链正常

• Chrome - Web 开发环境正常

• Connected device - 设备连接正常

• Network resources - 网络资源正常

⚠️ 需要关注的警告：

• Flutter channel 警告 - 这是正常的，因为使用的是鸿蒙定制版本

• Git repository 警告 - 已通过环境变量解决

❌ 可选安装的组件：

• Android toolchain - 如果需要 Android 开发

• Xcode - 如果需要 iOS 开发

• Android Studio - 如果需要 Android 开发

4. 常见问题解决

Flutter Git 警告解决

如果看到 Git repository 警告，添加以下环境变量：

export FLUTTER_GIT_URL=git@gitcode.com:openharmony-tpc/flutter_flutter.git

Android 开发环境配置（可选）

如果需要 Android 开发，可以安装 Android Studio：

1. 下载 Android Studio：

   • 访问：https://developer.android.com/studio?hl=zh-cn

   • 下载并安装 Android Studio

2. 配置 Android SDK：

   flutter config --android-sdk /Users/jianguo/Library/Android/sdk
   

3. 接受 Android 许可证：

   flutter doctor --android-licenses
   

iOS 开发环境配置（可选）

如果需要 iOS 开发：

1. 安装 Xcode：

   • 从 App Store 下载安装 Xcode

2. 配置 Xcode：

   sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
   sudo xcodebuild -runFirstLaunch
   

3. 安装 CocoaPods：

   sudo gem install cocoapods
   

总结

通过上面的检测结果可以看到，鸿蒙开发环境配置成功！主要的鸿蒙开发工具链都正常工作。

核心组件状态

• ✅ HarmonyOS toolchain - 鸿蒙开发工具链正常

• ✅ Flutter 3.32.4 - 鸿蒙版 Flutter 正常

• ✅ DevEco Studio - 开发环境正常

• ✅ 网络资源 - 下载镜像配置正常

下一步

1. 创建第一个鸿蒙 Flutter 项目

2. 配置鸿蒙设备或模拟器

3. 开始您的鸿蒙应用开发之旅

注意：Android 和 iOS 开发环境是可选的，如果只需要开发鸿蒙应用，当前配置已经完全满足需求。

到此 Mac 环境配置完成！

三方库适配，就可以继续往前推进了。

 

参考资料

[1] https://developer.huawei.com/consumer/cn/download/: https://developer.huawei.com/consumer/cn/download/