[鸿蒙2025领航者闯关] Flutter项目适配鸿蒙系统的实践与探索

项目背景

锅圈云铺是我们用Flutter开发的B2B订货平台，主要给锅圈食汇的线下门店用，功能包括商品浏览、下单、扫码支付这些。之前只做了Android和iOS版，后来看到鸿蒙用户越来越多，尤其是三四线城市的商家，用鸿蒙手机的越来越多，加上华为有激励金政策，团队决定适配鸿蒙，这个任务就交给了我。

应用介绍：

我们花了两周时间做了市场调研：

• 超过30%的潜在客户明确要求支持鸿蒙
• 工业平板、智慧屏这些设备里，鸿蒙系统的占比已经到45%了
• 适配鸿蒙还能让我们接触到更多智能制造的场景，比如智慧工厂、工业互联网

看来这事必须做了。5月初，我们正式启动了鸿蒙适配项目。

技术选型和适配方案

选型过程

项目启动会上，大家就怎么适配鸿蒙吵了一通。主要就两种思路：

• 用ArkTS重新写一个鸿蒙原生版本
• 基于现有Flutter代码做适配

最后我们选了Flutter适配，原因很简单：

• 成本低，大部分代码可以复用，能省下60%的开发工作量
• 团队熟悉，我们已经做了两年Flutter，不用再招人培训
• 体验一致，用户在哪个平台用起来都一样
• 迭代快，一次开发多端部署，后面加功能也方便

适配思路

方案定了，接下来就是怎么做了。我们按三个层面来：

1. SDK替换：用openharmony-sig的flutter_flutter SDK替换官方Flutter SDK
2. 插件适配：把现有插件换成鸿蒙兼容版本，实在没有的就用条件编译处理
3. 配置调整：改改项目配置，让它能编译打包鸿蒙版本

具体实现

SDK配置

我们用的是openharmony-sig的flutter_flutter SDK（3.7.12-ohos-1.0.4版本），这个SDK已经针对鸿蒙做了优化，我们不用自己去改引擎。

环境配置这块踩了个坑。按文档配置完后，flutter doctor一直报"Flutter与OpenHarmony不兼容"，搞了半天才发现是同时装了官方Flutter SDK，PATH里官方SDK优先级更高。后来改了bash_profile，把openharmony-sig的SDK路径放前面，这才搞定。

插件适配

项目里用了一堆第三方插件，适配时遇到了不少问题。下面挑几个典型的说说：

webview_flutter：官方版本在鸿蒙上完全跑不起来，网页根本加载不出来。我们试了好几个适配分支，最后用了openharmony-tpc提供的版本，注意要用指定的ref分支：

dependency_overrides:webview_flutter:git:url:"https://gitcode.com/openharmony-tpc/flutter_packages.git"path:"packages/webview_flutter/webview_flutter"ref:br_webview_flutter-v4.8.0_ohos

permission_handler：鸿蒙的权限机制跟Android/iOS不一样，得在module.json5里手动声明权限。我们用dependency_overrides替换成openharmony-sig的版本，然后在配置文件里加上需要的权限：

dependency_overrides:permission_handler:git:url:"https://gitcode.com/openharmony-sig/flutter_permission_handler.git"path:"permission_handler"

// ohos/entry/src/main/module.json5 { "module": { "requestPermissions": [ { "name": "ohos.permission.LOCATION", "reason": "用于获取设备位置信息" } ] } }

camera：拍照功能在鸿蒙上也得用适配版本。openharmony-sig提供了兼容版本，直接用就行：

dependency_overrides:camera:git:url:"https://gitcode.com/openharmony-sig/flutter_packages.git"path:"packages/camera/camera"

不过要注意，鸿蒙上使用相机也需要申请权限，记得在module.json5里加上ohos.permission.CAMERA权限声明,前提是在应用市场申请了这个权限。

image_picker：图片选择器适配相对简单，直接用openharmony-sig的版本，基本不用改代码：

dependency_overrides:image_picker:git:url:"https://gitcode.com/openharmony-sig/flutter_packages.git"path:"packages/image_picker/image_picker"

shared_preferences：本地存储这个插件适配得很完善，直接替换就能用，数据格式也是兼容的：

dependency_overrides:shared_preferences:git:url:"https://gitcode.com/openharmony-sig/flutter_packages.git"path:"packages/shared_preferences/shared_preferences"

device_info_plus：获取设备信息的插件，openharmony-sig版本提供了鸿蒙设备的详细信息，比如HarmonyOS版本号、设备型号等：

dependency_overrides:device_info_plus:git:url:"https://gitcode.com/openharmony-sig/flutter_plus_plugins.git"path:"packages/device_info_plus/device_info_plus"

scan：扫码功能我我一开始用的是开源库中适配的版本，但是发现有BUG，然后自己copy了一套代码把BUG修复然后使用了自己修复好的：

dependency_overrides:scan:git:url:"https://gitcode.com/nutpi/fluttertpc_scan.git"

jpush_harmony_sdk：极光推送有官方提供的鸿蒙SDK，需要同时配置Flutter插件和原生依赖。在pubspec.yaml里添加：

dependencies:jpush_harmony_sdk:git:url:"https://github.com/jpush/jpush-harmony-flutter-plugin.git"

然后在ohos/oh-package.json5里也要配置对应的HAR包依赖。

package_info_plus：获取应用包信息的插件，这个适配也很简单：

dependency_overrides:package_info_plus:git:url:"https://gitcode.com/openharmony-sig/flutter_plus_plugins.git"path:"packages/package_info_plus/package_info_plus"

总的来说，大部分常用插件openharmony-sig都有适配版本，直接用dependency_overrides替换就行。少数没有适配的，要么用条件编译做兼容，要么找社区提供的替代方案。

鸿蒙端配置

Flutter侧改完了，鸿蒙端也得配置。我是在项目根目录建了个ohos文件夹，里面放鸿蒙的原生代码和配置。

项目结构

ohos目录下主要有这些：

• entry/ - 入口模块，放ArkTS代码
• har/ - Flutter插件编译生成的HAR包放这
• build-profile.json5 - 构建和签名配置
• oh-package.json5 - 鸿蒙依赖管理，类似Android的gradle

module.json5配置

这个文件最重要，权限、Ability、设备类型啥的都得在这配。我们项目的配置大概这样：

{ "module": { "name": "entry", "type": "entry", "deviceTypes": ["phone"], "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "exported": true }, { "name": "PushMessageAbility", "srcEntry": "./ets/entryability/PushMessageAbility.ets", "skills": [ { "actions": ["action.ohos.push.listener"] } ] } ], "requestPermissions": [ { "name": "ohos.permission.LOCATION", "reason": "用于获取设备位置信息" }, { "name": "ohos.permission.INTERNET" } ] } }

权限这块踩过坑。有些权限是system_basic级别的，普通应用申请不了，比如ohos.permission.INSTALL_BUNDLE。我们一开始没注意，配了才发现不行，只能去掉。

签名配置

签名在build-profile.json5里配，Debug和Release两套都要配。我们刚开始只配了Debug，后来要打包Release才发现还得再配一套。

SDK版本也要注意，compatibleSdkVersion和targetSdkVersion得根据实际情况设置。我们用的是API 17到20，兼容性还算好。

HAR包配置

Flutter插件编译后会生成HAR包，得在oh-package.json5里把依赖配上。我们项目用了不少插件，HAR包一堆：

{ "dependencies": { "@ohos/flutter_ohos": "file:./har/flutter.har", "webview_flutter_ohos": "file:./har/webview_flutter_ohos.har", "permission_handler_ohos": "file:./har/permission_handler_ohos.har", "camera_ohos": "file:./har/camera_ohos.har", "jpush_harmony_sdk": "file:./har/jpush_harmony_sdk.har" } }

每个插件都得手动加，有点麻烦，但没办法。

EntryAbility定制

如果需要初始化第三方SDK或者注册自定义插件，得在EntryAbility.ets里处理。我们项目里初始化了极光推送和客服SDK：

exportdefaultclassEntryAbilityextendsFlutterAbility{configureFlutterEngine(flutterEngine:FlutterEngine){super.configureFlutterEngine(flutterEngine)GeneratedPluginRegistrant.registerWith(flutterEngine)FlutterCallNativeRegistrant.registerWith(flutterEngine)}onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{// 处理推送点击JpushHarmonySdkPlugin.setClickWant(want,this.context)returnsuper.onCreate(want,launchParam)}onWindowStageCreate(windowStage:window.WindowStage):void{super.onWindowStageCreate(windowStage);// 初始化客服SDKZCSobotApi.init(this.context,windowStage)}}

推送这块要注意，onCreate和onNewWant里都得处理推送点击事件，不然推送点不开。

推送配置

推送功能配置比较特殊，除了配PushMessageAbility，还得在module.json5里加proxyData配置。我们也是查了文档才知道要配这个：

{ "module": { "proxyData": [ { "uri": "datashareproxy://com.gqsh.yunpu/PushMessage", "requiredWritePermission": "ohos.permission.WRITE_PRIVACY_PUSH_DATA" } ] } }

PushMessageAbility得单独实现，用来处理后台推送消息。这个Ability不会显示界面，就是专门处理推送的。

资源文件

字体、图片这些资源会被自动打包，鸿蒙端从rawfile/flutter_assets目录读取。我们项目里的自定义字体都能正常显示，没遇到啥问题。

编译打包

编译流程基本固定，但有几个地方要注意：

• DevEco Studio版本和SDK版本要匹配，不然编译会报错
• HAR包要放到har目录下，路径别搞错了
• 打包Release的时候记得用Release签名

整体来说，鸿蒙端的配置比Android复杂一点，但熟悉了流程也还好。

条件编译处理

有些插件没有鸿蒙版本，比如amap_flutter_map，我们就用条件编译处理。地图功能这块，鸿蒙上显示静态地图，其他平台用交互式地图：

WidgetbuildMap(){if(Platform.isHarmonyOS){returnImage.network('https://example.com/static-map.png');}else{returnAMapFlutterMap(/* 地图配置 */);}}

虽然功能上做了妥协，但至少能用，不影响主要业务流程。

踩过的坑

编译构建问题

刚开始适配那会儿，编译这块最头疼。各种报错，依赖冲突、版本不匹配啥的，每天都能遇到新问题。

印象最深的是有一次编译死活过不去，报"找不到hvigor命令"。查了半天资料，最后发现是DevEco Studio 4.0跟鸿蒙SDK API 12不兼容。升级到5.0后问题解决了，但之前卡了快两天。

性能优化

适配完第一次在鸿蒙设备上跑，发现加载数据的时候特别卡，体验很不好。

我们做了几轮优化：

• 图片加载优化，加了缓存机制，减少内存占用
• 动画帧率从60fps调到50fps，适配鸿蒙的渲染机制
• 优化网络请求，去掉不必要的传输
• 用了些鸿蒙系统提供的性能优化API

效果还挺明显的，启动时间从2.5s降到2.0s，页面切换能稳定在59fps，内存占用也降了8.3%。

权限管理

鸿蒙的权限机制跟Android/iOS不太一样，刚开始申请权限老是失败。位置权限这块最明显，鸿蒙里需要单独处理，但我们一开始用的是统一的逻辑。后来单独给鸿蒙写了套权限申请代码，这才正常。

适配成果

开发效率

我们花了2个月完成了适配，如果用原生开发的话估计得6个月。代码复用率大概85%，后面维护也只需要维护一套代码。

性能表现

性能这块还挺让人意外的，鸿蒙版本居然比Android版本还好一点：

用户反馈

6月中旬应用上架华为应用市场，拿到了优质推荐。首月下载量500多，评分4.8。

个人成长

技术提升

这次适配对我来说是个很好的学习机会。以前只做Flutter，现在对跨平台适配有了更深的理解：

1. 理解了Flutter引擎跟不同系统是怎么交互的，特别是跟鸿蒙的通信机制
2. 学了不少鸿蒙的核心特性，比如分布式能力、方舟编译器、Ability框架这些
3. 学会了怎么设计可扩展的适配架构，支持多平台
4. 积累了跨平台开发的问题定位经验，遇到问题知道从哪入手了

参与生态建设

2025年我们也在鸿蒙生态里做了不少事情：

1. 应用上架：6月份"锅圈云铺"成功上架华为应用市场，首月下载量500多
2. 参加创新大赛：虽然没有获奖，但是很有意义
3. 加入激励计划：入选了华为开发者联盟的"鸿蒙应用激励计划"，拿到了资源支持
4. 社区分享：在鸿蒙开发者社区发了15篇技术文章，阅读量5万+，回答了一百多个技术问题
5. 技术分享：在公司内部和行业会议做了3次分享，累计参与人数300+
6. 组织参加了多长HDD赋能交流会活动

1025HDD.jpg

后续计划

技术方向

1. 分布式能力：深挖鸿蒙的分布式能力，做更复杂的跨设备协同功能
2. 性能优化：用上鸿蒙的新特性，比如方舟编译器、渲染引擎优化这些，把性能再提升一下
3. 架构优化：重构适配架构，让多端适配更灵活，降低后续成本
4. AI能力：结合鸿蒙的AI能力，做一些智能化功能，比如设备诊断、预测性维护
5. 插件贡献：给openharmony-sig贡献更多鸿蒙兼容插件，回馈社区

生态参与

1. 继续参与鸿蒙生态建设，多参加官方活动和社区讨论
2. 推动行业标准制定，把我们的实践经验总结成最佳实践
3. 培养团队能力，让更多人掌握跨平台适配
4. 探索新场景，基于鸿蒙特性找新的业务增长点，比如智慧工厂、智能物流

总结

回顾这两个多月的适配过程，从一开始的迷茫到最终成功上线，踩了不少坑，但也学到了很多。

最大的感受是：

1. 技术变化太快了，得保持开放心态，新东西来了就去学
2. 开源社区真的很有用，openharmony-sig提供的SDK和插件帮了大忙
3. 团队协作很重要，很多问题都是大家一起讨论才解决的
4. 持续学习是必须的，技术迭代太快，不学习就落后了

接下来我们还会继续在鸿蒙生态里深耕，探索"鸿蒙+行业"的各种可能性。

最后想对正在或者准备做Flutter鸿蒙适配的开发者说：别怕踩坑，大胆去做。当你看到自己的应用在鸿蒙设备上跑起来的时候，那种成就感真的很棒！

WidgetbuildMap(){if(Platform.isHarmonyOS){returnImage.network('https://example.com/static-map.png');}else{returnAMapFlutterMap(/* 地图配置 */);}}

虽然功能上做了妥协，但至少能用，不影响主要业务流程。

踩过的坑

编译构建问题

刚开始适配那会儿，编译这块最头疼。各种报错，依赖冲突、版本不匹配啥的，每天都能遇到新问题。

印象最深的是有一次编译死活过不去，报"找不到hvigor命令"。查了半天资料，最后发现是DevEco Studio 4.0跟鸿蒙SDK API 12不兼容。升级到5.0后问题解决了，但之前卡了快两天。

性能优化

适配完第一次在鸿蒙设备上跑，发现加载数据的时候特别卡，体验很不好。

我们做了几轮优化：

• 图片加载优化，加了缓存机制，减少内存占用
• 动画帧率从60fps调到50fps，适配鸿蒙的渲染机制
• 优化网络请求，去掉不必要的传输
• 用了些鸿蒙系统提供的性能优化API

效果还挺明显的，启动时间从2.5s降到2.0s，页面切换能稳定在59fps，内存占用也降了8.3%。

权限管理

鸿蒙的权限机制跟Android/iOS不太一样，刚开始申请权限老是失败。位置权限这块最明显，鸿蒙里需要单独处理，但我们一开始用的是统一的逻辑。后来单独给鸿蒙写了套权限申请代码，这才正常。

适配成果

开发效率

我们花了2个月完成了适配，如果用原生开发的话估计得6个月。代码复用率大概85%，后面维护也只需要维护一套代码。

性能表现

性能这块还挺让人意外的，鸿蒙版本居然比Android版本还好一点：

用户反馈

6月中旬应用上架华为应用市场，拿到了优质推荐。首月下载量500多，评分4.8。

个人成长

技术提升

这次适配对我来说是个很好的学习机会。以前只做Flutter，现在对跨平台适配有了更深的理解：

1. 理解了Flutter引擎跟不同系统是怎么交互的，特别是跟鸿蒙的通信机制
2. 学了不少鸿蒙的核心特性，比如分布式能力、方舟编译器、Ability框架这些
3. 学会了怎么设计可扩展的适配架构，支持多平台
4. 积累了跨平台开发的问题定位经验，遇到问题知道从哪入手了

参与生态建设

2025年我们也在鸿蒙生态里做了不少事情：

1. 应用上架：6月份"锅圈云铺"成功上架华为应用市场，首月下载量500多
2. 参加创新大赛：虽然没有获奖，但是很有意义
3. 加入激励计划：入选了华为开发者联盟的"鸿蒙应用激励计划"，拿到了资源支持
4. 社区分享：在鸿蒙开发者社区发了15篇技术文章，阅读量5万+，回答了一百多个技术问题
5. 技术分享：在公司内部和行业会议做了3次分享，累计参与人数300+
6. 组织参加了多场HDD赋能交流会活动

1025HDD.jpg

后续计划

技术方向

1. 分布式能力：深挖鸿蒙的分布式能力，做更复杂的跨设备协同功能
2. 性能优化：用上鸿蒙的新特性，比如方舟编译器、渲染引擎优化这些，把性能再提升一下
3. 架构优化：重构适配架构，让多端适配更灵活，降低后续成本
4. AI能力：结合鸿蒙的AI能力，做一些智能化功能，比如设备诊断、预测性维护
5. 插件贡献：给openharmony-sig贡献更多鸿蒙兼容插件，回馈社区

生态参与

1. 继续参与鸿蒙生态建设，多参加官方活动和社区讨论
2. 推动行业标准制定，把我们的实践经验总结成最佳实践
3. 培养团队能力，让更多人掌握跨平台适配，自己也会多多组织HDG活动赋能开发者
4. 探索新场景，基于鸿蒙特性找新的业务增长点，比如智慧工厂、智能物流

总结

回顾近半年的学习之路和适配过程，从一开始的迷茫到最终成功上线，踩了不少坑，但也学到了很多。

最大的感受是：

1. 技术变化太快了，得保持开放心态，新东西来了就去学
2. 开源社区真的很有用，openharmony-sig提供的SDK和插件帮了大忙
3. 团队协作很重要，很多问题都是大家一起讨论才解决的
4. 持续学习是必须的，技术迭代太快，不学习就落后了

接下来我们还会继续在鸿蒙生态里深耕，探索"鸿蒙+行业"的各种可能性。

最后想对正在或者准备做Flutter鸿蒙适配的开发者说：别怕踩坑，大胆去做。当你看到自己的应用在鸿蒙设备上跑起来的时候，那种成就感真的很棒！