搭建鸿蒙 Flutter 开发环境

约 1007 字大约 3 分钟

2025-08-05

准备工作

安装 DevEco Studio NEXT IDE
安装 Git, 如果要同时适配安卓，需要安装 Android Studio；如果要适配 iOS，需要安装 Xcode

环境搭建

环境变量配置：

# Flutter Mirror
export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

# HarmonyOS SDK
export TOOL_HOME=/Applications/DevEco-Studio.app/Contents/
export DEVECO_SDK_HOME=$TOOL_HOME/sdk # command-line-tools/sdk
export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH # command-line-tools/ohpm/bin
export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH # command-line-tools/hvigor/bin
export PATH=$TOOL_HOME/tools/node/bin:$PATH # command-line-tools/tool/node/bin

安装 Flutter

这边建议新手直接指定 flutter 路径，而不是使用 fvm, 因为 fvm 会校验 flutter 版本，在结合 ai 开发的时候，有些问题。

如果在项目开发中，需要使用多个 Flutter 版本，可以考虑使用 fvm

安装 FVM
使用 fvm 官方 flutter 版本

fvm install stable

安装自定义鸿蒙版本，进入 ~/fvm/version 目录。

git clone -b 3.22.0-ohos https://gitcode.com/openharmony-tpc/flutter_flutter.git

接下来使用 fvm list 命令查看 SDK版本 列表。使用命令 fvm global hongmeng 将 hongmeng 设置成了全局默认版本。


┌──────────┬─────────┬───────────────────┬──────────────┬──────────────┬────────┬───────┐
│ Version  │ Channel │ Flutter Version   │ Dart Version │ Release Date │ Global │ Local │
├──────────┼─────────┼───────────────────┼──────────────┼──────────────┼────────┼───────┤
│ stable   │ stable  │ 3.32.8            │ 3.8.1        │ Jul 25, 2025 │        │ ●     │
├──────────┼─────────┼───────────────────┼──────────────┼──────────────┼────────┼───────┤
│ hongmeng │         │ 3.22.1-0.0.pre.33 │ 3.4.0        │              │ ●      │       │
└──────────┴─────────┴───────────────────┴──────────────┴──────────────┴────────┴───────┘

运行 fvm doctor 命令查看当前环境信息。

这里可能会报错，建议直接按报错信息来就可以。

flutter doctor -v
┌────────────────────────────────────────────────────────┐
│ ⚠ Flutter SDK: (hongmeng) is not valid Flutter version │
└────────────────────────────────────────────────────────┘
✔ Do you want to continue? · yes

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ ⚠ Version mismatch detected: cache version is 3.22.1-ohos-1.0.4, but expected hongmeng. │
└─────────────────────────────────────────────────────────────────────────────────────────┘
This can occur if you manually run "flutter upgrade" on a cached SDK.

✔ How would you like to resolve this? · Move 3.22.1-ohos-1.0.4 to the correct cache directory and reinstall hongmeng
Moving SDK to the correct cache directory...
Removing incorrect SDK version...
┌────────────────────────────────────────────────────────┐
│ ⚠ Flutter SDK: (hongmeng) is not valid Flutter version │
└────────────────────────────────────────────────────────┘
✔ Do you want to continue? · yes

最终，运行 flutter list 命令查看版本信息。

┌───────────────────┬─────────┬───────────────────┬──────────────┬──────────────┬────────┬───────┐
│ Version           │ Channel │ Flutter Version   │ Dart Version │ Release Date │ Global │ Local │
├───────────────────┼─────────┼───────────────────┼──────────────┼──────────────┼────────┼───────┤
│ stable            │ stable  │ 3.32.8            │ 3.8.1        │ Jul 25, 2025 │ ●      │       │
├───────────────────┼─────────┼───────────────────┼──────────────┼──────────────┼────────┼───────┤
│ 3.22.1-ohos-1.0.4 │         │ 3.22.1-ohos-1.0.4 │ 3.4.0        │              │        │ ●     │
└───────────────────┴─────────┴───────────────────┴──────────────┴──────────────┴────────┴───────┘

变为 3.22.1-ohos-1.0.4

项目配置

创建新项目

进入项目根目录，如果项目还未创建，则使用 flutter create 命令创建项目

flutter create my_app

在当前项目目录，设置使用的 Flutter SDK 版本

fvm use 3.22.1-ohos-1.0.4  --force

已有项目

如果项目已经创建，还未添加鸿蒙平台支持，则使用以下命令添加鸿蒙平台支持。

flutter create --platforms ohos .

其中，.代表当前目录。

创建命令执行成功后，项目中会出现 ohos目录，这里面存放的就是鸿蒙平台的相关代码。

签名

1.在运行项目前，先对项目进行签名，否则在运行过程中会出现这样的错误

请通过DevEco Studio打开ohos工程后配置调试签名(File -> Project Structure -> Signing Configs 勾选Automatically generate signature)

2.用 DevEco 打开上面的 ohos 目录，注意不是项目目录，是项目下面的 ohos 鸿蒙目录，然后根据提示依次打开 File -> Project Structure -> Signing Configs, 点击自动签名即可。

3.签名成功后，文件 ohos/build-profile.json5 会自动更新，里面的字段 signingConfigs 出现相应的签名配置信息。

运行

运行 Flutter 项目，在项目根目录使用 fvm flutter run 或者在 IDE 中点击运行按钮.

快速创建空项目

mkdir demo
cd demo
fvm use 3.22.1-ohos-1.0.4
fvm flutter create .
fvm flutter create --platforms ohos . --org run.oldbird
fvm flutter build hap # 这一步很重要，第一次安装，会下载一些工具，必然用dev-studio会报错。

FloatingActionButton 导致无法运行

空项目，需要注意点，不能使用 FloatingActionButton, 奇葩的不行，注意将代码删除。

No Hmos SDK found. Try setting the HOS_SDK_HOME environment variable.

如果遇到 [!] No Hmos SDK found. Try setting the HOS_SDK_HOME environment variable. 这个报错，可以这样配置：

fvm flutter config --ohos-sdk=/Users/$(whoami)/Library/OpenHarmony/Sdk

如果还未解决，建议如下配置:

0.移除之前的设置：fvm flutter config --ohos-sdk=''
1.前往 /Applications/DevEco-Studio.app/Contents/sdk 目录下
2.在该目录下，创建两个空文件夹：hmscore 和 openharmony

最终目录：

./
├── default
│   ├── hms
│   ├── openharmony
│   └── sdk-pkg.json
├── hmscore
└── openharmony

not valid Flutter version

如果比较烦类似提示，not valid Flutter version, 建议不要用 fvm, 而是直接指定 flutter sdk 的路径。

搭建鸿蒙 Flutter 开发环境

公告