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

欢迎大家。在已支持 iOS/Android 的项目中增加平台目录，保持。

程序媛夏天

244人浏览 · 2026-03-20 08:35:29

程序媛夏天 · 2026-03-20 08:35:29 发布

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

欢迎大家加入跨平台开发者社区。

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

适用场景

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

前置条件

项	说明
IDE	已安装 DevEco Studio
Flutter-OH	已按官方文档完成 Flutter OH 环境搭建（含 SDK、fvm/路径等）
设备	真机或模拟器，且 `hdc`、`flutter devices` 能识别 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 根目录）。

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

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

三、适配 `pubspec.yaml`

1. 环境与 Flutter 约束

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

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

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

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

2. 拉取依赖

flutter clean
flutter pub get

四、三方库适配

适配前请先查阅：

OpenHarmony 三方库兼容性列表

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

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（鸿蒙侧）

4. 平台判断代码

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

import 'dart:io';

if (Platform.isAndroid) {
  // Android
} else if (Platform.isIOS) {
  // iOS
} else if (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 --debug
flutter 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

六、检查清单（小结）

步骤	动作
1	`flutter create --platforms ohos .`
2	DevEco 打开 `ohos/`，配置 Signing
3	调整 `pubspec.yaml` 的 `environment` 与 git 版插件
4	`flutter pub get`，处理编译报错与缺失插件
5	代码中补充 `Platform.isOhos` 等分支（如有）
6	`flutter run` / `flutter build hap` + `hdc install`