从零开始，在鸿蒙设备上成功运行第一个 Flutter 应用
欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net

一、环境配置核心步骤

具体的windows安装流程及环境配置可以按照：https://bxming.blog.csdn.net/article/details/156203074

1.1 安装清单

组件	版本要求	作用
Flutter SDK	3.27.5-ohos	跨平台框架
DevEco Studio	6.0.2(22)	鸿蒙SDK和模拟器
Android Studio（非必要）	2025.2.3.9-windows	安卓SDK和模拟器

关键原则：所有安装路径尽量不要有中文和空格，建议直接放在 C:\flutter，如果非要加空格，建议用下划线代替。（空格多了会看到经典款“锟斤铐烫烫烫”）。

1.2 环境变量配置

# 国内镜像加速（必须配置，否则下载会卡住）
FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
PUB_HOSTED_URL=https://pub.flutter-io.cn

# Path中添加Flutter的bin目录
C:\flutter\bin

事实上国内镜像也卡，慢慢等吧，没报错就是能行。如果20+分钟一点没动可以Ctrl + C 中止进程，再输入flutter doctor -v 继续安装。

1.3 验证环境

flutter doctor -v

目标：

• [✓] HarmonyOS toolchain
• [✓] Android toolchain
• [✓] Android Studio

二、项目创建与运行

2.1 创建项目

flutter create my_app
cd my_app

2.2 配置SDK版本

编辑 ohos/build-profile.json5，确认版本与本地已安装的模拟器版本匹配：

"compatibleSdkVersion": "6.0.2(22)"   // 匹配已安装的模拟器版本

或者在新建模拟器时在DevEco Studio中快捷下载：

2.3 启动模拟器并运行

# 查看已连接设备
flutter devices

# 运行到鸿蒙设备
flutter run

三、踩坑记录与解决方案

问题	原因	解决方案
下载font-subset卡住半小时	访问国外服务器慢	已配置国内镜像，纯网络问题，换个时间段重试
文件被占用无法删除	后台进程未关闭	重启电脑后删除cache文件夹
Android toolchain 感叹号	缺少cmdline-tools或许可证	SDK Manager中安装并运行flutter doctor --android-licenses
模拟器API版本不匹配	版本号格式错误	改成与本地模拟器一致的6.0.2(22)格式
Index.ets编译错误	误修改了自动生成的文件	删除后重新flutter run自动生成
路径中包含空格	Flutter工具链识别异常	重命名为下划线或直接删除空格

四、成功标志

运行日志中出现以下信息即为成功：

Install successfully finished
com.example.my_app successfully launched

鸿蒙模拟器屏幕上显示 Flutter 默认计数器应用。

五、核心经验总结

1. 路径不要有空格 — 最隐蔽的问题源头，建议直接用 C:\flutter
2. 配置环境变量别打错字 —更隐蔽的问题源头，建议直接从教程里复制粘贴
3. 国内镜像解决大部分卡顿 — 如果还卡，是网络问题，换个时间段
4. API版本要与本地模拟器一致 — 改成 6.0.2(22) 这种具体版本号
5. 遇到问题先 flutter clean — 能解决一半的疑难杂症
6. 环境变量改了要重启命令行 — 否则不会生效

---

关键教训：文件名少用中文、少用空格；自动生成的代码尽量别动，如果误改了，直接删掉重新生成即可。