1. 为什么天气数据值得在鸿蒙上单独建一个层做生活服务类应用的人十有八九最后都会碰上天气需求。外卖要预测配送时段、骑行要判断出门时机、旅游要规划行程、健康类应用要评估运动环境甚至排队点单都能被一场暴雨影响。天气不是一个锦上添花的功能而是直接影响用户决策链路的底层数据之一。Flutter 生态里处理天气数据weather_pack 算是相当完整的一套方案。它封装了数据源接入、多城市管理、实时天气与逐小时预报、空气质量、生活指数、缓存策略等一整套逻辑。问题在于这套库当初是按照 Android 和 iOS 的运行时能力设计的到了鸿蒙生态里插件注册机制、权限模型、沙盒路径、网络栈、甚至应用生命周期管控都变了直接拿现成的编译产物跑大概率会在启动阶段就挂在插件绑定上。本文要解决的就是让 weather_pack 在鸿蒙端像在 Android 上一样无感运行同时把气象数据按照鸿蒙应用的习惯重新组织成数据中心模块方便上层的出行、外卖、运动、旅游等业务线直接订阅和消费。我会先拆解天气数据在鸿蒙应用里的正确组织方式再讲清楚 weather_pack 鸿蒙化时哪些地方必须动、哪些地方可以保留然后给出完整的适配实操步骤最后把踩过的坑整理成速查表。内容定位是面向已经有 Flutter 基础、正在做鸿蒙化改造的客户端开发者或者是准备把 Flutter 业务迁到鸿蒙的应用负责人。项目中牵涉的代码量不小但整体思路遵循一个原则能用平台通道解决的不轻易改 Dart 层能在鸿蒙侧做好兼容的不污染原本的数据模型。确保后续鸿蒙 API 升级时你只需要动最少的代码。2. 适配前的架构判断weather_pack 在鸿蒙端应该以什么形态存在2.1 weather_pack 的能力边界与鸿蒙化的三个层级先说清楚 weather_pack 到底给了你什么。它核心包含四块东西数据源抽象层、天气模型定义、多城市存储与切换、以及一套默认的 UI 组件。数据源抽象层允许你通过 provider 机制接入不同的天气服务商模型定义覆盖了实况天气、当日预报、逐小时预报、空气质量、生活指数、预警信息这些常规字段。UI 组件是锦上添花的实际项目里大部分都是自己重写界面。鸿蒙化改造从低到高有三个层级第一层是初级适配目标就是跑起来。具体指在 OpenHarmony 的 Flutter 引擎分支上编译通过插件能注册网络请求能发出去。这一层不涉及架构改动。第二层是能力适配目标是把鸿蒙原生的能力接进来。典型的包括鸿蒙的位置服务而非经纬度直接传给天气服务商、原子化服务的跨应用数据共享、以及鸿蒙后台任务对天气刷新周期的限制适配。第三层是架构融合目标是让 weather_pack 成为鸿蒙应用里的气象数据中心而非一个独立的三方 SDK。其他业务模块通过统一的数据访问层订阅天气而不是各自去调 weather_pack 的接口。第三层才是这篇文章讨论的核心。2.2 为什么不能直接把 Android 实现搬过来很多人会想Flutter 不是跨平台吗Android 能跑鸿蒙不是也有 Flutter 支持吗确实OpenHarmony 社区维护了一版 Flutter 引擎主流的 Flutter 业务代码可以编译成鸿蒙的 HAP 包。但三方库的插件部分不行。weather_pack 如果依赖了 device_info、geolocator、location 这类插件这些插件在鸿蒙上必须有对应的 ohos 实现。有一部分知名插件的鸿蒙实现已经由社区补齐比如 device_info、path_provider、shared_preferences 都有对应版本。但 weather_pack 本身的原生依赖、以及它内部可能引用的其他插件未必全部覆盖。更麻烦的是鸿蒙的权限模型。Android 上你只需要在 AndroidManifest 里声明权限运行时请求一次鸿蒙的权限分成了 system_basic 和 system_core 两个等级普通应用能申请的只有 system_basic 里的那些。定位权限在鸿蒙上属于 system_basic 中的 user_grant 类型意味着除了在 module.json5 里声明还需要在运行时动态请求并等待用户授权。这个逻辑跟 Android 的运行时权限类似但是接口完全不同。所以适配工作的本质是把 weather_pack 里所有触碰到系统能力的地方全部抽出来放到鸿蒙平台通道层重新实现Dart 层的外部接口保持不变。这样做的好处是上层业务代码完全不知道底下换了一套原生实现将来鸿蒙 API 再怎么升级都只影响通道层。2.3 技术选型用什么方案桥接鸿蒙与 Flutter目前 Flutter 跑鸿蒙的主流路线是用 OpenHarmony 社区维护的 flutter_flutter 和 flutter_packages 仓库。前者对应 Flutter 引擎的 OpenHarmony 分支后者是各常用插件的 ohos 实现。weather_pack 适配时我选择的桥接方案是标准的 MethodChannel没有用 Pigeon 这类代码生成工具。原因是weather_pack 的接口调用频率低、参数简单城市 ID、经纬度、刷新开关标准 MethodChannel 完全够用而且出了问题最好排查。Pigeon 适合参数结构复杂、双向调用频繁的场景气象数据虽然字段多但那是在 Dart 侧的数据模型通道两侧交换的其实只是城市编码和 JSON 字符串接口面很薄。再说状态管理。weather_pack 本身不依赖任何状态管理库但鸿蒙化之后我建议在适配层之上用 Provider 做一层气象数据中心的门面封装。原因很实在Provider 在 Flutter 社区普及率高、上手门槛低而且对鸿蒙场景下的多业务订阅模型支持得好。WeatherDataCenter 作为 ChangeNotifier内部持有实时天气、逐小时列表、空气质量、生活指数四份数据业务模块只依赖这个类不直接接触 weather_pack。3. 鸿蒙环境准备与工程改造的重点环节3.1 Flutter 鸿蒙化运行环境的搭建要点开始改代码之前先把鸿蒙侧的 Flutter 环境跑通。我这里用的是社区维护的 OpenHarmony 分支具体版本号不建议照抄因为迭代快以官方仓 README 为准。但有几个判断标准可以分享引擎分支必须与你的 Flutter SDK 版本对应否则编译出来的 libflutter.so 和插件框架不兼容。判断方式很简单看仓库里 engine 的 tag 是否包含你当前 Flutter 版本的主版本号。DevEco Studio 的版本要能匹配鸿蒙 SDK。我踩过的一个坑是DevEco 版本过新导致编译时使用新的 API 特性但 Flutter 引擎分支里还没适配报一堆 undefined symbol。后来锁定到官方文档推荐的组合一次通过。环境准备清单大致如下OpenHarmony Flutter SDK对应 flutter_flutter 仓库的 ohos 分支DevEco Studio 及配套的 HarmonyOS SDKNode.js 环境HAP 构建链路会用到hdc 工具相当于鸿蒙版的 adb需要强调的是HAP 的构建链路和 APK 完全不同。Flutter 工程里新增 ohos 目录后Dart 代码会先编译成标准 Flutter 产物然后由鸿蒙侧的 Flutter 引擎加载。所以你的 Flutter 业务代码几乎不用改原生插件则必须在 ohos 目录下有对应实现。3.2 module.json5 中的权限声明与隐私合规鸿蒙应用的所有权限声明都集中在 module.json5 文件里。天气应用至少需要两类权限网络权限和定位权限。网络权限属于 system_basic声明如下{ module: { requestPermissions: [ { name: ohos.permission.INTERNET }, { name: ohos.permission.LOCATION, reason: $string:location_reason, usedScene: { abilities: [ MainAbility ], when: inuse } } ] } }注意 LOCATION 权限有三个细节。第一必须提供 reason 字符串资源指向 App 内的隐私说明文案第二usedScene 里的 when 字段控制前后台使用场景天气应用建议只在 inuse 时获取位置避免额外的权限合规负担第三鸿蒙如果目标版本较新还要求应用在 UI 上展示隐私政策并获取用户同意否则即使权限申请通过应用也有可能被系统判定为违规。定位权限的运行时请求逻辑不能放在 Dart 侧直接调必须走鸿蒙侧实现。天气应用的合理做法是首次进入首页时如果定位权限未授权通过 Toast 或弹窗提示用户跳转设置页而不是在启动页强制请求。实测下来这种软引导的用户接受度远高于启动即弹窗。3.3 沙盒路径与持久化存储的兼容处理weather_pack 里大概率会保存城市列表、上次刷新时间、用户的单位偏好摄氏/华氏等数据。Android 上你用 shared_preferences 保存鸿蒙上对应的是 Preferences 库路径和接口都不同。这里有一个省事的办法使用社区提供的 shared_preferences 的 ohos 实现Dart 层代码一行不用改。但如果你要保存的数据里有缓存文件——比如天气图标的位图缓存、或者离线天气包——那就要处理沙盒路径了。鸿蒙应用沙盒路径与 Android 完全不同且不同版本之间还有差异。推荐的做法是凡是涉及路径获取的全部通过 path_provider 的 ohos 实现来获取。它返回的路径是基于当前应用沙盒的天然适配鸿蒙的数据隔离要求。不要自己在 Dart 层硬编码 /data/storage/el2/ 这类路径鸿蒙每次版本升级都有可能调整沙盒结构硬编码路径是给自己埋雷。4. 实操全流程把 weather_pack 跑上鸿蒙的完整步骤4.1 建立 ohos 插件工程并配置依赖我的做法是新建一个独立的 ohos 插件模块来承载 weather_pack 的原生适配逻辑不直接改 weather_pack 源码。这样保证未来 weather_pack 升级时我可以直接用新版本替换适配层不受影响。具体步骤在 Flutter 工程根目录执行 OpenHarmony 分支的 flutter create --templateapp 生成 ohos 目录。在 ohos 目录下创建一个独立的 library module命名如 weather_pack_ohos专门放置原生适配代码。在 ohos 工程根模块的 oh-package.json5 里声明依赖并通过本地 har 包方式关联 weather_pack_ohos。在 MainAbility 或 EntryAbility 的 onCreated 生命周期中注册 weather_pack 插件。这里有个关键的代码位置Flutter 引擎加载插件是通过 FlutterPluginRegistry 完成的。鸿蒙侧的写法是继承 FlutterPlugin 并实现相应接口然后在 ability 的 onCreate 里调用 flutterEngine.getPluginRegistry().register()。示例代码如下import { FlutterPlugin, MethodChannel, MethodCall } from ohos/flutter_ohos; export class WeatherPackPlugin implements FlutterPlugin { private channel: MethodChannel | null null; onAttachedToEngine(binding: FlutterPluginBinding): void { this.channel new MethodChannel(binding.getBinaryMessenger(), weather_pack); this.channel.setMethodCallHandler(this.handleMethodCall.bind(this)); } private async handleMethodCall(call: MethodCall, result: MethodResult): Promisevoid { switch (call.method) { case getWeatherByCityId: // 调用鸿蒙原生天气数据服务或转发到后端聚合层 break; case getLocationCity: // 通过鸿蒙位置服务获取当前城市 break; default: result.notImplemented(); } } onDetachedFromEngine(binding: FlutterPluginBinding): void { this.channel?.setMethodCallHandler(null); this.channel null; } }4.2 数据源接入给 weather_pack 换一套可观测的数据供应链路weather_pack 的设计里数据源是通过 provider 注入的。鸿蒙端适配时我不建议直接用它自带的 provider 去请求第三方天气 API而是自己实现一个 WeatherDataSource 接口内部走鸿蒙的网络栈并且加入缓存和降级策略。原因很简单。HarmonyOS NEXT 上应用对网络的访问管控更严格特别是用户授予仅在使用中允许权限后应用切到后台会被系统挂起这时候如果天气数据还在刷新回调永远不会回来。必须在 Dart 层做超时保护和降级策略拿到昨天的缓存数据先展示等下次进入前台再刷新。我的实现思路是三层结构数据源层只负责按城市 ID 获取天气 JSON来源可以是后端聚合服务也可以是 weather_pack 自带的 provider。缓存层用鸿蒙 Preferences 保存最近一次成功拉取的数据 JSON带时间戳。数据中心层对外暴露 State 和刷新方法内部封装了读缓存 - 拉新数据 - 更新缓存的流程。这样做最大的价值是上层业务不用关心数据是实时还是缓存只需要知道当前 State 是 loading、success 还是 error。而且这套结构天然适配鸿蒙的后台限制模型——应用从后台回前台时数据中心检测到数据过期自动触发静默刷新用户是无感知的。4.3 定位服务的鸿蒙原生实现天气数据的核心触发点是城市。weather_pack 允许直接传城市 ID也可以根据经纬度反查城市。鸿蒙端更合理的做法是利用鸿蒙的位置服务把定位结果传给后端由后端返回对应的城市 ID 和天气数据。鸿蒙侧的定位实现需要用 ohos.geoLocationManager 模块。代码骨架如下import geoLocationManager from ohos.geoLocationManager; export async function getCurrentLocation(): PromisegeoLocationManager.Location { try { const location await geoLocationManager.getCurrentLocation(); return location; } catch (err) { // 返回默认城市的兜底逻辑 } }注意几个细节鸿蒙定位服务要求应用在前台且有可见 UI 时才能获取到定位后台调用会直接失败。定位的精度参数不要一味求高天气场景用 500 米精度就够省电且响应快。如果用户拒绝定位权限必须回到手动选择城市的交互。weather_pack 的城市搜索接口是同步返回本地的城市列表这块在鸿蒙端不需要做任何改动。4.4 UI 渲染层Impeller 引擎与鸿蒙字体渲染的适配weather_pack 自带的 UI 组件在鸿蒙上会碰到两个问题。一个是 Flutter 渲染引擎的工作方式差异。鸿蒙社区版的 Flutter 引擎使用的渲染方案和原版一致但部分场景下 GPU 加速策略不同导致动画掉帧。实测下来天气页面的温度数字跳变动画、以及降雨雷达图的粒子效果在低端鸿蒙设备上会有肉眼可感知的掉帧。对策有两个。轻量方案把 weather_pack 自带的动画关闭改成简单的透明度渐变换场视觉效果差别不大性能提升明显。进阶方案把降雨雷达、风速风向这类基于 CustomPainter 的重型组件换成鸿蒙原生的 Canvas 能力通过平台通道渲染到原生 View 上再嵌入 Flutter 的 Texture 层。这个方案性能最好但开发成本也最高不建议第一次适配就做。另一个是字体渲染问题。鸿蒙的系统字体 HarmonyOS Sans 的中文数字和西文字体在字重、字距上与 Android 上常用的 Roboto 不同。直接使用 weather_pack 默认的排版参数在鸿蒙上会出现部分文字拥挤、温度数值与单位符号间距异常的问题。我的做法是在适配层统一覆盖 TextStyle指定 fontFamily 使用鸿蒙系统字体并针对温度数字单独设置 tabular 特性保证数字等宽。5. 插件通信与组件状态管理的鸿蒙化改造细节5.1 Flutter 组件通信机制在鸿蒙侧的等价实现Flutter 的三方库尤其是 weather_pack 这类需要跟系统能力打交道的库内部通常会拆成多个模块数据模块、UI 模块、工具模块。模块之间通过事件总线、全局状态或继承关系通信。鸿蒙化的过程中最让我头疼的不是 MethodChannel 本身而是 weather_pack 内部模块之间的事件广播。Android 端它用的是 EventChannel 实时推流鸿蒙端 EventChannel 的接口虽然也存在但两边的事件发送频率和线程切换策略有差异偶尔会出现事件丢失。排查下来发现事件丢失主要是因为鸿蒙侧 EventChannel 的 sink 在 UI 线程创建而 Dart 侧监听器注册在后台 isolate。Flutter 引擎在鸿蒙上的线程模型与原版一致但插件注册时机略有差异。解决方法是把 EventChannel 的事件发送全部切到 platform 线程保证 Dart 侧能稳定收到。如果项目里对事件时序有强依赖比如数据加载完成 - 自动滚动到当前小时这类联动建议在 Dart 侧加一层事件缓冲等 UI 组件挂载完成后再消费事件。5.2 用 Provider 构建鸿蒙端的气象数据中心weather_pack 的原始用法是谁需要天气谁自己调接口。这种模式在鸿蒙上非常吃亏因为多个页面各自发请求既浪费流量又容易触发系统频控。我改成了 Provider 单例模式让天气数据在整个应用生命周期内只维护一份。具体结构是这样的class WeatherDataCenter extends ChangeNotifier { WeatherDataCenter._(); static final WeatherDataCenter instance WeatherDataCenter._(); WeatherState _state WeatherState.initial; WeatherState get state _state; ListCityWeather _cityWeatherList []; ListCityWeather get cityWeatherList _cityWeatherList; Futurevoid refreshAll() async { _state WeatherState.loading; notifyListeners(); try { // 并发拉取所有关注城市的数据 _cityWeatherList await Future.wait( _cityIds.map((id) weatherPack.fetchByCityId(id)) ); _state WeatherState.success; } catch (e) { _state WeatherState.error; } notifyListeners(); } }上层组件通过 context.watch () 订阅数据变化。这个方案的直接收益是外卖页面和旅游页面同时显示天气时只发生一次网络请求。更重要的是Provider 的 notifyListeners 机制天然适配鸿蒙的应用生命周期——应用回到前台时只需要调用 refreshAll 判断是否需要刷新所有订阅者会自动收到通知更新 UI不需要每一页单独写生命周期监听。5.3 weather_pack 的城市管理模块改造weather_pack 的城市管理模块支持关注多个城市、上下滑动切换、按拼音搜索。这个模块在鸿蒙化时有两个坑。第一是城市数据的存储位置。天气应用很容易做到用户关注了 20 个城市这些数据如果存在轻量级偏好里每次修改都要整体重写性能很差。我改成了按城市 ID 分 key 存储每个城市的天气数据、关注顺序、是否置顶分开存避免大对象反复序列化。第二是城市搜索的索引构建。weather_pack 自带一份全球城市列表 JSON鸿蒙端直接打包进 HAP 没有任何问题。但如果你的应用内城市列表更新频率高比如新增了小众旅游城市需要做远程配置更新。远程配置下发后先写入沙盒目录再由 Dart 侧加载合并而不是直接替换内置资源。这样做的好处是即使远程配置拉取失败应用依然可以使用内置城市列表兜底。6. 常见问题与排查技巧实录6.1 高频问题速查表问题现象根因分析解决方案应用启动后天气组件空白无任何报错Flutter 引擎加载插件失败weather_pack 依赖的通道未注册检查 ohos 目录下插件是否正确注册到 FlutterPluginRegistry确认插件类名与 Dart 侧调用名一致定位返回城市错误或偶发超时鸿蒙对后台定位管控严格或权限未正确申请确认定位权限仅在前台场景申请使用 500 米精度超时时间放宽到 10 秒超时后切换默认城市天气图标不显示图标资源路径在鸿蒙沙盒中不存在改用 Asset 方式打包图标避免动态写入沙盒或确保写入前先创建目录首次拉取数据慢首页白屏 3 秒以上没有缓存策略所有数据都走网络数据中心层增加先读缓存后拉新策略首页首次展示用缓存数据后台静默刷新从桌面图标进入应用后天气长时间不更新鸿蒙挂起应用后台网络请求Dart 层 Future 无回调前台切换时检查数据新鲜度超过 30 分钟则触发刷新并在刷新时加 Loading 状态提示温度数字在部分设备上显示不全鸿蒙字体渲染宽度与传统字体不同温度数字统一使用等宽数字特性设置明确的字体回退链避免自定义字体未打包导致回退异常多个页面同时请求天气导致内存峰值过高weather_pack 默认每次创建独立数据对象使用 Provider 单例数据中心让所有页面共享同一份天气数据应用在鸿蒙上编译报错找不到某 C 符号DevEco 与 Flutter 引擎分支版本不匹配严格按 flutter_flutter 仓库 README 的版本组合搭建环境不要混用 DevEco 最新版6.2 独家排查心得先抓生命周期再查网络鸿蒙上调试天气类应用最浪费时间的问题是数据加载失败但网络请求明明发成功。我踩过几次坑之后总结出一个经验遇到天气数据不正常时先按这个顺序排查——第一步确认应用是不是在前台。鸿蒙系统一旦把应用切到后台网络请求可能不报错但回调永远不会触发因为线程被挂起。这个现象在 Android 上基本不存在Android 的后台只是降低优先级不会直接冻结线程。鸿蒙的挂起机制更彻底所以天气数据刷新必须放在进入前台的时机。第二步检查权限回调时机。鸿蒙的定位授权弹窗和 Android 不同Android 的授权弹窗是 application 级别的鸿蒙每次冷启动后首次调用定位都会再确认一次。如果你的 weather_pack 适配代码在权限回调之前就发起了定位请求会因为权限未就绪而失败。正确做法是先请求权限回调成功后再调 getCurrentLocation。第三步查看沙盒缓存目录有没有写入权限。鸿蒙对沙盒内子目录的访问有严格限制Preferences 只能写在应用专属目录不能写在随意创建的目录下。如果缓存写入失败weather_pack 的数据持久化逻辑会静默跳过表现就是重启应用后城市列表还在但天气数据全部重新加载。6.3 性能调优低端鸿蒙设备上的天气页优化最后说一个很多人容易忽略的问题鸿蒙设备覆盖面很广从几百元的入门机到旗舰机都有。天气页面往往作为应用首页或常驻模块性能直接影响用户体验。我在适配时做了几件事效果很明显第一把 weather_pack 的逐小时预报列表改成懒加载。默认情况下它会一次性渲染 24 小时的卡片低端设备上切换 tab 的掉帧很严重。改成可视区域预加载 滑动动态构建后帧率稳定很多。这个改动不影响任何数据逻辑只是把 ListView.builder 的构造粒度变细。第二重绘频率控制。天气页面的温度数字变化、空气质量指数变化如果每次刷新都重建整棵树低端设备会吃不消。我用 Selector 按数据块拆分订阅温度变化时只重建温度文本空气质量变化时只重建空气质量组件块。Provider 的 Selector 做这件事非常顺手比全局 notifyListeners 节省大量不必要的 build 开销。第三图标预解码。天气图标如果是网络图低端设备上每次加载都会重新解码造成图片闪烁。适配层里我把天气图标按状态码预解码到内存缓存后续直接走内存位图效果立竿见影。我个人在实际操作中最深的体会是鸿蒙化适配并不是简单的编译通过而是要把原有的插件能力、权限模型、生命周期管理、渲染策略全部按照鸿蒙的设计哲学重新整理一遍。天气这种强依赖系统能力的三方库适配难度比纯 UI 库高一个量级但只要把数据中心、权限链路、缓存策略这三条主线理清楚剩下的都是体力活。最后再分享一个小建议适配过程中尽量保持 Dart 业务层零改动所有鸿蒙特性都隔离在平台通道层这样未来鸿蒙版本迭代时你的适配层可以快速跟随升级不至于被旧代码拖住。 
长河君 · 2026/10/10 12:40:20 · 阅读 1.2k 鸿蒙适配实战：Flutter天气库weather_pack的无缝迁移方案
1. 为什么天气数据值得在鸿蒙上单独建一个层做生活服务类应用的人十有八九最后都会碰上天气需求。外卖要预测配送时段、骑行要判断出门时机、旅游要规划行程、健康类应用要评估运动环境甚至排队点单都能被一场暴雨影响。天气不是一个锦上添花的功能而是直接影响用户决策链路的底层数据之一。Flutter 生态里处理天气数据weather_pack 算是相当完整的一套方案。它封装了数据源接入、多城市管理、实时天气与逐小时预报、空气质量、生活指数、缓存策略等一整套逻辑。问题在于这套库当初是按照 Android 和 iOS 的运行时能力设计的到了鸿蒙生态里插件注册机制、权限模型、沙盒路径、网络栈、甚至应用生命周期管控都变了直接拿现成的编译产物跑大概率会在启动阶段就挂在插件绑定上。本文要解决的就是让 weather_pack 在鸿蒙端像在 Android 上一样无感运行同时把气象数据按照鸿蒙应用的习惯重新组织成数据中心模块方便上层的出行、外卖、运动、旅游等业务线直接订阅和消费。我会先拆解天气数据在鸿蒙应用里的正确组织方式再讲清楚 weather_pack 鸿蒙化时哪些地方必须动、哪些地方可以保留然后给出完整的适配实操步骤最后把踩过的坑整理成速查表。内容定位是面向已经有 Flutter 基础、正在做鸿蒙化改造的客户端开发者或者是准备把 Flutter 业务迁到鸿蒙的应用负责人。项目中牵涉的代码量不小但整体思路遵循一个原则能用平台通道解决的不轻易改 Dart 层能在鸿蒙侧做好兼容的不污染原本的数据模型。确保后续鸿蒙 API 升级时你只需要动最少的代码。2. 适配前的架构判断weather_pack 在鸿蒙端应该以什么形态存在2.1 weather_pack 的能力边界与鸿蒙化的三个层级先说清楚 weather_pack 到底给了你什么。它核心包含四块东西数据源抽象层、天气模型定义、多城市存储与切换、以及一套默认的 UI 组件。数据源抽象层允许你通过 provider 机制接入不同的天气服务商模型定义覆盖了实况天气、当日预报、逐小时预报、空气质量、生活指数、预警信息这些常规字段。UI 组件是锦上添花的实际项目里大部分都是自己重写界面。鸿蒙化改造从低到高有三个层级第一层是初级适配目标就是跑起来。具体指在 OpenHarmony 的 Flutter 引擎分支上编译通过插件能注册网络请求能发出去。这一层不涉及架构改动。第二层是能力适配目标是把鸿蒙原生的能力接进来。典型的包括鸿蒙的位置服务而非经纬度直接传给天气服务商、原子化服务的跨应用数据共享、以及鸿蒙后台任务对天气刷新周期的限制适配。第三层是架构融合目标是让 weather_pack 成为鸿蒙应用里的气象数据中心而非一个独立的三方 SDK。其他业务模块通过统一的数据访问层订阅天气而不是各自去调 weather_pack 的接口。第三层才是这篇文章讨论的核心。2.2 为什么不能直接把 Android 实现搬过来很多人会想Flutter 不是跨平台吗Android 能跑鸿蒙不是也有 Flutter 支持吗确实OpenHarmony 社区维护了一版 Flutter 引擎主流的 Flutter 业务代码可以编译成鸿蒙的 HAP 包。但三方库的插件部分不行。weather_pack 如果依赖了 device_info、geolocator、location 这类插件这些插件在鸿蒙上必须有对应的 ohos 实现。有一部分知名插件的鸿蒙实现已经由社区补齐比如 device_info、path_provider、shared_preferences 都有对应版本。但 weather_pack 本身的原生依赖、以及它内部可能引用的其他插件未必全部覆盖。更麻烦的是鸿蒙的权限模型。Android 上你只需要在 AndroidManifest 里声明权限运行时请求一次鸿蒙的权限分成了 system_basic 和 system_core 两个等级普通应用能申请的只有 system_basic 里的那些。定位权限在鸿蒙上属于 system_basic 中的 user_grant 类型意味着除了在 module.json5 里声明还需要在运行时动态请求并等待用户授权。这个逻辑跟 Android 的运行时权限类似但是接口完全不同。所以适配工作的本质是把 weather_pack 里所有触碰到系统能力的地方全部抽出来放到鸿蒙平台通道层重新实现Dart 层的外部接口保持不变。这样做的好处是上层业务代码完全不知道底下换了一套原生实现将来鸿蒙 API 再怎么升级都只影响通道层。2.3 技术选型用什么方案桥接鸿蒙与 Flutter目前 Flutter 跑鸿蒙的主流路线是用 OpenHarmony 社区维护的 flutter_flutter 和 flutter_packages 仓库。前者对应 Flutter 引擎的 OpenHarmony 分支后者是各常用插件的 ohos 实现。weather_pack 适配时我选择的桥接方案是标准的 MethodChannel没有用 Pigeon 这类代码生成工具。原因是weather_pack 的接口调用频率低、参数简单城市 ID、经纬度、刷新开关标准 MethodChannel 完全够用而且出了问题最好排查。Pigeon 适合参数结构复杂、双向调用频繁的场景气象数据虽然字段多但那是在 Dart 侧的数据模型通道两侧交换的其实只是城市编码和 JSON 字符串接口面很薄。再说状态管理。weather_pack 本身不依赖任何状态管理库但鸿蒙化之后我建议在适配层之上用 Provider 做一层气象数据中心的门面封装。原因很实在Provider 在 Flutter 社区普及率高、上手门槛低而且对鸿蒙场景下的多业务订阅模型支持得好。WeatherDataCenter 作为 ChangeNotifier内部持有实时天气、逐小时列表、空气质量、生活指数四份数据业务模块只依赖这个类不直接接触 weather_pack。3. 鸿蒙环境准备与工程改造的重点环节3.1 Flutter 鸿蒙化运行环境的搭建要点开始改代码之前先把鸿蒙侧的 Flutter 环境跑通。我这里用的是社区维护的 OpenHarmony 分支具体版本号不建议照抄因为迭代快以官方仓 README 为准。但有几个判断标准可以分享引擎分支必须与你的 Flutter SDK 版本对应否则编译出来的 libflutter.so 和插件框架不兼容。判断方式很简单看仓库里 engine 的 tag 是否包含你当前 Flutter 版本的主版本号。DevEco Studio 的版本要能匹配鸿蒙 SDK。我踩过的一个坑是DevEco 版本过新导致编译时使用新的 API 特性但 Flutter 引擎分支里还没适配报一堆 undefined symbol。后来锁定到官方文档推荐的组合一次通过。环境准备清单大致如下OpenHarmony Flutter SDK对应 flutter_flutter 仓库的 ohos 分支DevEco Studio 及配套的 HarmonyOS SDKNode.js 环境HAP 构建链路会用到hdc 工具相当于鸿蒙版的 adb需要强调的是HAP 的构建链路和 APK 完全不同。Flutter 工程里新增 ohos 目录后Dart 代码会先编译成标准 Flutter 产物然后由鸿蒙侧的 Flutter 引擎加载。所以你的 Flutter 业务代码几乎不用改原生插件则必须在 ohos 目录下有对应实现。3.2 module.json5 中的权限声明与隐私合规鸿蒙应用的所有权限声明都集中在 module.json5 文件里。天气应用至少需要两类权限网络权限和定位权限。网络权限属于 system_basic声明如下{ module: { requestPermissions: [ { name: ohos.permission.INTERNET }, { name: ohos.permission.LOCATION, reason: $string:location_reason, usedScene: { abilities: [ MainAbility ], when: inuse } } ] } }注意 LOCATION 权限有三个细节。第一必须提供 reason 字符串资源指向 App 内的隐私说明文案第二usedScene 里的 when 字段控制前后台使用场景天气应用建议只在 inuse 时获取位置避免额外的权限合规负担第三鸿蒙如果目标版本较新还要求应用在 UI 上展示隐私政策并获取用户同意否则即使权限申请通过应用也有可能被系统判定为违规。定位权限的运行时请求逻辑不能放在 Dart 侧直接调必须走鸿蒙侧实现。天气应用的合理做法是首次进入首页时如果定位权限未授权通过 Toast 或弹窗提示用户跳转设置页而不是在启动页强制请求。实测下来这种软引导的用户接受度远高于启动即弹窗。3.3 沙盒路径与持久化存储的兼容处理weather_pack 里大概率会保存城市列表、上次刷新时间、用户的单位偏好摄氏/华氏等数据。Android 上你用 shared_preferences 保存鸿蒙上对应的是 Preferences 库路径和接口都不同。这里有一个省事的办法使用社区提供的 shared_preferences 的 ohos 实现Dart 层代码一行不用改。但如果你要保存的数据里有缓存文件——比如天气图标的位图缓存、或者离线天气包——那就要处理沙盒路径了。鸿蒙应用沙盒路径与 Android 完全不同且不同版本之间还有差异。推荐的做法是凡是涉及路径获取的全部通过 path_provider 的 ohos 实现来获取。它返回的路径是基于当前应用沙盒的天然适配鸿蒙的数据隔离要求。不要自己在 Dart 层硬编码 /data/storage/el2/ 这类路径鸿蒙每次版本升级都有可能调整沙盒结构硬编码路径是给自己埋雷。4. 实操全流程把 weather_pack 跑上鸿蒙的完整步骤4.1 建立 ohos 插件工程并配置依赖我的做法是新建一个独立的 ohos 插件模块来承载 weather_pack 的原生适配逻辑不直接改 weather_pack 源码。这样保证未来 weather_pack 升级时我可以直接用新版本替换适配层不受影响。具体步骤在 Flutter 工程根目录执行 OpenHarmony 分支的 flutter create --templateapp 生成 ohos 目录。在 ohos 目录下创建一个独立的 library module命名如 weather_pack_ohos专门放置原生适配代码。在 ohos 工程根模块的 oh-package.json5 里声明依赖并通过本地 har 包方式关联 weather_pack_ohos。在 MainAbility 或 EntryAbility 的 onCreated 生命周期中注册 weather_pack 插件。这里有个关键的代码位置Flutter 引擎加载插件是通过 FlutterPluginRegistry 完成的。鸿蒙侧的写法是继承 FlutterPlugin 并实现相应接口然后在 ability 的 onCreate 里调用 flutterEngine.getPluginRegistry().register()。示例代码如下import { FlutterPlugin, MethodChannel, MethodCall } from ohos/flutter_ohos; export class WeatherPackPlugin implements FlutterPlugin { private channel: MethodChannel | null null; onAttachedToEngine(binding: FlutterPluginBinding): void { this.channel new MethodChannel(binding.getBinaryMessenger(), weather_pack); this.channel.setMethodCallHandler(this.handleMethodCall.bind(this)); } private async handleMethodCall(call: MethodCall, result: MethodResult): Promisevoid { switch (call.method) { case getWeatherByCityId: // 调用鸿蒙原生天气数据服务或转发到后端聚合层 break; case getLocationCity: // 通过鸿蒙位置服务获取当前城市 break; default: result.notImplemented(); } } onDetachedFromEngine(binding: FlutterPluginBinding): void { this.channel?.setMethodCallHandler(null); this.channel null; } }4.2 数据源接入给 weather_pack 换一套可观测的数据供应链路weather_pack 的设计里数据源是通过 provider 注入的。鸿蒙端适配时我不建议直接用它自带的 provider 去请求第三方天气 API而是自己实现一个 WeatherDataSource 接口内部走鸿蒙的网络栈并且加入缓存和降级策略。原因很简单。HarmonyOS NEXT 上应用对网络的访问管控更严格特别是用户授予仅在使用中允许权限后应用切到后台会被系统挂起这时候如果天气数据还在刷新回调永远不会回来。必须在 Dart 层做超时保护和降级策略拿到昨天的缓存数据先展示等下次进入前台再刷新。我的实现思路是三层结构数据源层只负责按城市 ID 获取天气 JSON来源可以是后端聚合服务也可以是 weather_pack 自带的 provider。缓存层用鸿蒙 Preferences 保存最近一次成功拉取的数据 JSON带时间戳。数据中心层对外暴露 State 和刷新方法内部封装了读缓存 - 拉新数据 - 更新缓存的流程。这样做最大的价值是上层业务不用关心数据是实时还是缓存只需要知道当前 State 是 loading、success 还是 error。而且这套结构天然适配鸿蒙的后台限制模型——应用从后台回前台时数据中心检测到数据过期自动触发静默刷新用户是无感知的。4.3 定位服务的鸿蒙原生实现天气数据的核心触发点是城市。weather_pack 允许直接传城市 ID也可以根据经纬度反查城市。鸿蒙端更合理的做法是利用鸿蒙的位置服务把定位结果传给后端由后端返回对应的城市 ID 和天气数据。鸿蒙侧的定位实现需要用 ohos.geoLocationManager 模块。代码骨架如下import geoLocationManager from ohos.geoLocationManager; export async function getCurrentLocation(): PromisegeoLocationManager.Location { try { const location await geoLocationManager.getCurrentLocation(); return location; } catch (err) { // 返回默认城市的兜底逻辑 } }注意几个细节鸿蒙定位服务要求应用在前台且有可见 UI 时才能获取到定位后台调用会直接失败。定位的精度参数不要一味求高天气场景用 500 米精度就够省电且响应快。如果用户拒绝定位权限必须回到手动选择城市的交互。weather_pack 的城市搜索接口是同步返回本地的城市列表这块在鸿蒙端不需要做任何改动。4.4 UI 渲染层Impeller 引擎与鸿蒙字体渲染的适配weather_pack 自带的 UI 组件在鸿蒙上会碰到两个问题。一个是 Flutter 渲染引擎的工作方式差异。鸿蒙社区版的 Flutter 引擎使用的渲染方案和原版一致但部分场景下 GPU 加速策略不同导致动画掉帧。实测下来天气页面的温度数字跳变动画、以及降雨雷达图的粒子效果在低端鸿蒙设备上会有肉眼可感知的掉帧。对策有两个。轻量方案把 weather_pack 自带的动画关闭改成简单的透明度渐变换场视觉效果差别不大性能提升明显。进阶方案把降雨雷达、风速风向这类基于 CustomPainter 的重型组件换成鸿蒙原生的 Canvas 能力通过平台通道渲染到原生 View 上再嵌入 Flutter 的 Texture 层。这个方案性能最好但开发成本也最高不建议第一次适配就做。另一个是字体渲染问题。鸿蒙的系统字体 HarmonyOS Sans 的中文数字和西文字体在字重、字距上与 Android 上常用的 Roboto 不同。直接使用 weather_pack 默认的排版参数在鸿蒙上会出现部分文字拥挤、温度数值与单位符号间距异常的问题。我的做法是在适配层统一覆盖 TextStyle指定 fontFamily 使用鸿蒙系统字体并针对温度数字单独设置 tabular 特性保证数字等宽。5. 插件通信与组件状态管理的鸿蒙化改造细节5.1 Flutter 组件通信机制在鸿蒙侧的等价实现Flutter 的三方库尤其是 weather_pack 这类需要跟系统能力打交道的库内部通常会拆成多个模块数据模块、UI 模块、工具模块。模块之间通过事件总线、全局状态或继承关系通信。鸿蒙化的过程中最让我头疼的不是 MethodChannel 本身而是 weather_pack 内部模块之间的事件广播。Android 端它用的是 EventChannel 实时推流鸿蒙端 EventChannel 的接口虽然也存在但两边的事件发送频率和线程切换策略有差异偶尔会出现事件丢失。排查下来发现事件丢失主要是因为鸿蒙侧 EventChannel 的 sink 在 UI 线程创建而 Dart 侧监听器注册在后台 isolate。Flutter 引擎在鸿蒙上的线程模型与原版一致但插件注册时机略有差异。解决方法是把 EventChannel 的事件发送全部切到 platform 线程保证 Dart 侧能稳定收到。如果项目里对事件时序有强依赖比如数据加载完成 - 自动滚动到当前小时这类联动建议在 Dart 侧加一层事件缓冲等 UI 组件挂载完成后再消费事件。5.2 用 Provider 构建鸿蒙端的气象数据中心weather_pack 的原始用法是谁需要天气谁自己调接口。这种模式在鸿蒙上非常吃亏因为多个页面各自发请求既浪费流量又容易触发系统频控。我改成了 Provider 单例模式让天气数据在整个应用生命周期内只维护一份。具体结构是这样的class WeatherDataCenter extends ChangeNotifier { WeatherDataCenter._(); static final WeatherDataCenter instance WeatherDataCenter._(); WeatherState _state WeatherState.initial; WeatherState get state _state; ListCityWeather _cityWeatherList []; ListCityWeather get cityWeatherList _cityWeatherList; Futurevoid refreshAll() async { _state WeatherState.loading; notifyListeners(); try { // 并发拉取所有关注城市的数据 _cityWeatherList await Future.wait( _cityIds.map((id) weatherPack.fetchByCityId(id)) ); _state WeatherState.success; } catch (e) { _state WeatherState.error; } notifyListeners(); } }上层组件通过 context.watch () 订阅数据变化。这个方案的直接收益是外卖页面和旅游页面同时显示天气时只发生一次网络请求。更重要的是Provider 的 notifyListeners 机制天然适配鸿蒙的应用生命周期——应用回到前台时只需要调用 refreshAll 判断是否需要刷新所有订阅者会自动收到通知更新 UI不需要每一页单独写生命周期监听。5.3 weather_pack 的城市管理模块改造weather_pack 的城市管理模块支持关注多个城市、上下滑动切换、按拼音搜索。这个模块在鸿蒙化时有两个坑。第一是城市数据的存储位置。天气应用很容易做到用户关注了 20 个城市这些数据如果存在轻量级偏好里每次修改都要整体重写性能很差。我改成了按城市 ID 分 key 存储每个城市的天气数据、关注顺序、是否置顶分开存避免大对象反复序列化。第二是城市搜索的索引构建。weather_pack 自带一份全球城市列表 JSON鸿蒙端直接打包进 HAP 没有任何问题。但如果你的应用内城市列表更新频率高比如新增了小众旅游城市需要做远程配置更新。远程配置下发后先写入沙盒目录再由 Dart 侧加载合并而不是直接替换内置资源。这样做的好处是即使远程配置拉取失败应用依然可以使用内置城市列表兜底。6. 常见问题与排查技巧实录6.1 高频问题速查表问题现象根因分析解决方案应用启动后天气组件空白无任何报错Flutter 引擎加载插件失败weather_pack 依赖的通道未注册检查 ohos 目录下插件是否正确注册到 FlutterPluginRegistry确认插件类名与 Dart 侧调用名一致定位返回城市错误或偶发超时鸿蒙对后台定位管控严格或权限未正确申请确认定位权限仅在前台场景申请使用 500 米精度超时时间放宽到 10 秒超时后切换默认城市天气图标不显示图标资源路径在鸿蒙沙盒中不存在改用 Asset 方式打包图标避免动态写入沙盒或确保写入前先创建目录首次拉取数据慢首页白屏 3 秒以上没有缓存策略所有数据都走网络数据中心层增加先读缓存后拉新策略首页首次展示用缓存数据后台静默刷新从桌面图标进入应用后天气长时间不更新鸿蒙挂起应用后台网络请求Dart 层 Future 无回调前台切换时检查数据新鲜度超过 30 分钟则触发刷新并在刷新时加 Loading 状态提示温度数字在部分设备上显示不全鸿蒙字体渲染宽度与传统字体不同温度数字统一使用等宽数字特性设置明确的字体回退链避免自定义字体未打包导致回退异常多个页面同时请求天气导致内存峰值过高weather_pack 默认每次创建独立数据对象使用 Provider 单例数据中心让所有页面共享同一份天气数据应用在鸿蒙上编译报错找不到某 C 符号DevEco 与 Flutter 引擎分支版本不匹配严格按 flutter_flutter 仓库 README 的版本组合搭建环境不要混用 DevEco 最新版6.2 独家排查心得先抓生命周期再查网络鸿蒙上调试天气类应用最浪费时间的问题是数据加载失败但网络请求明明发成功。我踩过几次坑之后总结出一个经验遇到天气数据不正常时先按这个顺序排查——第一步确认应用是不是在前台。鸿蒙系统一旦把应用切到后台网络请求可能不报错但回调永远不会触发因为线程被挂起。这个现象在 Android 上基本不存在Android 的后台只是降低优先级不会直接冻结线程。鸿蒙的挂起机制更彻底所以天气数据刷新必须放在进入前台的时机。第二步检查权限回调时机。鸿蒙的定位授权弹窗和 Android 不同Android 的授权弹窗是 application 级别的鸿蒙每次冷启动后首次调用定位都会再确认一次。如果你的 weather_pack 适配代码在权限回调之前就发起了定位请求会因为权限未就绪而失败。正确做法是先请求权限回调成功后再调 getCurrentLocation。第三步查看沙盒缓存目录有没有写入权限。鸿蒙对沙盒内子目录的访问有严格限制Preferences 只能写在应用专属目录不能写在随意创建的目录下。如果缓存写入失败weather_pack 的数据持久化逻辑会静默跳过表现就是重启应用后城市列表还在但天气数据全部重新加载。6.3 性能调优低端鸿蒙设备上的天气页优化最后说一个很多人容易忽略的问题鸿蒙设备覆盖面很广从几百元的入门机到旗舰机都有。天气页面往往作为应用首页或常驻模块性能直接影响用户体验。我在适配时做了几件事效果很明显第一把 weather_pack 的逐小时预报列表改成懒加载。默认情况下它会一次性渲染 24 小时的卡片低端设备上切换 tab 的掉帧很严重。改成可视区域预加载 滑动动态构建后帧率稳定很多。这个改动不影响任何数据逻辑只是把 ListView.builder 的构造粒度变细。第二重绘频率控制。天气页面的温度数字变化、空气质量指数变化如果每次刷新都重建整棵树低端设备会吃不消。我用 Selector 按数据块拆分订阅温度变化时只重建温度文本空气质量变化时只重建空气质量组件块。Provider 的 Selector 做这件事非常顺手比全局 notifyListeners 节省大量不必要的 build 开销。第三图标预解码。天气图标如果是网络图低端设备上每次加载都会重新解码造成图片闪烁。适配层里我把天气图标按状态码预解码到内存缓存后续直接走内存位图效果立竿见影。我个人在实际操作中最深的体会是鸿蒙化适配并不是简单的编译通过而是要把原有的插件能力、权限模型、生命周期管理、渲染策略全部按照鸿蒙的设计哲学重新整理一遍。天气这种强依赖系统能力的三方库适配难度比纯 UI 库高一个量级但只要把数据中心、权限链路、缓存策略这三条主线理清楚剩下的都是体力活。最后再分享一个小建议适配过程中尽量保持 Dart 业务层零改动所有鸿蒙特性都隔离在平台通道层这样未来鸿蒙版本迭代时你的适配层可以快速跟随升级不至于被旧代码拖住。