Flutter for OpenHarmony商城实战：从选型到商品详情页落地

做OpenHarmony商城App的时候，团队第一个争论就是跨端框架选什么。倒不是OpenHarmony原生不行——ArkUI的声明式语法这两年进步很快——关键是团队刚从Flutter项目里出来，怀里揣着一套已经打磨好的商城组件和状态管理方案。真要推倒重写，光商品详情页这种交互密集的页面，布局、滚动、图片缓存、SKU联动这些老坎就得再过一遍，工期乐观估也要两三周。所以看到Flutter for OpenHarmony这条路线时，我们几乎没怎么纠结就定了：一份Dart代码，跑在Android、iOS、OpenHarmony三端。

这篇文章就用商城App里最典型的商品详情页做载体，从选型理由、环境搭建、数据层设计、UI落地，到OpenHarmony上特有的适配问题和几段排错复盘，完整讲一遍。适合两类人：一类是刚接触Flutter、想搞明白它在OpenHarmony上到底怎么跑的新手；另一类是已经入了Flutter的坑、正准备把现有App迁到OpenHarmony的团队。内容偏实战，尽量少讲虚的，直接上能用的代码和思路。

1. 为什么在OpenHarmony上做商城App，我最终选了Flutter

1.1 三个路线的实际对比

选型那会儿，摆在我们面前的主要是三条路：纯原生ArkUI、React Native、以及Flutter for OpenHarmony。

纯原生ArkUI的优势是性能和系统能力调用最直接，HarmonyOS的声明式UI写起来也确实顺手。但劣势同样明显：团队里没人写过ArkUI。商城这种以列表、详情、购物车为主的业务，页面数量不少，每个页面都用原生重写一遍，人力成本是明摆着的。再加上ArkUI的生态起步时间不长，第三方组件、图表库、图片加载这些常用能力都得自己造轮子。

React Native那条路更坎坷，主要问题在于RN对OpenHarmony的适配一直没有形成稳定的社区版本，JS引擎和原生桥接的兼容性需要自己维护的东西太多。试了两天就放弃了——团队没有精力养一套非主流的桥接层。

Flutter for OpenHarmony反而是当时最稳妥的。OpenHarmony SIG组在Gitee上有专门的flutter引擎移植分支，虽然不能跟Android官方支持比，但Dart侧代码基本不用改，UI自绘机制天然不依赖原生控件，商城页面99%的自绘UI可以直接复用。我们线上Android版商城已经在用Flutter写，几千行Dart代码平移过来，成本低得惊人。

三个方案摆在一起，差异其实就一句话：ArkUI和RN都是在学一门新语言新生态，Flutter只是在换一个运行平台。

1.2 Flutter在OpenHarmony上到底怎么跑起来的

很多人第一次接触Flutter for OpenHarmony，会误以为它是把Android的Flutter引擎打包直接搬过去的。实际不是。OpenHarmony上跑Flutter，本质是把Flutter的引擎层替换成了适配OHOS图形子系统的版本。

我拿电视盒子打比方：Dart代码就是剧本，Flutter引擎是播放器，而OpenHarmony的图形栈是电视屏幕。Flutter的UI并不渲染成ArkUI的组件树，而是自己通过Skia（后续也在往Impeller迁移）直接绘制到屏幕上。也就是说，在OpenHarmony上打开一个Flutter页面，原生侧其实只提供了一个宿主容器，剩下的画面都是Flutter引擎自己画出来的。

系统能力这块，Flutter通过PlatformChannel跟OHOS侧通信。比如要在详情页调相机、存图片、拿设备信息，Dart侧发起一个MethodChannel调用，OHOS侧用同一套平台通道做实现注册。我们当时做了一个商品晒图功能，相机调用就是在OHOS侧实现了一个CameraPlugin，Dart侧跟Android/iOS一样用image_picker这个接口，只是换了底层的实现注册。

理解了这个结构，就能解释很多后续踩到的问题：凡是Flutter能自己画的，在OpenHarmony上都相对顺畅；凡是必须依赖原生组件的，就要小心platform view和插件适配这两道坎。

1.3 这套组合适合什么项目

聊完选型，必须泼一盆冷水。Flutter for OpenHarmony不是万能药。

适合做的，就是商城、工具、资讯这类以自绘UI为主、原生能力依赖少的应用。我们当时把商品详情页、列表页、购物车全部迁过来，页面级别几乎零改动，依赖的原生能力只有WebView、相机、相册这几个，都有现成或可开发的通道。

不适合做的，是重度依赖系统原生交互的应用，比如AR、复杂地图、系统设置类。OpenHarmony侧的原生控件封装还不像Android那么丰富，PlatformView的成熟度也有限，硬做会砸在适配阶段。

选型建议就一句话：先盘一下自己现有页面对原生控件的依赖程度，再决定要不要走Flutter for OpenHarmony。依赖原生越少，这条路越香。

2. 环境搭建与项目初始化：文档之外的那点坑

2.1 从Gitee拉引擎分支：版本匹配是第一道坎

环境搭建最容易被忽视的就是版本匹配。Flutter for OpenHarmony不是从pub.dev或者flutter.dev官方分发渠道拿的，而是OpenHarmony SIG组维护的flutter仓库的openharmony分支，托管在Gitee上。

我们当时踩的第一个坑就是：用官方Flutter SDK建工程，然后跑flutter build，结果编出来的产物在OpenHarmony真机上根本起不来。查了半天发现是版本分支不对——OpenHarmony侧的引擎用的是OHOS SDK的图形接口，跟官方Flutter引擎的OpenHarmony适配是绑定具体版本的。

实操建议：直接clone Gitee上的flutter_flutter仓库，切到openharmony分支，用这个SDK去跑项目。同时OpenHarmony SDK用DevEco Studio配套的版本，别追新，两个SDK的版本组合以能跑通hello world为准。我们当时固化的版本组合是这样的（版本号会更新，关键看稳定性）：

版本匹配这里没有太多捷径，最快的验证方式就是脚手架建一个默认工程，真机上跑起来再继续。第一步跑不起来就升级版本，跑起来了就固化锁死，后面所有开发都基于这一套。

2.2 创建工程：从Flutter命令行到OHOS工程目录

环境配好后，创建工程本身不复杂，但有个关键点：Flutter工程的ohos目录不是自动生成的。

我当时先用flutter命令创建纯Dart工程，然后跑到Gitee仓库在openharmony分支下提供的模板里，把ohos平台目录拷贝进项目。这一步官方文档提得很隐晦，很多人卡在这里。

实际流程是这样：

# 1. 用openharmony分支的flutter SDK创建工程 flutter create --org com.example mall_app # 2. 从模板仓库拷贝ohos平台目录到工程根目录 cp -r flutter_templates/ohos mall_app/ # 3. 进入ohos目录，配置包名和应用名 cd mall_app/ohos # 修改module.json5和build-profile.json5里的包名 # 4. 回到工程根目录，拉取Dart依赖 flutter pub get

之所以要手动拷贝ohos目录，是因为OpenHarmony侧的应用工程结构（entry、hvigorfile、module.json5这些）跟Flutter默认的平台目录不共享一套生成逻辑。手动拷完注意把ohos工程的包名跟Flutter侧的applicationId保持一致，否则后面混编时签名和渠道会乱。

2.3 首次构建的报错排查：镜像、依赖与DartVMInitializer

第一次构建时，我们遇到了两个相当经典的报错。

第一个是依赖下载慢到怀疑人生。OpenHarmony的hvigor依赖默认走外网下载，不搭镜像的话，几个小时都下不完。解决办法是把hvigor的仓库地址替换成国内镜像，然后在ohos/build-profile.json5里配置好仓库源。这个不展开说了，团队内部文档里都有，核心就是：一旦涉及下载，第一反应就是换镜像源，别傻等。

第二个是运行期一直刷E/flutter (31173): [ERROR:flutter/runtime/dart_vm_initializer.cc(41)]这样的日志，然后页面卡住不动。这个报错是Flutter引擎的Dart VM初始化阶段的全局异常捕获在打印未处理异常，通常意味着应用里某个异步操作抛错但没有被任何try-catch接住。我们后来定位到是商品数据接口的网络层在OpenHarmony真机上用了LocalSocket方式，但代码里还在用旧版的IOClient，导致连接失败后抛了异常没人管。这个后面第六章专门讲，这里先记住：这个E/flutter日志是"有异常没处理"的信号，不是Flutter引擎本身坏了。

2.4 混合开发：把Flutter模块打成AAR/HAR给原生工程用

项目后期我们走的是混合开发模式，原生ArkUI页面（比如设置、账号安全）保留不变，商品端（首页、搜索、详情、购物车）全部塞进Flutter模块。这种模式下，Flutter侧要产出供原生工程引用的二进制包。

这里就涉及到热词里的flutter aar。在Android世界叫AAR，在OpenHarmony侧对应的是HAR或者直接产物so/hap的组合。操作上跟Android的集成方式类似：先把Flutter模块用hvigor构建出release产物，然后在原生工程里通过har依赖引进来。

踩得比较深的坑是资源合并：Flutter产的so库和assets资源，在原生工程打包成hap时偶尔会冲突。我们的规避方式是把Flutter模块构建产物放到一个独立的存储路径，原生工程只引用不覆盖。另外，混编时Dart侧的入口要配置成可被外部的flutterEngine拉起，否则原生页面跳Flutter页面时找不到入口。

混合开发建议放到项目稳定后再做。前期还是全Flutter页面单跑，把业务逻辑跑通，再考虑把原生页面嵌进来。一开始就混编，会同时面临两套构建体系和两套调试环境的复杂度，排查故障时非常痛苦。

3. 商品详情的数据层设计：JSON、异步与状态管理

3.1 数据模型：先把商品结构定清楚

商品详情页的UI再花哨，底子都是数据。页面从上到下要展示轮播图、标题、价格、规格、库存、图文详情，这些字段我按接口返回的JSON结构建了对应的Dart模型。

我们用的模型没有上json_serializable那套代码生成器，因为商城接口字段不算特别多，手写fromJson反而更直观，也方便针对OpenHarmony侧的特殊字段做容错。核心模型大概是这样的：

class ProductDetail { final int id; final String title; final String subtitle; final List<String> images; final double price; final double originalPrice; final int stock; final List<SkuGroup> skuGroups; final String detailHtml; ProductDetail({ required this.id, required this.title, required this.images, required this.price, ... }); factory ProductDetail.fromJson(Map<String, dynamic> json) { return ProductDetail( id: json['id'] as int, title: json['title'] as String? ?? '', images: (json['images'] as List?)?.map((e) => e.toString()).toList() ?? [], price: (json['price'] as num?)?.toDouble() ?? 0, skuGroups: (json['skuGroups'] as List?) ?.map((e) => SkuGroup.fromJson(e as Map<String, dynamic>)) .toList() ?? [], detailHtml: json['detailHtml'] as String? ?? '', ); } } class SkuGroup { final String groupName; final List<SkuOption> options; SkuGroup({required this.groupName, required this.options}); factory SkuGroup.fromJson(Map<String, dynamic> json) { return SkuGroup( groupName: json['name'] as String, options: (json['options'] as List) .map((e) => SkuOption.fromJson(e as Map<String, dynamic>)) .toList(), ); } }

这里有个容易忽略的点：商品接口返回的字段经常是null，比如部分商品没有originalPrice、没有subtitle。Dart的强类型不会容忍你直接json['stock'] as int，一旦null就崩。所以所有字段都要给空值兜底，这是详情页稳定性的第一道防线。

3.2 Repository模式：为什么不能直接在页面里发请求

很多新手写详情页，习惯在State里面直接建Dio对象，然后_http.get(...)一把梭。页面少了还好，商城这种多业务复用的项目，十个页面各写各的请求，后面改个接口地址、加个公共请求头，就是个灾难。

我们统一用了Repository模式。所有网络请求收敛到ProductRepository里，页面只跟仓库打交道：

class ProductRepository { final Dio _dio; ProductRepository(this._dio); Future<ProductDetail> fetchDetail(int productId) async { final resp = await _dio.get('/api/product/detail', queryParameters: { 'productId': productId, }); return ProductDetail.fromJson(resp.data['data']); } }

Dio的实例在入口处统一配置，baseUrl、超时时间、拦截器（统一加签名、统一解析错误码）都在这一个地方做。页面拿到的永远是解析好的ProductDetail模型，不关心网络细节。

3.3 Dart异步三件事：事件循环、微任务与错误边界

商品详情页的数据加载绕不开Dart的异步机制。热搜词里有个问题问得很好："flutter future的then回调是放入微任务队列吗"。答案是：then回调确实会被放入微任务队列（microtask queue），它在Dart单线程事件循环中优先级比事件队列高，当前同步代码执行完后会立即执行微任务。

这个机制在详情页有个很典型的坑：你在then回调里更新状态时，如果回调里做了什么耗时计算，会直接卡住UI事件的调度，因为微任务会连续执行完才回到事件循环。所以两个经验：

• then回调里只做状态赋值和轻量操作，重活扔到compute或者切到异步事件里去。
• FutureBuilder里不要嵌套async逻辑，尤其不要在builder里直接await网络请求，会导致重复请求和状态错乱。

页面加载数据的正确姿势是集中管理请求生命周期：

@override void initState() { super.initState(); _load(); } Future<void> _load() async { setState(() => _loading = true); _errorMessage = null; try { _detail = await _repository.fetchDetail(widget.productId); } catch (e) { _errorMessage = '网络异常，请稍后重试'; } finally { if (mounted) { setState(() => _loading = false); } } }

这里最容易被忽略的是那个if (mounted)。异步请求返回时页面可能已经销毁了（用户快速退出详情页），还继续调setState会触发"setState() called after dispose()"的异常。电商场景里用户点进点出很频繁，这个检查必须写。

3.4 状态管理：为什么没上Bloc，选了ChangeNotifier

详情页的状态包括：加载状态、商品数据、当前选中的SKU组合、收藏状态。这些状态分布在轮播图、信息区、SKU弹窗、底部操作栏多个组件里，不是单纯用setState能管好的。

我们没有上Bloc，因为详情页的状态复杂度还没到需要事件流维度来管理的程度。Bloc那套的样板代码在这种中小型页面上反而是负担。选的是ChangeNotifier + ListenableBuilder的组合，简单直接。

class DetailState extends ChangeNotifier { ProductDetail? detail; bool loading = false; String? errorMessage; int selectedSkuIndex = -1; bool favorited = false; Future<void> load(int productId) async { loading = true; errorMessage = null; notifyListeners(); try { detail = await _repository.fetchDetail(productId); } catch (e) { errorMessage = '加载失败，请重试'; } finally { loading = false; notifyListeners(); } } void toggleFavorite() { favorited = !favorited; notifyListeners(); } }

详情页根组件用ListenableBuilder包住，子组件通过局部监听拿到自己关心的字段。收藏按钮只监听favorited，SKU弹窗只监听selectedSkuIndex和detail.skuGroups。这样改一个字段不会全页刷新，滚动性能要好很多。

4. 商品详情页UI落地的全过程

4.1 首屏结构：一个CustomScrollView打底

详情页整体框架我用的是CustomScrollView而不是SingleChildScrollView + Column。原因有两条：一是页面内部有多段滚动内容（轮播图、信息区、SKU区、图文详情），CustomScrollView天然支持给特定区块添加吸顶效果；二是后面要接下拉刷新，RefreshIndicator跟CustomScrollView配合最顺。

页面骨架：

RefreshIndicator( onRefresh: _onRefresh, child: CustomScrollView( slivers: [ SliverAppBar( title: Text('商品详情'), pinned: true, ), SliverToBoxAdapter(child: _BannerSection(detail: detail)), SliverToBoxAdapter(child: _InfoSection(detail: detail)), SliverToBoxAdapter(child: _SkuEntrySection(state: state)), SliverToBoxAdapter(child: _DetailWebView(html: detail.detailHtml)), ], ), )

每一段UI都拆成独立组件，父组件只负责把数据传下去。这样页面不会因为某个区域逻辑变复杂而膨胀成几千行的巨型build方法。

4.2 轮播图：PageView + 缩放手势 + 指示器

商品轮播图是比较容易做崩的模块，尤其图片一多，内存和滚动体验问题就来了。

我用的方案是PageView.builder，好处是懒加载 —— 屏幕外的商品图不会提前解码占用内存。每张图外面包一层InteractiveViewer，支持双指缩放和拖动查看细节：

SizedBox( height: 375, child: PageView.builder( controller: _pageController, itemCount: detail.images.length, onPageChanged: (index) { setState(() => _currentImage = index); }, itemBuilder: (context, index) { return InteractiveViewer( maxScale: 3.0, child: Image.network( detail.images[index], fit: BoxFit.cover, frameBuilder: (context, child, frame, wasSyncLoaded) { if (frame == null) { return Container(color: Colors.grey[200]); } return child; }, ), ); }, ), )

frameBuilder在这里做了占位灰底，图片没加载完时不至于白屏闪烁。

4.3 价格区：营销信息怎么做得不廉价

价格区做起来不难，但电商文案里那些促销标签、划线价、满减信息一多，UI就容易乱。我们定的规则是：当前售价最大最醒目，原价做删除线且弱化，营销标签用圆角小色块排在一行，最多三个，多了换行。

页面里的价格不是一个简单的Text，而是一个RichText组合：

RichText( text: TextSpan( children: [ TextSpan( text: '¥${detail.price.toStringAsFixed(2)}', style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold, color: PriceColor), ), if (detail.originalPrice > detail.price) TextSpan( text: ' ¥${detail.originalPrice.toStringAsFixed(2)}', style: TextStyle(fontSize: 14, color: Colors.grey, decoration: TextDecoration.lineThrough), ), TextSpan( text: ' ${_promotionTag(detail)}', style: TextStyle(fontSize: 12, color: Colors.white, backgroundColor: PriceTint), ), ], ), )

这里有个细节坑：RichText里的backgroundColor和文字的圆角没法统一控制，促销标签文字背景是直角的，看起来突兀。后来我把标签单独抽成Container组件包一层ClipRRect放进去，观感才正常。

4.4 SKU规格选择：弹窗、联动与防抖

SKU选择是详情页交互最复杂的模块。用户点"选择规格"弹出底部弹窗，弹窗里列出颜色、尺码等规格分组，用户点选组合后回显对应SKU的价格和库存，再点确认加购。

核心逻辑在SkuSelector组件里维护一个已选规格的映射：

class SkuSelector extends StatefulWidget { final DetailState state; ... } class _SkuSelectorState extends State<SkuSelector> { Map<String, String> _selectedOptions = {}; SkuMatch? _matchCurrentSelection() { final selections = _selectedOptions.entries.toList() ..sort((a, b) => a.key.compareTo(b.key)); // 与服务端返回的SKU组合匹配，返回对应价格库存 return widget.state.detail!.skuList.firstWhere( (sku) => _selectedOptions.keys.every( (groupName) => sku.optionValues[groupName] == _selectedOptions[groupName], ), orElse: () => skuList.first, ); } }

这里容易出问题的是"库存为0的规格要不要置灰"。我们的做法是：该规格组合下任何SKU有库存就可选，完全无库存的置灰。用户选到置灰的规格时，按钮直接不可点，避免提交后服务端报错。

加购按钮的防抖我们用了简单的_submitting布尔开关，请求没回来前不响应第二次点击。千万别小看这个，商城秒杀场景下用户连点两下加购，订单就可能下重了。

4.5 图文详情与下拉刷新

图文详情这块，我用的是平台View加载商品介绍的HTML页面，而不是把一张动辄几千像素的长图塞进列表。原因很简单：长图在SingleChildScrollView里一次性渲染整个坐标系，滚动和内存开销都大；HTML交给平台侧的WebView去解析和渲染，对这些内容的处理更成熟。

下拉刷新则复用RefreshIndicator，刷新回调里重新走一遍_load()流程。注意刷新时不要直接清空页面数据再等接口返回，那样会闪空白。我们的做法是先保留旧数据，等新数据返回后一次性替换。

4.6 底部操作栏：加购、收藏、立即购买

底部操作栏是固定定位在页面底部的，用SafeArea包住防止全屏设备底部Home条遮挡。里面四个按钮：收藏（心形图标）、客服、加入购物车、立即购买。收藏点击走DetailState.toggleFavorite()，加购和立即购买则把当前选中的SKU提交到购物车模块。

这里有个导航上的细节：立即购买不能直接用Navigator.push跳支付页，因为订单是在服务端创建的。正确流程是先调创建订单接口，拿到订单号再跳支付页。这个流程写错的话，用户在弱网环境下会看到"订单提交失败"的诡异提示。

5. OpenHarmony平台特有的适配与进阶

5.1 PlatformView与ArkWeb：图文详情的适配真相

前面提到图文详情用平台View。在Android上，Flutter嵌WebView用AndroidView；在OpenHarmony上，对应的是UiViewFactory和ArkWeb组件的桥接。

问题是，PlatformView本来就是Flutter各平台适配里最闹心的一块，因为原生控件和Flutter自绘UI不在同一个渲染坐标系里，触摸事件、键盘弹出、页面滚动都有边界情况。OpenHarmony上的实现还不像Android那么久经考验，我们实际遇到的坑是：WebView滚动时，Flutter侧的外层CustomScrollView偶尔会吞掉手指事件，导致WebView内部滚动和页面滚动手感不一致。

解决思路有两个：第一，图文详情尽量独立成页，不进主列表滚动流；第二，如果必须在滚动列表里内嵌WebView，给WebView固定高度，内部滚动自己处理，外部列表只负责WebView整体滚动。

5.2 Impeller与Skia：渲染引擎在OHOS上别乱切

Flutter 3.x之后在iOS和Android上逐渐默认启用Impeller渲染引擎，但OpenHarmony移植版目前主要还是走Skia路径。我们没改任何渲染配置，原因很简单：OpenHarmony上的Flutter测试覆盖集中在Skia，切到Impeller没人给你兜底。

真机上如果遇到动画掉帧，不要第一反应是换渲染引擎。先把flutter run --profile跑起来，用PerformanceOverlay定位是栅格化瓶颈还是布局瓶颈。我们遇到过详情页打开弹出SKU弹窗时掉帧，最后定位到是弹窗里规格选项数量太多，一次性build了几十个嵌套圆角容器，用RepaintBoundary包了一层就缓解了。渲染引擎切换是最后的手段，轻易别动。

5.3 系统能力：相机、权限与隐私弹窗

商品晒图功能要调相机。Android上直接申请CAMERA权限，OpenHarmony侧用@ohos.camera接口实现，但权限弹窗逻辑要适配OHOS的应用权限模型。第一次调的时候，因为我们没在module.json5里声明相机权限，服务端校验通过但真机上弹窗就是不出现，代码报"permission denied"。

排查结果：OpenHarmony的权限声明除了要在module.json5的requestPermissions字段里写，还需要在页面侧通过abilityAccessCtrl接口做运行时授权申请。两步缺一不可。这个坑在Android上不存在，因为manifest声明后系统会自动提示。到了OHOS，运行时授权要手动调用，很多Android转过来的人会漏。

5.4 XTS认证视角：上架前要过的兼容门槛

如果项目做完打算走OpenHarmony的应用认证流程，XTS兼容性测试是绕不开的。XTS那套测试用例会覆盖到应用生命周期、权限管理、IPC通信、应用沙箱等多个维度。我们当时在认证前跑了一遍用例，暴露出来的主要问题集中在：

• 应用在静默后台被系统回收后，Flutter引擎重启逻辑没处理好，导致返回前台白屏。
• 部分原生权限声明了却没实际使用，被判定为权限滥用。

这两类问题都不难修，但如果在开发阶段就按XTS的规范来，后期能省大量返工时间。建议在项目初期就看一下XTS的用例范围。

6. 三处耗时最长的排错复盘

6.1 未处理异常导致页面白屏：DartVMInitializer报错的真相

文章开头提到E/flutter DartVMInitializer报错，我们第一次遇到时，整个详情页冷启动直接白屏。当时团队里没人知道这个日志什么意思，查了半天资料，最后定位链路是这样的：

先加全局异常捕获：

void main() { runZonedGuarded(() { FlutterError.onError = (details) { // 接入自己日志系统 reportError(details.exception); }; runApp(const MallApp()); }, (error, stack) { reportError(error, stack); }); }

加了捕获之后，日志里能看到真正崩的异常堆栈了。问题出在商品数据接口返回的skuList字段，在部分商品上是个空数组，但我们的解析代码用了firstWhere(orElse: () => skuList.first)，空数组上取.first就直接抛Bad state: No element。这个异常发生在Future的调用链上，没有catch，直接被引擎当作未处理异常打印出来了。

这件事给我们的教训是两层：第一，解析层必须对所有集合做空值兜底，不能想当然地认为返回一定有值；第二，生产环境一定要全局挂异常捕获，不然你会看到一屏DartVMInitializer日志但完全不知道业务代码哪里炸了。

6.2 图片资源过大导致的OOM

详情页轮播图和图文详情图片都是后台编辑上传的，编辑上传时没有做压缩，好几张图单张4MB以上。在低配真机上，轮播图滑两次就OOM。

排查过程：先用flutter run --profile观察内存曲线，发现图片组件一加载，内存直接往上窜。原因在于Flutter引擎对网络图片解码后默认保留原始尺寸的位图，4MB的图解码成位图后内存可能膨胀到20MB以上。

修复方案是双管齐下：代码层给图片服务加?imageMogr2/thumbnail/800x800这样的缩略图参数，轮播图和列表只拉缩略图，不拉原图；内存层把ImageCache的默认上限调低，防止缓存池被大图撑爆：

PaintingBinding.instance.imageCache.maximumSize = 200; PaintingBinding.instance.imageCache.maximumSizeBytes = 80 << 20;

图文详情那个页面因为本身就是WebView渲染，不受Flutter内存池影响，倒没出问题。轮播图、商品列表这种Flutter侧直接解码的地方，是OOM重灾区。

6.3 购物车角标的组件通信：Stream比全局State好用

详情页点了加购之后，底部导航栏的购物车角标要立刻更新。这个跨页面通信的场景，我们没有引入全局状态管理框架，用了一个轻量级EventBus。

Dart侧定义一个全局的StreamController作为事件通道：

class CartEvents { static final StreamController<int> _controller = StreamController.broadcast(); static void add(int count) => _controller.add(count); static Stream<int> get stream => _controller.stream; }

详情页加购成功后发事件，购物车页签的宿主在initState里监听Stream、更新角标。用Stream而不是直接拿全局变量，好处是事件天然支持多订阅者，以后列表页、搜索页也要更新角标时，加监听就行，不用改详情页的代码。

这里要小心一个坑：StreamController用完之后要close，不然一直挂在内存里。我们用broadcast全局单例的话，一般不手动close，监听端在State里监听时要在dispose里取消订阅。

StreamSubscription? _sub; @override void initState() { super.initState(); _sub = CartEvents.stream.listen((count) { setState(() => _cartCount = count); }); } @override void dispose() { _sub?.cancel(); super.dispose(); }

这套模式在商品详情页、购物车、首页三个模块之间通用，代码量不大，但把跨页面通信解耦得很干净。

6.4 防抖在加购场景下的必要性

第三个排错其实是我的失误。加购按钮那会儿没有做请求防抖，测试在弱网环境下双击加购，购物车里出现了两条相同的订单商品。虽然服务端可以合并，但用户体验很怪。

后来在_submitOrder和_addToCart两个方法入口都加了_submitting开关，请求未返回期间按钮置灰并显示一个轻量loading。这个改动十五分钟搞定，但直接避免了一类商城高频投诉。

顺带说一个细节：加购成功后的Toast提示，在OpenHarmony上不要用Android的Toast通道，Flutter侧用SnackBar或者Overlay自己渲染，比走平台通道要稳。因为部分OHOS真机的Toast高度跟Flutter页面不共享状态，容易顶掉底部操作栏的位置。

最后分享一个小技巧：商品详情页的骨架屏。最开始的版本里，数据加载期间整个页面是白底加一个居中的转圈，在OpenHarmony真机上冷启动加载商品数据要等两秒左右，用户反馈"感觉像卡死了"。后来我在加载期间放了一套骨架屏布局，灰色圆角块模拟轮播图、标题、价格条的位置，数据回来后切换成真实内容。表面看只是UI细节，但电商场景里详情页的加载时间是用户流失率的高敏指标，骨架屏的成本非常低，收益却很明显。

骨架屏、错误重试、下拉刷新这三件套加完，商品详情页才算真正达到上线标准。Flutter for OpenHarmony这条路走到现在，我最深的体会是：跨端框架移植，真正的难点从来不是Dart代码本身，而是每一层平台对接的边界问题。把这些边界问题摸熟，这套组合的性价比确实很高。