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

超过30%的潜在客户明确要求支持鸿蒙工业平板、智慧屏这些设备里，鸿蒙系统的占比已经到45%了适配鸿蒙还能让我们接触到更多智能制造的场景，比如智慧工厂、工业互联网看来这事必须做了。5月初，我们正式启动了鸿蒙适配项目。回顾这两个多月的适配过程，从一开始的迷茫到最终成功上线，踩了不少坑，但也学到了很多。技术变化太快了，得保持开放心态，新东西来了就去学开源社区真的很有用，openharmony-sig提供

kirk_wang

709人浏览 · 2025-12-25 16:30:18

kirk_wang · 2025-12-25 16:30:18 发布

项目背景

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

应用介绍：

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

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

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

技术选型和适配方案

选型过程

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

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

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

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

适配思路

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

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

具体实现

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：

export default class EntryAbility extends FlutterAbility {
  configureFlutterEngine(flutterEngine: FlutterEngine) {
    super.configureFlutterEngine(flutterEngine)
    GeneratedPluginRegistrant.registerWith(flutterEngine)
    FlutterCallNativeRegistrant.registerWith(flutterEngine)
  }
  
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 处理推送点击
    JpushHarmonySdkPlugin.setClickWant(want, this.context)
    return super.onCreate(want, launchParam)
  }
  
  onWindowStageCreate(windowStage: window.WindowStage): void {
    super.onWindowStageCreate(windowStage);
    // 初始化客服SDK
    ZCSobotApi.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，我们就用条件编译处理。地图功能这块，鸿蒙上显示静态地图，其他平台用交互式地图：

Widget buildMap() {
  if (Platform.isHarmonyOS) {
    return Image.network('https://example.com/static-map.png');
  } else {
    return AMapFlutterMap(/* 地图配置 */);
  }
}

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

踩过的坑

编译构建问题

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

印象最深的是有一次编译死活过不去，报"找不到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%，后面维护也只需要维护一套代码。

指标	原生开发（预期）	Flutter适配（实际）
开发周期	6个月	2个月
代码复用率	0%	约85%
维护成本	双端维护	单端维护

性能表现

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

指标	Android版本	鸿蒙版本	提升
启动时间	2.5s	2.0s	20%
页面切换帧率	58fps	59fps	1.7%
内存占用	180MB	175MB	8.3%
电池消耗	10%/小时	9%/小时	10%

用户反馈

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

个人成长

技术提升

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

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

参与生态建设

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

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

1025HDD.jpg

后续计划

技术方向

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

生态参与

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

总结

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

最大的感受是：

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

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

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

Widget buildMap() {
  if (Platform.isHarmonyOS) {
    return Image.network('https://example.com/static-map.png');
  } else {
    return AMapFlutterMap(/* 地图配置 */);
  }
}