从决定做一个“家庭药箱管理 血压记录”的跨端应用到最终在 OpenHarmony 设备上稳定跑起来整个过程比我想象的要曲折不少。尤其是 Flutter 在 OpenHarmony 生态里还属于“新移民”网上资料鱼龙混杂很多坑只能自己踩。这篇就把我从选型、环境搭建、核心模块实现到真机调试的完整实战记录整理出来重点讲清楚“为什么这么干”和“踩了哪些雷”希望能给准备入坑 Flutter OpenHarmony 的同学省下几天时间。1. 为什么把家庭药箱App选型为Flutter OpenHarmony先说背景。家里老人有高血压常备药七八种过期药混在药箱里是常态血压记录还停留在纸笔时代。市面上要么是单功能提醒App要么是绑定特定硬件的健康应用始终没有一个“药箱管理 血压趋势记录”二合一的方案。既然没有合适的干脆自己造一个。1.1 选型逻辑不选ArkUI选Flutter的理由当时摆在面前的两条路一是直接用 OpenHarmony 官方的 ArkUI ArkTS 开发二是用 Flutter 的 OpenHarmony 分支。ArkUI 的优势是原生、跟系统版本同步但问题也明显ArkTS 生态相对年轻第三方库基本等于零图表、日期选择器、扫描识别这些常用能力都得自己从轮子造起。而且我本身有 Flutter 的项目积累切到 ArkTS 意味着重头学一套 UI 框架。Flutter 这边虽然 OpenHarmony 不是它的官方一级平台但已经有社区维护的分支支持核心渲染引擎打通之后Dart 代码层面的体验和 Android/iOS 基本一致。我做过的登录、表单、图表这些模块可以直接搬过来改。关键取舍点是对比项ArkUI ArkTSFlutter (OpenHarmony分支)生态成熟度低三方库稀缺高pub.dev大量库可用跨平台复用仅OpenHarmony一套代码多端复用性能原生直接调用系统能力自绘引擎性能接近原生学习曲线需重新学ArkTS/声明式UI已有Flutter经验可迁移打包体积较小稍大但可接受对个人开发者来说成本最低的方案就是押注 Flutter 的跨平台能力顺便把这次 OpenHarmony 适配当成对未来国产系统布局的提前演练。1.2 项目功能规划的初始拆分整个App一开始就拆成了三大块药箱管理药品的增删改查、有效期提醒、库存数量、分类标签降压药/降糖药/感冒药等。血压记录手动录入高压/低压/心率自动生成趋势图支持历史查询可按时间段筛选。家庭共享同一个设备多成员档案区分“父亲/母亲/爷爷”等标签数据独立存储。这版先聚焦前两块家庭共享放到后续迭代。血压记录之所以单独拎出来是因为它的数据模型跟药箱里的普通药品完全不同——血压数据天然是时间序列后面要做图表分析和统计不能跟药品库存混在一个表里。2. 环境搭建与工程初始化OpenHarmony跑Flutter的第一道坎2.1 版本匹配关系是最大的坑OpenHarmony 的 Flutter 分支不像 Google 官方那样用flutter doctor一把梭搞定。社区维护的 openharmony/flutter_flutter 分支版本需要和 OpenHarmony SDK 的版本严格匹配。我首轮装环境就栽了装了最新 DevEco Studio 5.0 API 12 的 SDK然后拉了一个比较新的 Flutter 分支结果编译报错各种 undefined symbol折腾一整天才发现是 SDK 和 Flutter 引擎版本不配套。我的建议是按社区 CI 验证过的组合来别追新组件版本DevEco Studio5.0.x对应API 12/13OpenHarmony SDKAPI 12 或 13flutter_flutterOpenHarmony 5.0.x 分支不要直接拉 masterflutter_engine配套的 ohos 引擎包搞不清最新版本匹配的直接去 OpenHarmony 的 flutter 仓库看 README里面维护了一个表格。每次升级前也先查一下自己用的组合有没有人验证过比盲升级稳得多。2.2 一步步搭建 Flutter OpenHarmony 开发环境我的实际操作路径供复现安装 DevEco Studio从官方下载最新稳定版搞定 OpenHarmony SDK命令行工具hvigorw也会自动装好。用 Git 克隆 flutter_flutter 分支git clone https://gitee.com/openharmony-sig/flutter_flutter.git cd flutter_flutter git checkout remotes/origin/OpenHarmony-5.0.x把flutter命令加进 PATH运行./flutter/bin/flutter --version确认版本号是3.x.x-ohos这样的后缀说明分支正确。安装编译 OpenHarmony HAP 需要的工具链./flutter/bin/flutter config --ohos-sdk /path/to/ohos-sdk这里的/path/to/ohos-sdk是 DevEco Studio 自带的 SDK 目录Windows 上一般在C:\Users\xxx\AppData\Local\OpenHarmony\Sdk。创建项目./flutter/bin/flutter create --platforms ohos family_medicine注意指定--platforms ohos否则不会生成ohos目录。编译安装到模拟器./flutter/bin/flutter run -d device-id设备ID通过flutter devices查看OpenHarmony 模拟器或真机都能列出。2.3 “新建项目后跑不起来”的典型症状与对策我自己遇到的“新建项目后跑不起来”主要是因为这三个原因基本都是环境问题Flutter 分支和 SDK 版本不匹配编译报 Gradle 依赖下载失败或 C 符号找不到。解法是换到 CI 验证过的分支。OpenHarmony SDK 的签名配置缺失。DevEco Studio 默认自动签名但命令行启动时容易漏配。需要在ohos工程里配置好自动签名或手动证书。模拟器没有开启 GPU 加速Flutter 的 Skia/Impeller 渲染直接崩。在模拟器设置里开启硬件加速或者换真机调试。环境跑通的那一刻说实话挺激动。但后面真正写业务代码时才发现更大的挑战是数据模型和界面怎么设计。3. 药箱核心模块设计从数据模型到界面编排药箱管理听起来不就是个增删改查吗但真正动手时药品的数据结构、状态管理、UI 交互的细节比预期复杂。比如“过期提醒”不是简单比个日期而是要分“临期30天内”“已过期”“缺货库存为0”三种状态每种状态的展示样式和交互逻辑都不一样。3.1 药品数据模型设计我用 sqflite 作为本地数据库因为药箱数据量不大但字段多适合关系型结构。药品表的核心字段class Medicine { final int id; final String name; // 药品名称 final String category; // 分类降压/降糖/感冒/其他 final String spec; // 规格如 5mg*30片 final int totalCount; // 总数量 final int remaining; // 剩余数量 final DateTime expireDate; // 有效期 final DateTime createdAt; // 入库时间 final String desc; // 备注 }这里有两个容易忽略的设计点分类字段用枚举字符串而不是数字方便前端直接映射标签颜色也方便后续做筛选 SQL 时一眼看懂。totalCount 和 remaining 分开存而不是只存 remaining。这样界面上能显示“已用/总量”的进度条同时也能知道曾买过多少辅助判断囤药是不是太多了。3.2 药品列表与状态管理药箱首页是整个App的门面我直接用 Flutter 的ListView.builder做懒加载列表。每张药品卡片显示名称/分类标签/剩余数量/有效期剩余天数。重点逻辑是过期状态的计算int daysUntilExpiry(DateTime expireDate) { final now DateTime.now(); return expireDate.difference(now).inDays; }根据返回值分为三种 UI 状态负数标红卡片上盖“已过期”印章0到30标橙显示“临期”角标大于30绿色正常显示这个逻辑单独抽成一个纯函数方便单元测试。实际上药箱App最容易出 bug 的就是日期边界比如今天恰好是到期日difference可能是0要归入临期而不是过期。3.3 新增/编辑药品的交互细节新增药品我用了模态表单页showModalBottomSheet而不是跳整页、因为用户不想录一个药还切个页面。表单里有一个容易踩的坑日期选择器。Flutter 自带showDatePicker在中文环境下月份显示是英文的需要本地化配置MaterialApp( localizationsDelegates: [ GlobalMaterialLocalizations.delegate, GlobalWidgetsLocalizations.delegate, ], supportedLocales: [ Locale(zh, CN), ], )不做这步日期选择器看起来就非常“洋气”给家里的老人用体验很差。保存逻辑走的是 Provider sqflite表单提交后先插入数据库再调Provider.ofMedicineStore(context, listen: false).refresh()触发列表刷新。后面会专门讲这个状态管理设计。3.4 下拉刷新与列表联动首页用了RefreshIndicator做下拉刷新。这个在 Android 上很常见但 OpenHarmony 上 Flutter 的分支渲染得也还行没有遇到兼容问题。刷新回调里重新查一次数据库更新状态Futurevoid _onRefresh() async { await _store.refreshFromDb(); }这里说实话本地数据库小下拉刷新更多是个交互习惯让用户觉得“我在主动同步数据”。4. 血压记录模块实现采集、存储与可视化血压记录是药箱App之外独立的一个大模块。之所以说“大”是因为它不只是记录两个数字还要考虑测量时间、服药前后的区别、心率、备注以及最核心的——趋势可视化。血压数据只有画成趋势图才能直观看出用药后有没有改善。4.1 血压记录的数据模型与校验血压记录表结构class BloodPressure { final int id; final int systolic; // 高压收缩压 final int diastolic; // 低压舒张压 final int heartRate; // 心率 final int memberId; // 家庭成员ID final DateTime measuredAt; // 测量时间 }输入校验写了单独的函数因为血压数据有其特殊性String? validateBP(int systolic, int diastolic) { if (systolic 50 || systolic 250) return 高压值超出合理范围; if (diastolic 30 || diastolic 150) return 低压值超出合理范围; if (systolic diastolic) return 高压必须大于低压; return null; }特别提醒高压必须大于低压这条校验很容易漏。我见过有人录入 110/135如果不校验后面图表会画出完全违背生理常识的诡异曲线。表单还放了“测量时间”字段默认是当前时间但患者可能补录昨晚的测量所以必须是可改的。4.2 血压趋势图用fl_chart实现曲线展示图表库我选了fl_chart在 OpenHarmony 的 Flutter 分支上跑通过没有遇到平台通道缺失的问题因为纯 Dart 绘制。趋势图的核心需求是展示最近30天的收缩压/舒张压变化并且要画一条参考线——正常范围的上限。高血压诊断标准是140/90所以我在图里加了两条横虚线收缩压参考线140mmHg舒张压参考线90mmHg这样老人一看就明白今天量的是不是超标了。fl_chart 的 LineChart 实现要点LineChart( LineChartData( minY: 50, maxY: 200, lineBarsData: [ LineChartBarData( spots: systolicSpots, color: Colors.red, barWidth: 2, isCurved: true, ), LineChartBarData( spots: diastolicSpots, color: Colors.blue, barWidth: 2, isCurved: true, ), ], extraLinesData: ExtraLinesData( horizontalLines: [ HorizontalLine(y: 140, color: Colors.red.withOpacity(0.4), dashArray: [4, 4]), HorizontalLine(y: 90, color: Colors.blue.withOpacity(0.4), dashArray: [4, 4]), ], ), ), )这版先用的是折线图而不是柱状图因为血压是连续监测数据趋势比单点数值更重要。4.3 记录列表与筛选趋势图下方是记录列表按时间倒序展示。我加了一个时间段筛选的 SegmentedButton支持“近7天 / 近30天 / 全部”。筛选逻辑在数据层用 SQL 查询解决避免在内存里过滤大数据集FutureListBloodPressure queryByDateRange(int memberId, DateTime start, DateTime end) async { final db await _db; return db.query( blood_pressure, where: member_id ? AND measured_at BETWEEN ? AND ?, whereArgs: [memberId, start.millisecondsSinceEpoch, end.millisecondsSinceEpoch], orderBy: measured_at DESC, ); }数据库查询返回后图表和列表共用同一份数据所以切换筛选条件时两边的视觉组件会同步更新。4.4 血压统计卡片记录多了之后光看图形不够直观。我加了三张统计卡片近7天平均高压/低压最高血压值与发生时间记录次数平均值的计算逻辑里有一个坑要不要排除异常值最初我直接把所有记录平均结果发现偶尔一次数值异常比如电子血压计没绑好测出一个 200会严重拉高均值。后来加了一个中位数过滤先排序去掉最高/最低5%的记录再做平均。虽然不如专业医学统计严谨但对家庭用户足够直观也不至于被异常值误导。5. 状态管理与组件通信Provider在药箱场景里的正确打开方式Flutter 里的状态管理方案非常多从 setState 到 Bloc、Riverpod、Provider新入门的同学往往被这个选择题卡住。这次项目里我用的是Provider原因是它上手简单、官方推荐而且足够支撑中小型应用。5.1 为什么是Provider而不是Bloc/Riverpod说实话药箱App这种规模用不用 Bloc 都行。但我的选择逻辑是方案学习成本代码量可维护性适用场景setState低少差跨组件传参混乱小组件内部状态Provider中低中好依赖注入清晰中小型AppRiverpod中中很好编译期安全中型以上Bloc高多很好但样板代码多大型复杂业务药箱App的最核心交互是“列表页-详情页-编辑页”之间的数据同步以及血压趋势图与记录列表之间的联动用 Provider 的ChangeNotifier模式刚好能优雅解决不需要引入更复杂的框架。5.2 MedicineStore的设计ChangeNotifier 依赖注入我写了两个核心 StoreMedicineStore和BloodPressureStore都继承ChangeNotifier。class MedicineStore extends ChangeNotifier { ListMedicine _medicines []; ListMedicine get medicines _medicines; Futurevoid loadAll() async { _medicines await MedicineDao.getAll(); notifyListeners(); } Futurevoid addMedicine(Medicine m) async { await MedicineDao.insert(m); await loadAll(); } }UI侧用Consumer监听变化局部刷新而不是整体 rebuildConsumerMedicineStore( builder: (context, store, child) { return ListView.builder( itemCount: store.medicines.length, itemBuilder: (context, index) MedicineCard(store.medicines[index]), ); }, )5.3 组件通信的几个实际场景场景一编辑页保存后列表页刷新编辑页在Navigator.pop之前先拿到根部的MedicineStore调用更新方法// 编辑页内部 final store context.readMedicineStore(); await store.updateMedicine(updated); Navigator.of(context).pop();这里用context.read而不是context.watch因为不需要重建编辑页只是拿到 Store 的引用执行方法。场景二血压记录列表和趋势图联动两个组件都是同一个BloodPressureStore的Consumer筛选条件变化时notifyListeners()两者同时重建。这个联动如果用 setState 去做会非常痛苦因为父子组件层级较深传参要层层递进。Provider 的“状态提升 跨层共享”优势在这里体现得淋漓尽致。场景三底部导航栏与模块隔离我用一个IndexedStack包裹三个页面药箱、血压、我的。三个页面不共享状态但共享同一个MultiProvider容器MultiProvider( providers: [ ChangeNotifierProvider(create: (_) MedicineStore()), ChangeNotifierProvider(create: (_) BloodPressureStore()), ], child: IndexedStack(...), )5.4 使用 Provider 时容易踩的坑忘加ChangeNotifierProvider就使用context.watch运行时直接崩报ProviderNotFoundException。排查思路是沿着报错栈看是哪个context对应的路由没有包 provider。在dispose中调用notifyListeners会报A Consumer was used after being disposed。防止办法是异步操作里先检查mounted再通知。ChangeNotifier的notifyListeners是全量通知如果一个页面上有几个不相关的组件都在监听同一个 Store它们都会被重建。性能敏感场景可以考虑用Selector精确选择。6. 真机调试踩坑实录从崩溃日志到Gradle配置问题Flutter 项目跑 Android 时顺手无比一切换到 OpenHarmony 就是各种平台的“惊喜”。这一节我把真实遇到的几个问题完整记录下来每个问题都给出排查链路而不是直接丢结论。6.1 “E/flutter: Unhandled Exception: PlatformException”问题排查第一次在 OpenHarmony 真机上点击某个按钮日志直接喷出来E/flutter (31173): [error:flutter/runtime/dart_vm_initializer.cc(41)] Unhandled Exception: PlatformException(error, ..., channel: sqflite)这就是典型的平台通道Platform Channel未实现的问题。Flutter 通过一套统一的通道跟原生侧通信但 OpenHarmony 的融合层只实现了部分系统能力。排查链路是这样的报错里明确写了channel: sqflite说明是数据库插件没被当前平台识别。打开pubspec.yaml确认用的是支持 OpenHarmony 的 fork 版 sqflitesqflite_ohos而不是官方版sqflite。dependencies: sqflite_ohos: ^1.0.0在 Dart 代码里导入路径也要跟着换import package:sqflite_ohos/sqflite.dart;重编译跑通。后来我查了 flutter 官方仓库的 ohos 支持列表发现很多常用插件shared_preferences、path_provider、sqflite都已经有 ohos 分支版本但版本号各不相同必须手动逐个替换依赖。这一个坑就花了半天。6.2 Gradle 插件警告Flutter Main Gradle Plugin Imperatively构建过程中还碰到一个非常醒目的警告You are applying Flutters main Gradle plugin imperatively using the apply script method...意思是项目里的android/app/build.gradle还在用老式的apply方式引入 Flutter 的 Gradle 插件而新版 Gradle 期待的是声明式插件声明。对纯 OpenHarmony 工程来说这个警告不影响编译但如果是 android ohos 的双工程共存项目容易导致 Gradle 同步失败。我的处理方式在项目根目录build.gradle里改用插件声明plugins { id com.android.application version 8.0.0 apply false id dev.flutter.flutter-gradle-plugin version x.x.x apply false }android/app/build.gradle里去掉顶部的apply语句。这个警告对 OpenHarmony 的ohos工程没有直接影响但强迫症看着难受顺手改掉也避免后面切换目标平台时挖坑。6.3 真机安装与HAP签名配置如果只在模拟器跑DevEco Studio 的自动签名基本够用。但是到了真机OpenHarmony 对应用签名要求更严格必须走传统的 HAP 签名流程。我的实际步骤在 DevEco Studio 里生成密钥和证书请求把.cer、.p7b配到ohos工程。命令行构建 HAPhvigorw assembleHap安装到真机hdc install entry/build/default/outputs/default/entry-default-signed.haphdc是 OpenHarmony 的设备连接工具类似 Android 的adb。这一步常见错误是证书链不完整报签名校验失败。解决办法是回到 DevEco 重新生成一份包含完整证书链的项目级签名配置。6.4 性能问题首帧渲染慢与列表卡顿真机上能跑起来后还会遇到性能问题。OpenHarmony 当前的 Flutter 分支在低端设备上比如某些 RK3568 开发板首帧渲染会比 Android 慢 1 秒左右列表快速滑动时偶发掉帧。我做的优化项图片资源压缩药品图标统一用 webp 格式平均体积减少70%。列表项 const 构造尽量让卡片 widget 成为 const减少 rebuild 时重建实例。使用RepaintBoundary隔离频繁重绘的血压图表区域。打开 Impeller 渲染如果当前分支支持OpenHarmony 的 Flutter 分支从 3.7 开始支持 Skia 和 Impeller 切换。在flutter run时加参数flutter run --enable-impeller实测某些平台上 Impeller 能明显改善渲染一致性但部分 GPU 驱动不兼容会闪屏需要灵活切换。7. 可复用的性能优化与后续扩展思路到这一步药箱管理 血压记录已经能在一个 OpenHarmony 真机上完整跑通了。但作为一个长期维护的项目我还在持续做优化和功能扩展。7.1 数据层索引与数据库迁移sqflite 数据库虽然轻量但随着血压记录增多几十年每天 2 条大概 2 万条查询会变慢。我加了measured_at字段的索引CREATE INDEX idx_bp_measured_at ON blood_pressure(measured_at);同时用 sqflite 的onUpgrade回调做数据库版本迁移return openDatabase( path, version: 2, onCreate: (db, version) { ... }, onUpgrade: (db, oldVersion, newVersion) async { if (oldVersion 2) { await db.execute(CREATE INDEX ...); } }, );如果不提前设计好版本号后面加字段时会导致老用户升级直接崩。7.2 与OpenHarmony系统能力结合camera与通知从“家庭药箱”这个场景往深想光靠手动录入是不够的。我下一阶段计划接入 OpenHarmony 的 Camera 能力做“药盒扫一扫”拍照识别药品名称和有效期。现有 Flutter 生态里的camera插件在 ohos 上支持度还不完整所以我评估了两个路径路径一通过 OpenHarmony 的 Camera Kit 写好原生插件暴露通道给 Flutter 调用。路径二先从二维码切入如果药盒上有电子监管码直接用 ZXing 扫码解析通用性更好实现的复杂度也更低。另外还有服药提醒功能。Flutter 的本地通知插件在 OpenHarmony 上还不完善需要借助系统的后台任务 API比如 TerminableKit来实现。这块涉及系统级 API开发量不小放到二期。7.3 Flutter在OpenHarmony上的一些长期观察跟 OpenHarmony 生态打了这段时间交道有几个体会社区的发展比想象中快但文档跟不上代码。很多 API 用法要直接去读开源仓里的 issue 和 PR 才知道正确姿势。用 Flutter 做 OpenHarmony 应用最大的收益是“一份Dart代码全端跑”但最大的代价是——你始终要操心 Flutter 分支的维护状态万一某段平台能力官方没有对齐只能自己 fork 修补。如果目标是纯粹只做 OpenHarmony 应用长期还是建议转向 ArkUI但如果你像我一样有跨端需求Flutter 分支是一条低成本的路。7.4 我给同路人留下的三条经验最后总结三条我这次实战里最想分享给后来者的经验版本匹配是第一优先级。环境和分支不匹配造成的报错排查时间远比写业务代码长。开工前花半小时确认版本组合收益极大。多关注社区维护的插件 fork 列表。很多你以为没有的库其实早就有人改了 OpenHarmony 适配版比如sqflite_ohos、shared_preferences_ohos。换依赖就能解决的问题别自己造轮子。真机调试尽早做。模拟器上跑得再顺真机上摄像头权限、GPU 渲染、HAP 签名这些坑早晚要面对。项目第一天就在真机上跑通 hello world后面每一步都会更踏实。这次从环境搭建到血压图表画出来的过程是我最近最投入的一段开发经历。药箱App的第一版虽然朴素但已经能真正解决家里的问题——老人开始主动追着问“今天的血压数据你帮我看了吗”。把技术转换成身边实实在在的方便这种成就感大概是做独立开发最原始的动力了。下一步我会继续把 Camera 扫码、服药提醒、多成员档案做完到时候再回来填坑更新。