已有 Flutter 项目改造支持鸿蒙

木子雨廷
19 阅读25分钟

前言：

  • 最近在项目里做了一版 Flutter 项目兼容鸿蒙的改造。一开始以为只是把 android、ios 之外再生成一个 ohos 目录，然后跑一下命令就可以了。真正做下来才发现，Flutter 兼容鸿蒙不是简单多一个平台目录，也不是把原来的 Flutter 代码原封不动丢给鸿蒙工具链就能跑起来。
  • 对一个已经按 Android、iOS 思路开发完成的 Flutter App 来说，鸿蒙兼容最核心的问题其实是：Dart 层业务逻辑要尽量复用，原有页面体验要保持，三方插件、系统权限、构建工具、签名配置和真机调试链路还要逐个打通。
  • 这篇文章就结合当前这个 Demo，聊一聊在 Flutter 项目里如何做鸿蒙兼容。文章不单独讲某一个命令，而是从项目落地角度说清楚：前期需要准备什么电脑环境、Flutter SDK 该怎么选、DevEco Studio 如何配置、项目如何生成 ohos 工程、插件如何替换、权限如何处理、构建过程中遇到了哪些问题，以及后续继续做鸿蒙兼容时建议遵守的一些标准。

正文：

这个 Demo 的鸿蒙兼容，主要从下面几个维度来理解：

  1. Flutter 兼容鸿蒙的整体思路
  2. 前期需要准备哪些环境
  3. 电脑系统和开发工具如何选择
  4. Flutter SDK 应该使用哪一类版本
  5. 如何给已有 Flutter 项目生成 ohos 工程
  6. 鸿蒙工程目录里哪些文件最关键
  7. 三方插件如何处理
  8. 权限、签名和真机运行如何配置
  9. 改造过程中遇到的问题和坑
  10. 后续继续完善鸿蒙兼容时的建议
  • Flutter 兼容鸿蒙的基本思想

普通 Flutter 项目通常只关注几类平台：

  • Android
  • iOS
  • Web
  • macOS / Windows / Linux

业务代码写在 lib 目录里，平台工程分别放在：

android/
ios/
web/
macos/
windows/
linux/

鸿蒙兼容后，项目里会新增一个平台目录：

ohos/

可以把它理解成 Flutter 项目里的另一个平台工程。

也就是说：

  • lib 目录里的 Dart 页面、路由、状态管理、网络请求逻辑尽量复用
  • ohos 目录负责承载 HarmonyOS 侧的 Ability、权限、签名、资源和构建配置
  • 纯 Dart 依赖通常可以直接继续使用
  • 涉及原生能力的插件需要确认是否支持 ohos
  • Android 原生代码和 iOS 原生代码不能直接在鸿蒙侧复用

所以 Flutter 兼容鸿蒙，不是把 App 重写一遍，而是把原来的 Flutter App 多接入一个 HarmonyOS 平台出口。

可以把它理解成：

  • Flutter Dart 层：尽量不动
  • 平台工程层：新增 ohos
  • 插件层：逐个确认是否有鸿蒙实现
  • 系统能力层：按鸿蒙权限和 API 重新接入
  • 构建发布层：使用 DevEco Studio、Hvigor、HarmonyOS 签名体系

当前 Demo 的核心目标就是：

  • 保留原来的 Flutter 页面

  • 保留原来的 Fluro 路由

  • 保留原来的网络、列表、详情页逻辑

  • 给项目补齐鸿蒙平台工程

  • 替换不支持鸿蒙的平台插件

  • 能在鸿蒙模拟器或真机上正常构建、安装和运行

  • 前期需要做的准备工作

做 Flutter 鸿蒙兼容之前，不建议一上来就改代码。

更推荐先把环境、SDK、项目依赖和设备链路准备好。

前期需要确认的内容主要有：

  • 当前电脑系统是否支持 DevEco Studio 和鸿蒙工具链
  • Flutter SDK 是否是支持 ohos 的版本
  • Dart SDK 版本是否满足项目 pubspec.yaml
  • DevEco Studio 是否安装完整
  • HarmonyOS SDK 是否下载完整
  • Node.js、ohpm、hvigor 是否可用
  • 是否准备了鸿蒙模拟器或真机
  • 项目里使用了哪些三方插件
  • 哪些插件已经支持 ohos
  • 哪些插件需要替换成本地鸿蒙适配包
  • 是否需要网络、存储、相册、相机、定位等权限
  • 是否配置了调试签名

这个阶段非常重要。

因为很多鸿蒙兼容问题并不是 Dart 代码写错，而是环境不完整、SDK 版本不匹配、插件没有鸿蒙实现、签名没有配置好。

如果这些基础没理顺，后面很容易出现：

Unknown platform ohos
Unable to find flutter-hvigor-plugin
ohpm install failed
hvigor build failed
No implementation found for method
INSTALL_FAILED
module.json5 permission error

这些问题看起来都像构建报错，但根因可能完全不同。

  • 电脑环境准备

当前比较推荐使用 macOS 或 Windows 做鸿蒙 Flutter 开发。

如果是 macOS，建议：

macOS 12 及以上
Apple Silicon 或 Intel 均可
内存建议 16GB 及以上
磁盘至少预留 30GB 以上空间

如果是 Windows，建议：

Windows 10 / Windows 11 64 位
内存建议 16GB 及以上
磁盘至少预留 30GB 以上空间

为什么要预留比较多空间？

因为鸿蒙开发会同时依赖：

  • DevEco Studio
  • HarmonyOS SDK
  • Flutter SDK
  • Dart SDK
  • ohpm 缓存
  • hvigor 缓存
  • 模拟器镜像
  • 项目的 build 产物

这些内容加起来会比较大。

尤其是第一次构建时，ohos/oh_modules、.hvigor、build 等目录会生成很多缓存文件。

  • DevEco Studio 准备

Flutter 项目兼容鸿蒙，需要安装 DevEco Studio。

建议选择和项目目标 HarmonyOS SDK 匹配的版本。

当前 Demo 的鸿蒙工程里可以看到：

"compatibleSdkVersion": "5.1.0(18)",
"runtimeOS": "HarmonyOS"

所以这里建议安装支持 HarmonyOS 5.1 SDK 的 DevEco Studio 版本。

安装 DevEco Studio 后，需要在 SDK Manager 里确认这些内容：

HarmonyOS SDK
OpenHarmony SDK
ArkTS
Toolchains
Previewer
Emulator
Hvigor
ohpm

其中比较关键的是：

  • Toolchains：提供鸿蒙侧编译、打包、签名等基础能力
  • ohpm：鸿蒙包管理工具，用于安装 ohos 工程依赖
  • Hvigor：鸿蒙工程构建工具，类似 Android 里的 Gradle
  • Emulator：用于本地模拟器调试

安装完成后，可以在终端确认工具是否可用：

ohpm -v
hvigor -v

如果命令找不到，通常说明 DevEco Studio 的工具链路径没有加入环境变量。

可以在 DevEco Studio 里查看 SDK 安装路径，然后把对应的 toolchains、ohpm、hvigor 路径加入 PATH。

  • Flutter SDK 准备

这是鸿蒙兼容里最容易踩坑的地方。

普通 Flutter 官方 SDK 默认支持 Android、iOS、Web、桌面平台，但不一定直接支持 ohos。

做鸿蒙兼容时，需要使用支持 HarmonyOS / OpenHarmony 的 Flutter SDK。

通常有两种做法：

  • 使用已经适配鸿蒙的 Flutter SDK 分支
  • 使用厂商或社区提供的 Flutter 鸿蒙 SDK 包

这类 SDK 的特点是：

  • flutter devices 能识别鸿蒙设备
  • flutter create 支持生成 ohos 平台目录
  • Flutter engine 包含鸿蒙侧运行能力
  • 工程里会生成 ohos 目录
  • ohos/hvigorfile.ts 会接入 flutter-hvigor-plugin

当前 Demo 的 .metadata 里已经记录了 ohos 平台：

migration:
  platforms:
    - platform: root
    - platform: ohos

这说明项目已经不是普通 Flutter 官方模板，而是生成过鸿蒙平台工程。

选择 Flutter SDK 时要重点看两点。

第一点是项目 Dart SDK 版本。

当前 Demo 的 pubspec.yaml 中写的是：

environment:
  sdk: ">=3.9.0 <4.0.0"

这代表项目依赖的 Dart SDK 需要大于等于 3.9.0。

所以本地 Flutter SDK 自带的 Dart 版本也要满足这个范围。否则执行：

flutter pub get

时可能会出现类似错误：

The current Dart SDK version is x.x.x.
Because bili_caricature requires SDK version >=3.9.0 <4.0.0, version solving failed.

第二点是 Flutter SDK 是否支持 ohos。

可以执行：

flutter doctor -v
flutter devices
flutter create --help

如果 SDK 支持鸿蒙，通常可以看到 ohos 相关平台能力。

如果执行鸿蒙相关命令时提示不认识 ohos，说明当前 SDK 不是鸿蒙适配版。

这里不要用普通 Flutter SDK 硬跑。

因为即使 Dart 层能 pub get，后续也会卡在：

  • 不能生成 ohos 目录

  • 不能构建 HAP

  • 不能识别鸿蒙设备

  • 找不到 flutter-hvigor-plugin

  • 找不到鸿蒙 engine 产物

  • 建议的环境版本组合

实际项目里，建议把环境版本固定下来，不要每个人各装各的。

可以在团队文档里明确写清楚：

DevEco Studio：支持 HarmonyOS 5.1 SDK 的版本
HarmonyOS SDK：5.1.0(18)
Flutter SDK：支持 ohos 的 Flutter SDK，且 Dart >= 3.9.0
Dart SDK：>= 3.9.0 < 4.0.0
Node.js：建议使用 LTS 版本
ohpm：使用 DevEco Studio 随 SDK 安装的版本
Hvigor：使用 DevEco Studio 随 SDK 安装的版本

为什么不建议混用版本？

因为鸿蒙 Flutter 工程同时依赖 Flutter 工具链和 HarmonyOS 工具链。

Flutter SDK 太旧，可能不支持当前 Dart 语法和依赖版本。

DevEco Studio 太旧，可能不支持当前 compatibleSdkVersion。

ohpm 或 Hvigor 版本不匹配，可能导致 ohos 工程依赖安装失败。

所以做鸿蒙兼容时，最好先确定一套能稳定构建的版本组合，然后团队统一。

  • 当前项目使用到的关键能力

当前 Demo 没有把 Flutter 项目重写成 ArkTS，而是继续保留 Flutter 技术栈。

项目里用到的主要能力有：

Flutter
Dart
HarmonyOS SDK
DevEco Studio
Hvigor
ohpm
flutter-hvigor-plugin
本地 ohos 插件适配包

当前项目的 pubspec.yaml 里可以看到：

dependencies:
  flutter:
    sdk: flutter
  flutter_screenutil: ^5.9.3
  fluro: ^2.0.5
  dio: ^5.9.2
  webview_flutter: ^4.13.1
  shared_preferences:
    path: packages/flutter_packages_ohos/packages/shared_preferences/shared_preferences

这里可以分成两类。

第一类是纯 Dart 或 Flutter UI 层依赖，比如：

  • flutter_screenutil
  • fluro
  • dio
  • easy_refresh
  • signals_flutter
  • collection
  • uuid

这些依赖大多不直接调用 Android 或 iOS 原生能力，兼容鸿蒙的成本相对低。

第二类是平台插件，比如：

  • shared_preferences
  • webview_flutter
  • 相机插件
  • 相册插件
  • 定位插件
  • 权限插件
  • 文件选择插件
  • 支付、分享、推送类插件

这类依赖必须确认是否有 ohos 实现。

当前 Demo 已经把 shared_preferences 改成本地鸿蒙适配包：

shared_preferences:
  path: packages/flutter_packages_ohos/packages/shared_preferences/shared_preferences

并且本地插件里声明了 ohos 平台：

flutter:
  plugin:
    implements: shared_preferences
    platforms:
      ohos:
        package: io.flutter.plugins.sharedpreferences
        pluginClass: SharedPreferencesPlugin
        dartPluginClass: SharedPreferencesOhos

这一步非常关键。

如果继续使用只支持 Android、iOS 的插件版本，Dart 代码可能可以编译，但运行到插件调用时会报：

MissingPluginException
No implementation found for method xxx
  • 如何给已有 Flutter 项目生成 ohos 工程

对于已有 Flutter 项目，通常不是新建项目，而是在原项目基础上补齐鸿蒙平台目录。

大致流程是：

flutter clean
flutter pub get
flutter create --platforms ohos .

不同鸿蒙 Flutter SDK 的命令可能略有差异，有些 SDK 使用的是：

flutter create .

或者提供单独的鸿蒙平台生成命令。

最终目标是让项目根目录出现：

ohos/

生成后，项目结构大致会变成：

lib/
android/
ios/
ohos/
assets/
packages/
pubspec.yaml

当前 Demo 里已经存在 ohos 目录，说明这一步已经完成。

生成 ohos 后，建议先不要急着改业务代码，而是先跑通最小链路：

flutter pub get
cd ohos
ohpm install
cd ..
flutter run -d <鸿蒙设备>

如果使用 DevEco Studio，也可以直接打开 ohos 目录，先让它同步工程依赖，然后再运行。

  • 鸿蒙工程目录里哪些文件最关键

ohos 目录生成后，不需要每个文件都看。

早期重点关注这些文件就够了：

ohos/build-profile.json5
ohos/oh-package.json5
ohos/hvigorfile.ts
ohos/entry/src/main/module.json5
ohos/entry/hvigorfile.ts

ohos/build-profile.json5 主要负责产品、签名、SDK 版本和模块配置。

当前 Demo 里比较关键的是：

"compatibleSdkVersion": "5.1.0(18)",
"runtimeOS": "HarmonyOS"

这表示项目按 HarmonyOS 5.1 目标 SDK 构建。

ohos/oh-package.json5 是鸿蒙工程包配置。

当前 Demo 中类似这样：

{
  "modelVersion": "5.1.0",
  "name": "bili_caricature",
  "version": "1.0.0"
}

ohos/hvigorfile.ts 是构建入口。

当前 Demo 中可以看到：

import path from 'path'
import { appTasks } from '@ohos/hvigor-ohos-plugin';
import { flutterHvigorPlugin } from 'flutter-hvigor-plugin';

export default {
    system: appTasks,
    plugins:[flutterHvigorPlugin(path.dirname(__dirname))]
}

这里最关键的是：

flutterHvigorPlugin(path.dirname(__dirname))

它把 Flutter 工程和鸿蒙 Hvigor 构建串起来。

如果这个插件缺失，鸿蒙工程可能只认识自己的 ArkTS 模块，不知道如何处理 Flutter 产物。

ohos/entry/src/main/module.json5 是入口模块配置。

当前 Demo 里声明了入口 Ability 和网络权限：

"abilities": [
  {
    "name": "EntryAbility",
    "srcEntry": "./ets/entryability/EntryAbility.ets",
    "exported": true
  }
],
"requestPermissions": [
  {"name" :  "ohos.permission.INTERNET"}
]

因为项目里使用了 dio 请求网络，所以 INTERNET 权限必须配置。

如果没有这个权限，页面代码可能没有问题，但网络请求会失败。

  • 权限配置要按鸿蒙重新梳理

Android 里常见的权限配置在：

android/app/src/main/AndroidManifest.xml

iOS 里常见的权限配置在：

ios/Runner/Info.plist

鸿蒙里则需要关注：

ohos/entry/src/main/module.json5

例如网络权限：

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  }
]

如果后续项目使用相册、相机、定位、麦克风、文件访问等能力，也要在鸿蒙侧补对应权限。

这里不能想当然地认为 Android 配过了，鸿蒙就自动有了。

每个平台都有自己的权限声明体系。

迁移时建议做一张表：

业务能力        Android 权限        iOS 权限描述        HarmonyOS 权限
网络请求        INTERNET          无或 ATS 配置        ohos.permission.INTERNET
相机            CAMERA            NSCameraUsage...    对应相机权限
相册            READ_MEDIA...      NSPhotoLibrary...   对应媒体读取权限
定位            ACCESS_FINE...     NSLocation...       对应定位权限
麦克风          RECORD_AUDIO       NSMicrophone...     对应麦克风权限

这样可以避免运行时才发现某个平台缺权限。

  • 签名配置和真机运行

鸿蒙真机运行通常需要签名。

DevEco Studio 可以帮助生成默认调试签名。

当前 Demo 的 build-profile.json5 里已经有签名配置，类似：

"signingConfigs": [
  {
    "name": "default",
    "type": "HarmonyOS",
    "material": {
      "certpath": "...",
      "keyAlias": "debugKey",
      "profile": "...",
      "storeFile": "..."
    }
  }
]

这里要注意一点：

签名文件路径、证书、Profile、密码属于本机开发环境配置，不建议随便提交到公共仓库。

团队协作时可以采用两种方式：

  • 调试签名由每个开发者本机生成
  • 发布签名由 CI 或专门负责人统一管理

如果签名配置不正确，可能会遇到：

Failed to sign the hap
Profile does not match device
Install failed
No valid signing config

这类问题不是 Flutter 页面问题，而是鸿蒙工程签名链路问题。

  • 插件兼容是改造重点

Flutter 兼容鸿蒙最容易出问题的地方不是普通 Widget，而是插件。

纯 Dart 代码通常比较好处理。

比如：

dio
fluro
collection
uuid
signals_flutter

这些依赖主要运行在 Dart 层，不强依赖某个平台的原生代码。

但平台插件不同。

例如：

shared_preferences
webview_flutter
path_provider
image_picker
permission_handler
url_launcher
camera
video_player
connectivity_plus
device_info_plus
package_info_plus

这些插件通常需要 Android、iOS、Web、macOS 等平台分别实现。

兼容鸿蒙时，必须确认它是否包含：

platforms:
  ohos:

如果没有，就要选择：

  • 找社区已有的鸿蒙适配版本
  • 把插件替换成本地 path 依赖
  • 自己补一个 ohos 平台实现
  • 暂时屏蔽这部分能力
  • 用 Dart 层方案替代

当前 Demo 对 shared_preferences 的处理方式就是本地路径替换：

shared_preferences:
  path: packages/flutter_packages_ohos/packages/shared_preferences/shared_preferences

这种方式的好处是：

  • 项目可以明确使用支持鸿蒙的平台实现
  • 不受 pub.dev 原始版本是否支持鸿蒙影响
  • 后续如果要改插件源码，可以直接在本地调试

但它也有成本：

  • 插件版本需要自己维护
  • 后续升级 Flutter SDK 时要重新验证
  • 多人协作时要保证本地路径包一起提交
  • 依赖树可能和官方包有差异

所以建议先从项目实际使用的插件清单开始排查。

可以执行：

flutter pub deps

然后把依赖分成三类：

  • 纯 Dart 依赖
  • Flutter UI 依赖
  • 平台插件依赖

优先处理平台插件。

  • 当前项目的改造链路总结

当前 Demo 的鸿蒙兼容链路大致是：

  • 项目根目录保留原有 Flutter 结构
  • 使用支持 ohos 的 Flutter SDK
  • 通过 Flutter 工具生成 ohos 平台工程
  • ohos/build-profile.json5 配置 HarmonyOS SDK 和签名
  • ohos/hvigorfile.ts 接入 flutter-hvigor-plugin
  • ohos/entry/src/main/module.json5 配置入口 Ability 和网络权限
  • pubspec.yaml 中把 shared_preferences 切成本地鸿蒙适配版本
  • 原有 lib 下的页面、路由、网络请求、列表和详情逻辑继续复用
  • 最后通过 DevEco Studio 或 Flutter 命令运行到鸿蒙设备

这套方案的核心是：

Flutter 业务层尽量少改，平台差异集中在 ohos 工程和插件层处理。

业务页面仍然写：

NavigatorUtils.push(context, path, arguments: arguments);

网络请求仍然走：

dio.get(...)

本地缓存仍然走：

SharedPreferences.getInstance()

至于这些能力在鸿蒙侧如何落地，由平台工程、插件和权限配置共同完成。

  • 改造过程中遇到的问题和坑
  • 问题1：普通 Flutter SDK 不认识 ohos

一开始最容易犯的错误是直接使用原来的 Flutter SDK。

执行命令时可能会看到：

Unknown platform ohos

或者生成项目时没有 ohos 目录。

原因是普通 Flutter SDK 不一定包含鸿蒙平台支持。

解决方式是换成支持 HarmonyOS / OpenHarmony 的 Flutter SDK，然后重新执行：

flutter doctor -v
flutter pub get
flutter create --platforms ohos .

这里要注意，换 SDK 后不要只看 flutter --version，还要确认：

flutter devices
flutter doctor -v

能不能识别鸿蒙设备和鸿蒙工具链。

  • 问题2：Dart SDK 版本和项目约束不一致

当前项目的 pubspec.yaml 要求：

sdk: ">=3.9.0 <4.0.0"

如果本地 Flutter SDK 自带的 Dart 版本低于 3.9.0，flutter pub get 会直接失败。

这类问题不能靠改依赖版本硬绕过去。

更合理的做法是：

  • 确认项目实际需要的 Dart 版本
  • 使用匹配的 Flutter 鸿蒙 SDK
  • 团队统一 SDK 版本
  • 必要时降低项目语法和依赖约束，但要充分测试

否则可能出现开发 A 能跑，开发 B 不能跑，CI 也不能跑的情况。

  • 问题3：插件没有鸿蒙实现

这是最常见的问题。

比如原来 Android、iOS 都能正常用的插件，到了鸿蒙后可能报：

MissingPluginException
No implementation found for method xxx

这说明 Dart 层调用到了插件通道，但鸿蒙侧没有对应实现。

当前 Demo 中 shared_preferences 就需要替换为支持 ohos 的版本：

shared_preferences:
  path: packages/flutter_packages_ohos/packages/shared_preferences/shared_preferences

处理插件时建议按下面顺序排查：

  1. 先看插件是否官方支持 ohos
  2. 再看社区是否有鸿蒙适配版本
  3. 如果能力简单，可以自己补 ohos 实现
  4. 如果能力暂时不关键，可以先在鸿蒙侧降级或关闭
  5. 如果是核心能力，必须安排专项适配和测试

不要等所有页面都跑起来后再回头处理插件。

插件问题越早排查越好。

  • 问题4：鸿蒙权限没有配置

项目里使用 dio 做网络请求。

Android 里只要 AndroidManifest.xml 有网络权限即可。

但鸿蒙侧必须在：

ohos/entry/src/main/module.json5

中声明：

"requestPermissions": [
  {"name" :  "ohos.permission.INTERNET"}
]

如果没有配置，可能会出现页面能打开，但接口请求失败。

这种问题容易被误判成：

  • 接口地址错误
  • dio 配置错误
  • 证书问题
  • 代理问题

所以排查网络问题时，第一步应该先看鸿蒙权限。

  • 问题5：ohpm install 或 Hvigor 同步失败

鸿蒙工程依赖需要通过 ohpm 安装。

如果 ohos 目录下的依赖没有安装完整，构建时可能会报：

Cannot find module
Cannot find flutter-hvigor-plugin
ohpm install failed
hvigor build failed

常见原因有：

  • DevEco Studio SDK 没装完整
  • ohpm 没有加入 PATH
  • 网络代理影响依赖下载
  • oh_modules 缓存损坏
  • Flutter SDK 和鸿蒙工程模板不匹配

可以尝试：

cd ohos
ohpm install
cd ..
flutter clean
flutter pub get

如果还是失败，可以删除构建缓存后重新同步：

ohos/oh_modules
ohos/.hvigor
build/

删除缓存前要确认这些目录里没有手写代码。

一般来说，它们都是工具生成的依赖和构建产物。

  • 问题6：签名配置是本机环境，不要随便共享

鸿蒙真机运行需要签名。

DevEco Studio 自动生成的调试签名通常带有本机路径，比如：

/Users/xxx/.ohos/config/xxx.cer
/Users/xxx/.ohos/config/xxx.p12
/Users/xxx/.ohos/config/xxx.p7b

如果把这些配置直接提交，其他同事拉下来后可能路径不存在。

更严重的是，签名密码和证书信息不应该公开。

建议做法是：

  • 本地调试签名各自生成
  • 发布签名单独管理
  • 仓库里不要提交敏感签名材料
  • CI 里通过安全变量或密钥管理系统注入

如果项目必须提交 build-profile.json5，也要检查里面是否包含敏感内容。

  • 问题7：Android 原生能力不能直接迁移到鸿蒙

很多 Flutter 项目里会有自定义 Android 原生代码，比如：

android/app/src/main/kotlin/...
android/app/src/main/java/...

这些代码可能用于：

  • MethodChannel
  • 推送
  • 支付
  • 分享
  • 文件选择
  • WebView 定制
  • 原生页面跳转
  • 设备信息获取

这些代码不能直接在鸿蒙侧复用。

鸿蒙侧需要用 ArkTS / TS 按 HarmonyOS API 重新实现。

如果项目里有自定义 Channel，要建立一张迁移表：

Channel 名称
Dart 调用方法
Android 实现位置
iOS 实现位置
鸿蒙是否已实现
鸿蒙实现位置
是否影响主流程

这样可以清楚知道哪些能力已经兼容，哪些能力只是页面暂时没点到。

  • 问题8：WebView 类插件要重点验证

当前项目里依赖了：

webview_flutter: ^4.13.1

WebView 在鸿蒙兼容里属于高风险插件。

原因是它强依赖平台原生 WebView 能力。

即使 Dart API 一样，不同平台的行为也可能有差异，比如：

  • 页面加载回调
  • JS 注入
  • Cookie
  • UserAgent
  • 文件选择
  • URL 拦截
  • HTTPS 证书
  • 返回键处理
  • 混合内容加载

如果项目中 WebView 是核心功能，不能只验证页面能打开。

至少要测试：

  • 加载普通 HTTPS 页面
  • 加载业务 H5 页面
  • JSBridge 是否可用
  • 登录态 Cookie 是否正常
  • 返回键是否符合预期
  • 页面关闭后是否释放资源

如果当前插件版本没有鸿蒙实现，就需要找对应的 webview_flutter_ohos 或使用鸿蒙侧原生能力重新封装。

  • 问题9：资源路径和大小写问题

Flutter 资源通常写在：

flutter:
  assets:
    - assets/images/
    - mock/

当前 Demo 也是这种配置。

鸿蒙侧运行时也会打包这些 Flutter assets。

但要注意：

  • 文件名大小写要和代码引用完全一致
  • 不要依赖某些系统对大小写不敏感的行为
  • 资源路径不要写成本地绝对路径
  • mock 数据如果用于线上包，要确认是否需要剔除

有些资源问题在 Android 上可能没暴露，到鸿蒙打包或运行时才暴露。

所以兼容时建议把资源加载路径统一扫一遍。

  • 问题10：UI 能跑不代表体验已经兼容

Flutter 页面能在鸿蒙上显示，只代表第一步完成。

还需要继续验证：

  • 状态栏高度
  • 安全区域
  • 返回手势
  • 系统返回键
  • 输入法弹起
  • 弹窗位置
  • Loading 层
  • Toast
  • 图片加载
  • 列表滚动
  • 下拉刷新
  • 横竖屏
  • 暗黑模式
  • 字体缩放

当前 Demo 使用了：

flutter_screenutil: ^5.9.3
flutter_easyloading: ^3.0.5
easy_refresh: ^3.4.0
card_swiper: ^3.0.1
flutter_staggered_grid_view: ^0.7.0

这些库大多是 UI 层能力，但在新平台上仍然要看实际效果。

尤其是：

  • 瀑布流是否抖动
  • Banner 是否铺满
  • Loading 是否遮挡导航
  • 下拉刷新是否和系统手势冲突
  • 屏幕适配是否符合鸿蒙设备尺寸

不要只看首页能打开就认为兼容完成。

  • 推荐的改造步骤

如果从零开始改一个 Flutter 项目兼容鸿蒙，我比较推荐下面这个顺序。

第一步，锁定环境版本。

DevEco Studio
HarmonyOS SDK
Flutter 鸿蒙 SDK
Dart SDK
ohpm
Hvigor

第二步，生成 ohos 平台工程。

flutter create --platforms ohos .

第三步，先跑一个最小 Flutter 页面。

不要一开始就跑完整业务。

可以先确认：

  • App 能安装
  • 首页能显示
  • Debug 日志可见
  • 热重载或重新运行链路可用

第四步，梳理依赖。

重点看：

flutter pub deps

把插件分成：

  • 不需要处理
  • 需要鸿蒙版本
  • 需要自己适配
  • 暂时移除或降级

第五步，处理权限。

把 Android、iOS 里声明过的能力迁移到鸿蒙侧：

ohos/entry/src/main/module.json5

第六步，处理签名和真机调试。

先用 DevEco Studio 跑通调试签名，不要一开始就纠结发布签名。

第七步，跑主流程。

比如当前 Demo 可以按这些流程测试：

  • 首页启动
  • 资讯列表
  • 资讯详情
  • 漫画列表
  • 漫画详情
  • 个人页
  • 网络请求
  • 本地缓存
  • 返回逻辑

第八步，处理平台差异。

比如：

  • WebView
  • 分享
  • 下载
  • 存储
  • 相册
  • 权限弹窗
  • 系统返回

第九步，整理文档和团队规范。

把能跑通的环境和步骤写下来，避免后续每个人重复踩坑。

  • 鸿蒙兼容的推荐标准

结合这次项目实践，我比较推荐下面这套标准：

  1. 先统一开发环境，再开始改代码
  2. Flutter SDK 必须使用支持 ohos 的版本
  3. Dart SDK 版本要满足项目 pubspec.yaml 约束
  4. DevEco Studio 和 HarmonyOS SDK 版本要和 compatibleSdkVersion 对齐
  5. ohos 工程生成后，先跑通最小链路
  6. 纯 Dart 依赖和平台插件要分开排查
  7. 所有平台插件都要确认是否有 ohos 实现
  8. 不要默认 Android 插件能力会自动迁移到鸿蒙
  9. 网络、相机、相册、定位等权限要在 module.json5 中重新声明
  10. 本地调试签名和发布签名要分开管理
  11. 不要把敏感签名材料提交到公共仓库
  12. ohpm install、Hvigor 同步和 Flutter 构建链路都要能独立跑通
  13. WebView、支付、推送、分享这类能力要专项测试
  14. UI 能显示不等于体验兼容完成
  15. 每次升级 Flutter SDK 或 DevEco Studio 后，都要重新做回归测试
  • 还可以继续优化的点

当前实现已经打通了鸿蒙兼容的基础链路，但如果要做得更完整，还可以继续补下面这些能力。

  • 优化1：补齐插件兼容清单

建议在项目里维护一份插件兼容表。

内容可以包括：

插件名称
当前版本
是否纯 Dart
是否支持 Android
是否支持 iOS
是否支持 ohos
鸿蒙替代方案
当前验证状态
负责人

这样后续升级依赖时，不会不知道哪个插件会影响鸿蒙。

  • 优化2：把环境版本写入项目文档

建议在 README.md 或 docs 目录里补充：

DevEco Studio 版本
HarmonyOS SDK 版本
Flutter 鸿蒙 SDK 获取方式
Dart SDK 版本
ohpm 配置方式
运行命令
常见问题

环境文档越清楚，团队接入成本越低。

  • 优化3：为鸿蒙单独建立测试清单

鸿蒙兼容测试不能只复用 Android 测试清单。

建议单独覆盖：

  • 安装启动
  • 权限弹窗
  • 系统返回
  • 网络请求
  • 本地缓存
  • WebView
  • 图片加载
  • 列表滚动
  • 页面跳转
  • 冷启动
  • 热启动
  • 横竖屏
  • 深色模式
  • 异常断网

这样更容易发现平台差异。

  • 优化4：把鸿蒙构建接入 CI

本地能打包不代表团队能稳定交付。

后续可以把鸿蒙构建接入 CI。

CI 里至少要做：

flutter pub get
flutter analyze
flutter test
ohpm install
flutter build hap

具体命令要以实际鸿蒙 Flutter SDK 支持为准。

如果 CI 能稳定产出 HAP，说明项目兼容链路比较健康。

  • 优化5：沉淀平台差异封装

如果后续鸿蒙侧差异越来越多，不建议在业务页面里到处写：

if (Platform.isOhos) {
  ...
}

更推荐把差异收敛到：

  • 平台服务层
  • 插件封装层
  • 工具类
  • 路由能力判断
  • 权限能力判断

业务页面只关心“我要打开 WebView”“我要保存缓存”“我要申请权限”，不要关心每个平台怎么实现。

结束：

这篇文章就先写到这里。

相比普通 Flutter 项目开发，兼容鸿蒙更考验项目的工程化能力。它不是只多一个平台目录，也不是页面能显示就算完成，而是要同时处理：

  • Flutter SDK 版本
  • DevEco Studio 环境
  • HarmonyOS SDK
  • ohpm 和 Hvigor 构建链路
  • ohos 平台工程
  • 插件鸿蒙实现
  • 权限声明
  • 签名配置
  • 真机调试
  • 平台差异测试
  • 后续依赖升级维护

这次 Demo 的思路可以总结成一句话：

业务层尽量复用，平台层补齐鸿蒙，插件层逐个适配。

在 Flutter 项目里做鸿蒙兼容时，真正重要的不是生成一个 ohos 目录，而是先想清楚：

  • 当前 Flutter SDK 是否支持鸿蒙
  • 项目 Dart 版本是否匹配
  • DevEco Studio 和 HarmonyOS SDK 是否对齐
  • 哪些插件依赖平台能力
  • 哪些权限需要重新声明
  • 签名和真机运行是否跑通
  • Android 原生能力是否需要在鸿蒙侧重写
  • WebView、支付、推送、分享等能力是否有替代方案
  • 团队后续如何统一环境和构建流程

这些问题理顺之后，Flutter 兼容鸿蒙就会清晰很多。

技术最终还是服务交付。鸿蒙兼容的价值，不是让项目目录里多一个平台文件夹，而是让已有 Flutter 业务可以在新的系统生态里稳定运行、持续迭代，并且尽量减少重复开发成本。

avatar
文章
阅读
粉丝