做这个项目的起因其实很朴素:去年旅游的时候,每到一个城市都想找当地的一级博物馆,网上的信息东一块西一块,门票政策、开放时间、镇馆之宝这些关键信息散落在不同的App里,越查越乱。后来我把全国备案博物馆的公开名录整理了一遍,发现数量接近7000家,数据量完全够一个独立App玩起来。跨平台展示这类"信息查询+列表筛选"需求,Flutter本身就是最顺手的工具,但真正麻烦的地方在于鸿蒙——它已经是一个独立生态,不是改改AGP配置就能跑的。这篇文章就是我用Flutter把"全国博物馆查询"从零做到鸿蒙设备上并可上架的完整记录,包括数据怎么建模、查询怎么做、hap包怎么打出来,以及文档里基本不会写的坑。
1. 项目立项时的三个关键判断
1.1 为什么是Flutter而不是原生鸿蒙
鸿蒙原生开发本身并不难,ArkTS加上声明式UI写起来和SwiftUI很像,如果一个应用只在鸿蒙手机、平板、折叠屏上运行,那用原生开发完全没问题。但"全国博物馆查询"从一开始就需要覆盖 Android、iOS、鸿蒙三大平台,甚至后续可能要跑在Windows和macOS的桌面端做数据维护界390面。
Flutter在这类场景下的优势非常直接:一份Dart代码同时编译出各平台的产物,UI层面用Skia/Impeller自绘引擎渲染,不依赖系统组件,因此三端视觉差异可以压到非常小。实际开发中我发现,列表、详情页、搜索交互、设置页这几块写完,Android和iOS端几乎零改动,鸿蒙端也只是做了引擎和插件的适配,业务代码大部分复用。
另一个关键判断是团队成本。如果一个四人小组各维护一套原生代码,数据模型和接口逻辑要去三个仓库同步,这个成本对小工具型App来说是致命的。Flutter把状态管理、网络层、数据缓存、页面路由都收敛在一个工程里,后期维护只需要改一份代码。
1.2 数据是"重"资产,必须一开始就设计好
博物馆查询类App的核心资产不是代码,而是数据。国内博物馆数量多、分布广,不同省份的博物馆命名方式、行政归属、开放情况差异很大。比如"故宫博物院"是部级直属,"某省博物馆"是省文旅厅下属,到县级还有各种专题馆和纪念馆,数据源格式五花八门。
我在立项时定了一条原则:数据层必须和UI层完全解耦。UI永远不直接操作数据源,所有查询都经过仓库层(Repository)转发。这样将来数据源从本地JSON换成云端API,或者从SQLite换成Drift,UI代码都不需要大改。
数据字段设计上,除了常规的馆名、省份、城市、地址、简介之外,我还加了几个容易被忽略的字段:provinceCode用于省市级联筛选,level表示博物馆等级,lat和lng用于地图跳转,ticketPolicy用于存门票政策文本。这些字段在后续开发中帮了大忙。
1.3 App形态:查询工具,不是内容平台
市面上已经有一些文博类App,但很多做成了社区或内容平台,强调UGC、购买门票、预约活动,反而让"查个博物馆信息"这个高频需求被埋没。这个项目的定位非常克制:纯查询工具。打开App第一眼就是全国六大地区分区的博物馆列表,点进详情页能看基本信息,收藏喜欢的馆,其他功能一概不做。
克制的好处是,开发周期可控,审核风险小,产品边界清晰。我把所有额外功能放到后期扩展计划里,先保证核心链路跑通,这也符合小团队做应用的现实路径。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 鸿蒙化Flutter开发环境搭建:比官方文档多走的三步
2.1 基础工具链与国内镜像配置
Flutter本身的环境配置网上教程很多,但做鸿蒙化开发时,有几个环节是和普通Flutter工程不一样的。先列一下我最终使用的工具链:
| 工具 | 版本 | 说明 |
|---|---|---|
| Flutter SDK | 3.22.x(鸿蒙化分支) | 不能直接用官方主线的Flutter SDK |
| OpenHarmony SDK | 5.x | 从DevEco Studio里安装 |
| DevEco Studio | 5.x | 鸿蒙IDE,用于编译hap、签名、跑模拟器 |
| Java | 17 | 鸿蒙工具链依赖 |
| 代码编辑器 | VS Code + Flutter插件 | 写Dart业务代码 |
普通Flutter环境只需要配置PUB_HOSTED_URL和FLUTTER_STORAGE_BASE_URL两个镜像变量,鸿蒙化之后还需要确保SDK路径正确,并且不能用最新版本强行编译,版本要锁定在鸿蒙适配过的分支上。我最初用Flutter 3.22官方版试过一次,跑鸿蒙构建时直接提示找不到鸿蒙工具链,这个问题换到OpenHarmony SIG维护的flutter_flutter仓库后解决。
2.2 鸿蒙Flutter SDK接入与版本锁定
这里有一个很容易踩的坑:Flutter官方SDK不直接支持鸿蒙打包,需要使用OpenHarmony SIG维护的flutter_flutter仓库。我实际操作时是手动克隆flutter_flutter仓库到本地,然后把它作为Flutter SDK使用,而不是通过官方渠道下载。
环境变量方面,我配置了以下内容:
bash复制export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-
