野蛮人柯南做剧本杀组队App这个项目，我给自己选了一条不那么主流的路：用Flutter去开发OpenHarmony应用。说白了就是想验证一件事——这套已经被Android和iOS验证过的跨端框架，真正搬到OpenHarmony生态里能不能干重活、能不能上真机、能不能把剧本库这种典型列表页跑得流畅。整个项目里最有代表性的一块就是剧本库列表：接口请求、分页加载、筛选项、图片缓存、空状态和重试逻辑全都有，麻雀虽小五脏俱全。这篇文章把这一块的完整实现过程摊开讲，环境怎么搭、代码怎么组织、哪些坑必须绕，给正在评估Flutter for OpenHarmony的团队，也给自己研究跨端应用的个人开发者做个参考。
先说结论：OpenHarmony上的Flutter没有网上传闻那么“玩具”，但也绝对算不上“无缝”。只要把SDK版本、插件兼容性和真机调试这三关过了，写一个剧本库列表这种业务页面完全可行。
1. 项目背景与整体设计思路
1.1 为什么选择Flutter来开发OpenHarmony应用
剧本杀组队App的业务核心是让玩家找到剧本、找到搭子、约好车。这类产品多数团队会优先做小程序和Android，其次才是iOS，突然多出一个OpenHarmony渠道，如果用ArkTS单独维护一套代码，人力成本直接翻倍。我们团队当时已经积累了不少Flutter业务代码和组件，决定评估Flutter for OpenHarmony，本质上是想复用这套资产。
另一个考虑是生态。Flutter的生态是跨端框架里最成熟的，Dart语言、包管理、状态管理社区都有大量实践。OpenHarmony这一侧还处于早期，很多系统能力要看厂商适配，但至少路由、网络、基础UI组件这些通过Flutter引擎和社区插件已经能覆盖。相比之下，Compose Multiplatform对OpenHarmony的支持距离可用还很远，React Native在OpenHarmony上也没有一个统一可用的官方形态，所以Flutter算是矮子里面拔将军，也是当前最现实的选择。
不过要提醒一句：OpenHarmony是一个开源操作系统发行版，和手机厂商的商用OS并不完全一样。你在开发时面对的是OpenHarmony的API和SDK，Flutter引擎跑在它提供的ACE框架之上，很多能力最后还是要通过PlatformChannel去调用原生侧。这个前提会影响后面所有技术选型。
1.2 剧本库在组队App里的定位与功能边界
剧本库是整个App的流量入口，用户在首页看到一堆店和车，真正下单前一定会先点开剧本库去确认“这个本子我喜不喜欢、难度合不合适”。所以这个页面不能只是一个简单的列表，它必须承担筛选、检索、详情引导这三件事。
我最初把功能范围划得比较窄：剧本列表按分页加载，顶部支持类型、难度、人数筛选，支持关键词搜索，卡片上展示封面、名称、类型标签、玩家人数、游戏时长、评分和难度。再往后的剧本详情页、收藏、上车操作都不在这一个列表页里做，通过点击卡片跳转即可。
这个边界很重要。OpenHarmony适配期的问题会消耗大量时间，如果一开始就把列表页做成一个“超级页面”，后期排查问题和性能优化都会非常痛苦。现在Spring、扩展性都不差，我宁可先保证核心链路跑通，再加功能。
1.3 状态管理、网络层与缓存选型
状态管理我选了Provider，没有上bloc。原因很简单：剧本库是一个典型的“列表 + 筛选 + 分页”页面，状态无非是列表数据、loading、error、hasMore这几个，用ChangeNotifier就能表达清楚。bloc那套事件流在这里反而增加样板代码，对新人也不友好。如果后续业务复杂度上来了，要同时维护多个页面共享剧本收藏状态，再考虑Riverpod或bloc也不迟。
网络层选Dio，它和OpenHarmony的兼容性很好，因为核心实现是纯Dart，走dart:io的Socket，不依赖平台通道。加上拦截器之后，可以让后端的code、message、data结构自动解包，错误码统一处理。
缓存这块我没有在列表页做完整数据库缓存，只用了一个内存级封面图片缓存。原因有两个：一是剧本数据本身需要实时更新，本地存一份过期数据反而容易让用户产生误解；二是OpenHarmony上第三方缓存插件还没有完全统一适配，依赖太多反而容易踩坑。后面会详细讲图片缓存怎么设计。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与工程搭建
2.1 OpenHarmony SDK与Flutter版本对齐
这一步做不好，后面所有报错都会变得莫名其妙。OpenHarmony的Flutter适配仓库通常叫flutter_flutter和flutter_engine，从OpenHarmony SIG维护的分支拉取，不要直接拉Flutter官方stable分支。官方分支里没有ohos平台的工具链，跑了半天发现flutter create根本不认识ohos这个platform。
我当时的做法是先把OpenHarmony SDK装好。用DevEco Studio安装游刃有余，就是注意SDK目录要自己看得懂，后面flutter config要指给它。OpenHarmony SDK目录里会有native、js、ets几个子目录，实际写原生侧时用得上。
Flutter版本和OpenHarmony版本得对齐。社区仓库里通常会有类似3.x-ohos的分支或标签，不同分支对应的OpenHarmony API等级不一样，如果设备是OpenHarmony 4.0时代的，最好找对应时期的Flutter分支，不要拿着最新Flutter去适配老设备。版本对不上最典型的症状是构建时候报“minOSVersion mismatch”或者设备上首帧白屏。
环境变量示例：
bash复制export OHOS_SDK_HOME=/home/you/ohos-sdk
export PATH=$PATH:/home/you/flutter_flutter/bin
flutter config --ohos-sdk=$OHOS_SDK_HOME
flutter doctor -v
flutter doctor里如果能看到ohos相关条目，至少说明工具链的一部分已经通了。
2.2 创建Flutter工程并接入ohos平台
老一套的