最近我把一个成语闯关应用拿 Flutter 重写了一遍顺手把鸿蒙端的适配也跑通了。这个项目不算复杂但覆盖的点特别全在线题库、关卡状态管理、填空题交互、多端打包再加上跨平台到鸿蒙的适配链路几乎把 Flutter 日常开发里会碰到的“硬骨头”都过了一遍。这篇就围绕这个在线成语闯关应用聊清楚整个开发和适配过程包括为什么这么选型、核心模块怎么拆、鸿蒙端有哪些坑、以及最终怎么落地。适合两类人看一类是想拿 Flutter 做一个完整项目练手的开发者另一类是正准备把现有 Flutter 工程适配到鸿蒙设备、但又不知道从哪下手的同学。1. 项目定位与技术选型分析1.1 为什么选 Flutter 做小体量休闲应用成语闯关这种应用本质上是一个“高频交互 轻数据”的工具类产品。它不像电商或者视频 App 那样需要大量原生能力核心就是展示题目、收集点击、记录进度、拉取题库。这类场景恰恰是 Flutter 最舒服的领域一套 Dart 代码跑多端UI 自绘保证不同设备上的渲染一致性再加上热重载调试交互类页面非常快。选 Flutter 还有一个现实考虑团队当时手上的 Android 和 iOS 两端 UI 经常出现细微差异原生控件在不同系统版本上表现不一致改一处要对两套代码。Flutter 的渲染不走原生控件所有组件都是引擎自己画的这样至少能保证我这边调试出来的效果到用户手机上是同一套。对于成语闯关这种对排版和动画有要求的应用来说这个优势尤其明显——九宫格候选字的对齐、答题成功的弹跳动画、错题时的抖动反馈用 Flutter 的动画系统写起来比原生省一半时间。有人可能会问为什么不直接选 uni-app 或者 React Native这里有个关键差异Flutter 不是靠原生控件桥接而是直接通过 Skia 渲染引擎把界面画出来所以在复杂动画和自定义绘制上Flutter 的掌控力更强。成语题里那种“把汉字拖进空格”的交互如果用 RN 做需要频繁处理原生 View 和 JS 层的通信很容易掉帧Flutter 里因为整个 UI 都是自己控制的事件体系处理手势和动画要顺滑得多。1.2 成语闯关的场景拆解数据、状态与界面技术选型之外我习惯先想清楚“这个应用到底有哪些状态”再动手。成语闯关拆开来看其实是三层东西数据层是最简单的。一条成语记录无非是成语本身、拼音、解释、例句、难度等级、所属分类。整个题库的量级撑死几千条单条数据不超过 1KB算下来全量题库也就几兆。这个量级完全不需要上重型数据库一份 JSON 文件加上内存缓存就够了。状态层稍微复杂一点。用户走到哪一关、这一关完成了几颗星、哪一题答对答错、还有几条提示机会、生命值剩多少——这些都属于“关卡内状态”。另外还有“全局进度”比如总共解锁了多少关、成就勋章拿了几个。这个部分需要一套清晰的状态管理方案否则写到后面会变成到处传参的地狱。界面层是重头戏。答题页需要展示一条成语的部分汉字、候选字区域、错误提示区、进度条、按钮状态。看起来简单但移动端屏幕小横竖屏切换后布局要自适应成语的四个字如果不在同一行候选字和空格位的联动关系容易乱。这些细节在后面的开发部分会展开讲。1.3 鸿蒙端适配在技术栈里的位置讲完 Flutter 本身再来说鸿蒙。可能有人以为 Flutter 官方直接支持鸿蒙实际情况不是这样。Flutter 官方目前没有把鸿蒙列为一等平台鸿蒙端要跑 Flutter 代码依赖的是社区和厂商合作的适配层原理类似在鸿蒙系统上嵌入一套 Flutter 引擎再把 Dart 层的逻辑桥接到鸿蒙的运行时环境。工程上的表现就是你的 Flutter 代码不用动但工程结构要多一个鸿蒙壳工程常见做法是在原项目里增加一个ohos目录里面是鸿蒙应用的标准工程结构包括hvigor构建脚本、entry模块、module.json5配置文件等。构建的时候先用 Flutter 的打包工具把 Dart 代码编译成 so 库和资源文件再通过鸿蒙的构建链把它们一起打成 HAP 包。我第一次接触这个结构的时候也愣了一下因为相比 Flutter 原生那套“一条命令出 Android 包”的体验鸿蒙适配多了一层壳。但换个角度想这层壳其实也是好事它把原生侧需要单独处理的事情权限声明、签名、页面生命周期隔离出去了Flutter 代码层面反而可以保持纯粹不用塞一堆平台判断。2. 开发环境与跨平台工程改造2.1 环境准备清单与版本对齐鸿蒙适配的坑很多不是 Flutter 代码的问题而是环境对齐的问题。先说结论一定要先把 Flutter 版本固定下来再根据 Flutter 版本选适配层的版本乱升版本是灾难的开始。我这边实际使用的环境是这样Flutter SDK3.16 左右的稳定版本Dart 版本随之固定。为什么要锁版本因为 Flutter 内部 ABI 变化很频繁如果适配层是基于某个 Flutter 版本编译的你本地 Flutter 太新打包出的产物可能跟适配层的预期对不上运行直接崩。鸿蒙的 IDE 和 SDK安装对应版本的 IDE 后在 SDK Manager 里把鸿蒙 SDK 的default和latest组件都装上同时确认命令行工具hvigor能全局访问。Node.js 环境鸿蒙构建链有一部分依赖 Node 脚本做资源处理和签名没装的话会在构建中间步骤报错。Java部分场景需要 JDK 处理签名版本建议 11 以上。这些环境变量建议写进一个.env文件里管理尤其当电脑上同时有多个 Flutter 版本时靠 PATH 顺序控制很容易翻车。2.2 普通 Flutter 工程接入鸿蒙壳工程的目录结构如果已经有一个 Flutter 项目想要加入鸿蒙支持建议的结构长这样my_cy_app/ ├── lib/ # Flutter 业务代码 ├── assets/ # 图片、题库 JSON 等资源 ├── ohos/ │ ├── entry/ │ │ └── src/main/ │ │ ├── module.json5 # 鸿蒙模块配置 │ │ └── resources/ # 图标、字符串等资源 │ ├── build-profile.json5 # 鸿蒙构建配置 │ └── hvigorfile.ts # 构建脚本入口 └── pubspec.yaml # Flutter 依赖配置ohos目录就是鸿蒙侧的壳工程。它不是从零手写的一般是用 IDE 新建一个空工程后再把 Flutter 插件的适配包加进去。这个壳工程负责创建原生窗口、加载 Flutter 引擎并把 Flutter 的 so 库和资源合并进最终产物。壳工程里有个细节要注意module.json5里的abilities配置相当于安卓的 Activity 声明。默认生成的配置里只有一个入口页面如果你在 Flutter 侧用到了多路由或者深链跳转需要在鸿蒙侧注册对应的 ability 或者做路由映射否则会出现在 Flutter 内跳转正常、但外部唤起就打不开的情况。2.3 关键配置文件pubspec.yaml 与 module.json5跨平台工程里最容易被忽略但最关键的其实是配置文件。pubspec.yaml这头除了常规依赖还需要确保资源声明完整。成语应用的题库 JSON、字体文件、配音音频都要在assets区块列出来否则打包后资源找不到到时候排查半天发现只是配置漏了。flutter: uses-material-design: true assets: - assets/data/idioms.json - assets/fonts/wenhei.ttf - assets/audio/correct.mp3 - assets/audio/error.mp3module.json5这头权限声明是重点。成语闯关是个在线应用肯定要联网拉题库那网络权限必须在鸿蒙侧开如果你还要做答题错误上报可能涉及网络状态读取权限。一个典型的配置如下{ module: { name: entry, type: entry, abilities: [ { name: MainAbility, srcEntry: ./ets/MainAbility.ts, launchType: singleton } ], requestPermissions: [ { name: ohos.permission.INTERNET } ] } }这里最容易踩的坑是在 Flutter 侧怎么配都拿不到网络权限跑起来就是请求超时。其实问题根本不在 Flutter而在鸿蒙壳工程没声明ohos.permission.INTERNET。先检查原生侧的配置再回去调试 Dart 代码能省大量时间。2.4 四个平台的一次构建与产物差异当 Flutter 工程和鸿蒙壳工程都齐了构建命令大概是这样的Android 是常规操作flutter build apk --releaseWeb 端也简单flutter build web --release鸿蒙端则是进入ohos目录走鸿蒙自己的构建链cd ohos hvigorw assembleHap --mode module -p productdefault这里有个值得说的点Flutter 构建出来的产物到鸿蒙侧其实要经历一次“包装”。Flutter 编译出的libflutter.so、libapp.so会被放进鸿蒙工程的libs/目录最终由鸿蒙打包工具合并进 HAP。所以鸿蒙构建的时间通常比 Android 长不是你的机器差而是它多了一层合并动作。构建产物差异也要注意同一个 Flutter 工程Android 上打出来的是 APK鸿蒙上是 HAP两者签名机制完全不同需要分别配置签名文件。我最初就犯过这个错用 Android 的签名逻辑去理解鸿蒙结果安装时一直提示签名校验失败。3. 在线成语闯关应用核心模块开发3.1 成语题库设计在线拉取、缓存与离线降级成语题库的设计遵循一个原则先保证离线再考虑在线。用户不可能永远有网络如果启动时才发现题库没加载体验会很糟糕。所以我的做法是把一份基础题库内置在应用里启动时再异步请求远程接口看有没有更新。远程接口的数据结构大概长这样{ version: 12, categories: [ { id: basic, name: 基础 }, { id: advanced, name: 进阶 } ], idioms: [ { word: 画蛇添足, pinyin: huà shé tiān zú, meaning: 比喻做了多余的事非但无益反而不合适。, example: 事情已经做完你再加一段反而画蛇添足。, difficulty: 1, category: basic } ] }在线拉取的接口用dio写几行代码的事。关键在缓存策略远程数据拉到后要存到本地方便下次秒开。我用的是shared_preferences配合 JSON 序列化——题库数据不超过几兆完全够用。FutureIdiomQuestionRepository loadRepository() async { final prefs await SharedPreferences.getInstance(); final localData prefs.getString(idiom_repo); if (localData ! null) { return IdiomQuestionRepository(IdiomRepo.fromJson(jsonDecode(localData))); } final response await dio.get(https://api.example.com/idiom/repo); if (response.statusCode 200) { await prefs.setString(idiom_repo, jsonEncode(response.data)); return IdiomQuestionRepository(IdiomRepo.fromJson(response.data)); } // 离线降级用 assets 内置版本 final bundleData await rootBundle.loadString(assets/data/idioms.json); return IdiomQuestionRepository(IdiomRepo.fromJson(jsonDecode(bundleData))); }为什么用shared_preferences而不是文件读写因为存储的是一整份数据读写一次就好了没必要引入 File 的异步细节。如果未来题库量级上到几十兆再换hive不迟。现在这个阶段简单可靠就是最大的优点。3.2 关卡状态机与进度存储闯关应用的核心不是题库而是状态流转。我把一个关卡的生命周期拆成四个状态锁定、可挑战、通关、完美通关。完美通关的区别在于一颗星还是三颗星这会影响后续解锁逻辑。Dart 里的写法用一个枚举加一个状态类enum LevelStatus { locked, playable, completed, perfect } class LevelState { final int levelId; final LevelStatus status; final int stars; final DateTime? lastPlayedAt; }状态转换逻辑集中在LevelManager里不散落在各个页面。比如当用户以全对成绩通关第 3 关时自动把第 4 关的locked改成playable。这么设计的好处是不管用户从哪个入口进来——继续闯关、重玩旧关、看广告解锁——最终都要走同一个状态入口不会出现规则不一致的情况。进度存储用的是shared_preferences形如level_3_status completed和level_3_stars 2。为什么不用数据库因为状态数据量太小几十个 key 而已数据库属于杀鸡用牛刀。但如果以后要加“每日挑战”“赛季排行榜”那再迁移到sqflite也不迟状态管理层已经隔离好了。3.3 填空题交互与反馈动画的实现细节答题页是用户最关心的界面。我的实现分成三个区域题目区展示成语字格及答案状态、候选区待选汉字集合、操作区提示、重开、过关按钮。成语填空的交互有两种常见方案点击选择和拖拽填入。考虑到手机触屏的精度我最终用了点击式——先点候选字再点目标空格填入。这样不会因为手指拖动误触导致选错字做起来也简单得多。核心 Widget 结构如下class AnswerBoard extends StatelessWidget { final ListString? slots; // 当前每个格子的内容null 表示空 final ListString candidates; // 候选字列表 final void Function(int slotIndex, String char) onPlace; // 每个格子是固定的宽度候选字区域用 Wrap 布局 }交互逻辑分三步选中候选字、选中空格、校验。校验不能只看对不对还要考虑“已经填入的字能不能换掉”。例如用户填对了第一字、填错了第二字直接点第二字空格应该把已有字弹回候选区而不是覆盖。校验细节有一个容易忽略的点成语里的多音字和繁体字。题库数据里的word字段如果存的是繁体而候选区用的是简体就会出现字面不同但实际是对的。最稳妥的做法是题库只存简体统一用简体校验并把多音字拼音单独存一个字段方便后续做“读音提示”玩法。动画反馈上我用的是AnimatedOpacity加自定义的shake动画。答对时正确格子弹跳放大答错时整行抖动并标红。动画时长控制在 300ms 以内太慢了打断节奏太快了起不到反馈作用。实测下来 200ms–250ms 是比较舒服的区间。3.4 数据上报与成就体系的轻量方案闯关数据如果不能上报成就体系就做不起来。但小体量项目也不想接一整套数据分析 SDK最省事的方案是搭一个简单的上报接口一次 POSTbody 就是 JSON字段包括关卡 ID、得分、耗时、答错次数。上报时机选在每一关结算页面出现之后异步执行不阻塞 UI。失败就静默重试一次再失败则把事件追加到本地队列等下次 App 启动有网络时补发。成就体系本地化程度很高。我在AchievementManager里维护一套规则列表比如“通关任意分类的所有关卡”“连续答对 20 题”“总用时少于 60 分钟通关 10 关”。每条规则是一个纯函数输入状态输出是否达成。本地校验、本地弹通知、本地展示不用依赖服务端。这里需要注意并发问题上报和成就判断都是围绕同一份关卡状态数据展开的如果一边改状态一边读成就容易读到中间值。我的做法是在结算页面把状态更新和成就检查放在同一个事务函数里更新完成后再触发上报保证数据一致性。4. 鸿蒙端适配实战踩坑、排查与优化4.1 构建期问题速查跨平台最让人头疼的就是构建时出一堆看不懂的错误。我把鸿蒙适配过程中遇到的构建期问题按频率排了个序做成一个速查表症状常见原因解决方式构建时提示找不到hvigor命令环境变量没配或 Node 版本太低把 IDE 自带的工具目录加入 PATH检查node -v版本打包后提示libflutter.so不存在Flutter 产物没有正常合入鸿蒙工程检查构建脚本里 Flutter 产物路径确认 build 顺序报错Signature verification failedHAP 签名配置缺失或签名文件过期在build-profile.json5里配置正确的签名证书重新签名编译提示compatible SDK version not foundIDE 的 SDK 版本和工程要求不一致打开 SDK Manager 安装对应版本或在工程里降低compileSdkVersion这里我想特别啰嗦一句鸿蒙的构建错误信息有时候很不直观比如密码签名文件路径错误时只会提示“签名失败”不会告诉你文件不存在。遇到这类问题先在命令行单独跑一遍签名命令验证证书再回 IDE 里构建能更快定位问题。4.2 运行期兼容性问题构建成功只是第一步运行期的坑更隐蔽。我遇到过的三个典型问题每个都排查了很久第一个是网络请求超时。Dart 代码在 Android 上跑得好好的鸿蒙上却连不上接口。后来发现是鸿蒙侧默认启用了严格的网络安全策略需要除了声明 INTERNET 权限外还要在配置里允许明文流量。开发阶段直接允许 cleartext上线前再收紧到 HTTPS。第二个是字体渲染不一致。鸿蒙系统自带字体的fontFamily名称和 Android 不一样直接在TextStyle里指定字体名称鸿蒙端可能 fallback 到默认字体导致成语的汉字显示效果和 Android 差很远。解决方式是把自定义字体打包进 assets并在pubspec.yaml里声明不依赖系统字体。第三个是滚动手感差异。问题的根源在于鸿蒙的触摸事件参数和 Flutter 默认的滚动引擎预期不完全一致。如果你发现列表滚动很钝或者有迟滞感可以在MaterialApp里调整scrollBehavior或者在具体列表页设置physics。4.3 多端自适应布局与交互统一成语闯关要同时在手机和平板甚至折叠屏上跑得舒服布局策略要提前定好。我的做法是以“可用宽度”为标准划分两个档位竖屏手机按窄屏布局候选字区横向铺满平板或横屏状态下题目区和候选区改为上下分栏或者把答题卡居中显示最大宽度限制在 480dp 左右避免字格被拉得太大影响视觉。LayoutBuilder( builder: (context, constraints) { final compact constraints.maxWidth 600; if (compact) { return _buildPhoneLayout(context); } return _buildTabletLayout(context); }, )交互统一是另一个容易被忽略的点。鸿蒙有自己的手势体系和侧滑返回机制Flutter 应用跑在鸿蒙上时页面内手势优先于系统手势。如果你在答题页实现了横向滑动切换题目就要考虑和系统返回手势的冲突。我最终的做法是答题页固定竖屏同时屏蔽了边缘侧滑手势这样在鸿蒙和 Android 上行为完全一致不需要维护两套逻辑。4.4 包体与性能优化的有效手段适配鸿蒙后我痛感包体膨胀的问题Flutter 本身要带引擎 so再加一套鸿蒙壳包体很容易冲破 30MB。优化手段有几个很有效。第一是裁剪 Flutter 引擎的架构支持。鸿蒙设备的 CPU 架构主要是 ARM64如果不需要 32 位把libflutter.so只保留 arm64-v8a 这一个 ABI包体能直接小 40%。第二是图片资源压缩。成语应用里大量使用了卡片背景和按钮贴图我用在线压缩工具把单张图从 500KB 压到 80KB 左右视觉上几乎看不出区别。题库里的成语解释还涉及到文本排版这方面不需要图片直接用 Flutter 排版就能搞定。第三是延迟加载题库。不要启动时就把题库全部塞进内存先加载基础分类用户进入具体分类页时再按需加载该类目。初始化耗时从 1.8 秒降到 0.6 秒体感提升很明显。性能方面成语闯关最常见的卡顿是在答题动画和音效同时触发时。这里可以用Timer.run把音效播放延后到动画结束或者用ValueNotifier批量更新多个格子的状态减少整棵树的重建。实测下来减少无意义的setState范围帧率从时有掉帧变得稳定满帧。写在最后一点实战体会整个项目从立项到鸿蒙适配跑通最深的体会是跨平台开发的最大成本不在写代码而在处理“平台差异的预期之外”。Flutter 帮你屏蔽了 UI 层的差异但构建链、权限模型、签名机制、手势习惯这些底层的东西仍然需要逐个平台去适配。尤其是鸿蒙端因为 Flutter 不是原生第一公民工程结构多了一层壳碰到问题时要先在原生侧排查而不是急着改 Dart 代码。最后分享一个小技巧尽量把平台相关的初始化代码收敛到同一个文件里用条件导入控制不同平台走不同实现。这样无论将来鸿蒙适配层怎么升级或者要加一个新的平台你只需要改一个文件而不是满项目找if (Platform.isAndroid)。我当初就是没做这层抽象后面适配鸿蒙时翻了好几个文件才找到问题。现在这个项目跑下来安卓、Web、鸿蒙三端共用一套业务代码维护起来确实轻松了不少。