01. Flutter鸿蒙开发从0开始：认识项目路线和学习顺序

很多同学第一次接触 Flutter 鸿蒙开发时，会把它理解成“装一个 Flutter，然后写 Dart 页面”。实际项目里还会多出 OpenHarmony SDK、DevEco Studio、ohpm、hvigor、hdc、签名和 ohos 工程目录。先把这条路线看清楚，后面配置环境、创建项目、调试真机、调用原生能力时就不会乱。

开发链路总览

Flutter 鸿蒙项目可以拆成三条线：第一条是 Flutter 线，负责 Dart 页面、组件、资源、网络请求和状态管理；第二条是鸿蒙工程线，负责 ohos 目录、Ability、签名、权限、ArkTS 插件和原生视图；第三条是工具链线，负责 JDK、DevEco Studio、OpenHarmony SDK、ohpm、hvigor、node 和 hdc。

三条线是同时工作的。flutter run 看起来只是一个命令，但它背后会先读取 Flutter 项目，再生成或同步鸿蒙工程，然后调用 hvigor 构建 hap，最后通过设备工具安装运行。因此新手排错时不能只盯 Dart 代码，必须能判断错误属于 Flutter、鸿蒙工程还是工具链。

Flutter 页面代码
   ↓
OpenHarmony Flutter SDK
   ↓
ohos/entry 鸿蒙宿主工程
   ↓
hvigor 构建 hap
   ↓
hdc 安装到真机或模拟器

工作区规划

Windows 环境下要特别重视目录规划。OpenHarmony Flutter 仓库说明中提到，Flutter 工程和依赖的插件工程需要在同一个磁盘。最稳妥的做法是单独准备一个工作区，把 SDK、项目、缓存和本地插件都放进去。

D:\flutter_ohos_workspace
├─ sdk
│  └─ flutter_flutter
├─ pub_cache
├─ projects
│  ├─ hello_ohos
│  └─ native_bridge_demo
└─ plugins
   └─ local_plugins

这种目录结构后面有两个好处：一是环境变量容易写清楚，二是排查插件路径、缓存路径、构建路径时不容易跨盘。尤其是后续写本地 plugin、PlatformView 或 MethodChannel 示例时，同盘会减少很多无意义报错。

先掌握的命令

入门阶段不用先背完整命令，只要把下面几条跑通：

flutter --version
flutter doctor -v
flutter devices
flutter create --platforms ohos hello_ohos
flutter run --debug -d <deviceId>
flutter build hap --release

flutter doctor -v 用来判断环境是否完整，flutter devices 用来判断设备是否被识别，flutter create --platforms ohos 用来判断 SDK 是否支持鸿蒙平台，flutter run 用来判断调试链路是否打通，flutter build hap 用来判断正式构建是否可用。

从零到能开发的学习顺序

比较顺的学习顺序如下：

1. 安装 Git、JDK 17、DevEco Studio
2. 配置 OpenHarmony SDK、ohpm、hvigor、node
3. 下载 flutter_flutter 并加入 PATH
4. 执行 flutter doctor -v 修复环境问题
5. 创建第一个 ohos 项目并运行
6. 学习项目目录、页面、路由、资源和网络
7. 学习 MethodChannel 调用原生能力
8. 学习 PlatformView 嵌入鸿蒙原生组件

前四步是环境基础，第五步是项目落地，第六步开始才是真正写业务页面，第七和第八步对应 Flutter 与鸿蒙原生能力的结合。不要一开始就跳到原生组件嵌入，否则遇到报错时很难判断是环境问题、项目问题还是桥接代码问题。

检查清单

环境初步完成后，可以按下面清单核对：

[ ] 工作区目录固定，路径不含奇怪符号
[ ] Git 可以正常执行
[ ] JDK 17 可以正常执行
[ ] DevEco Studio 已安装对应 SDK
[ ] ohpm、hvigor、node 都能在命令行识别
[ ] flutter_flutter/bin 已加入 PATH
[ ] flutter doctor -v 中 Flutter 和 OpenHarmony 检查通过
[ ] flutter create --platforms ohos 能生成 ohos 目录

路线图落地到项目阶段

从零开始的项目可以按阶段推进：

阶段一：环境可用
  产物：flutter doctor -v 通过

阶段二：项目可运行
  产物：hello_ohos 能在设备上打开

阶段三：页面可开发
  产物：首页、列表页、详情页能切换

阶段四：数据可接入
  产物：HTTP 请求能展示 loading、empty、error、success

阶段五：原生可桥接
  产物：Flutter 能调用 ArkTS 方法或嵌入原生视图

每一层都对应一个明确产物。环境层看 doctor，项目层看 ohos 目录和真机启动，页面层看导航与状态，数据层看请求结果，原生层看通道调用或原生视图是否能稳定工作。

初学者最容易混淆的三件事

第一，flutter_flutter 不是普通 Flutter SDK。它的意义在于扩展 OpenHarmony 平台能力。第二，ohos 目录不是缓存目录，它是项目里的鸿蒙宿主工程，后续会频繁修改。第三，DevEco Studio 不只是编辑器，它还提供 SDK、构建工具、签名和调试能力。

如果把这三点弄反，就会出现很多错误操作，比如删除 ohos 目录后不理解为什么原生插件没了，或者安装普通 Flutter SDK 后找不到 --platforms ohos 的构建能力。
供 SDK、构建工具、签名和调试能力。

如果把这三点弄反，就会出现很多错误操作，比如删除 ohos 目录后不理解为什么原生插件没了，或者安装普通 Flutter SDK 后找不到 --platforms ohos 的构建能力。