本文档介绍如何将已有的 Flutter 应用（已支持 iOS/Android）扩展支持鸿蒙平台，在现有项目中添加鸿蒙平台目录，保持多端代码复用。

---

前置条件

• 已安装 DevEco Studio
• 已完成 Flutter OH 环境搭建

---

开始适配

1. 备份现有项目

cp -r your_flutter_project your_flutter_project_backup

2. 添加鸿蒙平台支持

进入你的 Flutter 项目目录，执行以下命令：

cd your_flutter_project

# 为现有项目添加 ohos 平台支持
flutter create --platforms ohos .

执行成功后，项目新增 ohos 目录，结构如下：

your_flutter_project/
├── android/              # Android 平台代码
├── ios/                  # iOS 平台代码
├── ohos/                 # OpenHarmony 平台代码（新增）
│   ├── build-profile.json5
│   ├── hvigorfile.ts
│   ├── local.properties
│   ├── entry/            # 主入口模块
│   │   ├── build-profile.json5
│   │   ├── hvigorfile.ts
│   │   ├── oh-package.json5
│   │   └── src/
│   │       ├── main/
│   │       │   ├── ets/
│   │       │   │   ├── entryability/
│   │       │   │   │   └── EntryAbility.ets      # 主入口 Ability
│   │       │   │   └── pages/
│   │       │   │       └── Index.ets             # 主页面
│   │       │   └── resources/                    # 资源文件
│   │       └── ohosTest/                         # 测试代码
│   └── ohos/           # Flutter 引擎模块
├── lib/               # Dart 业务代码（多端复用）
├── test/
├── pubspec.yaml
└── ...

3. 配置项目签名

使用 DevEco Studio 打开 ohos 目录：

1. 选择 File → Project Structure → Project → Signing Configs
2. 勾选 Automatically generate signature 自动生成签名
3. 点击 OK 保存

4. 适配 pubspec.yaml

• 根据目标 Flutter OH 版本调整 SDK 约束：

# Flutter 3.27.4-ohos 版本
environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: ">=3.27.0"

# Flutter 3.22.0-ohos 版本
environment:
  sdk: '>=3.0.0 <4.0.0'
  flutter: ">=3.22.0"

• 获取依赖

flutter clean
flutter pub get

---

三方库适配

适配前，请先查阅 OpenHarmony平台已适配三方库，检查项目依赖的三方库是否已适配OpenHarmony 平台。若使用到的三方库未适配，可提交 issue 反馈。

1. 替换为 OpenHarmony 兼容版本

dependencies:
  # 原配置（Pub 官方版本，不支持 OpenHarmony）
  # path_provider: ^2.1.0
  
  # 新配置（OpenHarmony 适配版本）
  path_provider:
    git:
      url: "https://gitcode.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://gitcode.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://gitcode.com/openharmony-tpc/flutter_packages.git"
      path: "packages/url_launcher/url_launcher"
      ref: "br_url_launcher-v6.3.2_ohos"

2. 自定义库适配

如果项目中使用自定义的库，则需要为自定义库添加 OpenHarmony 平台实现。

适配指导请参考：开发Flutter Plugin

3. 平台判断代码适配

如果代码中有平台判断，需要添加 OpenHarmony 支持：

import 'dart:io';

// 原代码
if (Platform.isAndroid) {
  // Android 特定逻辑
} else if (Platform.isIOS) {
  // iOS 特定逻辑
}

// 适配后 - 添加 OpenHarmony 平台判断
if (Platform.isAndroid) {
  // Android 特定逻辑
} else if (Platform.isIOS) {
  // iOS 特定逻辑
} else if (Platform.isOhos) {
  // OpenHarmony 特定逻辑
}

4. 纯 Dart 三方库

通常纯 Dart 三方库无需修改即可在 OpenHarmony 上运行。但如果代码中有平台判断，还是需要参照上面 第3步 添加 添加 OpenHarmony 平台判断。

---

构建与运行

1. 连接设备

# 查看连接的设备
flutter devices

# 预期输出示例
# 9CN0123608000xxx (mobile) • 9CN0123608000xxx • ohos-arm64 • Ohos OpenHarmony-6.1.0.26

2. 运行调试

# 运行到鸿蒙设备
flutter run -d <device_id>

# 或使用简写（如果只有一台鸿蒙设备）
flutter run

3. 构建 HAP 包

# 调试版本
flutter build hap --debug

# 正式版本
flutter build hap --release

4. 安装 HAP 包

# 使用 hdc 工具安装
hdc install build\ohos\hap\entry-default-signed.hap

# 或指定设备
hdc -t <device_id> install build\ohos\hap\entry-default-signed.hap