水千户1. 从零搭建：Flutter for OpenHarmony 文件存储与数据库的整体思路
1.1 为什么存储和数据库在 OpenHarmony 上不能照抄 Android 经验
先说结论：Flutter for OpenHarmony 这套东西，UI 渲染层跟 Android 上差别不大，真正让人头皮发麻的恰恰是文件存储和数据库这些“跑在系统底层”的能力。我自己是从 Android 应用开发转过来搞鸿蒙适配的，一开始的想法特别天真——不就是 path_provider 拿个目录，然后 sqflite 开个库吗？结果第一周就被现实教育了。
问题出在几个地方。第一，官方 Flutter SDK 根本不认识 ohos 这个平台，你必须用 OpenHarmony SIG 维护的 Flutter fork 版本，否则连工程都创建不出来。第二，pub.dev 上那些主流插件大多是按 Android/iOS 原生接口写的，直接塞进 OpenHarmony 工程里，虽然能编译过去，但运行时要么路径拿不到，要么直接报 MissingPluginException。第三，OpenHarmony 的应用沙箱目录模型跟 Android 的 /sdcard 逻辑完全不一样，你不摸清 el1/el2 那套区分，文件一旦写到系统认为“可清理”的区域，用户重启个设备或者清个缓存，数据就没了。
所以这篇指南不是教你怎么写 Flutter，而是讲清楚在 OpenHarmony 上做本地存储时要避开的那些雷：环境怎么搭、沙箱目录怎么选、数据库到底用 sqflite 还是鸿蒙原生 relationalStore、以及为什么你折腾了半天 RK3568 设备树，应用依然在真机上跑不起来。适合谁看？准备把 Flutter 应用迁移到 OpenHarmony 真机或模拟器的开发者、负责应用适配的客户端工程师，还有那些刚拿到一块开发板、正被“选哪个 dtb”折磨得睡不着的人。
1.2 方案选型：文件存储、内嵌数据库和原生能力怎么配合
我一直主张一个原则：先想清楚数据要活多久、要不要跨设备、能不能丢，再选存储方案。别看数据库功能强大，就什么都往里塞。下面这个表是我在实际项目里反复对比后沉淀下来的选型逻辑，你可以直接抄。
| 数据类型 | 推荐方案 | 理由 |
|---|---|---|
| 日志、导出文件、图片缓存 | dart:io + path_provider_ohos |
简单直接，不引入额外依赖 |
| 设置项、用户偏好 | shared_preferences_ohos / Hive |
Key-Value 读写快，天然适配配置类数据 |
| 结构化业务数据、需要 SQL 查询 | sqflite_common_ffi 或社区 sqflite_ohos |
CRUD 成本低，迁移路径成熟 |
| 需要系统备份、多端协同的数据 | 平台通道调鸿蒙 relationalStore |
原生能力，和系统深度绑定 |
| 图片、音视频等大对象 | 文件系统存实体，数据库只存路径元数据 | 避免数据库体积暴涨、性能劣化 |
这个表背后有一个很痛的教训。我第一个版本图省事，把用户上传的图片直接 Base64 塞进 SQLite 的 BLOB 字段，结果表只有几千行，数据库文件已经涨到 300 多 MB，查询越来越慢，最后只能写迁移脚本把所有大对象导出来换成文件路径。所以你在设计表结构的时候，一定要把“大字段只存路径”当成铁律，不要心存侥幸。
另外，很多从 Android 迁移过来的朋友会下意识地写 getExternalStorageDirectory()，觉得这就是外置 SD 卡路径。在 OpenHarmony 上这么写，得到的很可能是 null 或者一个跟媒体库绑定、行为跟预期完全不同的路径，这也是后面常见问题里我会重点展开的地方。先把这些概念理清，后面实操才不会翻车。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：把 Flutter 跑在 OpenHarmony 真机上的第一步
2.1 获取带 ohos 平台的 Flutter SDK
不要用 flutter.dev 下载的官方 SDK 去做 OpenHarmony 工程，它没有 ohos 这个 platform，执行 flutter build ohos 会直接告诉你平台不支持。正确做法是拉取 OpenHarmony SIG 维护的 flutter_flutter 仓库，这个仓库就是专门适配 OpenHarmony 的 Flutter SDK 分支。
bash复制# 拉取带 ohos 支持的 Flutter SDK，具体分支/tag 以仓库 Releases 页面为准
git clone https://gitee.com/openharmony-sig/flutter_flutter.git -b <选择与你 OpenHarmony 版本匹配的 tag>
# 把 SDK 的可执行文件加入环境变量
export PATH="$PWD/flutter_flutter/bin:$PATH"
# 确认版本，顺便检查有没有遗漏的依赖
flutter --version
flutter doctor -v
这里有一个关键点：fork 版本的版本号要跟你的 OpenHarmony 系统版本匹配。比如你的开发板烧的是 API 10 的系统，却拉了一个只支持 API 12 的 Flutter fork，构建阶段大概率会报 SDK 版本不匹配。我建议先确定设备烧录的 OpenHarmony 版本，再去仓库 Releases 页挑对应 tag，不要在版本上凑合。真正的主题是存储和数据库，但环境这一步过不去，后面全是白搭。
还需要装 DevEco Studio 或者至少是配套的命令行工具链，因为最终打包、签名、安装到真机，走的是鸿蒙的 hvigor 那套构建体系，不是 Gradle。首次构建时，Flutter 会自动调用 hvigor 编译 ohos 目录下的工程，所以 DevEco 的命令行工具能正常执行是硬前提。
2.2 PATH 环境变量与“新终端才能生效”的坑
这个坑看起来小，但能把新手卡半小时。很多人照着文档 export PATH=... 了，然后在同一个终端窗口里执行 flutter，提示还是 command not found，就开始怀疑 SDK 没下全，其实只是 shell 没有重新加载环境变量。
解决方式很简单：要么重新开一个终端窗口，要么手动执行 source ~/.zshrc（如果写在别的配置文件里就对应用 source 那个文件）。Windows 用户更常见的是在 PowerShell 里用 setx 写了环境变量，当前窗口不会立刻生效，必须新开窗口。
bash复制# Linux / macOS
export PATH="$PWD/flutter_flutter/bin:$PATH"
source ~/.zshrc
which flutter # 确认能找到
# Windows PowerShell 里先确认
Get-Command flutter
这个事儿看着不起眼，但我见过不少群里求助的人，最后发现就是没开新终端。顺带提一句，如果 flutter doctor -v 检查出 CMake 或者 Visual Studio 组件缺失，在下一个小节里也会遇到，因为只要你的项目里有一个带原生代码的插件，构建时就会调 CMake。
2.3 初始化工程与验证基本通路
环境变量没问题之后，创建一个带 ohos 平台的工程，流程跟创建 Android 工程几乎一样，只是多了一步 `flutter