Flutter 配合鸿蒙开发做跨平台应用,最近在社区里讨论度一直居高不下。我手上这个烘焙食谱大全 App 刚好需要同时覆盖 Android、iOS 和 HarmonyOS NEXT,所以从环境适配到业务落地完整地跑了一遍。这篇就以“烘焙食谱大全”为载体,把这个过程中的架构选型、数据层设计、组件通信、原生能力打通和常见坑点都摊开讲。适合已经有点 Flutter 基础、想往鸿蒙平台延伸的开发者,也适合正在做跨端技术选型的同学拿来当参考。

1. 项目定位与跨平台方案选型

1.1 鸿蒙原生与 Flutter 的边界问题

HarmonyOS NEXT 出来之后,很多团队的直觉是“做鸿蒙应用必须学 ArkTS 原生”。但从跨平台的角度看,如果团队已经沉淀了一套 Flutter 业务代码,完全有另一个选项:让 Flutter 作为跨端框架,通过嵌入式引擎接入鸿蒙体系。我实际跑下来的结论是,这条路走得通,但必须接受一个前提——你用的是社区或官方维护的鸿蒙适配版 Flutter SDK,而不是原生 Flutter 直接硬编。

为什么 Flutter 适合鸿蒙?核心原因在渲染层。Flutter 是自绘引擎,UI 不依赖系统控件,Framework 层负责 Widget 树、Element 树和 Render 树的协调,Engine 层负责栅格化,Embedder 层负责与操作系统交互。鸿蒙适配的重点恰好就在 Embedder 层,只要引擎能在鸿蒙上正常启动,开发者写出来的页面基本可以做到三端一致。对食谱这类内容型应用来说,图片、卡片、圆角、阴影的视觉还原度直接决定品质感,这一点 Flutter 天然占优。

1.2 烘焙食谱应用的功能边界

食谱应用听起来不算复杂,真要做成“大全”级别,功能边界很容易失控。我把 MVP 范围收敛成八个模块:首页推荐列表、分类筛选、关键词搜索、食谱详情、收藏夹、操作步骤、食材勾选、购物清单。为什么选这个业务来验证跨平台?因为它的主体是图文列表和详情页,数据模型简单,对平台差异不敏感,但又覆盖了列表刷新、状态同步、数据持久化这些常见技术点。

这样的范围对学习是友好的。如果你拿它当练手项目,生命周期可控;如果团队要做技术验证,它也能把 Flutter 在鸿蒙上的响应速度、内存占用、分包体积这些关键指标都测出来。真正常见的原生能力,比如系统分享、相册选图、消息推送,可以在后续阶段用 Platform Channel 补上,不影响主线。

1.3 技术栈清单与取舍

我用的技术栈如下:

模块 选型 说明
框架 Flutter Dart 语言,一套代码三端跑
状态管理 Riverpod 编译期安全,无 BuildContext 依赖
路由 go_router 声明式路径映射,支持传参和嵌套导航
数据库 sqflite 鸿蒙适配版 基于 SQLite,接近原生 SQL
本地偏好 shared_preferences 存用户设置、启动次数等轻量数据
图片加载 cached_network_image 带本地缓存,避免重复拉取
时间处理 intl 格式化时长、日期

这个清单不是越大越好。之前我考虑过 Bloc,但这个小项目里 Riverpod 的样板代码更少,理解门槛低;drift 功能更强,但涉及代码生成,在鸿蒙适配分支上需要额外验证。选 sqflite 而不是 drift,是因为它 API 稳定、更接近 SQL 原生语义,排查问题时心态不慌。

2. 环境搭建与工程初始化

2.1 鸿蒙侧环境准备

先解决一个基本问题:要在鸿蒙上跑 Flutter,开发环境不是只有 Android Studio 和 Flutter SDK 就够了,还需要 DevEco Studio、鸿蒙 SDK,以及对应的签名能力。DevEco Studio 的版本建议和目标鸿蒙 API 级别匹配,不要随手装最新版,否则可能出现 SDK 目录结构对不上、编译器版本不兼容的问题。

如果做过“鸿蒙应用开发基础认证”里的练习项目,对证书申请和签名配置应该不陌生;没做过也没关系,按文档走一遍就行。真机调试必须配签名,模拟器调试可以适当放宽。这里有个容易踩的坑:鸿蒙的签名体系和 Android 的 keystore 完全不同,不能用老思路去配置。第一次装环境时把时间多留一点,很多人卡在的不是 Flutter 侧,而是鸿蒙侧工程本身同步不过。

2.2 获取支持鸿蒙的 Flutter SDK 并创建工程

很多新手会问“如何用 Android Studio 创建 Flutter 项目”。这个问题要分路径回答。标准做法是:在 Android Studio 里安装 Flutter 插件,用 flutter create 生成标准工程。但鸿蒙不是 Flutter 官方直接支持的平台,所以你需要先拉取一个支持鸿蒙适配的 Flutter SDK 分支,配置 FLUTTER_ROOT 环境变量,然后执行类似下面的命令:

flutter create --org com.example --project-name baking_app --platforms android,ios,ohos .

注意 --platforms 是否识别 ohos ,取决于你用的适配分支是否完整。如果不识别,就先生成标准 Flutter 工程,再把鸿蒙工程目录手动补进去。创建完以后,用 DevEco Studio 打开工程里的 ohos 目录,或者直接打开工程根目录,等待 hvigor 同步完成。

这里有一点必须说清楚:Flutter SDK、Dart SDK、鸿蒙适配插件三者的版本是绑定的,不能随意升级其中一个。我看到过很多怪异的编译错误,最后都是因为某个依赖的适配包版本与 Flutter 分支不配套导致的。

2.3 跑通第一个鸿蒙页面

环境配好后,先别急着写业务代码,直接跑一个最小页面验证。我在项目里写了一个简单的 main.dart ,内容只有“Hello Baking”。

import 'package:flutter/material.dart';

void main() {
  runApp(const BakingApp());
}

class BakingApp extends StatelessWidget {
  const BakingApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: '烘焙食谱大全',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xFFE07A3F)),
      ),
      home: const HomePage(),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: Center(child: Text('Hello Baking')),
    );
  }
}

在鸿蒙模拟器上运行后,如果控制台出现 Flutter engine 成功初始化的日志,说明链路已经通了。这一步最值得关注的问题是:一旦页面起不来,要分清是 Dart 层异常还是引擎层异常,不要盲目重装工程。后面第七章我会把高频运行时错误单拎出来讲,这里先提个醒。

3. 架构设计与组件通信

3.1 目录分层:从入口到页面

食谱应用虽然不大,但架构不能省。我用了 feature-first 的折中方案,目录结构大致如下:

lib/
  main.dart
  app.dart
  core/
    database/
    theme/
    widgets/
  features/
    recipes/
      data/
      domain/
      presentation/
  shared/

core 放数据库连接、主题、通用组件; features/recipes 按功能域内聚, data 负责数据源, domain 放模型和仓库接口, presentation 放页面与状态。这个分层的价值在于,以后如果把食谱功能扩展到“餐谱计划”或者“食材库存”,不需要动核心框架,加 feature 就行。过度设计要避免,但完全没有边界会让跨组件通信变成一团乱麻。

3.2 Flutter 组件通信的几种常见姿势

“Flutter 组件通信”是很多新人必搜的问题,其实业内写法非常固定,我梳理成四类:

  • 父子组件通信:构造函数传参 + 回调函数,适合卡片、表单这类局部交互。
  • 跨页面传参:路由参数,适合详情页一次性读取 id 的场景。
  • 全局状态共享:Riverpod / Provider,适合收藏状态、登录态、用户设置等跨页面数据。
  • 事件广播:Stream 或自研 EventBus,适合“收藏变化后多个页面同步刷新”这类弱耦合通知。
方式 适用场景 需要警惕的点
构造函数传参 父子组件 层级深了会变成 props drilling
路由传参 页面跳转 返回结果难以多级回传
全局状态 跨页面共享 状态粒度过大会影响刷新范围
事件广播 松散通知 事件名重复会导致难排查

在食谱应用里,最典型的通信场景是收藏按钮。用户在首页点了一个爱心,顶部 AppBar 的收藏总数要更新,收藏夹 Tab 也要刷新。如果只靠路由传参回传,页面栈一深就非常痛苦。我的做法是用 Riverpod 的 Notifier 保存收藏 id 集合,任何页面只需要读取同一份状态即可。

3.3 状态管理落地:从 Provider 到 Riverpod

具体实现上,我定义了一个 FavoriteRecipesNotifier :

class FavoriteRecipesNotifier extends Notifier<Set<String>> {
  @override
  Set<String> build() {
    return {};
  }

  void toggle(String recipeId) {
    final current = {...state};
    if (!current.add(recipeId)) {
      current.remove(recipeId);
    }
    state = current;
  }
}

组件里通过 ref.watch(favoriteRecipesProvider) 去监听,收藏按钮点击后调用 ref.read(favoriteRecipesProvider.notifier).toggle(id) 。这样无论列表页、详情页还是收藏夹,状态始终是单一来源,不会出现“列表说收藏了,详情页还是未收藏”的错位。Riverpod 最大的好处是编译期就能发现 provider 拼写错误,重构起来比 Provider 稳很多。

4. 数据层设计与数据库调试

4.1 食谱数据模型设计

食谱表的核心字段如下:

字段 类型 说明
id TEXT 主键,用 uuid 或自增
name TEXT 食谱名称
category TEXT 分类,如面包、甜点、主菜
image_url TEXT 封面图地址
duration INTEGER 预计耗时,单位分钟
difficulty INTEGER 难度等级,1-3
ingredients_json TEXT 食材清单,JSON 数组
steps_json TEXT 操作步骤,JSON 数组
is_favorite INTEGER 是否收藏,0/1

为什么食材和步骤用 JSON 字段而不是拆成子表?因为这个业务里它们只随详情整存整取,不会出现“按食材反向搜索所有食谱”的需求。拆成两张表增加 join,查询复杂度和写入复杂度都上来了。如果以后要做“冰箱里有什么能做什么菜”的功能,再考虑拆表也不迟,这属于典型的按业务场景选 schema。

4.2 sqflite 在鸿蒙上的接入

鸿蒙适配的 sqflite 包与标准 sqflite 的 API 基本一致,我以社区常见的适配方案为例,初始化代码大致如下:

final dbPath = join(await getDatabasesPath(), 'baking.db');
final db = await openDatabase(
  dbPath,
  version: 1,
  onCreate: (db, version) async {
    await db.execute('''
      CREATE TABLE recipes(
        id TEXT PRIMARY KEY,
        name TEXT NOT NULL,
        category TEXT,
        image_url TEXT,
        duration INTEGER,
        difficulty INTEGER,
        ingredients_json TEXT,
        steps_json TEXT,
        is_favorite INTEGER DEFAULT 0
      )
    ''');
  },
);

首次启动时,我会把 assets 里的预置 JSON 解析后写入数据库。要注意的是 onUpgrade 回调,很多人图省事直接 DROP TABLE 再重建,这在开发期可以,上线后用户的数据就全没了。正确做法是先尝试 ALTER TABLE 加新字段,实在不行再建新表并把旧数据迁移过去。

提示:数据库版本号每次改动都递增,不要回退,否则用户的本地数据可能读不出来。

4.3 用 DB4S 快速验证数据库结构

数据库调试我强烈推荐一个桌面端工具:DB Browser for SQLite,简称 DB4S。它开源、免费,跨平台,可以直接打开应用沙盒里的 .db 文件,查看表结构、执行 SQL、手工修改数据。

我的流程是:在 App 里写一个调试入口,点击后把数据库文件复制到外部存储,然后通过文件管理导出到电脑,再用 DB4S 打开。有一次我发现列表查询奇慢,排查后发现是 is_favorite 字段没有索引。虽然 JSON 字段不适合直接建索引,但在 category 和 is_favorite 上建联合索引后,查询分类列表的性能立刻恢复正常。这种问题在代码里可能看半天看不出来,用 DB4S 看一眼执行计划立刻就明白了。

5. UI 交互实现与 Flutter 体验细节

5.1 底部导航栏与页面骨架

食谱应用我设计了四个 Tab:首页、分类、收藏、我的。Flutter 里最简单的做法是用 NavigationBar 配合 IndexedStack :

Scaffold(
  body: IndexedStack(
    index: currentIndex,
    children: const [HomePage(), CategoryPage(), FavoritePage(), ProfilePage()],
  ),
  bottomNavigationBar: NavigationBar(
    selectedIndex: currentIndex,
    onDestinationSelected: (value) => setState(() => currentIndex = value),
    destinations: const [
      NavigationDestination(icon: Icon(Icons.home_outlined), label: '首页'),
      NavigationDestination(icon: Icon(Icons.category_outlined), label: '分类'),
      NavigationDestination(icon: Icon(Icons.favorite_outline), label: '收藏'),
      NavigationDestination(icon: Icon(Icons.person_outline), label: '我的'),
    ],
  ),
)

用 IndexedStack 是为了在切换 Tab 时保留页面状态,否则每次切回来列表都会重建、滚动位置丢失。这一点和鸿蒙原生应用里底部导航的常见处理思路一致。另外要特别注意全面屏手势区,底部导航会被系统导航条遮挡,记得用 SafeArea 包裹,否则在真机上按钮会被截掉一部分。

5.2 下拉刷新与分页加载

首页食谱列表我用了 RefreshIndicator 配合 ListView.separated 。下拉刷新时重新从本地仓库读取数据,同时加一个短暂延迟模拟网络请求,让用户有明确的“刷新完成”反馈。

RefreshIndicator(
  onRefresh: () async {
    await _refreshRecipes();
  },
  child: ListView.separated(
    controller: _scrollController,
    itemCount: recipes.length + (hasMore ? 1 : 0),
    separatorBuilder: (_, __) => const SizedBox(height: 12),
    itemBuilder: (context, index) {
      if (index >= recipes.length) {
        return const Center(child: CircularProgressIndicator());
      }
      return RecipeCard(recipe: recipes[index]);
    },
  ),
)

数据量一旦超过 50 条,就不要一次把所有卡片全部渲染,我用 ScrollController 监听接近底部时加载下一批。这个策略对鸿蒙设备内存更友好,滚动性能也更稳定。下拉刷新的指示器颜色要适配深色模式,我吃过的亏是浅色背景下看不到加载圈,最后直接在主题里统一配置了 refreshIndicatorColor 。

5.3 详情页与转场动效

从列表跳到详情,我用 Hero 动画让封面图“飞”过去,视觉上非常连贯。详情页主要由三块组成:大图与基本信息、食材清单、操作步骤。食材清单做成可勾选列表,方便用户边买边核对;步骤用带序号的纵向布局呈现,整体就是一个“烘焙操作台”的感觉。

在鸿蒙上做中长文本展示时要注意换行逻辑。虽然 Flutter 是自绘文本,跨端观感一致,但不同系统字体渲染高度略有差异,最好在详情页真机跑一遍,确认食材用量里的计量符号不会折行折得很难看。这个细节很容易被忽略,但对内容型应用来说直接影响阅读体验。

5.4 Flutter 与其他跨端框架怎么选

“Flutter 和别的前端框架的优缺点”是搜索热度很高的话题。经常被拿来对比的是 React Native 和鸿蒙 ArkUI。

Flutter 的优势是渲染一致性强、动画流畅、生态成熟,尤其适合界面复杂度高、需要跨端统一还原的应用;代价是包体积偏大、PlatformView 复杂,以及鸿蒙适配还不是第一公民。React Native 走的是桥接原生组件路线,上手门槛低,但在复杂动画和高频列表场景需要额外优化。ArkUI 在鸿蒙上是原生体验,但跨端能力天然受限。

选型没有绝对答案。如果团队已有 Flutter 资产,鸿蒙版本的价值就很大;如果是从零开始且只做鸿蒙,ArkTS 可能是更直接的选择。面试官如果问 Flutter 系统架构,除了背出 Framework、Engine、Embedder 三层,最好能结合鸿蒙嵌入层的适配现状说明,这会明显加分。

6. 原生能力打通:Platform Channel 与 PlatformView

6.1 MethodChannel 实现系统分享

Flutter 侧做不了的系统能力,比如分享、相册、推送、实况窗,都要靠 Platform Channel 走原生实现。食谱应用里我实际用到的场景是把一份食谱文本分享到系统分享面板。

Dart 侧调用:

static const MethodChannel _channel = MethodChannel('baking/share');

Future<void> shareRecipe(String title, String content) async {
  await _channel.invokeMethod('shareText', {
    'title': title,
    'content': content,
  });
}

原生侧分别要在 Android 的 MainActivity、iOS 的 AppDelegate、鸿蒙的对应 EntryAbility 里注册同一个 channel 并响应调用。鸿蒙的处理方式是解析 Dart 传入的 Map,然后拉起系统分享面板。不同版本 API 会有差异,但思路一致:Dart 方法名与原生方法名对齐,参数用 Schema 化 Map 传递,不要直接塞一个复杂对象。

如果你还遇到类似 iOS Live Activity 或鸿蒙实况窗的需求,同样只能通过原生能力实现,Flutter 侧顶多做到调用入口,别指望纯 Dart 就能动态刷新锁屏卡片。

6.2 PlatformView:嵌原生视图的正确姿势

热搜里“flutter platformview”出现率很高,这是跨端开发绕不开的坎。Flutter 页面内部要嵌入原生地图、相机预览、WebView 时,Android 用 AndroidView ,iOS 用 UiKitView ,鸿蒙平台也有对应的 PlatformView 能力,但成熟度会随适配版本变化。

我的建议是分场景处理。如果只是展示一张地图定位,完全可以用静态截图替代,省去手势冲突和纹理注册的麻烦;如果需要实时交互,先去官方插件列表找现成方案,而不是一上来就自己写。我在食谱详情页做过“附近烘焙店”的嵌入尝试,结论是:静态展示足够,动态交互在鸿蒙上还需要等适配更完善。

注意:PlatformView 内部的触摸事件与 Flutter 手势系统之间经常互相“抢事件”,调试时优先固定视图尺寸,不要放在可滑动区域的正中央。

6.3 AAR 依赖与 Gradle 插件配置

鸿蒙 Flutter 工程集成第三方原生 SDK 时,Android 侧经常要依赖 .aar 文件。正确操作是把 aar 放到 android/app/libs ,然后在 app/build.gradle 的 dependencies 里引入。但你大概率会遇到下面这个报错:

You are applying Flutter's main Gradle plugin imperatively using the apply script...

这是新版本 Flutter 在迁移 Gradle 插件加载方式。从 Flutter 3.16 左右开始,官方要求用 plugins DSL 主动声明插件,而不是在 build.gradle 里用 apply plugin 。修复方法是把 settings.gradle 改为:

plugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.1.0" apply false
}

同时移除根 build.gradle 和 app/build.gradle 里重复的 apply plugin 行。鸿蒙侧的依赖管理则在 oh-package.json5 中声明,思路类似,但包名和版本来源都不同,不要共用一套配置。

7. 常见问题排查与经验补遗

7.1 Dart VM 初始化时的 Unhandled Exception

很多人在鸿蒙真机上第一次运行 Flutter 时,会看到这样的日志:

E/flutter: [ERROR:flutter/runtime/dart_vm_initializer.cc(41)] Unhandled exception:

第一反应是“引擎崩了”,其实这是 Dart 层未捕获异常的统一出口。关键要看它下面跟的具体异常类型和堆栈。我遇到过一次网络图片加载失败导致社区版红屏,原因是图片服务器返回 401,而 Image.network 默认遇到 4xx 会抛异常。

解决思路是三层防御:网络图片加 errorBuilder ;异步入口用 runZonedGuarded 包裹,把未捕获异常记录到文件;再在 FlutterError.onError 里做统一兜底,避免异常直接打到原生崩溃通道。

7.2 Future 的 then 回调到底放进哪个队列

搜过“flutter future的then回调是放入微任务队列吗”的人,多半是在准备面试。Dart 的 Event Loop 确实有微任务队列和事件队列, Future.then 里的回调默认是进微任务队列,会在当前同步代码执行完后立刻执行,而不是等下一个事件循环。

验证方式很简单:

void main() {
  Future(() => print('event queue'));
  Future.microtask(() => print('microtask'));
  print('sync');
}

输出顺序是 sync 、 microtask 、 event queue 。这个细节在优化数据库异步查询时很有用:如果 then 回调里又连接了大量耗时操作,等于把微任务队列塞满,界面渲染就会被挤到后面,表现就是“列表卡一下再出现”。大数据量处理记得放到后台 isolate。

7.3 页面重建导致状态丢失

鸿蒙应用从后台恢复,或者路由返回上一页时,页面可能被重建。如果把数据库读取直接写在 initState 里,用户就会看到短暂白屏。我的方案是把加载过程放进 FutureProvider ,数据在内存里有缓存,页面重建时可以立即恢复,无需重新查询。

收藏状态也一样,点击爱心后不能只更新内存,要同步写数据库。否则用户切后台再回来,发现收藏列表少了几项,这种数据不一致问题比 UI 错位更难排查。

7.4 包体积与首屏启动优化

最后补充一点性能经验。Flutter release 包在鸿蒙上的体积不算小,压缩空间主要在几个地方:开启 --split-debug-info 去除调试符号,用 --tree-shake-icons 裁剪图标字体,非首页模块延迟加载。

首屏启动时不要在主 Isolate 做大量 JSON 解析,把数据库预热放到后台 isolate。食谱应用第一次启动要导入几十条预置数据,如果直接在主线程解析 JSON,冷启动会明显变慢。我用 Isolate.run 把解析逻辑移出去之后,首屏时间下降了将近三分之一。

这个食谱应用从立项到三端跑通,前后花了两周,最大的体会是:Flutter 叠加鸿蒙开发,价值在于“一套业务代码能复用”,但不要幻想零成本。环境适配和平台插件的坑远比 UI 代码多。如果打算上手,建议先锁死一套经过验证的 Flutter SDK 与鸿蒙 SDK 版本,用最小项目跑通再扩展功能,同时一定把全局异常处理提前搭好。做完之后你会发现,真正的跨平台难点从来不是 Widget 怎么写,而是平台边界怎么管理。

更多推荐