IT巫师1. 项目背景与整体设计思路
先说结论：用 Flutter 写 OpenHarmony 应用完全可行，而且菜谱管理这个项目非常适合作为第一个练手实战。我之所以选这个题材，是因为菜谱管理几乎覆盖了 App 开发的所有基础能力——列表展示、数据持久化、图片处理、搜索筛选、增删改查，一套下来基本把日常开发的高频操作全过了一遍。
1.1 为什么选 Flutter + OpenHarmony 这个组合
OpenHarmony 的北向应用开发，官方主推的是 ArkTS 和 ArkUI。那为什么我还要用 Flutter 来做？三个原因：第一，Flutter 的跨端能力是现成的，一套 Dart 代码后面可以直接跑 Android 和 iOS，对个人开发者来说性价比很高；第二，Flutter 在 OpenHarmony 上的适配已经有官方 SDK 支持，社区也活跃，遇到问题能找到人问；第三，如果你的团队里有 Flutter 经验的人，上手 OpenHarmony 开发的曲线会平缓很多，不用重新学一套 UI 框架。
当然也要说实话，现在的 Flutter for OpenHarmony 还不算 100% 成熟，一些平台通道的插件需要自己适配。但菜谱管理这种偏工具类的 App，主要涉及 UI、数据库、图片和文件操作，这些都是基础能力，适配难度不大。
注意：当前 Flutter SDK for OpenHarmony 的版本迭代比较快，建议直接去 Gitee 上的 flutter_flutter 仓库拉取最新的 dev 分支，配合 DevEco Studio 一起用。
1.2 菜谱管理 App 的功能范围设计
我给我自己定的需求是这样：能添加菜谱，包含菜名、分类（热菜、凉菜、主食、汤羹）、食材清单、步骤描述、成品图；能浏览全部菜谱，按分类或者关键词筛选；能编辑和删除。权限方面做了简化，单机本地使用，不需要登录，数据存在本地。
这个规模对第一次接触 OpenHarmony 适配的人来说刚刚好——有足够的功能量去练习各种组件的用法，但又不至于因为功能太多导致排查问题时无从下手。
1.3 技术选型里几个关键决策
我在做技术选型时，最核心的几个点：
- 数据存储：优先考虑 OpenHarmony 自带的 RelationalStore（关系型数据库），它和 Android 里的 SQLite 很像，SQL 语法大部分通用，迁移成本低。最初也考虑过用 shared_preferences 存 JSON，但菜谱涉及步骤数组和图片路径，JSON 序列化和反序列化在数据量上去后会很痛苦。
- 图片处理：菜谱封面图我直接存本地路径，不搞 Base64 入库。图片压缩用 Flutter 的 image 包做，先把尺寸压到合理范围再存文件。
- 状态管理：没有上 Provider 或者 Riverpod，直接用 setState。原因很简单——项目规模小，状态层级浅，引入状态管理框架反而增加理解成本。
我用表格汇总一下选型决策，方便后面有需要的人直接参考：
| 模块 | 技术方案 | 选择理由 |
|---|---|---|
| UI 框架 | Flutter Widget | 热重载效率高，组件生态成熟 |
| 数据库 | RelationalStore | OpenHarmony 内置，SQL 兼容度高 |
| 图片处理 | image 包 + 文件路径存储 | 避免数据库膨胀，加载性能好 |
| 状态管理 | setState | 项目规模小，避免过度设计 |
| 构建工具 | DevEco Studio + hvigor | OpenHarmony 官方工具链 |
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境搭建与联调配置的实操细节
说实话，环境搭建是这次实战里踩坑最多的地方，比写业务代码花的时间还多。我觉得有必要把整个过程拆开仔细讲讲，因为很多问题都是环境和配置层面的，网上资料又少，能搜到的也都是零散片段。
2.1 开发环境到底需要装哪些东西
我的开发机是 Windows 11，最终装齐了这么几样东西：DevEco Studio 5.0（这里要注意，后面应用工程会用到）、Flutter SDK 的 OpenHarmony 分支版本、OpenHarmony SDK、Node.js（hvigor 构建依赖它），以及 ohpm 包管理工具。
这里有一个非常关键的坑必须提前交代：普通的稳定版 Flutter SDK 是不支持 OpenHarmony 的。你需要拉取专门适配过的 Flutter SDK，把 flutter 命令装好后，执行 flutter doctor，如果能看到 OpenHarmony 相关的通道，说明 SDK 装对了。
安装配置这块，DevEco Studio 自带了一个 SDK Manager，可以下载 OpenHarmony SDK 和工具链。但 Flutter SDK 需要手动配环境变量，我把几条核心命令贴在下面，方便直接抄作业：
bash复制git clone https://gitee.com/openharmony-sig/flutter_flutter.git
cd flutter_flutter
git checkout dev
export PATH=$PWD/bin:$PATH
flutter config --enable-openharmony
flutter doctor
flutter config --enable-openharmony 这步非常关键，不执行的话 flutter 命令创建的工程里不会有 ohos 平台目录。
2.2 创建工程与 DevEco Studio 的协同
Flutter 工程创建好后，会默认生成 android、ios、web 等平台目录，但不会有 ohos 目录。执行下面的命令补上：
bash复制flutter create --platforms ohos .
这会在工程里生成 ohos 目录。接下来你需要用 DevEco Studio 打开这个 ohos 子目录，而不是整个 Flutter 工程。等 DevEco Studio 完成同步之后，再用命令行或者 DevEco Studio 直接运行到模拟器/真机。
我个人的习惯是：代码热重载和调试用 VS Code 跑 flutter run -d <device>，跑起来之后用 DevEco Studio 来看日志和侧载。两个工具各管一段，效率最高。
2.3 真机运行前必须处理的权限问题
模拟器我用的是 OpenHarmony 的模拟器，但从 5.0 开始，很多 API 行为在模拟器和真机上表现不一样，特别是权限弹窗和数据持久化。所以有条件的话强烈建议直接上真机，比如润和或者 dayu200 这种 RK3568 开发板。
如果你是真机调试，需要在 ohos 工程里的 module.json5 文件中配置权限声明。菜谱管理 App 至少需要这两项：
json复制{
"name": "ohos.permission.READ_IMAGEVIDEO",
"reason": "读取菜谱图片",
"usedScene": {
"abilities": ["MainAbility"],
"when": "inuse"
}
}
这里有个容易漏的地方：OpenHarmony 的权限体系区分 system_grant 和 user_grant 两类。读相册属于 user_grant，需要在代码中动态申请。我第一次跑的时候忘了动态申请，点击选择图片后直接白屏，日志提示权限拒绝。
2.4 编译错误的速查与解决思路
整个搭建过程中，我遇到过几类频率极高的报错，这里先给个速查表：
| 报错关键词 | 原因 | 解决方案 |
|---|---|---|
Unable to locate adb |
DevEco 的 SDK adb 路径未识别 | 在 DevEco 的 SDK 路径下找到 adb，手动加进 PATH |
ohpm install failed |
依赖包未安装 | 在 ohos 目录下执行 ohpm install |
C++ build error in native |
Flutter 引擎 native 编译失败 | 检查 NDK 版本，DevEco 需要特定 NDK 版本 |
sign config missing |
未配置签名 | 在 DevEco 里配置自动签名 |
ERR_INVALID_ARG_TYPE |
Node 版本过低 | 升级 Node.js 到 18 以上 |
这些坑其实都是环境问题，不是你代码写错了。所以建议大家一次把环境按规范装好，避免反复折腾。
2.5 针对 x86 平台的设备树选择
有个细节值得单