参加 GitCode 组织的「开源鸿蒙跨平台开发训练营」第一天，目标是：在Mac系统上搭建Flutter跨平台开发环境。

        本小鱼Android背景，对跨平台以及flutter知之甚少，希望通过本次实践能扩大自己的技术面，同时学会能输出自己在学习过程中的收获与感悟。

参考教程：鸿蒙版 Flutter 环境 3.32 版本搭建指南（Mac 版）

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

下载链接：https://developer.huawei.com/consumer/cn/download/

1、系统架构判断，Mac要根据芯片架构下载对应的安装文件。

• 点击电脑左上角苹果图标 - 关于本机查看
• 命令行查看：终端输入 uname -m，输出arm64或aarch64，则为ARM架构；输出x86_64，则为x86架构

2、安装，如图

二、下载鸿蒙版 Flutter（3.32.4 版本）

1、 克隆项目

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

@@@ ~ % git clone https://gitcode.com/openharmony-tpc/flutter_flutter

Cloning into 'flutter_flutter'...
warning: redirecting to https://gitcode.com/openharmony-tpc/flutter_flutter.git/
remote: Enumerating objects: 1008374, done.
remote: Counting objects: 100% (15291/15291), done.
remote: Compressing objects: 100% (944/944), done.
remote: Total 1008374 (delta 14811), reused 14337 (delta 14337), pack-reused 993083 (from 1)
Receiving objects: 100% (1008374/1008374), 1.80 GiB | 3.37 MiB/s, done.
Resolving deltas: 100% (712278/712278), done.
Updating files: 100% (8649/8649), done.

2、切换到oh-3.32.4-dev 分支

@@@ ~ % cd flutter_flutter 
@@@ flutter_flutter % git checkout -b oh-3.32.4-dev origin/oh-3.32.4-dev
Updating files: 100% (12788/12788), done.
branch 'oh-3.32.4-dev' set up to track 'origin/oh-3.32.4-dev'.
Switched to a new branch 'oh-3.32.4-dev'

3、验证下载：

@@@ flutter_flutter % ./bin/flutter --version
Downloading Darwin x64 Dart SDK from Flutter engine a97ffb0c09df064e189643721b0154df9cefe106...
dart-sdk-url: https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com/flutter_infra_release/flutter/a97ffb0c09df064e189643721b0154df9cefe106/dart-sdk-darwin-x64.zip
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  126M  100  126M    0     0  3321k      0  0:00:38  0:00:38 --:--:-- 2902k
Building flutter tool...
Resolving dependencies... (2.8s)
Downloading packages... (32.8s)
Got dependencies.
Flutter 3.32.4-ohos-0.0.1 • channel [user-branch] •
https://gitcode.com/openharmony-tpc/flutter_flutter
Framework • revision 7dfc371a25 (6 days ago) • 2025-11-14 10:13:54 +0800
Engine • revision 8cd19e509d (5 months ago) • 2025-06-12 16:30:12 -0700
Tools • Dart 3.8.1 • DevTools 2.45.1

三、环境变量配置

1、查看配置文件

我经常记不起来电脑的配置文件是哪个，每次配置环境变量都要查一遍当前shell，最快速的方法终端输入：echo $SHELL

输出结果是/bin/zsh 或 /bin/bash

Shell 是 zsh，那么你的配置文件就是 ~/.zshrc

Shell 是 bash，那么你的配置文件通常是~/.bashrc

2、环境变量配置

打开配置文件：open ~/.zshrc

# DevEco Studio配置
export TOOL_HOME=/Applications/DevEco-Studio.app/Contents
export DEVECO_SDK_HOME=/Users/xxxx/Library/OpenHarmony/Sdk/18/toolchains:$PATH

# 工具路径配置
export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH
export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH

# Flutter路径配置（请根据实际路径修改）
export PATH=/Users/xxxx/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环境

3、刷新环境变量

source ~/.zshrc

四、环境检测

1、运行环境检测

flutter doctor -v

2、检测结果

flutter % flutter doctor -v

[!] Flutter (Channel [user-branch], 3.32.4-ohos-0.0.1, on macOS 15.5 24F74
    darwin-x64, locale zh-Hans-CN) [317ms]
    ! Flutter version 3.32.4-ohos-0.0.1 on channel [user-branch] at
      /Users/weidandan/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 https://gitcode.com/openharmony-tpc/flutter_flutter is
      not the same as FLUTTER_GIT_URL
    • FLUTTER_GIT_URL = git@gitcode.com:openharmony-tpc/flutter_flutter.git
    • Framework revision 7dfc371a25 (6 days ago), 2025-11-14 10:13:54 +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.2
    • Node version v18.20.1
    • Hvigorw binary at
      /Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw

[!] Android toolchain - develop for Android devices (Android SDK version 36.0.0)
    [531ms]
    • Android SDK at /Users/weidandan/Library/Android/sdk
    ✗ cmdline-tools component is missing.
      Try installing or updating Android Studio.
      Alternatively, download the tools from
      https://developer.android.com/studio#command-line-tools-only and make sure
      to set the ANDROID_HOME environment variable.
      See https://developer.android.com/studio/command-line for more details.
    ✗ Android license status unknown.
      Run `flutter doctor --android-licenses` to accept the SDK licenses.
      See https://flutter.dev/to/macos-android-setup for more details.

[✗] Xcode - develop for iOS and macOS [257ms]
    ✗ 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 [116ms]
    • Chrome at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

[✓] Android Studio (version 4.2) [115ms]
    • Android Studio at /Applications/Android Studio.app/Contents
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 11.0.8+10-b944.6916264)

[✓] Android Studio (version 2025.1) [111ms]
    • Android Studio at /Applications/Android Studio 2.app/Contents
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart
    • Java version OpenJDK Runtime Environment (build 21.0.6+-13391695-b895.109)

[✓] IntelliJ IDEA Community Edition (version 2025.2) [110ms]
    • IntelliJ at /Applications/IntelliJ IDEA CE.app
    • Flutter plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/9212-flutter
    • Dart plugin can be installed from:
      🔨 https://plugins.jetbrains.com/plugin/6351-dart

[✓] Connected device (3 available) [654ms]
    • 3RN0224807000110 (mobile) • 3RN0224807000110 • ohos-arm64     • Ohos
      OpenHarmony-5.0.5.165 (API 17)
    • macOS (desktop)           • macos            • darwin-x64     • macOS 15.5
      24F74 darwin-x64
    • Chrome (web)              • chrome           • web-javascript • Google
      Chrome 126.0.6478.62

[✓] Network resources [3.3s]
    • All expected network resources are available.

3、结果分析：

Android/ios环境未安装，flutter 以及 鸿蒙环境配置完成

五、创建DevEco Studio项目

1、新建Empty Ability项目

2、配置项目信息

3、项目目录：

电脑太老啦，不支持模拟器，不过我有真机😄

4、真机运行前，需要签名，登陆华为账号，选择自动签名即可

六、创建Flutter项目

1、创建工程 flutter create --platforms ohos <projectName>

flutter % flutter create --platforms android,ios,ohos first
Creating project first...
Resolving dependencies in `first`... 
Downloading packages... 
Got dependencies in `first`.
Wrote 107 files.

All done!
You can find general documentation for Flutter at: https://docs.flutter.dev/
Detailed API documentation is available at: https://api.flutter.dev/
If you prefer video documentation, consider:
https://www.youtube.com/c/flutterdev

In order to run your application, type:

  $ cd first
  $ flutter run

Your application code is in first/lib/main.dart.

补充一下flutter创建项目命令：

# 创建新项目
flutter create my_app

# 创建指定组织的项目
flutter create --org com.yourcompany my_app

# 创建指定平台的项目（可指定多个平台）
flutter create --platforms android,ios,ohos my_app

# 创建指定包名和多平台的项目
flutter create --org com.yourcompany --platforms android,ios,ohos my_app

2、进入工程根目录编译

第一次编译失败：

first % flutter build app --release
Running Hvigor task assembleApp...                                 39.9s
请通过DevEco Studio打开ohos工程后配置调试签名(File -> Project Structure -> Signing Configs
勾选Automatically generate signature)

使用DevEco  studio 打开 first/ohos，然后自动签名

再次编译：

first % flutter build app --release
Running Hvigor task assembleApp...                                 18.3s
✓ Built build/ohos/app/ohos-default-signed.app (7.8MB).

真机运行：

总结

很不喜欢配置环境，花了几个小时，总归是完成啦，还是很开心的，第一天完美结束 🎉

12月21日补充踩坑经历：

换了台设备，按照之前的步骤配置环境的，却一直提示：

确认多次环境变量是正确配置的

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

实在搞不懂为啥一直报错

直到我看到了如下解决方案

https://developer.huawei.com/consumer/cn/forum/topic/0201145649405032097?fid=0109140870620153026

打开DevStudio安装目录(Mac找打应用程序显示包内容)，按照下图增加两个空目录即可。

抄解决步骤，抄图。。。

每次配置环境每次踩坑，坑坑不一样。。。