已有 Flutter 应用适配鸿蒙平台指导文档

在已支持 iOS/Android 的项目中增加 ohos 平台目录，保持 Dart 业务代码多端复用。

适用场景

• 已有 Flutter 工程，希望 增量接入 OpenHarmony / 鸿蒙 NEXT（Flutter-OH）。
• 不打算新建工程，而是在 当前仓库 内补齐 ohos/ 与依赖、签名、构建流程。

前置条件

一、备份与添加鸿蒙平台

1. 备份现有项目（建议）

cp -r your_flutter_project your_flutter_project_backup

2. 为现有工程添加 ohos 平台

cd your_flutter_project# 在现有项目根目录执行，不要漏掉末尾的 .flutter create --platforms ohos .

成功后会出现 ohos/ 目录，与 android/、ios/ 并列。

3. 典型目录结构（示意）

your_flutter_project/├── android/├── ios/├── ohos/                          # 鸿蒙工程（新增）│   ├── build-profile.json5│   ├── hvigorfile.ts│   ├── local.properties│   ├── entry/                     # 主入口模块│   │   ├── build-profile.json5│   │   ├── hvigorfile.ts│   │   ├── oh-package.json5│   │   └── src/main/│   │       ├── ets/│   │       │   ├── entryability/EntryAbility.ets│   │       │   └── pages/Index.ets│   │       └── resources/│   └── ohos/                      # Flutter 引擎相关模块（随模板生成）├── lib/                           # Dart 业务（多端复用）├── test/├── pubspec.yaml└── ...

说明：不同 Flutter-OH 版本模板细节可能略有差异，以你本地生成结果为准；核心是 ohos/entry 与 ohos 根目录 的配置文件齐全。

二、配置签名

使用 DevEco Studio 打开项目中的 ohos 目录（打开该文件夹作为工程根，而非整个 Flutter 根目录）。

1. File → Project Structure（部分版本为 Project → Signing Configs）
2. 进入 Signing Configs
3. 勾选 Automatically generate signature（自动生成调试签名）或按团队规范配置正式证书
4. 保存（OK）

未正确配置签名时，flutter build hap 或安装阶段容易失败。

三、适配 pubspec.yaml

1. 环境与 Flutter 约束

按你所用的 Flutter-OH 发行版 调整 environment，例如：

# 示例：Flutter 3.27.x-ohosenvironment:sdk:'>=3.0.0 <4.0.0'flutter:">=3.27.0"

# 示例：Flutter 3.35.x-ohosenvironment:sdk:'>=3.0.0 <4.0.0'flutter:">=3.35.0"

注意：flutter 下限应 ≥ 当前实际使用的 OH 引擎版本，并与团队 CI 一致；具体以 官方发布说明 / CHANGELOG^[3] 为准。

2. 拉取依赖

flutter cleanflutter pub get

四、三方库适配

适配前请先查阅：

• OpenHarmony 三方库兼容性列表^[4]

若依赖未适配，可到社区跟踪进度或向 flutter_flutter issues^[5] 反馈。

1. 使用 OpenHarmony 适配分支（Git 依赖示例）

将 带原生实现的插件 从 pub.dev 默认源改为 openharmony-tpc 等维护的 git 路径，**ref 需按仓库实际分支/标签调整**：

dependencies:# path_provider 示例（ref 请对照官方文档当前推荐分支）path_provider:git:url:"https://atomgit.com/openharmony-tpc/flutter_packages.git"path:"packages/path_provider/path_provider"ref:"br_path_provider-v2.1.5_ohos"shared_preferences:git:url:"https://atomgit.com/openharmony-tpc/flutter_packages.git"path:"packages/shared_preferences/shared_preferences"ref:"br_shared_preferences-v2.5.4_ohos"url_launcher:git:url:"https://atomgit.com/openharmony-tpc/flutter_packages.git"path:"packages/url_launcher/url_launcher"ref:"br_url_launcher-v6.3.2_ohos"

2. 纯 Dart 包

无平台通道、仅 Dart 实现的包，多数 无需改源码 即可在 ohos 上随 Flutter 运行；若依赖了未适配的原生插件，仍需按上节替换。

3. 自研 Plugin

需为插件增加 ohos 平台实现，可参考：

• 开发 Flutter Plugin（鸿蒙侧）^[6]

4. 平台判断代码

在 Flutter-OH 提供的 dart:io 扩展下，可使用 **Platform.isOhos**。若原有逻辑只区分 Android / iOS，请补上鸿蒙分支：

import'dart:io';if (Platform.isAndroid) {// Android} elseif (Platform.isIOS) {// iOS} elseif (Platform.isOhos) {// OpenHarmony / 鸿蒙}

说明：Platform.isOhos 依赖 Flutter-OH SDK；纯官方 Flutter 不含此项，请在 OH 工具链下编译运行。

五、构建与运行

1. 确认设备

flutter devices

示例（示意）：

9CN0123608000xxx (mobile) • ohos-arm64 • Ohos OpenHarmony-x.x.x

2. 运行调试

flutter run -d <device_id># 仅一台鸿蒙设备时可简写flutter run

3. 构建 HAP

flutter build hap --debugflutter build hap --release

4. 安装 HAP

常见产物路径（以当前工具链为准，若与本地不一致请在 ohos/entry/build/... 下搜索 .hap）：

# 典型路径（相对 Flutter 项目根目录）# ohos/entry/build/default/outputs/default/entry-default-signed.hap

使用 hdc 安装（macOS / Linux 用 /，Windows 可将路径改为反斜杠）：

hdc install ohos/entry/build/default/outputs/default/entry-default-signed.hap# 多设备时指定序列号hdc -t <device_id> install ohos/entry/build/default/outputs/default/entry-default-signed.hap

六、检查清单（小结）

相关文档

• Flutter-OH 示例与文档：flutter_samples / ohos/docs^[7]
• 引擎与版本变更：flutter_flutter^[8]

文档随 Flutter-OH 版本演进，命令与路径请以你本地 SDK 及官方最新说明为准。